security-suite

安全套件

用途： 为已获授权的二进制文件和由代码仓库管理的提示词界面提供可组合、可重复的安全与内部测试基础操作。

此技能将职责拆分为基础操作，让安全工作流易于测试和复用。

防护措施

• 仅对你拥有或明确获准评估的二进制文件使用。
• 不要使用此工作流来规避法律限制，或在未经授权的情况下提取第三方专有内容。
• 优先采用行为保证和策略门控，而不是临时的一次性逆向工程。

基础操作模型

1. collect-static — 文件元数据、运行时启发式分析、链接库、嵌入式归档签名。
2. collect-dynamic — 沙箱化执行跟踪（进程、文件更改、网络端点）。
3. collect-contract — 通过探测帮助界面生成机器可读的行为契约。
4. compare-baseline — 比较当前契约与基线之间的变化（新增/移除的命令、运行时变化）。
5. enforce-policy — 允许列表/拒绝列表门控和基于严重程度的判定。
6. collect-redteam — 对代码仓库界面进行离线攻击包扫描，检查提示词注入、工具误用、秘密信息外泄和不安全 Shell 回归。
7. run — 精简的二进制编排器，用于组合基础操作并写入套件摘要。

快速开始

单次运行（默认动态命令为 --help）：

python3 skills/security-suite/scripts/security_suite.py run \
  --binary "$(command -v ao)" \
  --out-dir .tmp/security-suite/ao-current

基线回归门控：

python3 skills/security-suite/scripts/security_suite.py run \
  --binary "$(command -v ao)" \
  --out-dir .tmp/security-suite/ao-current \
  --baseline-dir .tmp/security-suite/ao-baseline \
  --fail-on-removed

策略门控：

python3 skills/security-suite/scripts/security_suite.py run \
  --binary "$(command -v ao)" \
  --out-dir .tmp/security-suite/ao-current \
  --policy-file skills/security-suite/references/policy-example.json \
  --fail-on-policy-fail

代码仓库界面红队测试：

python3 skills/security-suite/scripts/prompt_redteam.py scan \
  --repo-root . \
  --pack-file skills/security-suite/references/agentops-redteam-pack.json \
  --out-dir .tmp/security-suite-redteam

有关 OWASP Top 10 代码级审查，请参阅 references/owasp-checklist.md。

推荐工作流

1. 在已知良好的版本上捕获基线。
2. 在 CI 中对候选二进制文件运行套件。
3. 与基线比较并执行策略。
4. 出现未通过的判定时，阻止晋级。

输出契约

所有输出均写入 --out-dir 下：

• static/static-analysis.json
• dynamic/dynamic-analysis.json
• contract/contract.json
• compare/baseline-diff.json（提供基线时）
• policy/policy-verdict.json（提供策略时）
• suite-summary.json
• redteam/redteam-results.json（运行代码仓库界面红队测试时）

此输出结构特意设计为可供 CI 门控以机器方式读取。

策略模型

请将 skills/security-suite/references/policy-example.json 用作起点。

支持的检查项：

• required_top_level_commands
• deny_command_patterns
• max_created_files
• forbid_file_path_patterns
• allow_network_endpoint_patterns
• deny_network_endpoint_patterns
• block_if_removed_commands
• min_command_count

红队测试包模型

请将 agentops-redteam-pack.json 用作离线代码仓库界面红队检查的起点。

支持的目标字段：

• globs
• require_groups
• forbidden_any
• applies_if_any

每个测试用例都描述一个具体的对抗性提示词或操作员绕过尝试，并将其绑定到一个或多个由代码仓库管理的文件。首个随附测试包涵盖指令优先级、上下文过度暴露、破坏性 Git 误用、安全门控绕过，以及不安全 Shell 或秘密信息处理回归。

技术覆盖范围

此套件旨在适用于广泛的二进制文件类型，而不仅仅是 CLI 元数据：

• 静态运行时/库指纹识别
• 沙箱化行为观察
• 命令/契约捕获
• 变化分类
• 策略执行和 CI 判定
• 检查提示词和操作员契约回归的代码仓库界面红队测试

套件采用模块化设计，因此你以后可以添加更深入的基础操作（系统调用跟踪、SBOM 证明验证、模糊测试框架），而无需重写工作流。

验证

运行：

bash skills/security-suite/scripts/validate.sh
bash tests/scripts/test-security-suite-redteam.sh

冒烟测试（推荐）：

python3 skills/security-suite/scripts/security_suite.py run \
  --binary "$(command -v ao)" \
  --out-dir .tmp/security-suite-smoke \
  --policy-file skills/security-suite/references/policy-example.json

代码仓库界面冒烟测试：

python3 skills/security-suite/scripts/prompt_redteam.py scan \
  --repo-root . \
  --pack-file skills/security-suite/references/agentops-redteam-pack.json \
  --out-dir .tmp/security-suite-redteam-smoke

示例

场景：捕获基线并为新版本设置门禁

用户说： /security-suite run --binary $(command -v ao) --out-dir .tmp/security-suite/ao-v2.4

执行内容：

1. 套件针对 ao 二进制文件运行静态分析（文件元数据、链接库、嵌入式归档签名）、动态跟踪（在沙盒中执行 --help，观察进程、文件变更和网络端点）以及契约捕获。
2. 套件会在输出目录下写入 static/static-analysis.json、dynamic/dynamic-analysis.json、contract/contract.json 和 suite-summary.json。

结果： 捕获完整的 ao v2.4 基线快照，可在未来版本比较中用作 --baseline-dir。

场景：使用基线和策略设置 CI 回归门禁

用户说： /security-suite run --binary ./bin/ao-candidate --out-dir .tmp/ao-candidate --baseline-dir .tmp/security-suite/ao-v2.4 --policy-file skills/security-suite/references/policy-example.json --fail-on-removed --fail-on-policy-fail

执行内容：

1. 套件对候选二进制文件运行全部三种采集原语，然后将生成的契约与 v2.4 基线进行比较，生成 compare/baseline-diff.json，其中包含新增、移除或变更的命令。
2. 套件会评估策略文件中的检查项（必需命令、拒绝模式、网络允许列表、文件限制），并写入 policy/policy-verdict.json，其中包含通过/失败判定。

结果： 如果有命令被移除或策略检查失败，套件将以非零状态码退出，从而阻止候选版本在 CI 流水线中晋级。

场景：离线红队测试仓库的提示词和技能攻击面

用户说： /security-suite collect-redteam --repo-root .

执行内容：

1. 红队扫描器从 agentops-redteam-pack.json 加载攻击包，并针对具体攻击案例评估仓库自有的控制面。
2. 它会在所选输出目录下写入 redteam/redteam-results.json 和 redteam/redteam-results.md；如果有严重级别为 fail 的案例未被抵御，则以非零状态码退出。

结果： 无需托管模型扫描，仓库即可获得针对提示词注入、工具误用、上下文过度暴露、密钥处理和不安全 Shell 回归的确定性红队判定。

故障排除

问题	原因	解决方案
套件以非零状态码退出，但没有明确的问题说明	--fail-on-removed 或 --fail-on-policy-fail 因合理变更而触发	查看 compare/baseline-diff.json 和 policy/policy-verdict.json，确定具体差异，然后相应地更新基线或策略文件。
dynamic/dynamic-analysis.json 为空或内容很少	二进制文件需要 --help 之外的参数，或沙盒阻止了执行	如果支持，请提供自定义动态命令；或者确认二进制文件能在沙盒环境中运行（检查权限和缺失的共享库）。
contract/contract.json 显示命令数为零	二进制文件没有提供 --help 界面，或使用了非标准帮助标志	确认二进制文件支持 --help；对于帮助界面特殊的二进制文件，请使用正确的调用方式单独运行 collect-contract。
策略判定因 deny_command_patterns 而失败	新子命令匹配了策略文件中的拒绝正则表达式	可以重命名该子命令，或更新策略 JSON 中的 deny_command_patterns，排除合理的匹配模式。
未生成 baseline-diff.json	未提供 --baseline-dir，或该参数指向不存在的目录	确保基线目录存在，并包含此前运行生成的有效 contract/contract.json。
清理措辞后红队扫描失败	攻击包不再匹配目标文件中预期的防护措施措辞	查看 redteam/redteam-results.json，确认是控制措施退化还是正则表达式过于脆弱，然后有意更新目标文件或攻击包。

参考文档

• references/security-suite.feature — 可执行规范：可组合原语（静态／动态／契约）→ security-report.json，受授权范围约束，面向供应商的氛围（soc-qk4b）

• references/owasp-checklist.md

• references/agentops-redteam-pack.json

• references/policy-example.json