Cast a net over the web. Give NetCast3r one authorised public-facing asset, connect your model providers, and it maps the attack surface, hunts with a modern web and app coverage checklist, verifies proof before promotion, and continues through post-exploitation when a foothold appears — while you spectate and instruct mid-hunt. Secret hunting (310 patterns, 135 recipes) remains part of the deterministic path.
Install | Usage | Outputs | Docs | Security | Contributing
Detection is only the first step. A pattern match says that something looks like a key; NetCast3r asks the provider whether it is alive, records what that key can reach, and escalates when write access is enabled. Every finding leaves the pipeline with evidence, reproduction steps, and the value already redacted, so the report can go straight into a program.
Contents
- Seed one authorised URL or host; lock scope; connect brain providers
- Map the external surface (CT, passive DNS, resolve, HTTP/TLS, tech/WAF)
- Hunt with the coverage checklist, swarm roles, and secret/credential paths
- Prove candidates with a replayable PoC before promotion
- Pivot into post-ex objectives (lateral, cloud, identity) after a foothold
- Spectate brain and agent activity live; instruct mid-hunt without restart
- Continue until you pause — stalls deepen (new angles, knowledge feeds), never auto-stop
- Report continuously with redacted Markdown and PDF companions
The crawler maps the target's subdomains from certificate transparency and DNS first, then walks each host and collects the JavaScript inside scope, and finally pulls historical bundles from the Wayback Machine. The exegete reads each file and maps its logic. The prospector hunts credentials across 310 patterns. The classifier names any candidate the patterns did not recognise, rates its confidence, and remembers the answer for later runs. The assayer validates every candidate against its provider with read-only recipes. The chainer maps the escalation, the sentinel scores and de-duplicates, and the report is written with the values redacted. If no provider answers, the deterministic path still produces a report.
See docs/architecture.md.
Every candidate leaves the pipeline with one of four states: CONFIRMED carries live proof and is ready to submit, CORROBORATED means a second source agrees, INFERRED is a pattern match with no live check behind it, and UNRESOLVED has no verdict yet. Values are masked before the report is written.
The pattern catalog is built from the gitleaks rule set and the validation recipes follow the keyhacks endpoints. Every candidate is scored for confidence using its pattern, its entropy, its length, and the surrounding code. Unknown values are handed to the classifier agent, which names the service and can re-type the candidate so the right recipe runs. A route that omits the model still works: detection and validation never depend on a model.
See docs/architecture.md.
310 patterns cover cloud, storage, payments, messaging, CI, and model
credentials, and each candidate can be put to 135 read-only recipes across 121
providers. Every check is read-only by default, --tier write opts in to the
ones that change state. A report is written either way, with no provider key
required.
Recon collects, the exegete reads, the prospector ranks, the assayer puts each
candidate to its provider, and scribe writes the report and the dashboard.
With --dashboard the same run is mirrored live into the browser.
| File | What it is |
|---|---|
report.md |
the submission-ready report: impact, proof, reproduction, remediation |
results.json |
summary and findings, for scripts |
results.jsonl |
one finding per line, for streaming into other tools |
results.sarif |
SARIF 2.1.0, upload it to GitHub code scanning |
dashboard.html |
the self-contained dashboard, plus dashboard.json beside it |
--html writes a self-contained dashboard next to the report. The file
carries its own artwork and styles, so it opens in any browser, attaches to
an email, or sits in a repository without a build step.
netcast3r dashboard --results results open the run you just finished
netcast3r dashboard --demo --out dashboard.html write the sample run and exitThe console uses the same palette and the same state names, so a run reads the same in the terminal and in the browser. See docs/DESIGN.md.
Python 3.10 or newer.
pipx install git+https://github.com/DeathShotXD/NetCast3r.git
netcast3r --versionnetcast3r recon --input target.com --scope scope.txt --out-of-scope oos.txt
netcast3r run --input target.com --scope scope.txt --out-of-scope oos.txt --html
netcast3r run --input target.com --scope scope.txt --json --jsonl --sarif
netcast3r providers--depth, --rate, --delay, --timeout, and --retries tune the crawl.
Subdomain mapping runs by default for a domain target; pass --no-subdomains
to stay on the host you named.
--tier selects the action tier, --resume reuses earlier validations, and
--fail exits non-zero when findings exist.
NetCast3r exposes its real workspace over MCP to OpenCode and any other MCP client, and it drives itself without one:
netcast3r ui --no-open # the director starts with the control plane
netcast3r mcp --print-config # optional: paste into opencode.jsonc
opencode mcp listThe server has 307 typed tools with risk tiers, scope enforcement, single-use
approvals, rate limits, and a full tool-call audit, plus disposable inboxes,
OAST callbacks, named auth profiles, a scoped authenticated http_request, a
path-variant differential, run-to-run surface diffing, local reverse-engineering
analyzers for source, APKs, contracts, and binaries, allowlisted passive recon tools
and precise test cases, a Burp MCP bridge, an outbound MCP registry for HTTP and stdio
servers, a locked-down Docker sandbox, credential pivoting, threat-intel search
with CVE/PoC reproduction plans, STIX 2.1 export and TAXII 2.1 polling,
report-quality scoring and payout ROI, a persistent lesson/skill memory with a
per-technology expertise profile that the agent recalls before planning,
self-audit and diagnostics, and a bounded mission agent (agent_start) that
plans, probes, inventories, and verifies inside the mission's scope. See
docs/MCP.md.
It is its own harness. A Prime planner ranks every scoped mission from real
signals, and a durable director wakes on a ten-second tick, runs one scoped
pass at a time through the hunt, the operator, or the five-role mesh, watches it
to completion, and records whether the mission moved. An active mission set
to autonomous is the authorization: its in-scope chain runs without a
per-call approval step-up, audited as authorized:autonomous. Scope is still
enforced, approval decisions stay human-only, and it never fabricates findings:
findings_create records only what an operator or agent validated, every
bounty result still comes from verified runs, and the director never submits a
report. The command center has a Director strip with Engage, Pause, and Kill.
See docs/DIRECTOR.md.
A main brain loop runs beside the director: every 150 seconds it reads the whole plane - missions, campaign stage, live traffic, the log feed, the graph, the host, and the MCP connections - decides the highest-value next move, and steers. It cannot pause the hunt, create a finding, or submit a report. Talk to it from the brain dock on any screen or the Main brain panel in the command center; pause it with one click. See docs/BRAIN.md.
| Code | Meaning |
|---|---|
0 |
the command finished |
1 |
no input given, no command given, or --fail found something |
2 |
the arguments could not be parsed |
Both scope files take one entry per line. Blank lines and lines starting with
# are ignored. The out-of-scope file wins over the in-scope file.
example.com the host and all of its subdomains
*.example.com subdomains only
https://example.com/p scheme and path prefix
10.0.0.0/24 an IPv4 network
re:^api\. a regular expression against the host
The lab proves the pipeline with no provider key and nothing real:
bash lab/run_lab.sh
netcast3r run --input http://127.0.0.1:8099/ --out results \
--patterns lab/patterns.toml --recipes lab/recipes.tomlSee lab/README.md.
NetCast3r talks to any OpenAI-compatible endpoint. NVIDIA Nemotron reasoning
models are configured first by default, followed by OpenRouter, Ollama, and
OpenCode Zen. Run netcast3r providers to see what is configured. The
classifier is optional: detection and validation work without it.
The NVIDIA pool uses nemotron-3-ultra-550b-a55b for the strongest reasoning
pass, with nemotron-3.5-lightning-30b-a3b and the nano omni model as fast
fallbacks. Keys stay out of the config file: paste one in the dashboard, set
NETCAST3R_NVIDIA_KEY, or point api_key_file at a 0600 file. On a rate limit
the bus still rotates to the next provider, and a second provider is still
required before a candidate is marked corroborated.
- Architecture - stages, scope, tiers, and the fallback path
- MCP control plane - tools, policies, approvals, and OpenCode setup
- Director - the autonomous supervisor, Prime, and the kill switch
- Evidence graph - nodes, provenance, candidate paths, and verification
- Memory - the shared knowledge base, campaign stages, and the profile
- Exploits - the typed exploit module catalog and how it plans
- Capabilities - the external tool broker, API-spec ingestion, program briefs, and PoCs
- Web2root - single-seed surface map through foothold and report
- File-read chains - LFI to source disclosure, auth bypass, and the approval boundary
- Brain - main brain loop, spectate, and mid-hunt instruct
- Leads and evidence - how to inspect a hypothesis, its tool calls, and its verdict
- Evidence verdicts - supported, proven, redirect-only, and edge-blocked, and what each proves
- Regression bench - the offline corpus, precision/recall, and the release gate
- Host - the shell and filesystem, and the rules that gate them
- Main brain - the top-level reasoner and how to steer it
- Coverage - the 103-item modern checklist the hunt closes
- Self-evolution - the outcome ledger, proposals, and post-ex planning
- Design - palette, type, and the validation ladder
- Contributing - the ground rules for a pull request
- Security policy - how to report a problem in NetCast3r
- Changelog - what changed in each version
NetCast3r is built for authorized testing only. Run it against systems you own or have explicit written permission to assess.
MIT. See LICENSE.