无需重编译扩展检测能力:AgentShield 外部规则包(rule-pack)开发教程
无需重编译扩展检测能力:AgentShield 外部规则包(rule-pack)开发教程
AgentShield 是一款面向 AI agent 配置的安全扫描工具,内置 102 条检测规则。通过外部规则包(rule-pack),你可以在不修改源码、不重新编译的前提下,用一份 JSON 正则文件扩展检测能力,把团队私有安全基线、行业威胁情报一并纳入扫描。本文用 5 分钟带你从零写出第一个 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。
