README
¶
A single-binary bug bounty engine.
Scope-gated recon · template + active detection · deterministic verification · LLM-assisted triage — in one static Go binary, zero runtime dependencies.
[!WARNING] huntx proves vulnerabilities, it does not exploit them. Only test targets you own or are explicitly authorized to test. Active commands refuse to run without a scope file and
--authorized; rate-limiting, a total-request cap, and a block on state-changing methods are on by default. Read SECURITY.md.
Live demo
talkdedsec.github.io/tlk-huntx — the same dashboard, live in your browser on sample data. Click a finding for the detail drawer (evidence, repro, CWE), filter by severity, and open the Surface tab for the attack-surface graph.
What it is
The recon/scan space is full of great Go tools — nuclei, httpx, katana, bbot, reconftw. What nobody ships open-source is the part the closed tools (XBOW, Elastic) charge for: a machine-readable scope gate, two-tier verification (engine finds → a deterministic check re-confirms → only then does a language model see it), semantic dedup, and a human-ready report — all in one dependency-free binary.
The core rule, drawn from every AI-security post-mortem: an LLM finds, an LLM never confirms. Verification is deterministic and out-of-band; the model only ever clusters, explains, and writes up findings the engine already proved.
┌───────────────────────────────────────────┐
in-scope target →│ safety gate │ the fetch client is the
scope.json →│ scope · rate-limit · blast · authorized │ only thing that ever
identities →│ │ touches a target
└───────────────────────────────────────────┘
│
▼
discover → detect → verify → intelligence → interface
──────── → ────── → ────── → ──────────── → ─────────
recon templates re-confirm EV-ranked plan dashboard
crawl secrets OOB collab. attack chains report md/SARIF
fuzz active checks BOLA / IDOR FP feedback mcp · /huntx
api greybox out-of-band clusters notify · monitor
an engine finds · a deterministic check proves · only then a model triages
Install
# from source (needs Go 1.26+)
go install github.com/talkdedsec/tlk-huntx/cmd/huntx@latest
# or clone and build
git clone https://github.com/talkdedsec/tlk-huntx
cd tlk-huntx && go build -o huntx ./cmd/huntx
Pre-built binaries for linux/windows/darwin (amd64 + arm64) are on the releases page.
60-second quickstart
# 1. describe what you're allowed to test
cat > scope.json <<'EOF'
{ "program":"acme", "in_scope":["*.acme.com"], "allowed_methods":["GET","HEAD","OPTIONS"] }
EOF
# 2. is a target in scope? (sends nothing)
huntx --scope scope.json scope check api.acme.com evil.com
# 3. one shot: recon + crawl + scan + active checks + a ranked plan
huntx --scope scope.json --authorized full acme.com
# 4. read the results in the browser
huntx dashboard # http://localhost:8899
# 5. or produce a report
huntx --scope scope.json report huntx.findings.jsonl -o report.md
huntx report huntx.findings.jsonl -o huntx.sarif # SARIF for CI / code-scanning
Commands
| Command | What it does |
|---|---|
scope check |
Is a target in scope (sends nothing) |
recon |
Passive subdomains (crt.sh, Wayback, OTX, HackerTarget) + gated probing + graph |
full |
One shot: recon + crawl + scan + active param checks + ranked plan |
scan |
nuclei-compatible templates + secret scan (--verify to re-confirm) |
crawl |
Mine endpoints/params from HTML, JS, robots.txt, sitemap.xml |
fuzz |
Content discovery over a common-paths wordlist (soft-404 aware) |
api |
GraphQL introspection + OpenAPI/Swagger discovery |
reflect · sqli · ssti · lfi |
Per-parameter active checks (reflected XSS, error SQLi, template injection, path traversal) |
redirect |
Open-redirect detection |
ssrf · cmdi |
Out-of-band SSRF / command injection via a built-in collaborator |
hostheader |
Host-header injection |
bola / idor |
Object-level authz test across named identities |
greybox |
Correlate dangerous source sinks with live endpoints |
plan |
Rank findings by expected value and compose attack chains |
monitor |
Diff vs the last run; --interval to repeat, --notify webhook |
feedback |
Record triage decisions, self-calibrate confidence |
report |
Markdown or SARIF output (--min-severity to filter) |
dashboard |
Interactive local console (see the live demo) |
coordinate / worker |
Distributed scanning |
collaborator |
Standalone OOB interaction server |
mcp |
Model Context Protocol server (stdio) — drive huntx as typed tools |
Every active command enforces the scope gate; global flags may appear before or after the command.
Drive it from an agent
huntx mcp exposes the engine over the Model Context Protocol (stdio, JSON-RPC 2.0). An LLM agent
calls scope_check / recon / scan / plan / api / crawl as typed tools instead of parsing
CLI text. The /huntx skill in skill/huntx layers triage, dedup, and report
writing on top — the engine finds and proves, the model clusters and writes.
Safety by design
- Scope gate — a machine-readable in/out-of-scope decision (wildcards + CIDR, out-of-scope wins) on every outbound request. Nothing leaves the tool without passing it.
- Rate limit — per-host token bucket, global concurrency cap, automatic 429/WAF back-off.
- Blast radius — a total-request budget and a block on state-changing methods unless you opt in.
- Authorization — active pipelines refuse to run without a scope file and
--authorized. - Detection, not exploitation — probes prove a condition (a quote, a reflection, an OOB callback); they never carry destructive or DoS payloads.
Architecture
See docs/ARCHITECTURE.md for the layer/package map. In one line: a fetch
client that is the only thing allowed to touch a target, wrapped by scope + rate-limit + blast-radius,
feeding a discover → detect → verify → intelligence → interface stack.
Contributing
Issues and templates are welcome — keep additions detection-only and inside the safety gates. See CONTRIBUTING.md. Türkçe: README.tr.md.
License
MIT — see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
huntx
command
|
|
|
internal
|
|
|
agent
Package agent turns a pile of findings into a ranked playbook.
|
Package agent turns a pile of findings into a ranked playbook. |
|
apidisco
Package apidisco finds API attack surface: GraphQL endpoints that answer introspection, and exposed OpenAPI/Swagger specs whose declared paths become new endpoints to test.
|
Package apidisco finds API attack surface: GraphQL endpoints that answer introspection, and exposed OpenAPI/Swagger specs whose declared paths become new endpoints to test. |
|
authz
Package authz gates every active pipeline.
|
Package authz gates every active pipeline. |
|
blastradius
Package blastradius bounds the damage a run can do: a hard cap on total requests, and a block on state-changing HTTP methods unless explicitly allowed.
|
Package blastradius bounds the damage a run can do: a hard cap on total requests, and a block on state-changing HTTP methods unless explicitly allowed. |
|
cmdi
Package cmdi detects OS command injection out-of-band: it wraps a collaborator URL in shell metacharacters inside each parameter and checks whether the target's shell fetched it.
|
Package cmdi detects OS command injection out-of-band: it wraps a collaborator URL in shell metacharacters inside each parameter and checks whether the target's shell fetched it. |
|
collaborator
Package collaborator is an out-of-band interaction server, like a self-hosted Burp Collaborator.
|
Package collaborator is an out-of-band interaction server, like a self-hosted Burp Collaborator. |
|
crawl
Package crawl mines endpoints and parameters out of HTML and JavaScript: paths referenced in fetch/axios calls and links, query and form parameter names, and same-host script bundles worth pulling for more of the same.
|
Package crawl mines endpoints and parameters out of HTML and JavaScript: paths referenced in fetch/axios calls and links, query and form parameter names, and same-host script bundles worth pulling for more of the same. |
|
dashboard
Package dashboard serves a local read-only view of the attack surface and findings straight from the binary — the graph and findings files rendered as a single embedded page, no external services, no docker.
|
Package dashboard serves a local read-only view of the attack surface and findings straight from the binary — the graph and findings files rendered as a single embedded page, no external services, no docker. |
|
distributed
Package distributed spreads a scan across machines: a coordinator hands out targets over HTTP and collects findings, workers pull a target, scan it locally (through their own scope gate), and post results back.
|
Package distributed spreads a scan across machines: a coordinator hands out targets over HTTP and collects findings, workers pull a target, scan it locally (through their own scope gate), and post results back. |
|
engine
Package engine is the shared orchestration behind both the CLI and the MCP server: passive discovery + gated probing for recon, and template + secret detection with optional deterministic verification for scan.
|
Package engine is the shared orchestration behind both the CLI and the MCP server: passive discovery + gated probing for recon, and template + secret detection with optional deterministic verification for scan. |
|
feedback
Package feedback closes the false-positive loop.
|
Package feedback closes the false-positive loop. |
|
fetch
Package fetch is the only way huntx talks to a target.
|
Package fetch is the only way huntx talks to a target. |
|
fuzz
Package fuzz is lightweight content discovery: it requests a wordlist of common paths through the gated client and reports the ones that exist, using a soft-404 baseline so a catch-all page does not drown the results in false hits.
|
Package fuzz is lightweight content discovery: it requests a wordlist of common paths through the gated client and reports the ones that exist, using a soft-404 baseline so a catch-all page does not drown the results in false hits. |
|
graph
Package graph holds the attack surface as nodes (domain, subdomain, ip, port, service, endpoint, param, finding) and typed edges between them.
|
Package graph holds the attack surface as nodes (domain, subdomain, ip, port, service, endpoint, param, finding) and typed edges between them. |
|
greybox
Package greybox correlates source with runtime.
|
Package greybox correlates source with runtime. |
|
hostheader
Package hostheader detects host-header injection: it sends a canary host in the Host and X-Forwarded-Host headers and checks whether the application echoes it back into the body or a redirect.
|
Package hostheader detects host-header injection: it sends a canary host in the Host and X-Forwarded-Host headers and checks whether the application echoes it back into the body or a redirect. |
|
lfi
Package lfi detects local file inclusion / path traversal by requesting a few classic traversal sequences and matching the unmistakable signature of a system file (the /etc/passwd layout or a Windows .ini).
|
Package lfi detects local file inclusion / path traversal by requesting a few classic traversal sequences and matching the unmistakable signature of a system file (the /etc/passwd layout or a Windows .ini). |
|
mcp
Package mcp exposes huntx over the Model Context Protocol (JSON-RPC 2.0 on stdio), so an LLM agent drives recon/scan/scope as typed tools instead of parsing CLI text.
|
Package mcp exposes huntx over the Model Context Protocol (JSON-RPC 2.0 on stdio), so an LLM agent drives recon/scan/scope as typed tools instead of parsing CLI text. |
|
monitor
Package monitor turns huntx into a watchdog: it diffs one run against the last so a scheduled sweep surfaces only what changed — a new subdomain, a newly live host, a finding that was not there before — instead of re-reporting the world.
|
Package monitor turns huntx into a watchdog: it diffs one run against the last so a scheduled sweep surfaces only what changed — a new subdomain, a newly live host, a finding that was not there before — instead of re-reporting the world. |
|
notify
Package notify pushes a short message to a Slack/Discord-style incoming webhook.
|
Package notify pushes a short message to a Slack/Discord-style incoming webhook. |
|
openredirect
Package openredirect detects open redirects: it puts a canary host into common redirect parameters and checks whether the response's Location points off-site to that canary.
|
Package openredirect detects open redirects: it puts a canary host into common redirect parameters and checks whether the response's Location points off-site to that canary. |
|
ratelimit
Package ratelimit keeps huntx polite and ban-safe: a per-host token bucket caps request rate, a global semaphore caps concurrency, and Penalize backs off a host that answered 429 or tripped a WAF.
|
Package ratelimit keeps huntx polite and ban-safe: a per-host token bucket caps request rate, a global semaphore caps concurrency, and Penalize backs off a host that answered 429 or tripped a WAF. |
|
recon
Package recon discovers the attack surface.
|
Package recon discovers the attack surface. |
|
reflectx
Package reflectx detects reflected input, the precondition for reflected XSS.
|
Package reflectx detects reflected input, the precondition for reflected XSS. |
|
report
Package report turns findings into a HackerOne/Bugcrowd-ready markdown document.
|
Package report turns findings into a HackerOne/Bugcrowd-ready markdown document. |
|
sarif
Package sarif renders findings as SARIF 2.1.0 so a huntx run drops straight into GitHub code scanning or any CI that speaks SARIF.
|
Package sarif renders findings as SARIF 2.1.0 so a huntx run drops straight into GitHub code scanning or any CI that speaks SARIF. |
|
scope
Package scope is the safety core: every outbound target is checked here before any request leaves the tool.
|
Package scope is the safety core: every outbound target is checked here before any request leaves the tool. |
|
secrets
Package secrets flags high-confidence credentials leaked in a response or JS bundle.
|
Package secrets flags high-confidence credentials leaked in a response or JS bundle. |
|
session
Package session loads the identities used for access-control testing: each named role carries the headers (auth token, cookie) that authenticate it.
|
Package session loads the identities used for access-control testing: each named role carries the headers (auth token, cookie) that authenticate it. |
|
sqli
Package sqli detects error-based SQL injection: it sends a quote into each parameter and looks for a database error message that was not in the baseline response.
|
Package sqli detects error-based SQL injection: it sends a quote into each parameter and looks for a database error message that was not in the baseline response. |
|
ssrf
Package ssrf detects server-side request forgery out-of-band: it places a unique collaborator URL into URL-shaped parameters and, after a grace period, checks whether the target's server called back.
|
Package ssrf detects server-side request forgery out-of-band: it places a unique collaborator URL into URL-shaped parameters and, after a grace period, checks whether the target's server called back. |
|
ssti
Package ssti detects server-side template injection: it sends a marked arithmetic expression in each parameter and looks for the evaluated result in the response.
|
Package ssti detects server-side template injection: it sends a marked arithmetic expression in each parameter and looks for the evaluated result in the response. |
|
template
Package template runs nuclei-compatible detection templates.
|
Package template runs nuclei-compatible detection templates. |
|
verify
Package verify is the deterministic second tier: a finding is only trusted once re-confirmed without a language model in the loop.
|
Package verify is the deterministic second tier: a finding is only trusted once re-confirmed without a language model in the loop. |
Click to show internal directories.
Click to hide internal directories.