无需重编译扩展检测能力:AgentShield 外部规则包(rule-pack)开发教程

原创2026-10-13 23:03:581,407 阅读

无需重编译扩展检测能力:AgentShield 外部规则包(rule-pack)开发教程

AgentShield 是一款面向 AI agent 配置的安全扫描工具,内置 102 条检测规则。通过外部规则包(rule-pack),你可以在不修改源码、不重新编译的前提下,用一份 JSON 正则文件扩展检测能力,把团队私有安全基线、行业威胁情报一并纳入扫描。本文用 5 分钟带你从零写出第一个 rule-pack,并掌握作用域限定、多包加载与校验机制。

AgentShield AI agent 安全扫描工具外部规则包 rule-pack 开发教程

一、什么是外部规则包(rule-pack)

AgentShield 的内置规则是「声明式」的——每条规则就是一行 id / severity / category / pattern。外部规则包复用了完全相同的结构,只是把它写进一个 JSON 文件,用 --rule-pack 参数加载即可。

  • 零改动上线:无需改代码、无需编译,一个文件即可生效
  • 社区 / 私有复用:支持 MIT 协议的 Agent Threat Rules 之类的公开规则包
  • 计入总分:外部命中会与内置规则一起参与 A–F 评级
# 单个规则包
agentshield scan --rule-pack ./my-pack.json

# 可重复,一次加载多个包
agentshield scan --rule-pack ./pack-a.json --rule-pack ./pack-b.json

扫描启动时会打印 Loaded N external rules from <name>,确认规则包已生效。

二、为什么「不改代码」也能加规则

扫描器在运行时把内置规则与外部规则拼接后统一执行:

rules = [ ...内置规则, ...外部规则包规则 ]

加载逻辑集中在 src/rules/external.ts,加载后作为 extraRules 传入扫描编排 src/scanner/index.ts。换句话说,你写的是「数据」而不是「程序」——只要 JSON 合法,扫描器就能执行。

三、rule-pack JSON 结构速查表

一个 rule-pack 文件的最小可用版本如下:

{
  "version": 1,
  "name": "my-pack",
  "rules": [
    {
      "id": "tool-poisoning-001",
      "name": "工具描述投毒",
      "description": "工具描述中隐藏的注入指令",
      "severity": "high",
      "category": "injection",
      "patterns": ["ignore (?:all )?previous instructions"],
      "fileTypes": ["agent-md", "claude-md"]
    }
  ]
}
字段 层级 必填 说明
version 包 是 固定为 1
name 包 否 包名,用于加载日志
rules 包 是 规则数组,至少 1 条
id 规则 是 唯一标识,包内不可重复
name 规则 是 规则标题,展示在报告中
severity 规则 是 critical / high / medium / low / info
category 规则 是 见下方分类表
patterns 规则 是 JS 正则数组,至少 1 条
flags 规则 否 正则标志,如 i(忽略大小写)
fileTypes 规则 否 限定作用的文件类型

可用的 category 分类:

分类 含义 分类 含义
secrets 密钥泄露 mcp MCP 服务器
permissions 权限配置 skills 技能配置
hooks 钩子注入 agents 智能体配置
injection 提示注入 exposure / exfiltration 暴露 / 数据外泄
misconfiguration 错误配置

fileTypes 作用域类型(合法取值见 src/types.ts):claude-md、settings-json、mcp-json、agent-md、skill-md、hook-script、hook-code、package-manager-config、rule-md、context-md、unknown。不填 fileTypes 时,规则会对所有配置类型生效。

四、作用域限定、多正则与匹配细节

  • 限定文件类型:fileTypes: <a href="https://link.gitcode.com/i/de4f68d23de140b33a647c337283a42c" target="_blank">"mcp-json"] 让规则只扫描 MCP 配置,避免误报,行为见 [tests/rules/external.test.ts。
  • 多条正则:patterns 是数组,任一条命中即产生一条结果。
  • 全局匹配:加载器会自动补上 g 标志(见 src/rules/external.ts),同段文本出现 3 次就报告 3 条,且每条 id 唯一。
  • 结果封顶:单条规则在单个文件内最多 200 条结果,防止病态规则拖垮扫描。
  • 行号定位:命中会自动计算行号,并截取最多 100 字符证据(见 src/rules/external.ts)。

五、一次加载多个规则包

--rule-pack 可重复使用,多个包的规则会拼接后一起运行(见 src/rules/external.ts)。

⚠️ 注意:不同包之间出现相同 id 会直接报错中断,以避免规则来源混淆。请为每个团队 / 场景的包使用带前缀的唯一 id(如 team-a-001)。

六、校验机制与常见报错(fail-closed)

rule-pack 采用「失败即关闭」的校验策略:任何一步出错,整次扫描立即中止并报错,绝不带病运行(校验实现见 src/rules/external.ts)。

报错信息 触发原因
Rule pack not found: <path> 文件不存在
Invalid rule pack <path>: ... JSON 格式错误 / schema 不匹配
Duplicate rule id in pack: <id> 包内 id 重复
Duplicate rule id across packs: <id> 多包之间 id 冲突
Rule "<id>" has an invalid pattern: ... 正则无法编译

排查顺序:先修 JSON 语法 → 核对 severity / category 是否在合法取值内 → 最后检查正则。

七、最佳实践清单

  • ✅ 用短而精确的正则,避免宽泛匹配造成误报
  • ✅ 用 fileTypes 收窄作用域,只扫描真正相关的文件
  • ✅ 为 id 加团队 / 场景前缀,保证多包共存不冲突
  • ⚠️ 避免复杂回溯正则(ReDoS 防护是 v1 已知限制,见 src/rules/external.ts)
  • ✅ 用 examples/vulnerable/ 的示例配置本地自测,例如 injector.md 就含「ignore all previous instructions」这类注入文案,正好用来验证 injection 类规则

八、接入 CI 与 GitHub Action

外部规则包是纯本地文件,与内置能力完全兼容,可直接并入 CI 流程:

# 结合 JSON 输出,喂给自动化
agentshield scan --rule-pack ./my-pack.json --format json

# 结合 SARIF,上传到代码扫描
agentshield scan --rule-pack ./my-pack.json --format sarif --output agentshield.sarif

配合 --format json 的 findings[].id(外部规则结果以 external- 开头),即可在流水线里精确追踪你的自定义检测命中。

九、相关模块与文档

模块 路径 作用
规则包加载器 src/rules/external.ts 校验、编译、运行外部规则
扫描编排 src/scanner/index.ts 合并内置与外部规则执行
文件类型定义 src/types.ts fileTypes 合法取值
内置规则注册 src/rules/index.ts 对照内置规则写法
加载器测试 tests/rules/external.test.ts 校验各分支行为
参考示例 examples/vulnerable/ 本地自测用漏洞配置

完整的 --rule-pack 用法说明见 README.md,版本演进见 CHANGELOG.md。

登录后查看全文
agentshield