mcpnuke: Instructions file for Codex

AGENTS.md — Guidance for AI Coding Agents

Read this before making any change to mcpnuke. It is the product truth for how this repo is built, tested, and kept safe.

What this is

mcpnuke is an MCP red teaming and security scanner. Python 3.11+, package manager uv. It actively probes MCP servers, so all code and docs must assume authorized-use context — never add exploit PoCs, live credentials, or real target data to the repo.

Setup and verification

uv sync --all-extras          # install everything including dev
uv run pytest tests/ -v       # full suite must pass: 1040+ passed, 0 failed
uv run ruff check .           # must be zero
uv run mypy mcpnuke/          # must stay at or below the CI ceiling

CI gates all four on every push and PR. mcpnuke/core/ additionally enforces disallow_untyped_defs. If you edit pyproject.toml, run uv lock and commit uv.lock — CI checks they are in sync.

Code conventions

• Strong typing throughout: dict, list, frozenset, int, str hints on all functions. No Any to silence the checker.
• Module-level constants: UPPER_SNAKE_CASE, typed explicitly.
• Check signatures: check_name(result: TargetResult) for static checks; check_name(session: MCPSessionProtocol, result: TargetResult, probe_opts: dict | None = None) for behavioral checks.
• Every check body wrapped in with time_check("check_name", result):.
• Findings via result.add(check_name, severity, title, detail, evidence=...). Severities: CRITICAL, HIGH, MEDIUM, LOW.
• Credential regexes live in mcpnuke/patterns/credentials.py only, in the tier matching their false-positive risk — never in rules.py, probes.py, or a check module.

Adding a check

1. Write the failing test first: tests/test_<check_name>.py with at least positive detection, clean/negative, and timing-recorded cases. Use the conftest.py fixtures (result_with_tools([{...}])).
2. Implement the check in mcpnuke/checks/<name>.py.
3. Wire it into run_all_checks in mcpnuke/checks/__init__.py.
4. Document it in docs/checks.md and update the check totals in README.md / docs/checks.md — tests assert they match the registry.
5. Add a CHANGELOG.md entry.