Pathfinder

MCP server exposing offensive recon tooling to LLM agents — Claude Code, OpenCode, Codex, Hermes, any MCP client.

Pathfinder wraps the recon CLI tools security researchers already use (subfinder, httpx, nmap, ffuf, nuclei) into a single MCP server, so an LLM agent can plan and execute reconnaissance itself — not just tell you which commands to run.

Roadmap

• Phase 1 — passive subdomain enum, DNS, WAF detection, tech fingerprint, wayback discovery

• Phase 2 — active port scan, origin-bypass checks, nuclei templates

• Phase 3 — session state — the agent chains outputs across tools (scan_result tokens) instead of re-parsing raw text

• Phase 4 — HTML/JSON report export, target diffing (today vs. yesterday)

Related MCP server: Bug Bounty Assistant MCP

⚡ Quick start

One command, no clone, no venv (needs uv):

uvx --from "git+https://github.com/dewhush/pathfinder-mcp" pathfinder

Or the classic way:

git clone https://github.com/dewhush/pathfinder-mcp.git
cd pathfinder-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Requirements

Pathfinder wraps these CLIs. It degrades gracefully — a tool that can't find its binary reports MISSING_TOOL rather than crashing. Install the ones you want:

No external API keys required. Everything is local or free public APIs (CertSpotter, HackerTarget, AlienVault OTX, urlscan.io, Wayback).

🔌 Connect to your agent

Local Python:

claude mcp add pathfinder -- python -m pathfinder.server

uvx — no local Python, no clone:

claude mcp add pathfinder -- uvx --from "git+https://github.com/dewhush/pathfinder-mcp" pathfinder

Docker — no local Python needed:

# pull the release tarball and load it (no registry auth needed)
curl -L -o /tmp/pathfinder.tar.gz \
  https://github.com/dewhush/pathfinder-mcp/releases/download/v0.1.0/pathfinder.tar.gz
gunzip /tmp/pathfinder.tar.gz
docker load -i /tmp/pathfinder.tar
claude mcp add pathfinder -- docker run --rm -i ghcr.io/dewhush/pathfinder-mcp:0.1.0

hermes mcp add pathfinder --command "python -m pathfinder.server"

Add to your config:

{
  "mcpServers": {
    "pathfinder": {
      "command": "python",
      "args": ["-m", "pathfinder.server"]
    }
  }
}

Any MCP client (Docker, manual command): docker run --rm -i ghcr.io/dewhush/pathfinder-mcp:0.1.0

The Docker image bundles subfinder, httpx, nmap, ffuf and nuclei — the full toolset works with zero local installs. Local Python still needs those CLIs on PATH; anything missing degrades to MISSING_TOOL instead of crashing.

🧰 Tools

subdomain_enum(domain="example.com", source="all")     # or source="otx"
dns_resolve(host="example.com", record_type="A")
tech_detect(url="https://example.com")
wayback_discover(host="example.com", limit=500)

http_probe(hosts=["sub.example.com", "api.example.com"])
port_scan(host="example.com", top_ports=1000)
waf_detect(url="https://example.com")
origin_bypass_check(host="example.com")        # ORIGIN_EXPOSED / WAF_PROTECTED / UNKNOWN
endpoint_discover(url="https://example.com", wordlist="raft-small")
nuclei_scan(target="https://example.com", severity=["high", "critical"])
nuclei_scan(target="https://example.com", templates=["cves", "exposures"])

Origin bypass technique: docs/waf-origin-bypass.md. If a host reports ORIGIN_EXPOSED, the origin IP can be reached directly with a spoofed Host header:

curl -H "Host: example.com" https://<origin-ip>/

Built-in wordlists: raft-small (default), raft-medium, raft-big, common, seclists (expects /usr/share/seclists). Use wordlist="/abs/path" for a custom file.

🔗 Session chaining

Every tool returns structured JSON plus a scan_token. Pass it back into any other tool as from_token — Pathfinder resolves the token to the relevant hosts/URLs from the current session, so the agent chains steps without you re-typing targets:

flowchart LR
    A["subdomain_enum<br/>42 hosts"] -->|scan_token| B["http_probe<br/>7 live"]
    B -->|scan_token| C["waf_detect<br/>1 origin exposed"]
    C -->|"scan_token"| D["origin_bypass_check<br/>origin IP confirmed"]

Sessions are per-process and in-memory — nothing leaves the machine.

Development

pip install -e ".[dev]"
pytest                       # unit tests, no network, all tools mocked
ruff check src tests
ruff format src tests

License

MIT — 0xDew. Authorized use only.