scopeguard-mcp - Policy-first defensive security operations server

项目说明

ScopeGuard MCP

![CI]()
![CodeQL]()
![Python]()
![MCP]()

ScopeGuard is a policy-first defensi server for MCP. It lets AI clients plan
assessments, e 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 e, dual execution gates, bounded
resource use, e integrity, secure file access, durable audit history, threat
modeling, supply-chain controls, and negati.

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 acti, 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 tra 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 ne. Correlation fingerprints use keyed HMAC rather than

a guessable unsalted digest.

Completed scans persist a manifest digest, ruleset digest, timestamps, outcome, and

summary so e 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 permission and exporting signed audit heads to a separate
trust domain.

Architecture

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

MCP tools

| Tool | Purpose | Boundary |
|---|---|---|
| health | Report safety posture and audit integrity | No target access |
| create_dry_run_engagement | Create a bounded non-executing scope | Execute mode is una |
| re | Revoke an MCP-created dry-run engagement | Cannot revoke operator execute grants |
| check_scope | Normalize and e a target | Acti required |
| plan_assessment | Produce a bounded web or repository plan | No network or process execution |
| analyze_headers | Inspect caller-supplied response headers | Offline and input-bounded |
| scan_repository | Run read-only Python and secret checks | Requires both execution gates |
| list_audit_events | Read engagement-specific e | Requires audit:read |
| list_scan_runs | Read durable scan manifests and outcomes | Requires audit:read |
| | event order and the signed head | Does not reveal signing material |

Quick start

Python 3.11 or newer is required.

Example MCP client configuration:

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 the signed audit head after an assessment and anchor it in an append-only external
system:

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

Capabilities

| Capability | Allows |
|---|---|
| plan:assessment | Bounded web or repository planning for an in-scope target |
| analyze:headers | Offline analysis of supplied HTTP headers |
| scan:repository | Built-in read-only scanning under both execution gates |
| audit:read | Engagement audit events and durable scan-run e |

Configuration

| | Default | Purpose |
|---|---|---|
| SCOPEGUARD_STATE_DIR | <cwd>/.scopeguard | Private SQLite state directory |
| SCOPEGUARD_ALLOWED_ROOTS | current directory | Path-separated operator allowlist |
| SCOPEGUARD_EXECUTION_ENABLED | false | Enables operator-created execute engagements |
| SCOPEGUARD_REQUIRE_SEALED_AUDIT | true in execute mode | Fails execution closed without a audit seal |
| SCOPEGUARD_AUDIT_HMAC_KEY | unset | At least 32 bytes; signs the durable audit checkpoint |
| SCOPEGUARD_AUDIT_KEY_ID | key fingerprint | Non-secret identifier used for rotation tracking |
| SCOPEGUARD_MAX_TARGETS | 25 | Engagement target ceiling |
| SCOPEGUARD_MAX_HEADERS | 100 | Offline header count ceiling |
| SCOPEGUARD_MAX_HEADER_BYTES | 32768 | Total header input ceiling |
| SCOPEGUARD_MAX_FILES | 5000 | Repository file ceiling |
| SCOPEGUARD_MAX_FILE_BYTES | 1000000 | Per-file read ceiling |
| SCOPEGUARD_MAX_TOTAL_BYTES | 50000000 | Total repository read ceiling |
| SCOPEGUARD_MAX_FINDINGS | 2000 | Returned finding ceiling |

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

pri blocks, AWS access keys, GitHub tokens, and likely hard-coded secrets

Results include a deterministic file-manifest SHA-256 and ruleset SHA-256. Secret
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% co floor

Ruff lint and format

static type analysis with complete function signatures

Bandit and dependency scanning

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

package build and metadata

tagged release artifacts with an SBOM and GitHub build-pro attestation

Dependabot for Python and GitHub Actions dependencies

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

Local :

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, e, denial of service,
internet-scale scanning, and autonomous attack chains.

项目信息

开发语言：Python

Star 数：1

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Policy-first defensive security operations server for MCP展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。