# https://github.com/IRsoctierDT/ai-agentic-mcpscan 项目说明书 生成时间：2026-07-12 21:48:38 UTC ## 目录 - [项目概述、安装与运行模式](#page-overview) - [核心 scan 命令、检查项与 A–F 评分](#page-scan-checks) - [主机适配器:Claude、Cursor、Windsurf、Cline、VS Code、Zed、Continue](#page-adapters) - [信任评分与风险关系(`mcpscan trust`)](#page-trust) - [资产清单与安全框架映射](#page-inventory-atlas) - [漂移检测、SARIF 与 CI 集成](#page-drift-sarif) - [授权网络评估 `mcpscan lan`](#page-lan) - [内部架构、引擎与扩展点](#page-architecture) ## 项目概述、安装与运行模式 ### 相关页面 相关主题：[核心 scan 命令、检查项与 A–F 评分](#page-scan-checks)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/README.md) - [pyproject.toml](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/pyproject.toml) - [src/mcpscan/cli.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/cli.py) - [src/mcpscan/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/__init__.py) - [src/mcpscan/core/scanner.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/core/scanner.py) - [src/mcpscan/adapters/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/__init__.py) - [src/mcpscan/report/sarif.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/report/sarif.py) - [CHANGELOG.md](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/CHANGELOG.md)
# 项目概述、安装与运行模式 ## 一、项目定位与核心目标 `ai-agentic-mcpscan`（包名 `mcpscan`）是一个面向 **AI Agent / MCP（Model Context Protocol）生态** 的安全扫描器。它以静态分析为主、无需联网即可对本地 AI 客户端配置文件进行风险审计，重点关注三类资产： - **MCP 服务器声明**（stdio / SSE / HTTP 传输方式、端点 URL、命令与参数） - **工具授权范围**（tool-scope，过宽授权即风险点） - **宿主配置上下文**（不同 IDE / 编辑器的 MCP 配置文件） 项目在 v1.0.0 发布时被声明为 **stable**（[CHANGELOG.md:CHANGELOG.md]() 中 1.0.0 条目），当前最新版本为 v1.4.0。整体定位与发布节奏见 README 与 CHANGELOG 资料来源：[README.md:README.md]()、[CHANGELOG.md:CHANGELOG.md]()。 ## 二、安装方式 项目以标准 Python 包形式分发，安装信息由 `pyproject.toml` 描述。典型安装流程： ```bash # 从源码安装（推荐用于本地开发与 dogfood） pip install -e . # 或从 PyPI 安装稳定版 pip install ai-agentic-mcpscan ``` 依赖说明、Python 版本约束、可选 extras（如 SARIF 报告、Zed/VS Code 适配器所需的解析依赖）均集中在 `pyproject.toml` 中，资料来源：[pyproject.toml:pyproject.toml]()。安装完成后会在 PATH 中暴露 `mcpscan` 可执行入口，入口逻辑由 CLI 模块统一调度，资料来源：[src/mcpscan/cli.py:src/mcpscan/cli.py]()。 ## 三、CLI 入口与子命令结构 `mcpscan` 命令由 Click/Typer 风格的入口构建，子命令按 **Tier 分层** 组织： | Tier | 子命令 | 用途 | |------|--------|------| | Tier-1 | `mcpscan inventory` | AI/MCP 资产清单盘点（v1.1.0 引入） | | Tier-2 | `mcpscan atlas` | 框架映射分析（v1.2.0 引入） | | 安全核 | `mcpscan lan` | 局域网/网络端点安全审计（v0.8.0 起引入 Phase A 安全核，v0.9.0 完成接线，v1.3.0 增加 SARIF logical locations） | | 通用 | `mcpscan scan` | 默认扫描入口，支持 SARIF 输出与 `--fix` | 子命令注册与参数解析统一在 CLI 模块完成，资料来源：[src/mcpscan/cli.py:src/mcpscan/cli.py]()。版本号、特性开关集中在 `__init__.py`，资料来源：[src/mcpscan/__init__.py:src/mcpscan/__init__.py]()。 ## 四、运行模式与安全核 ### 4.1 离线静态扫描（默认模式） `mcpscan` 默认工作模式为 **纯静态、零网络访问**：读取本地 MCP/宿主配置文件，按规则集匹配风险项。核心调度逻辑在扫描器模块中实现，资料来源：[src/mcpscan/core/scanner.py:src/mcpscan/core/scanner.py]()。 ### 4.2 网络端点分析（`lan` 子命令的 Phase A 安全核） `mcpscan lan` 在 v0.8.0 引入 **Phase A 安全核**，明确要求： - 必须通过 **显式授权** 才允许进一步动作； - 在授权前 **禁止任何网络出站**，仅做本地配置解析与端点静态推断； - v0.9.0 完成与安全核的接线，v1.3.0 起 SARIF 输出附带 logical locations（ADR-16）。 资料来源：[CHANGELOG.md:CHANGELOG.md]() 中 v0.8.0 / v0.9.0 / v1.3.0 条目。 ### 4.3 报告与修复模式 - **SARIF 2.1.0 报告**：`--format sarif`（或默认在 CI 中启用）输出标准 SARIF，便于接入 GitHub Code Scanning 等平台，v0.4.0 引入，资料来源：[src/mcpscan/report/sarif.py:src/mcpscan/report/sarif.py]()、[CHANGELOG.md:CHANGELOG.md]()。 - **自动修复**：`--fix` 选项可对 **过度宽泛的 tool-scope 授权** 进行收敛（v0.5.0 引入，opt-in），资料来源：[CHANGELOG.md:CHANGELOG.md]()。 ### 4.4 宿主适配层 扫描器通过适配器抽象读取不同宿主配置，目前支持的适配器包括： - **VS Code**（原生 MCP，v0.6.0） - **Zed**（含 JSONC 支持，v0.7.0） 适配器注册逻辑集中在适配器包，资料来源：[src/mcpscan/adapters/__init__.py:src/mcpscan/adapters/__init__.py]()。 ## 五、Dogfood 与 Phase-2 工具链 v1.4.0 新增 **dogfood Phase-2 工具**： - **配置匿名化器**（config anonymizer）：用于在内部测试与社区复现时脱敏真实路径与凭据； - **网络实验 runbook**：在受控实验环境中演练 `lan` 子命令的网络端点检测路径。 这一阶段的工具补齐，使项目本身具备了“自托管 + 自验证”的能力闭环，资料来源：[CHANGELOG.md:CHANGELOG.md]() v1.4.0 条目。 ## 六、典型使用流程 ```mermaid flowchart LR A[安装 mcpscan] --> B[选择子命令] B --> C1[inventory
Tier-1 清单] B --> C2[atlas
Tier-2 映射] B --> C3[lan
安全核审计] B --> C4[scan
默认扫描] C1 --> D[SARIF / 文本报告] C2 --> D C3 --> D C4 --> D D --> E{是否 --fix} E -- 是 --> F[改写 tool-scope] ``` ## 七、小结 - **定位**：面向 MCP/AI Agent 生态的本地静态安全扫描器，离线优先、可选网络核； - **安装**：`pip install -e .` 或 `pip install ai-agentic-mcpscan`，由 `pyproject.toml` 描述； - **运行模式**：默认静态扫描、`lan` 授权型网络核、SARIF 报告、`--fix` 自动收敛、适配器多宿主覆盖； - **演进**：从 v0.4.0 的 SARIF 输出逐步叠加 Tier-1/Tier-2 资产与映射能力，v1.0.0 宣告稳定，v1.4.0 引入 dogfood Phase-2 工具链。 如需进一步了解某一子命令的内部实现，请参阅对应子系统的页面（如 `lan` 安全核、SARIF 报告、适配器层）。 --- ## 核心 scan 命令、检查项与 A–F 评分 ### 相关页面 相关主题：[主机适配器:Claude、Cursor、Windsurf、Cline、VS Code、Zed、Continue](#page-adapters), [项目概述、安装与运行模式](#page-overview), [内部架构、引擎与扩展点](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/engine.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/engine.py) - [src/mcpscan/scoring.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/scoring.py) - [src/mcpscan/checks/exposure.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/exposure.py) - [src/mcpscan/checks/secrets.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/secrets.py) - [src/mcpscan/checks/tool_scope.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/tool_scope.py) - [src/mcpscan/checks/pinning.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/checks/pinning.py)
# 核心 scan 命令、检查项与 A–F 评分 ## 1. 概述与定位 `mcpscan scan` 是 ai-agentic-mcpscan 的**核心入口命令**，负责对 AI Agent / MCP 客户端配置文件进行静态安全扫描。它的核心职责包括： - 解析并归一化来自不同宿主（Claude Desktop、Cursor、VS Code、Zed 等）的配置； - 调用四个内置检查模块对配置中暴露的 MCP Server 进行评估； - 基于检查结果计算 **A–F** 等级的综合安全评分； - 将结果以结构化 JSON / SARIF 等形式输出。 `engine.py` 作为编排器，串联检查模块、评分器与报告层；`scoring.py` 负责将各检查项的扣分聚合为最终等级；`checks/` 目录下的四个文件分别实现一个独立维度。这种分层结构保证了"扫描动作"与"判定逻辑"解耦，便于扩展新检查项。资料来源：[src/mcpscan/engine.py:1-60]() ## 2. scan 命令的工作流 `engine.py` 中定义的扫描流水线遵循"加载 → 适配 → 检查 → 评分 → 报告"五段式流程。资料来源：[src/mcpscan/engine.py:60-140]() ```mermaid flowchart LR A[配置加载] --> B[宿主适配器解析] B --> C[暴露面检查 exposure] B --> D[密钥检查 secrets] B --> E[工具权限检查 tool_scope] B --> F[版本钉死检查 pinning] C --> G[scoring.py 聚合] D --> G E --> G F --> G G --> H[A-F 评级] H --> I[JSON / SARIF 输出] ``` `engine.py` 在执行检查时通过统一的 `Finding` 数据结构传递"命中位置、严重级别、扣分值"等上下文，使得评分器无需关心每个检查的内部实现细节。资料来源：[src/mcpscan/engine.py:140-210]() ## 3. 四大内置检查项 ### 3.1 暴露面检查 (exposure) `checks/exposure.py` 检测 MCP Server 是否被绑定到 `0.0.0.0`、公网 IP、未加鉴权的 HTTP/SSE 端点等危险暴露场景。当命令、URL 或环境变量中存在此类模式时，会产生 `HIGH` 级 `Finding`，并向 `scoring.py` 提交较大扣分。资料来源：[src/mcpscan/checks/exposure.py:1-80]() ### 3.2 密钥泄露检查 (secrets) `checks/secrets.py` 在配置的命令行参数与环境变量中匹配常见的 API Key、Token、Bearer 等高熵字符串与正则规则（例如 `sk-`、`ghp_`、`xoxb-` 等前缀），命中即上报为 `CRITICAL` 级命中。该模块与社区中关注的"明文凭证"问题直接对应。资料来源：[src/mcpscan/checks/secrets.py:1-90]() ### 3.3 工具权限范围检查 (tool_scope) `checks/tool_scope.py` 检查 MCP Server 注册的工具集合是否过度宽泛（如 `*`、`filesystem:*`、全目录读写）。当发现 over-broad 授权时会发出 `MEDIUM`/`HIGH` 级命中，并在 `v0.5.0` 之后通过 `--fix` 选项（参见 PR #31）支持收紧工具范围。资料来源：[src/mcpscan/checks/tool_scope.py:1-100]() ### 3.4 版本钉死检查 (pinning) `checks/pinning.py` 验证 MCP Server 命令是否使用了精确版本号、校验和或 lockfile，而非 `latest`、`@latest`、浮动标签等不稳定引用。未钉死的依赖会被标记为 `MEDIUM` 级，便于在升级链路中追溯变更来源。资料来源：[src/mcpscan/checks/pinning.py:1-85]() ## 4. A–F 评分机制 `scoring.py` 将每个 `Finding` 的扣分（按严重级别映射：CRITICAL=20、HIGH=10、MEDIUM=4、LOW=1）累加，并按预设阈值映射到字母等级： | 等级 | 扣分区间 | 含义 | | --- | --- | --- | | A | 0 | 无实质风险 | | B | 1–4 | 仅存在轻微提示 | | C | 5–14 | 存在可改进项 | | D | 15–29 | 存在明确风险 | | F | ≥ 30 或任意 CRITICAL | 配置存在严重缺陷 | 评分器在遇到 CRITICAL 级命中时，会**直接置为 F**，即便累计扣分未达阈值——这是与社区多次反馈后形成的安全默认策略。资料来源：[src/mcpscan/scoring.py:1-120]() `engine.py` 在最终输出前会调用 `scoring.py` 的 `compute_grade()` 取得等级，并以 SARIF `level`、`security-severity` 等字段回填，确保 GitHub Code Scanning 等下游消费者能够正确渲染。资料来源：[src/mcpscan/engine.py:210-260]() ## 5. 扩展与最佳实践 - 新增检查项只需在 `checks/` 下实现一个返回 `List[Finding]` 的模块，并在 `engine.py` 的检查注册表中加入即可；评分由 `scoring.py` 统一处理。 - 通过 `--fail-on D` 等 CLI 参数可以让 CI 在等级低于 D 时直接失败，对接仓库 v0.4.0 引入的 Code Scanning 工作流（PR #28）。 - 对于暴露面与密钥类命中，建议先修复再触发 `scan`；对于 `tool_scope` 类问题，可直接使用 `--fix` 自动收窄。资料来源：[src/mcpscan/engine.py:260-310]() - 与 v1.1.0 `inventory`、v1.2.0 `atlas` 等命令配合时，`scan` 的输出可作为 Tier-2 框架映射的输入源，形成"资产清单 → 深度扫描 → 治理决策"的闭环。 --- ## 主机适配器:Claude、Cursor、Windsurf、Cline、VS Code、Zed、Continue ### 相关页面 相关主题：[核心 scan 命令、检查项与 A–F 评分](#page-scan-checks), [资产清单与安全框架映射](#page-inventory-atlas)
相关源码文件 以下源码文件用于生成本页说明： - 资料来源： [src/mcpscan/adapters/base.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/base.py) - 资料来源： [src/mcpscan/adapters/paths.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/paths.py) - 资料来源： [src/mcpscan/adapters/claude.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/claude.py) - 资料来源： [src/mcpscan/adapters/cursor.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/cursor.py) - 资料来源： [src/mcpscan/adapters/windsurf.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/windsurf.py) - 资料来源： [src/mcpscan/adapters/cline.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/adapters/cline.py)
--- ## 信任评分与风险关系(`mcpscan trust`) ### 相关页面 相关主题：[核心 scan 命令、检查项与 A–F 评分](#page-scan-checks), [资产清单与安全框架映射](#page-inventory-atlas)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/trust/analyze.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/trust/analyze.py) - [src/mcpscan/trust/collect.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/trust/collect.py) - [src/mcpscan/trust/model.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/trust/model.py) - [src/mcpscan/trust/render.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/render.py) - [src/mcpscan/domain.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/domain.py)
# 信任评分与风险关系(`mcpscan trust`) ## 概述与设计目标 `mcpscan trust` 是 ai-agentic-mcpscan 的核心子命令，用于对已采集的 AI/MCP 资产（Tier-1 inventory 命令的产物）进行**量化信任评估**，并把每条已识别的风险发现（findings）与最终信任分进行映射，从而回答「这个 MCP 服务器/工具到底可不可信」这一关键问题。资料来源：[src/mcpscan/trust/model.py:1-40]() 其核心设计目标包括： - **离线、可重现**：与 `mcpscan lan` 一样，`trust` 不发起任何网络请求，分数仅依赖已采集的本地配置快照，符合 v0.8.0 引入的安全核（safety core）约束。资料来源：[src/mcpscan/trust/collect.py:1-30]() - **与风险一体化**：信任分与 SARIF 2.1.0 finding（自 v0.4.0 起）使用同一份域对象，避免双轨语义。资料来源：[src/mcpscan/domain.py:1-60]() - **可插拔**：host adapter（VS Code、Zed 等）只负责采集，评分逻辑集中在 `trust/` 子模块，方便后续 tier-2 框架映射复用。资料来源：[src/mcpscan/trust/analyze.py:1-25]() ## 数据模型与域对象 `TrustScore` 的核心数据结构在 `trust/model.py` 中定义。它由**基底分（base score）**与**风险惩罚（risk penalty）**两部分组成： | 维度 | 字段 | 含义 | | --- | --- | --- | | 资产标识 | `asset_id`、`source_kind` | 来自 `domain.McpServer` / `McpTool` | | 基底分 | `base_score ∈ [0,100]` | 来源透明度、签名、供应链信号 | | 风险惩罚 | `penalty`、`finding_refs[]` | 引用 `domain.Finding` 的 severity | | 最终分 | `final_score` | `clamp(base_score − penalty, 0, 100)` | | 等级 | `band ∈ {trusted, cautious, untrusted}` | 离散分级，供 CLI/SARIF 使用 | 域层 `src/mcpscan/domain.py` 暴露 `Finding.severity`（`info/low/medium/high/critical`），并保证它在 trust 子模块、扫描器、SARIF 渲染器之间是同一枚举，杜绝「评分用一套术语、报告用另一套」的分歧。资料来源：[src/mcpscan/domain.py:80-140]() ## 分析流水线 `mcpscan trust` 的执行链路是：`collect → analyze → render`，三个阶段严格解耦。 1. **采集（collect.py）**：复用 Tier-1 inventory 的 adapter 输出（VS Code、Zed、Claude Desktop 等），把每台 host 的 MCP 配置归一化为 `list[InventoryItem]`。此阶段不引入任何外部 IO。资料来源：[src/mcpscan/trust/collect.py:40-90]() 2. **分析（analyze.py）**：对每个 `InventoryItem`，按权重表计算 `base_score`，再叠加其关联 findings 的 `penalty`。v1.4.0 引入的 `--anonymize` 配置匿名化（dogfood Phase-2）确保批量评估时不会泄露生产 host 的真实路径。资料来源：[src/mcpscan/trust/analyze.py:60-130]() 3. **渲染（render.py）**：输出三视图——人类可读的 CLI 表格、机器可读的 JSON，以及 SARIF `properties` 扩展（`trust/finalScore`、`trust/band`），便于 GitHub code-scanning 直接消费。资料来源：[src/mcpscan/trust/render.py:20-80]() 整体流程可概括为下图： ```mermaid flowchart LR A[host adapters] --> B[collect.py] B --> C[analyze.py] C --> D[render.py] D --> E[(CLI / JSON / SARIF)] C --> F[TrustScore + Findings] ``` ## 风险到信任分的映射 风险与分数不是简单的「一条 finding 扣 X 分」。`analyze.py` 采用**分段惩罚函数**：随当前 `base_score` 升高，单条 critical finding 的相对影响更大，避免出现「90 分资产扣 5 分变 85」与「30 分资产扣 5 分仍 25」被同等对待的情况。资料来源：[src/mcpscan/trust/analyze.py:140-200]() 关键规则： - `critical` 直接把分压制到 `< 40`，并强制 `band=untrusted`。 - `high` 按比例扣分，最多扣 `base_score * 0.3`。 - `medium/low/info` 仅影响透明度子项（`base_score` 的可解释性维度）。 - 当同一个 finding 同时被 v0.5.0 的 `--fix` 标记为「可自动收敛」时，`analyze.py` 在沙箱预览中给出「fixed_score」对照，便于用户人工确认。资料来源：[src/mcpscan/trust/analyze.py:210-260]() ## 输出与集成 最终 `TrustReport` 由 `render.py` 序列化： - CLI 视图：按 `band` 排序，critical 资产置顶，附带 `finding_refs` 的可点击 ID。资料来源：[src/mcpscan/trust/render.py:90-140]() - JSON 视图：保留完整 `TrustScore` 与原始 findings 引用，便于 CI 做阈值门禁。 - SARIF 视图：把 `finalScore` 写入 `result.properties`，使 GitHub code-scanning 能基于「trust band」设置不同的告警级别；这正是 v1.3.0 SARIF logical locations 改进（ADR-16）的延伸。资料来源：[src/mcpscan/trust/render.py:150-200]() ## 边界与已知约束 - `trust` 仅消费本地 inventory，**不会**主动探测 MCP server 行为，因此不替代运行时安全审计。 - 当前权重表以 v1.4.0 dogfood 阶段的样例集训练，后续 tier-2 框架映射（v1.2.0 atlas 命令）可能引入新维度，届时 `analyze.py` 的权重表需同步迁移。资料来源：[src/mcpscan/trust/analyze.py:1-30]() - 评分是**相对值**而非概率：相同分数在不同团队可能对应不同处置策略，CLI 输出会显式提示此点。资料来源：[src/mcpscan/trust/render.py:200-230]() --- ## 资产清单与安全框架映射 ### 相关页面 相关主题：[信任评分与风险关系(`mcpscan trust`)](#page-trust), [漂移检测、SARIF 与 CI 集成](#page-drift-sarif)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/inventory/collect.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/collect.py) - [src/mcpscan/inventory/classify.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/classify.py) - [src/mcpscan/inventory/fingerprint.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/fingerprint.py) - [src/mcpscan/inventory/model.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/model.py) - [src/mcpscan/inventory/render.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/inventory/render.py) - [src/mcpscan/atlas/model.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/atlas/model.py)
# 资产清单与安全框架映射 ## 概述 `ai-agentic-mcpscan` 的"资产清单与安全框架映射"由两条分层命令组成，构成 v1.0.0 稳定版之后的能力矩阵： - **Tier-1 资产清单（`mcpscan inventory`）**：自 v1.1.0 起引入（[#49](https://github.com/IRsoctierDT/ai-agentic-mcpscan/issues/49)），用于枚举本机/工作区内的 AI 与 MCP 相关资产，作为后续策略评估与合规映射的输入基线。 - **Tier-2 框架映射（`mcpscan atlas`）**：自 v1.2.0 起引入（[#51](https://github.com/IRsoctierDT/ai-agentic-mcpscan/issues/51)），将 Tier-1 输出映射到 OWASP / NIST 等安全控制框架，形成可审计的合规视图。 两者形成"发现 → 归类 → 映射"的两阶段流水线，全程为本地静态扫描，不发起远程网络请求，与 `mcpscan lan` Phase A 的"无网络"安全约束一致。 ## Tier-1 资产清单（inventory） ### 模块职责 `src/mcpscan/inventory/` 子包按职责横向拆分，便于单独扩展与测试： | 模块 | 职责 | |------|------| | `collect.py` | 通过 Host Adapter（VS Code、Zed、Claude Desktop 等，参见 v0.6.0 / v0.7.0）拉取配置文件与运行清单 | | `classify.py` | 基于命名与字段特征将条目归入"MCP server"、"Agent 工具"、"Skill / 命令"等类别 | | `fingerprint.py` | 对每个资产生成指纹（版本、传输方式、权限范围），便于后续去重与差异比对 | | `model.py` | 定义 `InventoryEntry`、`InventoryReport` 等不可变数据模型 | | `render.py` | 将模型渲染为人类可读的表格与机器可读的 JSON / SARIF 片段 | 各模块的协作边界遵循"输入纯函数化、副作用只在 collect / render 两端"的原则（资料来源：[inventory/collect.py:1-80]()）（资料来源：[inventory/classify.py:1-60]()）（资料来源：[inventory/fingerprint.py:1-80]()）（资料来源：[inventory/model.py:1-120]()）（资料来源：[inventory/render.py:1-100]()）。 ### 数据流 ```mermaid flowchart LR A[Host Adapter] --> B[collect.py] B --> C[classify.py] C --> D[fingerprint.py] D --> E[model.py] E --> F[render.py] F --> G[Inventory 报告] ``` `collect` 阶段只读取本地配置文件与状态文件，不发起任何远程调用；`render` 阶段统一输出 CLI 表格与 SARIF 2.1.0 两种形态，供后续 `mcpscan atlas` 或 CI code-scanning workflow 消费。 ## Tier-2 安全框架映射（atlas） `mcpscan atlas` 接收 Tier-1 的 `InventoryReport`，按控制域进行映射： - **数据模型集中化**：框架控制项与映射结果统一定义在 `src/mcpscan/atlas/model.py`，包括 `FrameworkControl`、`MappingResult`、`Coverage` 等结构（资料来源：[atlas/model.py:1-150]()）。 - **控制项三要素**：以"框架 ID + 控制项编号 + 适用条件"表达，框架 ID 默认遵循 OWASP LLM Top 10、NIST SP 800-53、MITRE ATLAS 等公开编号体系。 - **映射规则纯函数化**：输入 `InventoryEntry`，输出"满足 / 部分满足 / 不适用"三态结论，并附带证据回链到原始配置路径，便于审计追溯。 - **不改资产**：与 v0.5.0 引入的 `--fix`（针对"过宽工具作用域"的 opt-in 修复）严格分离，`atlas` 阶段只产出评估结论，不修改任何宿主配置。 ## 与其它命令的协作关系 - **v0.4.0 SARIF 输出**：`inventory` 与 `atlas` 的结果均经 `render.py` 汇入 SARIF 2.1.0，逻辑位置信息与 v1.3.0 的 `mcpscan lan` ADR-16 一致。 - **v0.5.0 `--fix`**：仅针对 `inventory` 识别出的"过宽工具作用域"进行就地收紧；`atlas` 阶段维持只读语义。 - **v0.8.0–v0.9.0 `mcpscan lan`**：三者在"无网络 + 本地授权"的统一安全核上共存，可在受限环境中串联执行。 - **v1.0.0 稳定声明**：自此两条命令进入 GA 状态，向后兼容 1.x 系列；v1.4.0 又在此基础上叠加了 Phase-2 配置匿名化与网络实验手册，为 dogfood 场景提供配套。 借助这套分层设计，安全团队可以先获得机器可读的资产清单，再获得框架维度的覆盖度视图，最终接入 SARIF / CI 完成自动化门禁，形成完整的"识别—评估—阻断"闭环。 --- ## 漂移检测、SARIF 与 CI 集成 ### 相关页面 相关主题：[核心 scan 命令、检查项与 A–F 评分](#page-scan-checks), [授权网络评估 `mcpscan lan`](#page-lan)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/drift/baseline.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/drift/baseline.py) - [src/mcpscan/drift/diff.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/drift/diff.py) - [src/mcpscan/drift/model.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/drift/model.py) - [src/mcpscan/drift/render.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/drift/render.py) - [src/mcpscan/drift/snapshot.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/drift/snapshot.py) - [src/mcpscan/report/sarif.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/report/sarif.py)
# 漂移检测、SARIF 与 CI 集成 ## 1. 概述与设计目标 `mcpscan` 的"漂移检测 + SARIF + CI 集成"组合，将 MCP/AI 主机的资产扫描结果转成可在 CI 流水线中消费的标准化安全信号。该能力由两个职责清晰的子模块组成： - **漂移检测（drift）**：以基线（baseline）作为已知安全状态，将新一次扫描得到的快照（snapshot）与基线对比，识别新增、变更或消失的 AI/MCP 资产项。 - **SARIF 报告（report/sarif）**：把扫描结果序列化为 [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) 规范，便于 GitHub Code Scanning 等平台直接渲染。 社区演进路径印证了该方向：在 v0.4.0 中引入"SARIF 2.1.0 输出与 code-scanning workflow"（[#28](https://github.com/IRsoctierDT/ai-agentic-mcpscan/issues/28)），并在 v1.3.0 中进一步为网络端点类发现补齐 SARIF logical locations（[ADR-16](https://github.com/IRsoctierDT/ai-agentic-mcpscan/issues/53)）。 资料来源：[src/mcpscan/drift/baseline.py:1-40]()，[src/mcpscan/report/sarif.py:1-40]() ## 2. 漂移检测模块架构 漂移模块按"模型—快照—基线—对比—渲染"分层组织，每个文件单一职责： | 文件 | 职责 | |---|---| | `drift/model.py` | 定义被对比的资产条目数据结构与状态字段 | | `drift/snapshot.py` | 负责从一次扫描结果生成不可变快照 | | `drift/baseline.py` | 负责基线的载入、保存与版本校验 | | `drift/diff.py` | 负责执行快照与基线的逐项比对并分类差异 | | `drift/render.py` | 负责将差异结果渲染为人类可读的文本或结构化输出 | 该分层使"扫描→快照→基线→对比→渲染"形成单向数据流，避免对比逻辑直接依赖 CLI 入口。资料来源：[src/mcpscan/drift/model.py:1-30]()，[src/mcpscan/drift/snapshot.py:1-30]()，[src/mcpscan/drift/diff.py:1-30]() ### 2.1 基线与快照生命周期 基线（baseline）代表"已接受"的安全状态，快照（snapshot）则代表"当前"扫描得到的状态。两者通常被实现为同一数据模型的两种序列化形态，因而可以复用相同的字段定义与校验逻辑。`drift/baseline.py` 负责把基线持久化到磁盘并在加载时进行版本/字段校验，`drift/snapshot.py` 则负责在每次扫描结束时构造一次完整快照。资料来源：[src/mcpscan/drift/baseline.py:1-60]()，[src/mcpscan/drift/snapshot.py:1-60]() ### 2.2 差异分类 `drift/diff.py` 在对比快照与基线时，将每一条资产项归入以下几类状态之一： - **新增（added）**：仅出现在快照、不在基线中。 - **移除（removed）**：仅出现在基线、不在快照中。 - **变更（changed）**：标识匹配，但关键字段（如权限范围、远端端点、传输命令）发生变化。 - **未变（unchanged）**：标识与字段均一致。 `drift/render.py` 据此输出差异摘要，供 PR 评论或本地审阅使用。资料来源：[src/mcpscan/drift/diff.py:1-80]()，[src/mcpscan/drift/render.py:1-60]() ## 3. SARIF 报告输出 `report/sarif.py` 将扫描发现序列化为 SARIF 2.1.0 文档。SARIF 的核心价值在于： 1. **位置精确**：每个 result 可绑定到具体配置文件与字段位置（如 MCP 服务器条目、权限项）。 2. **规则可枚举**：通过 `rules` 段预声明规则 ID、严重级别与描述，避免"散落 finding"。 3. **逻辑位置**：在 v1.3.0 之后，对网络端点类 finding 增加 logical locations，便于在 Code Scanning UI 中直接导航到"哪个 host 的哪个 server 暴露了哪个端点"。资料来源：[src/mcpscan/report/sarif.py:1-80]() ### 3.1 与漂移结果的衔接 SARIF 输出主要承载"当前快照的发现"，而漂移结果通常作为补充信息出现（例如把 `added`/`changed` 项映射为新的 result，或通过 SARIF 的 `properties` 字段附加漂移标记）。这一衔接使得 CI 既能看到"当前风险"，也能看到"相对于基线的演进"。资料来源：[src/mcpscan/report/sarif.py:80-160]() ## 4. CI 集成工作流 下图描述了从本地扫描到 PR 上 SARIF 上报的端到端流程： ```mermaid flowchart LR A[mcpscan 扫描] --> B[snapshot.py 生成快照] B --> C{存在基线?} C -- 否 --> D[首次: 保存为基线] C -- 是 --> E[diff.py 对比] E --> F[render.py 输出差异摘要] E --> G[report/sarif.py 生成 SARIF] G --> H[Code Scanning 上传] F --> I[PR 评论/本地审阅] ``` CI 侧推荐的最小集成步骤： 1. **首次运行**：`mcpscan` 在干净环境下生成基线文件并提交到仓库。 2. **后续 PR**：CI 执行扫描 → 生成快照 → 与仓库中的基线对比 → 输出 SARIF。 3. **上传 SARIF**：通过 `github/codeql-action/upload-sarif` 或等价步骤将 SARIF 上传，触发 Code Scanning 警报。 4. **门禁策略**：可基于 SARIF 的严重级别或漂移新增项数量决定是否阻断合并。 资料来源：[src/mcpscan/drift/snapshot.py:1-40]()，[src/mcpscan/drift/diff.py:1-40]()，[src/mcpscan/drift/render.py:1-40]()，[src/mcpscan/report/sarif.py:1-40]() ## 5. 已知限制与最佳实践 - **基线必须可重现**：建议把基线文件纳入仓库版本控制，并在 CI 中以受信任提交作为对比来源。 - **字段稳定性**：`drift/model.py` 中定义的字段是 diff 的契约；修改字段名或语义需同步更新基线与 SARIF 规则映射。 - **网络端点定位**：当 finding 涉及远端 URL/端点时，应利用 v1.3.0 起提供的 logical locations，以获得更好的 SARIF 可导航性。资料来源：[src/mcpscan/drift/model.py:1-40]()，[src/mcpscan/report/sarif.py:80-160]() 通过以上组合，`mcpscan` 能够在不引入外部 SaaS 依赖的前提下，把 MCP/AI 资产风险纳入标准化的代码安全治理流程。 --- ## 授权网络评估 `mcpscan lan` ### 相关页面 相关主题：[漂移检测、SARIF 与 CI 集成](#page-drift-sarif)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/lan/manifest.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/manifest.py) - [src/mcpscan/lan/policy.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/policy.py) - [src/mcpscan/lan/scope.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/scope.py) - [src/mcpscan/lan/budgets.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/budgets.py) - [src/mcpscan/lan/sanitize.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/sanitize.py) - [src/mcpscan/lan/audit.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/lan/audit.py) - [src/mcpscan/cli.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/cli.py)
# 授权网络评估 `mcpscan lan` `mcpscan lan` 是 ai-agentic-mcpscan 中专门用于**授权网络评估**的命令子系统。它在 Phase A 阶段被定义为"安全核心"（safety core），承担 AI / MCP 资产中**网络端点**（network endpoints）的发现、范围限定、策略检查与报告职责，并且在整个扫描生命周期中**严禁主动产生网络流量**。该命令最初在 v0.8.0 中以安全核心形态引入，并在 v0.9.0 中完成对 CLI 的接线，至 v1.3.0 时已支持 SARIF 逻辑位置标注（ADR-16），v1.4.0 又新增了 dogfood 阶段的配置匿名器与网络实验手册。资料来源：[src/mcpscan/lan/manifest.py:1-40](), [src/mcpscan/lan/policy.py:1-30](), [src/mcpscan/cli.py:1-60](). ## 设计目标与安全边界 `mcpscan lan` 的首要约束是**"不联网、只读、可审计"**： - **零网络出站**：所有网络端点的获取仅来源于已经落盘的本地配置（适配器读取的 host 配置文件、清单文件），严禁对发现的目标发起任何探测、握手或抓包。资料来源：[src/mcpscan/lan/audit.py:1-50]()。 - **授权先行**：命令在执行任何评估前必须验证授权（authorization）。缺乏或失效的授权凭证将导致扫描立刻失败，而不会进入范围枚举阶段。资料来源：[src/mcpscan/lan/policy.py:30-90]()。 - **可重放与可审计**：每次评估都生成不可篡改的清单（manifest）与审计日志，便于事后回溯。 - **可量化预算**：通过预算模块限制端点数量、并发与时间，避免在大型资产库中失控。 这一边界决定了 `lan` 子系统与其它主动网络扫描工具（如 nmap、zgrab）的本质差异：它是一台"离线显微镜"，而不是一台"探针"。资料来源：[src/mcpscan/lan/manifest.py:1-40](), [src/mcpscan/lan/budgets.py:1-40]()。 ## 核心模块与数据流 `lan` 子系统由六个互相协作的模块组成。下图展示从 CLI 入口到审计输出的典型调用链： ```mermaid flowchart LR A[CLI: mcpscan lan] --> B[policy.py
授权校验] B --> C[scope.py
范围裁剪] C --> D[manifest.py
端点清单生成] D --> E[sanitize.py
敏感字段清理] E --> F[budgets.py
预算与节流] F --> G[audit.py
审计与 SARIF 输出] ``` 各模块职责如下： - **`manifest.py`**：负责聚合从各 host 适配器（VS Code、Zed 等）读取的网络端点声明，形成评估所用的**清单**。它是唯一对端点元数据做规范化的地方。资料来源：[src/mcpscan/lan/manifest.py:20-80]()。 - **`policy.py`**：评估"是否被授权评估这一组端点"，包括授权范围、保留名单（allow/deny list）与组织级策略。授权失败时直接 abort。资料来源：[src/mcpscan/lan/policy.py:30-120]()。 - **`scope.py`**：依据授权策略对清单做二次裁剪，确保不会出现"清单里有、但未被授权评估"的端点，避免越权评估。资料来源：[src/mcpscan/lan/scope.py:1-60]()。 - **`budgets.py`**：限制评估规模——最大端点数量、最大评估时长、最大并发规则匹配次数，并在超限时安全降级而非继续运行。资料来源：[src/mcpscan/lan/budgets.py:1-70]()。 - **`sanitize.py`**：在结果落盘前对端点中的 token、密钥、用户标识进行匿名化/脱敏，防止敏感数据泄漏到 SARIF 或日志中。资料来源：[src/mcpscan/lan/sanitize.py:1-50]()。 - **`audit.py`**：记录"谁、何时、授权了什么、扫描了哪些清单、命中了哪些规则"，并以 SARIF 2.1.0 形式输出。v1.3.0 起支持网络端点命中的逻辑位置（ADR-16）。资料来源：[src/mcpscan/lan/audit.py:1-90]()。 ## SARIF 报告与 ADR-16 从 v1.3.0 起，`mcpscan lan` 的输出与项目整体对齐到 SARIF 2.1.0。对于网络端点类发现，SARIF 结果中会携带**逻辑位置**（logical location）字段，指向 `manifest.py` 中规范化后的端点条目，而非原始 host 配置文件路径。这一约定由 ADR-16 确立，目的是让代码扫描平台（GitHub Code Scanning 等）能够把发现稳定地绑定到 `mcpscan` 的领域模型，而不是绑定到某个特定的 IDE 配置文件。资料来源：[src/mcpscan/lan/audit.py:40-120](), [src/mcpscan/lan/manifest.py:60-110]()。 SARIF 结果的典型字段映射： | SARIF 字段 | 来源模块 | 说明 | |---|---|---| | `ruleId` | `policy.py` | 命中的策略规则标识 | | `logicalLocations` | `manifest.py` + ADR-16 | 规范化后的端点逻辑位置 | | `properties.budget` | `budgets.py` | 评估时的预算快照 | | `properties.sanitized` | `sanitize.py` | 是否经过脱敏处理 | | `properties.authorizedBy` | `audit.py` | 授权来源与时间戳 | ## 版本演进要点 - **v0.8.0**：首次引入 `mcpscan lan` 的 Phase A 安全核心（授权 + 零网络）。资料来源：[release v0.8.0 notes]()。 - **v0.9.0**：把 `lan` 命令正式连接到 CLI 的安全核心管线。资料来源：[release v0.9.0 notes]()。 - **v1.3.0**：为网络端点发现加入 SARIF 逻辑位置（ADR-16），提升与代码扫描平台的对接体验。资料来源：[release v1.3.0 notes]()。 - **v1.4.0**：在 dogfood 阶段补充配置匿名器与网络实验手册（network-lab runbook），帮助用户在受控环境中自验证 `lan` 的行为边界。资料来源：[release v1.4.0 notes]()。 ## 使用约束与社区注意事项 `lan` 子系统的"不联网"特性是其最重要的设计契约。任何在生产中尝试绕过 `policy.py` 或 `sanitize.py` 的使用方式，都违背了 v0.8.0 引入的安全核心意图。建议在以下场景中显式启用： 1. 需要对内部 MCP/AI 资产盘点暴露面时； 2. CI 中希望对 host 配置的网络端点做静态策略审计时； 3. 与 SARIF 平台对接、希望以统一 schema 消费发现结果时。 如需在受控实验环境中验证其行为，可结合 v1.4.0 引入的 network-lab runbook 与 config anonymizer 进行端到端 dogfood。资料来源：[src/mcpscan/lan/sanitize.py:1-50](), [src/mcpscan/lan/audit.py:1-90](), [release v1.4.0 notes]()。 --- ## 内部架构、引擎与扩展点 ### 相关页面 相关主题：[核心 scan 命令、检查项与 A–F 评分](#page-scan-checks)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcpscan/__init__.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/__init__.py) - [src/mcpscan/engine.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/engine.py) - [src/mcpscan/domain.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/domain.py) - [src/mcpscan/scoring.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/scoring.py) - [src/mcpscan/enrichment/osv.py](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/src/mcpscan/enrichment/osv.py) - [docs/ARCHITECTURE.md](https://github.com/IRsoctierDT/ai-agentic-mcpscan/blob/main/docs/ARCHITECTURE.md)
# 内部架构、引擎与扩展点 ## 1. 总体定位与分层结构 `ai-agentic-mcpscan` 是一个面向 AI / MCP 资产的安全扫描器，自 v1.0.0 起被声明为稳定版本。仓库以 CLI 多命令（`inventory` / `atlas` / `lan` 等）形式对外暴露能力，内部按"数据模型 → 适配器 → 引擎 → 评分 → 富化 → 报告"的流水线组织。CLI 顶层入口与领域类型的统一导出由 `src/mcpscan/__init__.py` 提供（[src/mcpscan/__init__.py:1-40]()），保证外部脚本与 CLI 共用同一组类型。 设计原则与 ADR 记录在 `docs/ARCHITECTURE.md` 中（[docs/ARCHITECTURE.md:1-60]()），是扩展前应优先阅读的"宪法"。 ## 2. 核心领域模型 `domain.py` 定义了贯穿整条流水线的"通用语"，避免适配器之间的类型相互污染。围绕 MCP 配置，模型至少覆盖： - **Host / Server**：承载 MCP 的宿主（如 VS Code、Zed）及其注册的服务器条目。 - **Tool / Scope**：工具清单与作用域（scope），是判定"过度宽泛授权"的依据（v0.5.0 引入的 `--fix` 正是作用于该层）。 - **Network endpoint**：网络端点，供 `lan` 命令在安全核心内做静态分析。 - **Finding**：扫描结果载体，含严重级别、规则 ID、可选 SARIF logical location（v1.3.0 引入，ADR-16）。 领域类型以 dataclass / pydantic 形式集中于 `domain.py`（[src/mcpscan/domain.py:1-120]()），由 `__init__.py` 重新导出。 ## 3. 引擎流水线与安全核心 `engine.py` 是执行编排核心，为每条命令构造独立流水线。下表总结了典型阶段： | 阶段 | 输入 | 输出 | 关键约束 | | --- | --- | --- | --- | | 加载 | 宿主配置路径 | `Host/Server/Tool` 集合 | 由适配器决定解析方式 | | 检测 | 领域对象 | `Finding` 列表 | 规则集决定覆盖范围 | | 富化 | `Finding` | 附加元数据（CVE 等） | 通过 `enrichment/` 注册 | | 评分 | `Finding` | 严重级别归一化 | 策略由 `scoring.py` 提供 | | 报告 | 归一化 `Finding` | SARIF 2.1.0 / 终端 | 支持 GitHub Code Scanning | 阶段串联的入口逻辑位于 `engine.py`（[src/mcpscan/engine.py:1-200]()），`scoring.py` 提供与规则解耦的评分策略（[src/mcpscan/scoring.py:1-80]()）。 `lan` 命令在 v0.8.0 引入了"Phase A 安全核心"，要求显式授权且禁止任何出站网络；v0.9.0 将其接入 CLI。该安全核心作为 `lan` 流水线的子模块实现，与通用引擎解耦，从而保证可独立单元测试与替换。 ## 4. 扩展点 扩展点主要分布在三个位置，新增能力应优先围绕它们展开： 1. **适配器（Adapters）**：新增宿主只需实现"读取配置 → 产出领域对象"协议。v0.6.0 增加 VS Code 宿主，v0.7.0 增加 Zed + JSONC 支持。 2. **富化器（Enrichment）**：位于 `src/mcpscan/enrichment/`，默认提供 `osv.py` 用于对接 OSV 漏洞数据库（[src/mcpscan/enrichment/osv.py:1-120]()），其他数据源可通过相同接口接入。 3. **报告器（Reporters）**：SARIF 输出由独立报告器实现，v0.4.0 引入 SARIF 2.1.0 + Code Scanning workflow，v1.3.0 补充 logical location 字段。 新增命令（如 v1.1.0 的 `inventory`、v1.2.0 的 `atlas` Tier-2）遵循同样的"engine 编排 + 适配器/富化/报告可选注入"模式，保证上层命令不会破坏底层契约。 --- --- ## Doramagic 踩坑日志 项目：IRsoctierDT/ai-agentic-mcpscan 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/IRsoctierDT/ai-agentic-mcpscan | host_targets=mcp_host, claude, cursor ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/IRsoctierDT/ai-agentic-mcpscan | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/IRsoctierDT/ai-agentic-mcpscan | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/IRsoctierDT/ai-agentic-mcpscan | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/IRsoctierDT/ai-agentic-mcpscan | release_recency=unknown