mcp-recon

An MCP server that gives an AI agent reconnaissance tools, and enforces the authorization scope in the server rather than in the prompt.

This is for targets you own or have written permission to test. A bug bounty programme with a published scope, a signed penetration testing engagement, your own infrastructure. Nothing else.

The scope.yaml file is the technical translation of that permission, and the server will not start without one. There is no unrestricted mode and no flag to switch the scope engine off.

Three refusals for three different reasons — an explicit deny rule, a name that is not in the allowlist, and a name that is in the allowlist but resolves to the cloud metadata service. The agent is told the same sentence every time; the audit log is where the reason lives. Reproduce it with demo/record.sh --play.

The problem

Give a language model an HTTP client and a system prompt saying "only test *.example.com" and it will mostly comply. "Mostly" is the problem: the prompt is a request, not a constraint, and there are three ordinary ways it stops being honoured.

• The agent reasons its way out. It finds internal-example.com in a certificate, decides that is obviously the same company, and checks it. Nothing malicious happened; it was being helpful.

• Something it reads tells it to. The agent fetches a page and the page contains text addressed to the agent. That is prompt injection, and its defining feature is that the attacker's text arrives through the same channel as your instructions, with no marker distinguishing them.

• A name resolves somewhere else. api.example.com is genuinely in scope. It resolves to 169.254.169.254. The agent did everything right and just read the cloud metadata service.

The third case is the interesting one, because no amount of prompt engineering addresses it. The agent cannot check what a hostname resolves to; it can only ask the tool, and by then the request has been made.

So the scope does not live in the prompt. It lives in the execution path, as a type:

# exec/http.py — this is the only way in
async def fetch(self, target: AuthorizedTarget, *, path: str) -> HttpFetchResult:

There is no overload taking a string, and nothing but the scope engine can produce an AuthorizedTarget. A tool that forgot to check the scope does not fail review — it fails to typecheck. tests/test_architecture.py parses the AST of every module under tools/ to confirm that none of them imports an executor, a socket library, or the one function that can mint that type.

An out-of-scope request is not discouraged; there is no way to express one. That is also what makes the injection case survivable: a page can say whatever it likes to the agent, and the worst outcome is that the agent tries something, the server refuses, and the refusal is logged.

Related MCP server: AynOps

The five layers

 MCP client (the agent)
        │  tool call with arguments
        ▼
┌─────────────────────────────────────────────────────────────┐
│ [1] Schema validation      Pydantic v2: types, formats,     │
│                            ranges, allowed header names     │
├─────────────────────────────────────────────────────────────┤
│ [2] Scope engine           deny → allow → default-deny →    │
│                            resolve → validate EVERY address │
│                            → pin      ◀── NOT NEGOTIABLE    │
├─────────────────────────────────────────────────────────────┤
│ [3] Budget & limits        token bucket per host, session   │
│                            quota, concurrency, timeouts     │
├─────────────────────────────────────────────────────────────┤
│ [4] Executor               the real operation, against the  │
│                            pinned address, size-capped      │
├─────────────────────────────────────────────────────────────┤
│ [5] Audit                  append-only JSONL: what was      │
│                            attempted, allowed, and refused  │
└─────────────────────────────────────────────────────────────┘

Layer 2 is the one that matters, and the order inside it is the design:

1. Is the scope still valid? expires is mandatory, and past that date everything is denied.

2. Canonicalise. 2130706433, 0x7f000001, 127.1, ::ffff:127.0.0.1 and [2002:7f00:1::] are all 127.0.0.1. EXAMPLE.com., example%2ecom and example。com are all example.com. A Cyrillic lookalike is not. Anything genuinely ambiguous — userinfo before the host, a backslash, a stray percent sign — is refused rather than guessed at.

3. Deny beats allow. Always, regardless of order or specificity.

4. Default deny. No allow rule, no access. Not being in the deny list is not a reason.

5. Resolve, then validate the address on its own merits. Loopback, link-local, cloud metadata, RFC 1918, CGNAT, multicast and reserved ranges are refused even when the name pointing at them is in your allowlist.

6. Pin the address. The executor connects to the IP the engine validated, with the real hostname in the Host header and in TLS SNI. Nothing re-resolves between the check and the connection, so DNS rebinding has no window to happen in, and TLS still validates against the hostname.

7. Every redirect hop repeats all of the above. Location: http://169.254.169.254/ from a host that is genuinely in scope is the cheapest SSRF there is. The chain stops at the first refusal.

What it will not do

The interesting part of a security tool is the list of things it was capable of and did not ship. In rough order of how often it comes up:

Installation

Requires Python 3.11 or later.

git clone https://github.com/dotMuny/mcp-recon && cd mcp-recon
uv sync
uv run mcp-recon --scope ./scope.yaml --check

To get a mcp-recon on your PATH — which is what an MCP client needs, since it launches the server from an unpredictable working directory:

uv tool install .

A container image is also defined; see Dockerfile for the mount layout, which keeps the scope file outside the image on purpose.

The scope file

scope:
  name: "example-program"
  authorized_by: "https://example.com/.well-known/security.txt -- public bug bounty, retrieved 2026-09-01"
  expires: "2027-12-31"

  allow:
    domains:
      - "example.com"          # the apex, and only the apex
      - "*.example.com"        # any subdomain at any depth, NOT the apex
    ips:
      - "203.0.113.0/24"

  deny:
    domains:
      - "admin.example.com"

  limits:
    requests_per_minute_per_host: 30
    total_requests_per_session: 1000

Full key reference, wildcard semantics and the limits you can set: docs/tools.md. Start from scope.example.yaml, and check it before you use it:

mcp-recon --scope ./scope.yaml --check

Connecting a client

claude_desktop_config.json, or claude mcp add:

{
  "mcpServers": {
    "recon": {
      "command": "mcp-recon",
      "args": [
        "--scope", "/absolute/path/to/scope.yaml",
        "--audit-log", "/absolute/path/to/audit/session.jsonl"
      ]
    }
  }
}

Both paths must be absolute. Any other stdio MCP client works the same way: diagnostics go to stderr, and stdout carries the MCP wire protocol and nothing else.

There is also a Streamable HTTP transport, which binds to loopback and requires a bearer token:

MCP_RECON_AUTH_TOKEN=$(openssl rand -hex 32) \
  mcp-recon --scope ./scope.yaml --transport http --port 8931

Think carefully before exposing that to a network. Anyone who reaches the port can run reconnaissance against your authorized targets, spend your budget, and put your source address on the traffic. Put it behind TLS and a reverse proxy that authenticates properly, or keep it on stdio.

The tools

Ten, plus two free introspection calls — get_scope and get_budget. Four passive tools that never contact the target (DNS, WHOIS, certificate transparency, TLS certificate), three active ones that make exactly one request each (http_fetch, http_headers_audit, check_ports), and three local decoders that cost nothing (analyze_jwt, decode_payload, parse_url).

Every description states what the tool does, what it does not do, and what it costs against the budget. Full table, costs, resources and prompts: docs/tools.md.

Tool output is data, not instructions

Everything a tool returns comes from outside — page bodies, DNS TXT records, certificate subjects, WHOIS text — and any of it can contain text addressed to the agent. The results carry a warning saying so, but the answer is structural rather than textual: the scope is enforced in this process, below the layer the agent operates at. An injected instruction can persuade the agent to try something; it cannot make the attempt succeed.

Development

uv sync
uv run pytest            # 409 tests, no network access required
uv run mypy --strict src
uv run ruff check

The whole suite runs offline. Every network call is mocked at the transport with respx or injected behind a protocol, and the handful of tests that open real sockets bind them on loopback. If a test ever reaches the internet, that is a bug — and you can prove it has not:

unshare -rn sh -c 'ip link set lo up; .venv/bin/python -m pytest'

409 passed, with no network interface but loopback.

Worth reading if you are here for the interesting parts:

• tests/data/bypass_cases.yaml — 90 scope-evasion attempts, each with the expected verdict and a note on why. Adding a case is one YAML block.

• tests/test_scope_props.py — Hypothesis generating hostnames and addresses against absolute invariants. "Almost never approves a loopback address" is not a security property.

• tests/test_architecture.py — the import rules, checked by reading the AST.

• src/mcp_recon/scope/normalize.py — every known allowlist bypass is a representation bug, and they all live here.

Documentation

• docs/threat-model.md — what the design protects against, and the six things it does not.

• docs/decisions.md — the design decisions with a real alternative, and what was given up.

• docs/tools.md — scope file reference, tool costs, budget behaviour, audit record format.

• SECURITY.md — how to report a scope bypass, and what counts as one.

Licence

Apache-2.0. See LICENSE.