Agent Compliance 安全扫描与豁免体系实战:基于 agent-governance-toolkit 的 AI Agent 代码合规治理指南
Agent Compliance 安全扫描与豁免体系实战:基于 agent-governance-toolkit 的 AI Agent 代码合规治理指南
导读
Agent Compliance(agent-governance-toolkit)是 Agent Governance Toolkit 生态中的合规包,为 AI Agent 系统提供运行时策略执行与安全扫描两大核心能力。本文以其开发指南 AGENTS.md 为主线,结合仓库源码深入讲解安全扫描引擎的扫描范围、严重级别阻断策略、.security-exemptions.json 豁免机制,以及本地构建、测试、代码风格与外部安全工具(detect-secrets、pip-audit、npm audit、bandit)的集成方式。读完本文,你将能够独立运行安全扫描、正确配置豁免文件,并把"临界/高危阻断合并、中低危仅告警"的治理策略落地到自己的 Agent 项目中。
一、Agent Compliance 的定位与核心能力
Agent Compliance(包名 agent-governance-toolkit-compliance,见 pyproject.toml)确保 Agent 在组织合规边界与安全策略内运行。它面向的典型场景包括:插件市场审核、Agent 技能(skill)与智能体(agent)代码的 CI 安全扫描、依赖漏洞治理。
根据 AGENTS.md,其核心能力分为两块:
- 安全扫描(Security Scanning):自动化检测硬编码密钥(secrets)、依赖 CVE、危险代码模式与不安全操作;
- 运行时策略执行(Runtime Policy Enforcement):落实 OWASP ASI 2026 控制项与完整性校验。
值得说明的是,包内同时通过 agent-governance-toolkit、agent-governance、agent-compliance、agt 等多个 CLI 入口暴露能力(见 pyproject.toml),本文聚焦其中与安全扫描直接相关的部分。
关键源码文件
| 文件 | 职责 |
|---|---|
| src/agent_compliance/security/scanner.py | 安全扫描引擎:密钥、CVE、危险代码模式检测 |
| src/agent_compliance/security/schemas/security-exemptions.schema.json | 豁免文件的 JSON Schema 定义 |
| src/agent_compliance/security/schemas/security-exemptions.example.json | 豁免文件完整示例 |
| tests/test_security_scanner.py | 安全扫描器测试套件(覆盖 finding 创建、豁免匹配、模式检测、报告格式化) |
二、构建、测试与代码质量基线
2.1 安装与测试命令
开发模式下安装依赖并运行全部测试:
# 安装依赖(开发模式)
pip install -e ".[dev]"
# 运行全部测试
pytest tests/ -v
# 带覆盖率运行测试(含分支覆盖率,输出 HTML 报告)
pytest tests/ --cov=src/agent_compliance --cov-report=html --cov-branch
# 类型检查
pyright src/
# 静态检查与格式化
ruff check . --fix
ruff format .
按 AGENTS.md 的要求,提交前必须运行 pytest tests/ -v,且新代码的目标覆盖率应高于 90%。
2.2 代码风格约定
- 格式化/Lint:Ruff,行宽 100,目标 Python 3.10+(当前 pyproject.toml 声明
requires-python = ">=3.11",实际以仓库为准); - 类型检查:Pyright basic 模式,忽略缺失 stub;
- Docstring:公开 API 使用 Google 风格;
- 导入排序:按 stdlib → 第三方 → 一阶方 → 本地分组,字母序排列;
- 公开 API 必须有类型注解;简单数据结构用
dataclasses,校验繁重的用 Pydantic。
三、安全扫描:扫描范围与排除规则
3.1 扫描的文件类型
扫描引擎覆盖以下内容(见 scanner.py):
- Python 文件(
*.py) - JavaScript / TypeScript(
*.js、*.ts) - Shell 脚本(
*.sh、*.bash) - PowerShell(
*.ps1) - 依赖清单文件(
requirements.txt、package.json、pyproject.toml) - Markdown 中的代码块(针对 skills 与 agents,路径模式为
skills/**/SKILL.md与agents/**/*.md)
3.2 排除规则
扫描器通过 SECURITY_SCAN_EXCLUSIONS 元组维护一份 glob 排除清单(scanner.py),常见类别包括:
- 测试夹具:
**/tests/fixtures/**、**/test/fixtures/**、**/__tests__/mocks/**、**/test_data/**、**/*.test.py、**/*.spec.js、**/*.test.ts - 示例文件:
**/*.example.*、**/examples/**、**/samples/**、**/docs/examples/**、**/*.sample.*、**/*.template.* - 构建产物:
**/dist/**、**/build/**、**/node_modules/**、**/.venv/**、**/__pycache__/** - 文档:
**/README.md、**/CONTRIBUTING.md
这些 glob 模式会被 _glob_to_regex 转换为正则表达式:** 匹配零或多个路径组件(含 /),* 匹配任意非 / 字符,? 匹配单个非 / 字符。测试 tests/test_security_scanner.py 专门回归验证了嵌套 ** 的展开行为,例如 tests/fixtures/deep/case/data.py 与 pkg/sub/tests/fixtures/data.py 都会被排除,而 src/contests.py 这种"名称里含 tests 但不是路径组件"的文件仍会参与扫描。
3.3 严重级别与阻断策略
这是治理策略的核心。SEVERITY_CONFIG(scanner.py)定义了四级严重度与是否阻断合并:
SEVERITY_CONFIG = {
"critical": {"emoji": "🔴", "blocks": True, "description": "Immediate security risk"},
"high": {"emoji": "🟡", "blocks": True, "description": "Serious vulnerability"},
"medium": {"emoji": "🟠", "blocks": False, "description": "Security improvement recommended"},
"low": {"emoji": "🟢", "blocks": False, "description": "Best practice suggestion"},
}
文档中的判定口径为:
| 严重级别 | 是否阻断 | 典型触发 |
|---|---|---|
critical |
阻断(blocks: True) | 硬编码密钥、RCE、CVSS ≥ 9.0 |
high |
阻断(blocks: True) | 命令注入、SQL 注入、CVSS 7.0–8.9 |
medium |
不阻断(blocks: False) | 弱加密、CVSS 4.0–6.9 |
low |
不阻断(blocks: False) | 最佳实践建议、CVSS < 4.0 |
实现上,SecurityFinding.is_blocking() 直接查表返回 blocks 值(scanner.py),run_all_scans() 汇总后仅统计 blocking 项决定 passed 结果(scanner.py)。format_security_report() 在存在 critical/high 时输出 Exit code: 1 (blocking - PR cannot merge),仅有 medium/low 时输出 Exit code: 0 (warnings only - PR can merge)(scanner.py)。
3.4 各扫描通道的实现细节
SecurityScanner.run_all_scans() 依序执行五类扫描:
scan_secrets():调用detect-secrets scan <dir> --all-files,解析其 JSON 输出(results键),命中即生成critical级secretsfinding(CWE-798);检测到sk_test_、test_key、mock_token、fake_secret、dummy_password、example.com、localhost、127.0.0.1等ALLOWED_TEST_PATTERNS的测试凭据会被放行(scanner.py)。scan_python_dependencies():对requirements.txt使用pip-audit --requirement,对pyproject.toml使用pip-audit --file,解析 JSON 中的dependencies<a href="https://link.gitcode.com/i/a10bbec9df32f30ec46e3ba4eda314f3" target="_blank">].vulns,默认按high级别生成cvefinding,并给出修复建议Update to <pkg>>=<fix_version>([scanner.py)。scan_node_dependencies():若存在package.json则在插件目录内执行npm audit --json,将 npm 的 critical/high/moderate/low 映射为本系统的四级严重度(scanner.py)。scan_code_patterns():调用bandit -r <dir> -f json -ll做 Python SAST,跳过 low-confidence 结果,并将 bandit 规则 ID(如 B201、B307、B506)映射为具体修复建议(scanner.py)。scan_markdown_code_blocks():提取 skills/agents 的 Markdown 代码块,分别用内置正则检测危险模式——Python 的eval()/exec()/pickle.loads()/os.system()、JS 的eval()/new Function()/innerHTML=、Shell 的rm -rf /与curl ... | bash(scanner.py)。
一个值得注意的健壮性设计:所有工具集成在工具缺失时优雅跳过(shutil.which 探测,_tool_available 不执行任何子进程,见测试 test_tool_available_does_not_execute),detect-secrets 输出非 JSON 时也不会崩溃(test_handles_non_json_output)。
四、豁免系统:.security-exemptions.json
误报是安全扫描落地时必然面对的问题。豁免系统允许在受控条件下抑制特定 finding,同时通过严格的字段校验防止"恶意或格式错误的豁免绕过安全检查"。
4.1 配置文件结构
豁免文件位于被扫描目录根部的 .security-exemptions.json(AGENTS.md 给出的最小结构):
{
"version": "1.0",
"exemptions": [
{
"tool": "detect-secrets",
"file": "tests/fixtures/mock.py",
"line": 10,
"reason": "Test fixture with intentionally fake credentials",
"approved_by": "security-team"
}
]
}
security-exemptions.schema.json 定义了完整字段语义:
version:固定为"1.0"(顶层与每条豁免均要求version/exemptions键);tool:产生 finding 的工具,枚举为detect-secrets、pip-audit、npm-audit、bandit、semgrep;category:finding 类别,枚举为secrets、cve、code-pattern、injection、file-operation;file:相对插件根目录的文件路径;line为行号(≥1);fingerprint:detect-secrets 提供的唯一指纹;rule:工具规则 ID(如 bandit 的 B201);package/version/cve:依赖漏洞豁免定位信息,cve需匹配^CVE-\d{4}-\d{4,}$;reason:必填,豁免理由(minLength 10);approved_by:审批人(critical/high 要求);ticket:跟踪工单(critical/high 要求);temporary:是否临时豁免;若为true,必须提供expires(ISO 8601 日期)。
4.2 加载时的严格校验
SecurityScanner._load_exemptions()(scanner.py)在加载阶段执行以下校验,任一不满足即丢弃该条豁免:
- 顶层必须是含
exemptions列表的字典; - 每条豁免必须包含
category、file、justification、approved_by四个必填字段(注意:运行时实现要求的字段名是justification,而 Schema 与文档示例中使用reason,两者均见于仓库,配置时以你的扫描器版本实际行为为准); category必须属于secrets/cve/code-pattern;justification必须是长度 ≥ 10 的字符串;- 若带
expires字段,须为合法 ISO 8601 日期,且过期豁免在加载时即被过滤(测试 test_load_exemptions_expired_filtered_out 验证:2020-01-01过期条目被剔除,2099-12-31保留)。
4.3 豁免匹配的三种策略
_is_exempted()(scanner.py)按顺序执行三种匹配:
- 精确匹配:
category+file+line三者完全一致(line 非空); - 类别 + 文件匹配:
category一致且file一致、line 为空——表示该文件内任意行命中即豁免; - CVE 匹配:finding 的
cve与豁免的cve一致——跨所有文件生效。
对应测试覆盖了按文件+行精确匹配(test_is_exempted_by_file_and_line)、按类别+文件匹配(test_is_exempted_by_category)与按 CVE 匹配(test_is_exempted_by_cve)。
4.4 完整示例:三种典型豁免
仓库提供了覆盖三种场景的示例文件:
{
"version": "1.0",
"exemptions": [
{
"tool": "detect-secrets",
"file": "tests/fixtures/mock_credentials.py",
"line": 12,
"fingerprint": "abc123def456",
"reason": "Test fixture with intentionally fake credentials for unit tests",
"approved_by": "security-team"
},
{
"tool": "bandit",
"file": "server/dev_mode.py",
"line": 89,
"rule": "B201",
"reason": "Flask debug mode only enabled in dev environment via FLASK_ENV environment variable check",
"approved_by": "plugin-author",
"ticket": "ADO-12345"
},
{
"tool": "pip-audit",
"package": "requests",
"version": "2.25.0",
"cve": "CVE-2023-32681",
"reason": "Not exploitable in our usage pattern - only internal API calls, no proxy configuration",
"temporary": true,
"expires": "2026-06-30",
"ticket": "ADO-67890",
"approved_by": "security-guardian"
}
]
}
典型使用原则:测试夹具中的假凭据用"文件 + 行号"精确豁免;开发环境专用的 bandit 规则命中用 rule + ticket 走审批;依赖漏洞若在特定用法下不可利用,则使用临时豁免 + 过期时间强制定期复查。
五、测试要求与边界约束
5.1 测试要求
按 AGENTS.md,所有新功能必须配套测试;安全相关测试至少覆盖:finding 创建、豁免匹配、模式检测、格式化输出。仓库的 tests/test_security_scanner.py 即围绕这些维度展开,并包含多组回归测试:
- markdown 嵌套代码块解析不崩溃(test_scan_markdown_nested_code_blocks);
- 二进制/乱码文件优雅跳过(test_scan_binary_file_skipped);
- 仅含注释的 markdown 不产生 finding(test_scan_comments_only_file);
node_modules/.venv中的 vendored Python 文件不触发 bandit(TestScanCodePatternsVendoredExclusion)。
5.2 硬性边界
- 绝不提交密钥、凭据或 API Key;
- 未经审批绝不放松严重级别阻断阈值;
- 绝不跳过新功能的测试覆盖;
- 公开 API 保持向后兼容。
六、外部工具集成一览
| 工具 | 职责 | 触发文件 | 缺失时行为 |
|---|---|---|---|
| detect-secrets | 密钥检测 | 全部文件(--all-files) |
跳过并提示 |
| pip-audit | Python CVE 扫描 | requirements.txt、pyproject.toml |
跳过并提示 |
| npm audit | Node.js CVE 扫描 | package.json |
跳过并提示 |
| bandit | Python SAST | *.py |
跳过并提示 |
所有集成均通过 shutil.which 探测工具可用性,缺失即跳过对应扫描,保证在最小化 CI 环境中也能正常运行;_tool_available 明确不通过子进程探测(见 scanner.py 及对应回归测试),避免在 PATH 探测环节执行任意二进制。
七、提交规范
仓库采用 Conventional Commits:
feat(security): add support for shell script scanning
- Add _check_shell_code_block method
- Detect dangerous rm -rf patterns
- Add tests for shell code validation
常用类型前缀:feat:、fix:、docs:、test:、refactor:、chore:;带作用域时在括号内标注(如 feat(security)),正文逐条列出变更点。
结语
围绕 AGENTS.md 展开的这套安全扫描体系,用一条主线把"扫什么 → 什么级别 → 是否阻断 → 如何豁免 → 如何测试"串成了可执行的治理闭环:四级严重度阻断策略把噪声与风险分层,严格的豁免校验防止旁路滥用,外部工具缺失时优雅降级保证了 CI 的鲁棒性。无论是接入插件市场审核,还是为自己的 Agent 技能库建立安全门禁,这套设计都提供了现成的参考范式。想要深入验证每一项行为,可以直接阅读 tests/test_security_scanner.py 中的 25+ 个测试用例——它们是这套治理逻辑最精确的行为规格。