ScopeGuard MCP

ScopeGuard is a policy-first defensive security operations server for MCP. It gives AI clients useful repository and web-security analysis while keeping authorization, execution, target scope, and auditability under operator control.

It is designed as a safer, maintainable alternative to broad shell-driven pentest orchestrators. “Better” here means stronger trust boundaries and engineering quality—not more autonomous exploitation.

The comparison below uses the public HexStrike AI v6 repository as the reference baseline. ScopeGuard is built on the official MCP Python SDK 2.x.

Why ScopeGuard

ScopeGuard does not include exploit generation, password attacks, payload generation, credential capture, or autonomous attack-chain execution.

Related MCP server: Symbiotic MCP Server

Included tools

• health — safety posture, supported capabilities, and audit-chain status

• create_dry_run_engagement — create an expiring, non-executing scope from MCP

• revoke_engagement — stop an engagement immediately

• check_scope — normalize and evaluate a URL, domain, IP/CIDR, or file target

• plan_assessment — produce a bounded web or repository baseline plan

• analyze_headers — inspect caller-supplied HTTP headers without making a request

• scan_repository — read-only built-in Python risk and secret checks

• list_audit_events and verify_audit_chain — inspect and verify evidence

Quick start

Python 3.11 or newer is required.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

scopeguard doctor
scopeguard-mcp

Configure an MCP client to launch the local stdio server:

{
  "mcpServers": {
    "scopeguard": {
      "command": "/absolute/path/to/scopeguard-mcp/.venv/bin/scopeguard-mcp",
      "env": {
        "SCOPEGUARD_STATE_DIR": "/absolute/path/to/scopeguard-state"
      }
    }
  }
}

Authorization workflow

MCP clients can create only dry-run engagements. They can check scope, build plans, and perform offline header analysis, but repository execution remains planned.

For a real read-only repository scan, the operator must create an execute engagement outside the model and launch the server with execution enabled:

export SCOPEGUARD_STATE_DIR=/absolute/path/to/scopeguard-state
export SCOPEGUARD_ALLOWED_ROOTS=/absolute/path/to/authorized-repositories
export SCOPEGUARD_EXECUTION_ENABLED=true

scopeguard create-engagement \
  --title "Repository security baseline" \
  --ticket SEC-1234 \
  --target file:/absolute/path/to/authorized-repositories/example \
  --capability scan:repository \
  --capability audit:read \
  --mode execute \
  --expires-in-minutes 60

scopeguard-mcp

The returned engagement ID is required by scan_repository. Both the engagement file scope and SCOPEGUARD_ALLOWED_ROOTS must contain the requested path. Symlinks are resolved before either policy is evaluated.

Capabilities

Configuration

The MCP server intentionally exposes only stdio. A future network transport must ship with standards-based authentication, request-size limits, and explicit deployment guidance; binding an unauthenticated security service to a port is not accepted here.

Repository analyzer

The dependency-free analyzer currently detects:

• Python eval / exec

• os.system / os.popen

• subprocess calls with shell=True

• unsafe Pickle deserialization

• yaml.load without a safe loader

• private-key blocks, AWS access keys, GitHub tokens, and likely hard-coded secrets

Secret values are never returned. Findings contain only rule metadata, location, and a short one-way fingerprint for correlation.

Development

pip install -e ".[dev]"
ruff check .
pytest
python -m build

The test suite includes a real in-memory MCP v2 discovery and tool-call round trip.

See ARCHITECTURE.md, SECURITY.md, and CONTRIBUTING.md for design and project policy.

Responsible use

Use ScopeGuard only on repositories and systems you own or are explicitly authorized to assess. The project is defensive tooling, not authorization to test a target.