appsec-toolbox-mcp

Let an AI agent audit code you do not trust, without giving it a shell, a path to choose, or the repository's code to run.

Ten pinned security scanners behind eight parameterless MCP tools, in one hardened container. The audited repository is treated as the attacker. The agent only ever collects evidence.

Recorded from examples/agent_demo.py against examples/vulnerable-sample. Waiting time is shortened; the real scan time is in the last line.

In 30 seconds

• What it is. Semgrep, Gitleaks, OSV-Scanner, Trivy, Checkov, Syft, and language specialists (Bandit, FindSecBugs, njsscan, gosec) exposed to any MCP client as fixed capabilities: security.sast, security.secrets, security.dependencies, and so on.

• The threat model. The repository under audit is hostile: it controls every file the scanners parse and every string the agent reads back. So the agent gets nothing to steer: no arguments, no target path, no shell, no way to run the repository's build or code.

• What you get. Native scanner reports, a run manifest that ties each report's SHA-256 to a recomputable fingerprint of the scanned tree, and an audit log of every tool call.

Related MCP server: agent-sec-mcp

Engineering highlights

Each claim links to the code or test that proves it.

Verification in layers. Unit tests cover the scripts. A smoke test drives the Makefile through Makefile MCP with fake scanners whose stubs fail if any hardening flag is missing. The image test runs the real scanners against a known-vulnerable sample, a hostile sample that tries every attack above, and offline mode, under the documented resource limits. Independent adversarial reviews attacked the image; every confirmed finding was fixed with a regression test, and what remains is written down in the threat model.

Quick start

IMAGE=ghcr.io/ai-ronin-systems/appsec-toolbox-mcp:0.3.0
docker pull "$IMAGE"
gh attestation verify "oci://$IMAGE" --owner ai-ronin-systems

Offline mode, the resource limits, and the target-settings hardening are on main and ship in the next release. To use them now: docker build -t appsec-toolbox-mcp:dev . and IMAGE=appsec-toolbox-mcp:dev.

Run it as an MCP stdio server against one repository:

docker run --rm -i \
  --read-only --cap-drop=ALL --security-opt=no-new-privileges:true \
  --tmpfs /tmp:rw,nosuid,nodev,size=3g --memory=6g --pids-limit=512 \
  --user "$(id -u):$(id -g)" \
  -v "$PWD/my-project:/runner/target:ro" \
  -v "$PWD/appsec-output:/runner/output:rw" \
  "$IMAGE"

Register the same command as a stdio server in any MCP client:

{
  "mcpServers": {
    "appsec-toolbox": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--read-only", "--cap-drop=ALL",
               "--security-opt=no-new-privileges:true",
               "--tmpfs", "/tmp:rw,nosuid,nodev,size=3g", "--memory=6g", "--pids-limit=512",
               "-v", "/abs/path/my-project:/runner/target:ro",
               "-v", "/abs/path/appsec-output:/runner/output:rw",
               "ghcr.io/ai-ronin-systems/appsec-toolbox-mcp:0.3.0"]
    }
  }
}

Compose, offline mode, language selection, and every evidence file are in Usage.

How it works

untrusted repository (read-only)
          |
          v
   /runner/target
          |
          v
 trusted Makefile + Makefile MCP
    |       |       |       |       |       |
 Semgrep Gitleaks   OSV    Trivy  Checkov   Syft
          |
          +---- language profile selection ----+
                 |       |        |        |
               Bandit FindSecBugs njsscan  gosec
               Python    Java     Node/JS   Go
          |
          v
    /runner/output   reports, run-manifest.json, suppressions.json, audit log

The operator mounts exactly one repository at /runner/target and one writable directory at /runner/output. The audited path is never an MCP parameter, so the agent has no host-path capability. A trusted Makefile holds every scanner command; Makefile MCP decides which of its targets the agent may call. Language specialists are picked by detection (APPSEC_LANGS=auto) or by the operator, never by the agent.

Threat model

The audited repository is the attacker, and the agent reading its reports may be steered by it. Read the threat model: attacker goals, sixteen threats with their controls and residual risks, what is and is not guaranteed, and an operator checklist.

Design choices

• Evidence, not verdicts. Reports stay in each scanner's native format. The toolbox never grades, deduplicates, or normalizes findings; a consumer does that with the full evidence.

• One closed set of scanners. Four language profiles, no plug-in framework, no user-defined pipelines. Generic SCA stays with OSV and Trivy; specialists add a different analysis engine, not a duplicate one.

• Coverage gaps are recorded, never papered over. A source-only Java project gets no FindSecBugs pass, because the toolbox will not compile untrusted code; the manifest says so.

• Everything pinned. Scanner versions are pinned and updated one at a time against known-positive and hostile fixtures (update policy).

It is not an autonomous auditor, an LLM agent, a DAST engine, a credential manager, a report normalizer, or a shell server.

Part of a larger system

appsec-audit-hound (planned)    decides why to scan, correlates evidence, writes findings
        | MCP
appsec-toolbox-mcp              collects governed, passive evidence   <- this repository
        | built on
makefile-mcp                    exposes trusted Make targets to agents, deny-by-default

Makefile MCP is published on PyPI and the official MCP Registry, with its own threat model.

Documentation

Development

pipx install pytest==8.4.2 && pipx install ruff==0.14.0
make test         # ruff, unit tests, smoke test
make image
make test-image   # the real image: known positives, hostile sample, offline mode

More in Usage.

License

Apache-2.0.