# angr-mcp MCP Server This project implements a Model Context Protocol (MCP) server that exposes core angr binary-analysis capabilities—loading binaries, constructing symbolic states, steering execution, and harvesting exploit artifacts—through a set of tool handlers. The initial focus is rapid vulnerability exploration: analysts can load a target, make its inputs symbolic, drive execution toward interesting addresses, and extract concrete witness inputs once a path of interest is found. ## Current Components - `angr_mcp/registry.py` – In-memory registry tracking angr projects, states, simulation managers, hooks, cached analyses, alert logs, and persisted job metadata. - `angr_mcp/server.py` – The MCP server entry point. It implements handlers for project loading, symbolic-state creation, environment instrumentation (hooks and SimProcedures), symbolic execution, breakpoint-style monitoring, state inspection, structured alert reporting, job persistence/management, constraint solving, CFG recovery, and backward slicing. It also integrates community exploration techniques shipped in `awesome-angr/ExplorationTechniques`. - `angr_mcp/utils/` – Binary-inspection and state-mutation helpers shared by the MCP handlers and tests (section scanners, literal cross-referencing, register/stack mutation primitives, and symbolic-handle registration). - `tests/test_mcp_server.py` – Integration tests that compile a small C binary and exercise the server end-to-end (load project, set symbolic stdin, run a targeted search, solve constraints, capture monitored events, and perform CFG/slice queries). - `tests/test_phase1_ctf.py` – Phase 1 regression suite recreating angr CTF levels 00–04 exclusively through MCP handlers, asserting predicate metadata, register/stack mutation APIs, and native replay of recovered inputs. - `tests/test_deep_call_partition.py` – Deep-call regression that builds a branching binary, extracts call chains, enforces state-budget guards, and demonstrates chunked symbolic execution reaching a buried target function. - `tests/test_taint_analysis.py` – Format-string taint regression that exercises pointer-aware taint sources and verifies sinks triggered through the new taint-analysis MCP handler. - `pyproject.toml` – Minimal configuration enabling `uv` to manage a local virtual environment. - `schemas/` – JSON Schema Draft 2020-12 definitions for every MCP handler request/response pair plus shared structures (alerts, jobs, UUIDs). ## Environment Setup 1. Create and activate the virtual environment with `uv`: ```bash UV_CACHE_DIR=.uv-cache uv venv .venv source .venv/bin/activate ``` 2. Install dependencies into the environment (angr and claripy are pulled from PyPI): ```bash UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python claripy angr ``` 3. Run the integration tests: ```bash .venv/bin/python -m unittest discover tests ``` The Phase 1 tests exercise 32-bit angr CTF binaries. If your host lacks 32-bit runtime libraries (`/lib/ld-linux.so.2`), the suite will skip the native replay assertions automatically. ## Usage Overview Instantiate `AngrMCPServer` and call the handlers programmatically or via your MCP transport: 1. `load_project` – load the binary and receive a `project_id`. 2. `setup_symbolic_context` – create entry/call/blank/full-init states with optional symbolic stdin/memory/registers (state IDs are tracked in the registry). 3. `instrument_environment` – install SimProcedures or custom hooks on addresses/symbols before execution. 4. `run_symbolic_search` – step or explore states, optionally attaching exploration techniques for coverage, loop exhaustion, etc. The handler returns new state IDs per stash, emits structured alert records, and registers/updates a job handle that can be resumed later. Use the optional `state_budget` parameter to detect and short-circuit state explosion; the run metadata reports the per-stash counts so clients can adapt chunk sizes. 5. `run_taint_analysis` – drive the vendored taint engine against a recorded state. Define taint *sources* (memory/register or pointer-aware monitors), specify *sinks* at target basic-block addresses, and receive structured hit records plus state snapshots whenever taint reaches the sink. 6. `monitor_for_vulns` – register inspection breakpoints (e.g., `mem_write`) so exploit-relevant actions are recorded (alerts accumulate alongside raw event logs). 7. `inspect_state` – fetch registers, memory, constraint sets, recorded events, and generated alerts for any stored state. 8. `solve_constraints` – query Claripy for concrete inputs/ranges from the current constraints. 9. `list_jobs`, `resume_job`, and `delete_job` – manage persisted simulation jobs (list metadata, hydrate back into memory, or remove from registry/disk). 10. `analyze_call_chain` – compute call-graph paths between functions so deep targets can be decomposed into manageable exploration stages. 11. `trace_dataflow` – run backward slices (optionally with DDG/CDG) to expose dependencies that matter for a chosen target. ## Current Status (October 29, 2025) - Core MCP plumbing is in place with registry-backed state tracking and resilient execution (errors are captured and returned to clients). - Structured alerting now highlights unconstrained instruction-pointer states and suspicious memory writes, returning normalized JSON objects alongside run results and state inspection payloads. - `setup_symbolic_context` and the new `mutate_state` handler support option presets, register copying/injection, stack adjustments, and symbolic handle tracking for later constraint solving. - Predicate descriptors (`address`, `stdout_contains`, `stdout_not_contains`) now drive `run_symbolic_search`, and predicate matches are recorded in the run payload alongside base64-encoded stdin/stdout streams. - `analyze_call_chain` recovers call-graph paths between functions (using the cached CFG) so deep targets can be chunked into controllable exploration segments. - `run_symbolic_search` accepts a `state_budget` cap and reports detailed state-pressure telemetry when the limit is approached or exceeded, allowing front-ends to shrink their search windows before the solver explodes. - The new `run_taint_analysis` handler wraps the angr taint engine with pointer-aware taint sources and sink-level taint checks, returning structured hit metadata and fresh state snapshots for downstream analysis. - Helper utilities in `angr_mcp/utils/` expose section scanners and literal cross-references used to automate angr CTF level analysis. - Jobs created via `run_symbolic_search` can be resumed, enumerated, and persisted to `.mcp_jobs/.json`; persisted jobs can be rehydrated across processes through `resume_job`. - JSON Schemas in `schemas/` describe every handler request/response, enabling downstream clients (e.g., GhidraMCP) to validate payloads. - Basic exploration techniques from the `awesome-angr` bundle remain dynamically loadable. - Symbolic stdin setup initializes the default `SimPacketsStream` content in-place to avoid compat issues with angr’s POSIX plugin. - Integration tests validate the exploit-oriented workflow end to end (requires installing `claripy` and `angr` via `uv pip`). Supplementary Phase 1 CTF tests assert deterministic solutions for levels 00–04 in `tests/test_phase1_ctf.py`. The deep-call regression (`tests/test_deep_call_partition.py`) stresses the call-chain handler, state-budget feedback, and chunked symbolic execution needed for very deep targets. The new taint regression (`tests/test_taint_analysis.py`) proves that taint from symbolic stdin can be tracked into a vulnerable `printf` call. ## Phase 1 angr_ctf Coverage Highlights - Level 00/01: `.rodata` token extraction and literal cross-referencing feed predicate descriptors that prove the concrete solution and ensure avoid sites remain untouched. - Level 02: Pure stdout-based predicates demonstrate predicate logging, metadata persistence, and streamed stdout capture for repro. - Level 03: Blank-state creation, symbolic register injection, and solver handle queries recover integer tuples that replay natively. - Level 04: Stack alignment helpers and symbolic push operations mirror the native stack frame without triggering alert detectors, validating stack integrity through the handler pipeline. ## Planned Next Steps - Extend alert coverage to include additional exploit heuristics (e.g., unconstrained stack pivots, self-modifying code) and configurable thresholds. - Add background job execution and progress polling so long-running searches can continue asynchronously while clients poll via job metadata. - Generate JSON Schemas directly from type annotations to avoid drift and integrate schema validation into the test suite when `jsonschema` is available. - Surface richer metadata (e.g., hook registry, cached analyses) through dedicated query endpoints to assist front-ends. ## Contributing Notes for Agents and Humans - Use `uv` for package management; keep the `.venv` environment in sync with `README` instructions. - Keep documentation (this file and `AGENTS.md`) updated with each change so future sessions understand the current context, constraints, and open items. - Prefer `apply_patch` for manual edits. Avoid destructive git commands unless explicitly approved.