Skip to content

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

docs: point the front page at the opt-in v2 Go beta

six2deze4499deb68bd
diff --git a/.github/ISSUE_TEMPLATE/v2-beta-feedback.md b/.github/ISSUE_TEMPLATE/v2-beta-feedback.md
new file mode 100644
index 0000000..e77bc4d
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/v2-beta-feedback.md
@@ -0,0 +1,82 @@
+---
+name: "v2 beta feedback"
+about: "Report anything you hit while running the reconFTW Go beta (v5.0.0-beta.x)"
+title: "[v2-beta] "
+labels: ["v2-beta", "feedback"]
+assignees: []
+---
+
+<!--
+CUT-10. This template is the beta feedback channel. Please use it for the Go
+rewrite (v5.0.0-beta.x) ONLY — for the bash release (v4.1 and earlier) use the
+normal Bug report template instead.
+
+Nothing here is required. A one-line report of "this broke" with the version is
+already useful; the rest just saves a round-trip.
+-->
+
+## What happened
+
+<!-- What you ran, and what you expected instead. -->
+
+## Version
+
+```
+# paste the output of:
+reconftw version
+```
+
+- Installed from: <!-- release tarball / built from source / Docker -->
+- OS + arch: <!-- e.g. Ubuntu 24.04 x86_64, macOS 15 arm64 -->
+
+## Are you migrating from bash v4.x?
+
+- [ ] Yes — I ran `reconftw migrate` on an existing `reconftw.cfg`
+- [ ] Yes — but I wrote a fresh TOML config by hand
+- [ ] No — this is a new install
+
+If you migrated: **please paste any `⚠ unknown key` warnings** the migrator
+printed. Those are the ones we most need to see — an unknown key means your
+config had something the migrator does not yet map.
+
+## Which of these does it touch?
+
+<!-- Tick anything relevant; this routes the issue faster. -->
+
+- [ ] Config migration (`reconftw.cfg` → TOML)
+- [ ] Output tree / file layout — see the note below
+- [ ] CLI flags behaving differently from bash
+- [ ] A tool not being found, or found but not running
+- [ ] Results differ from bash v1 on the same target
+- [ ] Performance
+- [ ] Docker / install
+- [ ] Something else
+
+### Known and already tracked — no need to report these
+
+Please skip these; they are open on purpose and reporting them just adds noise:
+
+- **`Recon/<domain>/` is not created.** The bash-shape compat tree currently
+ lives under the workspace root as `_compat/`. Whether v2 should also create the
+ top-level `Recon/<domain>/` symlink is an open decision (CUT-08), not an
+ oversight. **Do tell us if this breaks a script of yours** — that is exactly the
+ input we need to decide it.
+- **`dnscewl` / `dnstake` report as missing.** Neither resolves on macOS in this
+ beta.
+- **`dalfox` may exit non-zero** with `unexpected argument '--no-spinner'` if your
+ installed dalfox is v3.x — the pinned vector targets v2.9.2.
+
+## Logs
+
+<!--
+`logs/tools.jsonl` in the workspace records every tool invocation with its argv
+and outcome — it is usually the single most useful thing to attach.
+
+Secrets registered with the redactor are scrubbed from it, but PLEASE SKIM IT
+before pasting: it contains the command lines your scan actually ran, including
+target names.
+-->
+
+```
+# relevant log lines here
+```
diff --git a/README.md b/README.md
index 02edc17..be64ef0 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,7 @@ reconFTW leverages a wide range of techniques, including passive and active subd
- [Local Installation (PC/VPS/VM)](#local-installation-pcvpsvm)
- [Docker](#docker)
- [Terraform + Ansible](#terraform--ansible)
+- [Trying the v2 beta (Go rewrite)](#trying-the-v2-beta-go-rewrite)
- [⚙️ Configuration](#️-configuration)
- [🚀 Usage](#-usage)
- [Target Options](#target-options)
@@ -391,6 +392,22 @@ cd reconftw
---
+## Trying the v2 beta (Go rewrite)
+
+reconFTW is being rewritten in Go. The rewrite ships as an **opt-in pre-release**: it is
+listed on the [releases page](https://github.com/six2dez/reconftw/releases), and GitHub
+never points `releases/latest` at a pre-release — so **if you do nothing, you keep getting
+the bash release.** That is deliberate.
+
+The Go binary is `reconftw`; the bash entry point is `reconftw.sh`. They do not overwrite
+each other, so you can keep both and fall back at any time.
+
+- [**What the beta is, and what it is not**](docs/V2-BETA-ANNOUNCEMENT.md) — including three
+ things that are explicitly not finished yet.
+- [**Report something**](https://github.com/six2dez/reconftw/issues/new?template=v2-beta-feedback.md)
+ — the v2 beta feedback template. Bugs in the bash release still go to the normal Bug report.
+
+
## 🛠️ Troubleshooting
- Bash 4+ on macOS: The scripts auto-relaunch under Homebrew Bash. If you see a message about Bash < 4, run `brew install bash`, open a new terminal, and re-run `./install.sh`.
diff --git a/docs/V2-BETA-ANNOUNCEMENT.md b/docs/V2-BETA-ANNOUNCEMENT.md
new file mode 100644
index 0000000..7458f99
--- /dev/null
+++ b/docs/V2-BETA-ANNOUNCEMENT.md
@@ -0,0 +1,157 @@
+# reconFTW v2 beta — `v5.0.0-beta.1`
+
+reconFTW has been rewritten from bash to Go. This is the first public build of
+that rewrite, and it ships as an **opt-in pre-release**.
+
+This document is the canonical announcement for `v5.0.0-beta.1`. It leads with
+what the beta is, and then — at more length, because it matters more — with what
+it is not.
+
+---
+
+## What this is
+
+A single statically-linked binary that replaces the sourced-bash engine. Same
+recon philosophy: one command, a complete passive/active/vulnerability picture of
+a target. Different machinery underneath:
+
+- **Resumable by construction.** Every task records a checkpoint keyed by a hash
+ of its inputs — config slice, target, wordlist contents. Re-running skips
+ completed work.
+- **Structured output.** Artefacts are JSONL with a schema, written atomically,
+ scope-checked at the write boundary.
+- **Bounded concurrency.** One scheduler with a global ceiling and per-tool rate
+ limits, instead of unbounded background jobs sharing global state.
+- **Portable.** No bash 4.3+ requirement, no GNU-coreutils-on-macOS dance. Linux
+ and macOS, amd64 and arm64, plus a fully-static musl build for Alpine.
+- **TOML config**, with a migrator that reads your existing `reconftw.cfg` and
+ tells you loudly about every key it could not map.
+
+The ~100 external tools are still the ~100 external tools. The rewrite changed
+the orchestrator, not the toolbox.
+
+---
+
+## What this is NOT
+
+Three things are open. None of them is a surprise we are hoping you will not
+notice; they are the reason the beta exists at all.
+
+### 1. Parity is measured against ONE target, not three to five
+
+Bug-for-bug parity against bash v1 has been measured on **one** canonical target,
+run side-by-side with the outputs diffed. The acceptance criterion, **CUT-11**,
+asks for **three to five** canonical targets.
+
+That gap matters in a specific way: differences on any other target are
+**unmeasured, not verified-absent**. If v2 returns something bash v1 did not — or
+misses something bash v1 found — on a target we have not run, no test currently
+in the tree would have caught it. Please report those. A side-by-side diff on a
+target we have never run is the single most valuable thing a beta tester can
+send us.
+
+### 2. Throughput is unmeasured
+
+**No claim is made that v2 is faster than bash v1, or slower.** Nobody has
+benchmarked the two end to end against the same targets under the same rate
+limits, so any number you might expect to see here would be invented.
+
+The architecture changed in ways that plausibly cut either way — a bounded
+scheduler replaces unbounded background jobs, which can trade peak speed for
+predictability. Which way it actually lands is an open empirical question. If
+you run both, the timings are worth reporting; treat any assertion about v2's
+speed, including a favourable one, as unsupported until then.
+
+### 3. `Recon/<domain>/` is not created — **CUT-08** is open
+
+This is the one most likely to break something of yours.
+
+The beta does **not** create the top-level `Recon/<domain>/` tree. The
+bash-shape output tree is written under the workspace root as **`_compat/`**
+instead. Filenames inside it follow the v1 shape; the parent path does not.
+
+So a pipeline that reads `Recon/<domain>/subdomains/subdomains.txt` finds
+nothing under the beta, and a pipeline pointed at `_compat/` finds what it
+expects.
+
+Whether v2 should *also* create the top-level `Recon/<domain>/` path is an
+**open decision**, tracked as CUT-08 — not an oversight, and not something the
+beta is quietly hoping to skip. It is open because the answer depends on how
+many people actually script against that path and how, which is exactly what a
+beta period is for. **If this breaks a script of yours, say so.** That report is
+the input the decision is waiting on.
+
+---
+
+## Why the tag is `v5.0.0-beta.1` and not `v2.0.0-beta`
+
+"v2" is the **internal milestone name** for the Go rewrite. It is not the public
+version number, and it never will be.
+
+Public reconFTW tags are already at **`v4.1`**. A `v2.0.0-beta` tag would sort
+*below* the current public release: every tool that orders versions — package
+managers, update checkers, humans skimming a releases page — would read it as a
+downgrade, and some would refuse to install it over an existing v4.x. So the
+rewrite's first public tag continues the public sequence instead of restarting
+it: `v5.0.0-beta.1`.
+
+Expect `v5.0.0-beta.2`, `-beta.3` and so on during the beta period, and
+`v5.0.0` when it is no longer a beta.
+
+---
+
+## You are not affected unless you opt in
+
+**`releases/latest` continues to resolve to bash `v4.1`.**
+
+That is not a promise we are keeping by hand — it is how GitHub works. GitHub
+never points `releases/latest` at a pre-release, and the release pipeline marks
+this build as a pre-release. The install command documented at the top of the
+README resolves through `releases/latest`, so it keeps serving the bash release
+for the entire beta period.
+
+**If you do nothing, nothing changes for you.** To get the beta you have to name
+the tag explicitly — see the opt-in section in the README. The Go binary is
+`reconftw` and the bash entry point is `reconftw.sh`; they do not overwrite each
+other, so you can install the beta alongside your existing setup and fall back at
+any time by just running the other one.
+
+Migration details, and every breaking change with a before/after example, are in
+[MIGRATION.md](../MIGRATION.md) — start at §0.
+
+---
+
+## Where feedback goes
+
+Use the **[v2 beta feedback](https://github.com/six2dez/reconftw/issues/new?template=v2-beta-feedback.md)**
+issue template (`.github/ISSUE_TEMPLATE/v2-beta-feedback.md`). It applies the
+`v2-beta` and `feedback` labels automatically, which is what makes the triage
+below possible.
+
+Bugs in the bash release still go to the normal Bug report template. The beta
+template is for the Go rewrite only.
+
+Nothing in the template is required. A one-line "this broke" with the output of
+`reconftw version` is already useful.
+
+**Triage commitment (CUT-10):** a triage pass over open `v2-beta` issues once a
+month, with the summary posted publicly as a repository issue tagged `v2-beta` —
+what came in, what was fixed, what was deferred and why. The first pass happens
+the month after the beta ships.
+
+**No triage has happened yet, because the beta has not shipped yet.** This
+section describes a commitment, not a track record; judge it once there is
+something to judge.
+
+---
+
+## Known issues already tracked
+
+Please skip these — they are open on purpose, and reporting them adds noise
+rather than information:
+
+- `Recon/<domain>/` is not created (CUT-08, above). **Do tell us if it breaks a
+ script** — that specific report is wanted.
+- `dnscewl` and `dnstake` do not resolve on macOS in this beta.
+- `dalfox` may exit non-zero on `--no-spinner` if you have dalfox v3.x
+ installed; the pinned argument vector targets v2.9.2.