IRsoctierDT/ai-agentic-mcpscan

# AI Agentic MCPscan **状态：** ✅ MVP 功能已完成（已构建 Sprint 1–4，全部门禁通过） · 待发布至 PyPI。CLI 命令：`mcpscan`。许可证：Apache-2.0。 ## 功能说明 (MVP) - **发现** 通过 socket/进程枚举发现本地计算机上的 MCP server （直接捕获 `0.0.0.0` / 非 loopback 暴露），加上对 `/mcp` 和 `/sse` 的 loopback 探测。 - **静态审计** Claude 生态系统的 agent 配置（`.claude/settings.json`, `.mcp.json`, `claude_desktop_config.json`, `.env`），检查明文 secrets、 自动批准标志、过宽的 tool scope 以及未锁定的版本。 - **评分** 根据四个维度（暴露程度、凭据管理、 tool-scope 宽泛度、版本锁定）为每个 server 打分 **A–F**。 - **报告** 以三种形式输出优先级排序且经过**脱敏**处理的纯建议性修复方案：终端、独立的 HTML 文件以及结构化 JSON。 ## 信任特性（设计保证） - **仅限 Localhost** — 绝不触碰 LAN 或第三方系统。 - **默认离线且零遥测** — 使用 `--online` 手动开启可添加 OSV/PyPI 数据富化，并会明确提示。 - **Secrets 绝不泄露** — 所有地方均已脱敏；`--show-secrets` 仅显示 掩码/部分值，并伴有警告。 - **纯建议性** — 绝不写入您的配置文件。 - **完全无状态** — 仅在您明确要求时才生成报告。 - **通过自身扫描** — 不暴露任何端口，不携带任何明文 secret。 ## 安装 发布至 PyPI 后： ``` pipx install ai-agentic-mcpscan # provides the `mcpscan` command ``` 或立即从源码安装： ``` git clone https://github.com/IRsoctierDT/ai-agentic-mcpscan.git cd ai-agentic-mcpscan && pipx install . ``` 要求 **Python 3.11+** (macOS, Linux, Windows)。 ## 用法 ``` mcpscan scan # scan localhost + cwd project configs mcpscan scan --root ~/project # scan a specific project root (repeatable) mcpscan scan --json report.json # also write a stable JSON report (0600) mcpscan scan --html report.html # also write a self-contained HTML report mcpscan scan --fail-on critical # CI: exit non-zero only on Critical mcpscan scan --online # opt-in OSV enrichment (discloses egress) mcpscan scan --show-secrets # reveal masked (first-2/last-2) values mcpscan scan --absolute-paths # show full paths instead of ~ ``` 当发现的结果符合 `--fail-on`（默认：`high`）的条件时，退出码为非零，因此它可以直接无缝接入 CI。 ### 示例输出 ``` AI Agentic MCPscan — overall posture: F dimensions: credential=D, exposure=A, pinning=A, tool_scope=C findings: 1 critical, 1 high, 2 medium ▶ ~/.mcp.json#weather [grade F] [CRITICAL] Plaintext OpenAI API key in config where: ~/.mcp.json secret: [redacted len=37 sha256:c0cc596e] fix: Remove the literal value from the file. Reference it from a secret manager … and rotate the exposed credential. [MEDIUM ] Server 'weather' runs an unpinned package via npx fix: Pin the package to an exact version (e.g. npx some-pkg@1.2.3). ``` ## 文档 | 文档 | 内容说明 | |---|---| | [docs/SPEC.md](docs/SPEC.md) | 完整的产品和技术规范（可测试的需求、评分标准、威胁模型、DoD）。 | | [docs/DECISIONS.md](docs/DECISIONS.md) | 15 项架构决策记录。 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 组件模型、依赖方向、信任边界。 | | [docs/BACKLOG.md](docs/BACKLOG.md) | Sprint 标记的工单 + 需求到工单的可追溯性。 | | [docs/SECURITY_SIGNOFF.md](docs/SECURITY_SIGNOFF.md) | 威胁模型验证矩阵（安全签署）。 | | [SECURITY.md](SECURITY.md) · [CONTRIBUTING.md](CONTRIBUTING.md) | 报告政策 · 贡献者指南。 | ## 状态与路线图 MVP 在四个 Sprint 中已实现功能完整（基础架构 → 引擎 → 报告 → 集成与强化），建立在通过绿色 CI 门禁（ruff, mypy --strict, bandit, pytest 在 macOS/Linux/Windows × Python 3.11–3.13 下运行）的基础之上。目前 唯一的剩余步骤是经过人工审核的 PyPI 发布。 路线图：SARIF + GitHub code-scanning action，更多 host adapter（Cursor, Cline, …），手动开启的 `--fix`，以及在明确授权门禁下的授权 LAN 扫描。 ## 许可证 [Apache-2.0](LICENSE)。

标签：GraphQL安全矩阵, Python, 人工智能, 安全助手, 安全扫描器, 安全规则引擎, 插件系统, 文档结构分析, 无后门, 本地优先, 用户模式Hook绕过, 聊天机器人, 逆向工具