reconFTW is a tool designed to perform automated recon on a target domain by running the best set of tools to perform scanning and finding out vulnerabilities
Shell bug-bountybugbountybugbounty-tooldnshackingnucleiosintpenetration-testingpentestpentest-toolpentestingreconreconnaissancescannersecuritysecurity-toolssubdomainsubdomain-enumerationvulnerabilities
docs: define v1 requirements
six2dezb81aa640abab
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.mdnew file mode 100644index 0000000..08c074f--- /dev/null+++ b/.planning/REQUIREMENTS.md@@ -0,0 +1,107 @@+# Requirements: reconFTW++**Defined:** 2026-05-13+**Core Value:** Run one command, get a complete recon picture of a target — passive, active, and vulnerability layers — with resumable checkpoints, structured output, and zero-touch tool orchestration.++## v1 Requirements++Brownfield audit-driven milestone. Each requirement remediates a finding from `.planning/codebase/CONCERNS.md` or fills a known gap. Existing reconFTW capabilities are tracked under PROJECT.md `Validated` and are not re-listed here.++### Resilience++- [ ] **RESIL-01**: User can resume an interrupted recon and skip functions that finished cleanly while re-running functions that were killed mid-execution — via `.inprogress_<func>` sentinel written at `start_func`, renamed to `.<func>` at `end_func`, surfacing partial state on next invocation+- [ ] **RESIL-02**: A recon run aborts with a clear error (rather than producing truncated output) when the working filesystem fills mid-scan — via periodic `df` checks inside long subdomain/DNS loops and a `trap` on `ENOSPC` write failures+- [ ] **RESIL-03**: User can bound individual job time inside `parallel_funcs` via a `PARALLEL_JOB_TIMEOUT_SECONDS` setting, with stuck jobs terminated by `kill -TERM` so a hung tool no longer stalls an entire batch++### Security Hardening++- [ ] **SEC-01**: `safe_count()` no longer falls back to `eval` — all remaining callers in `lib/` and `modules/` write output to a temp file first, and the `else` branch at `lib/common.sh:760` is removed+- [ ] **SEC-02**: `sendToNotify()` quotes every variable it passes to `curl` — `$discord_url`, `${slack_channel}`, and the filename argument `${1}` are all `"$var"`-quoted at `modules/core.sh:1410-1414`+- [ ] **SEC-03**: `AXIOM_EXTRA_ARGS` is consumed via a bash array (`AXIOM_EXTRA_ARGS_ARR=()`) across `modules/subdomains.sh` and `modules/web.sh`, with intentional tokenization made explicit instead of relying on word-splitting an unquoted variable+- [ ] **SEC-04**: Installer verifies the integrity of `rustup` and `uv` bootstrappers via `verify_sha256()` against pinned hashes, and stability-critical Go tools (`nuclei`, `httpx`, `ffuf`, `puredns`, `subfinder`) re-introduce pinned versions captured in a `tools.lock`-style manifest++### Performance++- [ ] **PERF-01**: User can cap per-tool thread counts via `FFUF_THREADS_MAX`, `HTTPX_THREADS_MAX`, `HTTPX_UNCOMMONPORTS_THREADS_MAX`, `KATANA_THREADS_MAX`, `DALFOX_THREADS_MAX`, `DNSTAKE_THREADS_MAX` so multi-core hosts no longer scale linearly into target-overwhelming concurrency+- [ ] **PERF-02**: DNS brute/resolve operations have non-zero default timeouts (`DNS_BRUTE_TIMEOUT=6h`, `DNS_RESOLVE_TIMEOUT=4h`) so a hung resolver does not indefinitely stall a run++### Test Coverage++- [ ] **TEST-01**: Unit tests cover `parallel_funcs` barrier synchronization, heartbeat polling cadence, and the failure-counter increment path so regressions in parallel execution surface in CI+- [ ] **TEST-02**: A mocked end-to-end integration test exercises the `subdomains.sh` → `web.sh` → `vulns.sh` handoff so format-contract regressions (e.g., `webs.txt` shape, scope filter output) fail before manual testing+- [ ] **TEST-03**: Integration tests cover the axiom failover path: `axiom_disable_runtime` invocation on launch failure, partial-fleet fallback to local mode, and `AXIOM_AUTO_FIX_HOSTKEY` repair++### Documentation++- [ ] **DOCS-01**: `reconftw.cfg` documents every previously-hidden tunable — `PARALLEL_MAX_JOBS`, `ALLOW_TRANSFER`, `RAISE_ULIMIT`, `ULIMIT_TARGET`, and `AXIOM_EXTRA_ARGS` word-splitting semantics — as commented-out reference entries+- [ ] **DOCS-02**: Disk-space defaults align — either `reconftw.cfg:39` lifts `MIN_DISK_SPACE_GB` to `5` to match `modules/modes.sh:23`, or `modes.sh` drops the `:-5` fallback so the config value is authoritative++### Bug Fixes++- [ ] **FIX-01**: `modules/web.sh:2340` axiom-exec install path is `github.com/brosck/mantra@latest` (lowercase), matching the local install path fixed in commit `f64383c2`+- [ ] **FIX-02**: Scope-check unification — `is_in_scope_host()` (Python-backed, `lib/validation.sh`) and `domain_match_regex()` (ERE, `lib/common.sh`) agree on edge cases (trailing dots, wildcards, empty input, IDN), verified by a cross-check test in `tests/unit/`++## v2 Requirements++Acknowledged backlog. Tracked but not in current roadmap.++### Architecture++- **ARCH-01**: Split `modules/web.sh` (2965 lines) into `modules/web_analysis.sh` and `modules/web_detection.sh` to improve reviewability and isolated testing+- **ARCH-02**: Centralize secret handling so tokens can always be passed via files (e.g., `-tf` flag) instead of CLI args visible in `ps aux`++### Scaling++- **SCALE-01**: Add memory-aware permutation throttling so `gotator`/`regulator` adjust input size based on available RAM+- **SCALE-02**: Resolver-file health gate — abort `puredns` if fewer than N working resolvers are reachable (instead of silently degrading)++### Observability++- **OBS-01**: Surface venv health (missing imports, broken Python virtualenvs) in `tools_installed`/`check_optional_api_keys` startup summary so silent skips no longer hide failures+- **OBS-02**: Emit structured JSONL events at every module boundary by default (currently opt-in via `STRUCTURED_LOGGING=true`)++## Out of Scope++Explicit exclusions. Documented to prevent scope creep.++| Feature | Reason |+|---------|--------|+| Active exploitation / payload delivery | reconFTW maps attack surface and flags candidate vulns; weaponized exploitation belongs in user-driven tooling |+| GUI / web dashboard | CLI-first by design; report HTML is read-only output, not an interactive UI |+| Real-time streaming results | Output is file-based and post-run; live dashboards require a fundamentally different architecture |+| Multi-user collaboration | Single-operator CLI tool; team workflows handled by external systems (Faraday, custom aggregators) |+| Cloud SaaS hosting | Self-hosted CLI by design; Axiom is opt-in distributed execution, not managed hosting |+| Re-implementing wrapped tools | reconFTW orchestrates existing best-of-breed tools (subfinder, nuclei, httpx, ...) rather than competing with them |+| Removing `bash -lc` execution of `AXIOM_POST_START` | Config value is intentionally executable; documenting the contract is the chosen path, not removing the capability |++## Traceability++Which phases cover which requirements. Updated during roadmap creation.++| Requirement | Phase | Status |+|-------------|-------|--------|+| RESIL-01 | TBD | Pending |+| RESIL-02 | TBD | Pending |+| RESIL-03 | TBD | Pending |+| SEC-01 | TBD | Pending |+| SEC-02 | TBD | Pending |+| SEC-03 | TBD | Pending |+| SEC-04 | TBD | Pending |+| PERF-01 | TBD | Pending |+| PERF-02 | TBD | Pending |+| TEST-01 | TBD | Pending |+| TEST-02 | TBD | Pending |+| TEST-03 | TBD | Pending |+| DOCS-01 | TBD | Pending |+| DOCS-02 | TBD | Pending |+| FIX-01 | TBD | Pending |+| FIX-02 | TBD | Pending |++**Coverage:**+- v1 requirements: 16 total+- Mapped to phases: 0 (pending roadmap)+- Unmapped: 16 ⚠️++---+*Requirements defined: 2026-05-13*+*Last updated: 2026-05-13 after initial definition*