一、项目定位与核心目标

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 描述。典型安装流程：

# 从源码安装（推荐用于本地开发与 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 分层 组织：

子命令注册与参数解析统一在 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 条目。

六、典型使用流程

flowchart LR
    A[安装 mcpscan] --> B[选择子命令]
    B --> C1[inventory<br/>Tier-1 清单]
    B --> C2[atlas<br/>Tier-2 映射]
    B --> C3[lan<br/>安全核审计]
    B --> C4[scan<br/>默认扫描]
    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 报告、适配器层）。

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

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）累加，并按预设阈值映射到字母等级：

评分器在遇到 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

面向 MCP 服务器与本地 AI Agent 环境的本地优先、默认离线安全态势扫描器（命令行工具：mcpscan）。

概述与设计目标

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）两部分组成：

域层 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

整体流程可概括为下图：

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

概述

ai-agentic-mcpscan 的"资产清单与安全框架映射"由两条分层命令组成，构成 v1.0.0 稳定版之后的能力矩阵：

• Tier-1 资产清单（mcpscan inventory）：自 v1.1.0 起引入（#49），用于枚举本机/工作区内的 AI 与 MCP 相关资产，作为后续策略评估与合规映射的输入基线。
• Tier-2 框架映射（mcpscan atlas）：自 v1.2.0 起引入（#51），将 Tier-1 输出映射到 OWASP / NIST 等安全控制框架，形成可审计的合规视图。

两者形成"发现 → 归类 → 映射"的两阶段流水线，全程为本地静态扫描，不发起远程网络请求，与 mcpscan lan Phase A 的"无网络"安全约束一致。

Tier-1 资产清单（inventory）

模块职责

src/mcpscan/inventory/ 子包按职责横向拆分，便于单独扩展与测试：

各模块的协作边界遵循"输入纯函数化、副作用只在 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）。

数据流

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 完成自动化门禁，形成完整的"识别—评估—阻断"闭环。

1. 概述与设计目标

mcpscan 的"漂移检测 + SARIF + CI 集成"组合，将 MCP/AI 主机的资产扫描结果转成可在 CI 流水线中消费的标准化安全信号。该能力由两个职责清晰的子模块组成：

• 漂移检测（drift）：以基线（baseline）作为已知安全状态，将新一次扫描得到的快照（snapshot）与基线对比，识别新增、变更或消失的 AI/MCP 资产项。
• SARIF 报告（report/sarif）：把扫描结果序列化为 SARIF 2.1.0 规范，便于 GitHub Code Scanning 等平台直接渲染。

社区演进路径印证了该方向：在 v0.4.0 中引入"SARIF 2.1.0 输出与 code-scanning workflow"（#28），并在 v1.3.0 中进一步为网络端点类发现补齐 SARIF logical locations（ADR-16）。

资料来源：src/mcpscan/drift/baseline.py:1-40，src/mcpscan/report/sarif.py:1-40

2. 漂移检测模块架构

漂移模块按"模型—快照—基线—对比—渲染"分层组织，每个文件单一职责：

该分层使"扫描→快照→基线→对比→渲染"形成单向数据流，避免对比逻辑直接依赖 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 上报的端到端流程：

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 是 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 入口到审计输出的典型调用链：

flowchart LR
    A[CLI: mcpscan lan] --> B[policy.py<br/>授权校验]
    B --> C[scope.py<br/>范围裁剪]
    C --> D[manifest.py<br/>端点清单生成]
    D --> E[sanitize.py<br/>敏感字段清理]
    E --> F[budgets.py<br/>预算与节流]
    F --> G[audit.py<br/>审计与 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 结果的典型字段映射：

版本演进要点

• 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。

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 是执行编排核心，为每条命令构造独立流水线。下表总结了典型阶段：

阶段串联的入口逻辑位于 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 编排 + 适配器/富化/报告可选注入"模式，保证上层命令不会破坏底层契约。

Pitfall Log / 踩坑日志

项目：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