ScopeGuard MCP

ScopeGuard is a policy-first defensive security server for MCP. It lets AI clients plan assessments, evaluate web security headers, and scan explicitly authorized local source trees without exposing a general shell, network scanner, exploit generator, or credential tool.

The project demonstrates senior security-engineering concerns beyond rule detection: authorization boundaries, canonical scope evaluation, dual execution gates, bounded resource use, evidence integrity, secure file access, durable audit history, threat modeling, supply-chain controls, and negative testing.

Security guarantees

• MCP clients can create only short-lived dry-run engagements.

• Execute engagements are created and revoked only through the local operator CLI.

• Every target operation requires an active engagement, an explicit capability, and a canonical target that matches scope.

• Repository scans require both an execute engagement and the operator-controlled SCOPEGUARD_EXECUTION_ENABLED gate.

• Production execution can require an HMAC-sealed audit checkpoint. A missing or invalid seal fails closed.

• File traversal is bounded by file count, file size, total bytes, and finding count.

• Repository files are opened as regular files without following symlink components on supported POSIX platforms, reducing path-race exposure.

• Secret matches are never returned. Correlation fingerprints use keyed HMAC rather than a guessable unsalted digest.

• Completed scans persist a manifest digest, ruleset digest, timestamps, outcome, and summary so evidence can be correlated with the audit chain.

• The server uses local stdio only. It does not expose an unauthenticated network port.

These controls do not prove that a ticket represents legal authorization. The operator is still responsible for validating permission and exporting signed audit heads to a separate trust domain.

Related MCP server: hachiman

Architecture

flowchart LR
    A["Untrusted MCP client"] --> B["Typed stdio tools"]
    O["Operator CLI + environment"] --> C["Policy engine"]
    B --> C
    C --> D["Canonical scope matcher"]
    C --> E["Capability + expiry gate"]
    C --> F["Dual execution gate"]
    F --> G["Bounded repository analyzer"]
    C --> H["Offline header analyzer"]
    C --> I[("SQLite engagements")]
    G --> J[("Durable scan evidence")]
    C --> K[("Hash-chained audit events")]
    K --> L["HMAC-sealed checkpoint"]

See ARCHITECTURE.md, the threat model, and the operations runbook for the detailed design.

MCP tools

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

Example MCP client configuration:

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

Authorized execution workflow

Generate and store a random audit key in your secret manager. Do not commit it or place it in shell history. Then configure a dedicated state directory and the smallest possible repository root:

export SCOPEGUARD_STATE_DIR=/absolute/path/to/scopeguard-state
export SCOPEGUARD_ALLOWED_ROOTS=/absolute/path/to/authorized-repositories
export SCOPEGUARD_EXECUTION_ENABLED=true
export SCOPEGUARD_REQUIRE_SEALED_AUDIT=true
export SCOPEGUARD_AUDIT_HMAC_KEY='value-loaded-from-your-secret-manager'
export SCOPEGUARD_AUDIT_KEY_ID='primary-2026'

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

Export the signed audit head after an assessment and anchor it in an append-only external system:

scopeguard verify-audit
scopeguard export-audit-checkpoint > scopeguard-audit-head.json

The checkpoint contains only the event count, chain head, key identifier, and HMAC signature. It never includes the signing key.

Capabilities

Configuration

Repository analysis

The dependency-free analyzer detects focused high-signal patterns:

• Python eval and exec

• os.system and 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

Results include a deterministic file-manifest SHA-256 and ruleset SHA-256. Secret values are excluded from results, audit events, and scan records. This scanner is a bounded baseline, not a replacement for CodeQL, Semgrep, Gitleaks, dependency auditing, or expert review.

Engineering quality

The repository includes:

• Python 3.11–3.13 tests with a 90% coverage floor

• Ruff lint and format verification

• static type analysis with complete function signatures

• Bandit and dependency vulnerability scanning

• CodeQL analysis on pushes, pull requests, and a weekly schedule

• package build and metadata verification

• tagged release artifacts with an SBOM and GitHub build-provenance attestation

• Dependabot for Python and GitHub Actions dependencies

• architecture, threat-model, ADR, operations, contribution, and security documents

Local verification:

pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy src/scopeguard_mcp
bandit -q -r src
pytest
python -m build
twine check dist/*

Responsible use

Use ScopeGuard only on repositories and systems you own or are explicitly authorized to assess. The project intentionally excludes exploit generation, password attacks, credential collection, payload generation, persistence, evasion, denial of service, internet-scale scanning, and autonomous attack chains.