Agent Compliance 安全扫描与豁免体系实战:基于 agent-governance-toolkit 的 AI Agent 代码合规治理指南

原创2026-09-16 14:26:142,230 阅读
文章标签:人工智能AI 安全治理可信 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() 依序执行五类扫描:

  1. scan_secrets():调用 detect-secrets scan <dir> --all-files,解析其 JSON 输出(results 键),命中即生成 critical 级 secrets finding(CWE-798);检测到 sk_test_、test_key、mock_token、fake_secret、dummy_password、example.com、localhost、127.0.0.1 等 ALLOWED_TEST_PATTERNS 的测试凭据会被放行(scanner.py)。
  2. 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 级别生成 cve finding,并给出修复建议 Update to <pkg>>=<fix_version>([scanner.py)。
  3. scan_node_dependencies():若存在 package.json 则在插件目录内执行 npm audit --json,将 npm 的 critical/high/moderate/low 映射为本系统的四级严重度(scanner.py)。
  4. scan_code_patterns():调用 bandit -r <dir> -f json -ll 做 Python SAST,跳过 low-confidence 结果,并将 bandit 规则 ID(如 B201、B307、B506)映射为具体修复建议(scanner.py)。
  5. 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)按顺序执行三种匹配:

  1. 精确匹配:category + file + line 三者完全一致(line 非空);
  2. 类别 + 文件匹配:category 一致且 file 一致、line 为空——表示该文件内任意行命中即豁免;
  3. 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 即围绕这些维度展开,并包含多组回归测试:

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+ 个测试用例——它们是这套治理逻辑最精确的行为规格。

登录后查看全文
agent-governance-toolkit