企业官网建设流程全解析

AgentShield 是一个开源的AI agent 安全扫描器（AI agent security scanner），用 TypeScript 编写，专门扫描 Claude Code 等 AI agent 配置中的硬编码密钥、权限过度开放、hook 注入和 MCP 服务器风险。本文带你深入源码，逐层拆解它的扫描器架构与核心实现原理，帮助 TypeScript 开发者快速理解一个生产级安全扫描工具的完整设计。

一、AgentShield 是什么：102 条规则的安全引擎

AgentShield 的用法极简——一条命令扫描整个.claude/目录：

npx ecc-agentshield scan

它会输出一份 0–100 分的评分报告（A–F 等级），覆盖102 条规则、5 大类别：

仓库自带了可直接扫描的"靶场"：examples/vulnerable/，运行npm run scan:demo就能立即看到完整报告效果。

二、整体架构：一次 Scan 的完整路径

AgentShield 的源码组织非常清晰，整个扫描流程是一条单向管线，数据只向前流动：

CLI 入口 (commander) ↓ 文件发现 (scanner/discovery.ts) ↓ 规则执行 (rules/*.ts，102 条规则) ↓ Finding 标注 (source-context.ts 置信度分类) ↓ 评分引擎 (reporter/score.ts) ↓ 多格式渲染 (reporter/：终端 / JSON / HTML / SARIF)

各模块职责一目了然，核心目录结构如下：

三、源码逐层拆解：扫描管线的 4 个阶段

3.1 文件发现：如何找到所有该扫的文件

入口函数 discoverConfigFiles 是整个管线的起点，它做了几件精巧的事：

• 跳过噪声目录：内置IGNORED_DIRS黑名单（node_modules、dist、.git等 13 个目录），避免扫描生成物导致结果重复；
• 多根目录探测：通过CLAUDE_ROOT_MARKERS（claude.md、settings.json、mcp.json等文件名）自动识别仓库中所有.claude/根，而不是只扫顶层目录；
• 悬空符号链接检测：一个指向不存在的 skill 符号链接，意味着 agent 认为自己有某个能力但实际解析不到——这种"幽灵技能"会被直接产出为一条 Finding。

每个文件被发现时都被赋予了ConfigFileType（claude-md、settings-json、mcp-json、hook-script等），后续规则会依据这个类型决定是否参与检查。

3.2 规则注册：一个函数装下 100+ 条规则

所有内置规则由 getBuiltinRules 统一导出——它只是把 10 个规则文件的数组展开拼接：

return [ ...secretRules, // 10 条 ...permissionRules, // 10 条 ...hookRules, // 34 条 ...mcpRules, // 23 条 ...agentRules, // 25 条 ... ];

每条规则本质是一个"声明式对象 + 检查函数"的配对。以密钥检测 src/rules/secrets.ts 为例，核心就是一张正则模式表：

{ name: "anthropic-api-key", pattern: /sk-ant-[a-zA-Z0-9_-]{20,}/g, description: "Anthropic API key", },

这种"数据驱动"的设计让新增规则零成本。更妙的是外部规则包机制：src/rules/external.ts 支持--rule-pack参数加载社区 JSON 规则包，与内置规则同样参与评分——但加载时采用fail-closed策略：JSON 非法、schema 不合规、正则无法编译，扫描直接中止而非静默跳过。

3.3 评分引擎：从 Finding 到 A–F 等级

calculateScore 采用扣分制：从 100 分起步，每个 Finding 按严重程度扣分：

总分是 5 个类别分数的平均值，再映射为等级（≥90 为 A，<40 为 F）。

评分引擎最有价值的部分是置信度折扣（confidenceWeight）：并非所有 Finding 都同等可信。扫描器先通过 source-context.ts 判断文件来源——

• 在docs/、examples/等示例路径下发现的模板文件，扣分权重降至0.25，且单文件单类别上限 10 分，防止一个 MCP 目录文件"刷分"；
• settings.local.json这类项目本地配置降权至0.75；
• 插件缓存和插件清单降权至0.5；
• 但真实密钥永不降权——即使是文档里的密钥泄露也保持满额扣分。

这套"来源感知"机制（runtimeConfidence字段）是 AgentShield 控制误报的核心设计，值得做静态分析工具的同学重点阅读。

3.4 多格式输出：一份数据，五种渲染

扫描结果统一汇入SecurityReport类型，由 src/reporter/ 下的独立渲染器分别消费：terminal.ts（彩色终端）、json.ts（CI 管道）、html.ts（自包含高管报告）、sarif.ts（GitHub 代码扫描标准格式）。渲染器之间零依赖，新增输出格式只需实现一个渲染函数。

四、TypeScript 实现亮点：4 个值得学习的工程细节

4.1 不可变优先的类型建模

Rule 接口 定义了整个规则引擎的契约——每条规则是一个纯函数式对象：

export interface Rule { readonly id: string; readonly severity: Severity; readonly check: ( file: ConfigFile, allFiles?: ReadonlyArray<ConfigFile> ) => ReadonlyArray<Finding>; }

readonly+ReadonlyArray贯穿全库（src/types.ts 中Finding、SecurityReport均为不可变结构），类型系统在编译期就阻止了对扫描结果的意外篡改。

4.2 Zod Schema 校验不可信输入

外部规则包通过 RulePackSchema 做运行时校验，z.enum严格限定严重程度和类别枚举值，并限制单规则单文件最多 200 条 Finding 以防御病态规则包。"对外部输入 fail-closed"是安全工具的第一原则。

4.3 动态模块懒加载

CLI 入口 对注入测试、沙箱、污点分析等重模块采用await import()+ try/catch 懒加载：

const { runInjectionSuite } = await import("./injection/index.js");

好处有二：基础扫描不受扩展模块拖累，且某个可选模块损坏时扫描主流程依然可用。这是 CLI 工具隔离可选功能的典型模式。

4.4 tsup 双入口构建策略

tsup.config.ts 定义了两种截然不同的构建目标：

• CLI / 库入口：依赖保持 external，由 npm 消费者自行安装；
• GitHub Action 入口：通过noExternal把所有运行时依赖内联进单文件——因为 Action runner 执行的检出目录没有node_modules，还特别用 banner 注入createRequire解决 CJS 依赖在 ESM bundle 中的require("process")崩溃问题。

这份构建配置是"同一份代码，多种分发形态"的绝佳范例。

五、快速上手阅读：推荐三步阅读路径

1. 先读类型：通读 src/types.ts，Finding、Rule、SecurityReport三个接口就是全局地图；
2. 跟主线跑一遍：从 src/index.ts 的scan命令 → scan() →getBuiltinRules()→calculateScore()，20 分钟走完主链路；
3. 跑真实用例：npm run scan:demo扫描内置脆弱示例，配合 tests/ 下 60+ 个测试文件（每个规则家族都有回归测试）理解边界行为。

想验证规则准确性？仓库还内置了攻击语料库（--corpus-gate），CI 中强制要求所有已知攻击向量保持可检出。

六、总结

AgentShield 的源码是一次 TypeScript 工程实践的完整展示：数据驱动的规则引擎让 102 条检测规则保持可维护，来源感知评分优雅地平衡了检出率与误报，不可变类型建模保证了数据流的确定性，而fail-closed 校验与懒加载则体现了安全工具的审慎姿态。无论你是想做静态分析工具、CLI 框架，还是学习 TypeScript 类型设计，这个代码库都值得花时间精读。