构建 Foundry 多智能体 AI 安全评估系统时，按…

需要从零实现可复现、可治理、多智能体协作的 agentic AI 安全评估与漏洞发现系统时使用。

适用场景

解决思路

1. 理解 Foundry 是 Cisco 的开放规范，不是安装工具；用它作为蓝图构建自己的安全评估系统，定义 8 个核心角色和 5 个扩展角色，协调发现、验证和报告安全发现。
2. 实现 8 个核心角色：Orchestrator、Planner、Navigator、Detector、Explorer、Validator、Investigator、Publisher；扩展角色按需增加。
3. 实现 finding lifecycle：状态、判决、证据门控和指纹。
4. 实现 coordination model：原子认领、心跳存活检测、自动阻塞。
5. 实现 governance：沙箱、预算、按产出自动停止、覆盖率门控。
6. 实现 detection-to-prevention flywheel：规则捕获已知问题，explorer 发现新问题，规则缺口转化为新规则。
7. 使用 CodeGuard rule format 编写可移植检测规则，使规则可在 evaluation 和 prevention 之间转移。
8. 按仓库结构使用文件：`spec.md` 是约 130 条功能需求的主规范，`constitution.md` 是 11 条不可违反原则，`GLOSSARY.md` 是术语参考，`README.md` 是实现指南。
9. 阅读 `constitution.md`，理解 11 条原则，尤其：无监督执行、证据门控发现、可复现性、原子进度、故障安全默认（卡住时升级或让出，绝不猜测）。
10. 安装 spec-kit：在项目目录运行 `npm install -g @github/spec-kit`，或按你的 coding agent 的 spec-kit 安装方式安装。
11. 在项目目录运行 `speckit init`，创建 `.specify/` 目录用于 spec-driven development。
12. 注册宪法：运行 `cp path/to/foundry-security-spec/constitution.md .specify/memory/constitution.md`，把 constitution 复制进 spec-kit memory。
13. 运行 `/speckit.constitution`，在提示时选择 adopt existing constitution。
14. 播种规格：运行 `mkdir -p specs/001-foundry`。
15. 运行 `cp path/to/foundry-security-spec/spec.md specs/001-foundry/spec.md`，复制 seed specification。
16. 运行 `/speckit.clarify`，回答身份与范围问题：系统名、是否满足 authorized evaluation with source access、8 个核心角色是合并/拆分/保持原样（首次实现建议保持原样）。
17. 回答集成选择问题：版本控制系统、issue tracker、LLM provider、datastore、隔离运行时、部署目标。
18. 回答策略选择问题：严重性分类、是否显示 needs-review findings、标签命名约定。
19. 回答扩展范围问题：首次构建建议不启用 Attack-Mapper、Regression-Tracker、Compliance-Mapper、Impact-Assessor、Remediation-Drafter。
20. 生成规格：运行 `/speckit.specify` 加固已澄清规格。
21. 再次运行 `/speckit.clarify`，重复直到没有 clarification 标记残留。
22. 实现：运行 `/speckit.plan` 生成技术设计。
23. 运行 `/speckit.tasks` 生成任务 backlog。
24. 运行 `/speckit.implement` 开始实现。
25. 实现 Orchestrator 的 `evaluate(target_repo)`：FR-001 创建 evaluation 记录，target=target_repo，status=running。
26. 在 `evaluate` 中：FR-010 让 Planner 创建计划并存储 claim。
27. 在 `evaluate` 中：FR-020 把工作分发给 detection 和 exploration。
28. 在 `evaluate` 中：FR-005 监控 heartbeats 和 budgets。
29. 在 `evaluate` 中：FR-006 完成前检查 coverage gate，若 coverage 小于 required_coverage 则抛出 InsufficientCoverageError。
30. 在 `evaluate` 中：完成后更新 evaluation 为 complete，并返回 eval_id、findings、coverage。
31. 在 `evaluate` 异常时：FR-008 将 evaluation 标记为 failed 并记录 error。
32. 实现 Orchestrator 的 `monitor_health(eval_id)`：每 30 秒循环检查。
33. 在 `monitor_health` 中：FR-007 用 heartbeat_threshold=300 查找 stalled claims，对每个 stalled claim 调用 block_claim，reason=heartbeat_timeout。
34. 在 `monitor_health` 中：FR-009 检查预算是否耗尽；若耗尽，将 evaluation 状态设为 budget_exhausted 并退出。
35. 实现 Detector：FR-030 用 `RuleEngine.load(rules_corpus_path)` 加载 CodeGuard rules。
36. 实现 Detector 的 `process_claim`：FR-031 从 claim 提取相关 code units。
37. 在 `process_claim` 中：FR-032 对每个 unit 运行 `rule_engine.evaluate(code=unit.content, context=unit.context, language=unit.language)`。
38. 在 `process_claim` 中：FR-033 把 rule hit 转为 Finding，包含 claim_id、rule_id、severity、weakness_id、location、evidence、verdict=confirmed、status=validated。
39. 在 `process_claim` 中：FR-034 记录 coverage。
40. 实现 Explorer：FR-040 生成 investigation hypotheses。
41. 实现 Explorer 的 `investigate_claim`：FR-041 在 isolated sandbox session 中执行 hypothesis 测试。
42. 在 `investigate_claim` 中：FR-042 只有 result.has_reproduction 为真才创建 Finding，否则不创建；Finding 使用 verdict=needs-validation、status=pending。
43. 在 `investigate_claim` 中：FR-043 检查规则是否本应检测到该 finding。
44. 在 `investigate_claim` 中：FR-044 记录 rule gap，包含 finding_id、weakness_id、pattern、reason、suggested_rule，并存入 rule_gaps。
45. 实现 Explorer 的 `generate_hypotheses`：用 LLM 生成 3-5 个安全假设，聚焦逻辑 bug、状态混淆、竞态条件和规则无法表达的上下文相关问题；temperature=0.7 用于创造性探索。
46. 实现 Explorer 的 `record_rule_gap`：创建 RuleGap，reason=explorer_found_missed_by_detector，调用 draft_rule 生成 suggested_rule。
47. 实现 Validator：FR-050 检查 evidence completeness；required 包含 location 和 description，critical/high 额外要求 reproduction_steps 和 impact。
48. 实现 Validator 的 `validate_finding`：FR-051 在 sandbox 中尝试复现；不可复现则返回 verdict=rejected，reason=not_reproducible。
49. 在 `validate_finding` 中：FR-052 验证 severity assessment；若实际 severity 不同，更新 finding.severity 并记录 severity_adjustment。
50. 在 `validate_finding` 中：FR-053 生成 fingerprint。
51. 生成 fingerprint：FR-054 组合 weakness_id、file_path、function_name、root_cause_pattern；用 `hashlib.sha256` 取前 16 位。
52. 实现 Validator 返回：verdict=confirmed、fingerprint、severity、reproduction_evidence=session.get_transcript()。
53. 实现 Publisher：FR-060 只发布 verdict=confirmed 的 finding；否则抛 ValueError。
54. 在 Publisher 中：FR-061 用 fingerprint 查已有 issue；若存在则返回已有 issue_id。
55. 在 Publisher 中：FR-062 按 tracker schema 格式化 issue body。
56. 在 Publisher 中：FR-063 用 POST 请求 tracker API 创建 issue，例如 Jira 的 `/rest/api/2/issue`，带 Authorization Bearer token 和 JSON body。
57. 在 Publisher 中：FR-064 用返回的 issue key 更新 finding.issue_id，设置 finding.status=published，并保存。
58. 配置 `config/evaluation.yaml`：设置 evaluation.name。
59. 配置 `config/evaluation.yaml` 的 orchestrator：max_concurrent_claims、heartbeat_interval、stall_threshold。
60. 配置 `config/evaluation.yaml` 的 budget：max_tokens、max_duration_hours、per_agent_token_limit。
61. 配置 `config/evaluation.yaml` 的 coverage：required_percentage、scope、exclude。
62. 配置 `config/evaluation.yaml` 的 agents：core 启用 8 个核心角色，extensions 首次为空。
63. 配置 `config/evaluation.yaml` 的 integrations：llm、vcs、issue_tracker、datastore。
64. 配置 `config/evaluation.yaml` 的 sandbox：runtime、network_isolation、timeout_seconds、resource_limits（cpu、memory）。
65. 配置 `config/detection.yaml`：rules_corpus、enabled_categories、severity_mapping、rule_gaps.enabled、rule_gaps.auto_draft_rules、rule_gaps.review_queue。
66. 配置 `config/detection.yaml` 的 enabled_categories 可包含 injection、authentication、authorization、cryptography、data-exposure、configuration。
67. 配置 `config/detection.yaml` 的 severity_mapping 示例：critical 映射 CWE-89、CWE-78、CWE-79；high 映射 CWE-306、CWE-862；medium 映射 CWE-327、CWE-338；low 映射 CWE-209、CWE-532。
68. 运行评估：加载配置，初始化 Orchestrator，传入 llm_client、finding_store、claim_store、budget_manager。
69. 调用 `orchestrator.evaluate(target_repo=https://gitlab.internal/acme/webapp)`，输出 eval_id、findings、coverage。
70. 实现 atomic claim processing：用 `try_claim(claim.id, self.agent_id)` 原子认领；未认领到则直接返回。
71. 在 atomic claim processing 中：启动 heartbeat_task 持续发送 heartbeats；成功完成后调用 `complete`；异常则调用 `fail` 不重试；finally 取消 heartbeat_task。
72. 实现 evidence-gated finding creation：若 issue 无 location，记录 warning 并跳过；若 issue 无 reproduction，记录 warning 并跳过。
73. 实现 evidence-gated finding creation：只有证据充分才返回 Finding，设置 verdict=needs-validation。
74. 实现 BudgetManager：`check_budget` 检查已用 tokens 加请求 tokens 是否超过 limit；超限则 notify_budget_exhausted 并返回 False。
75. 实现 BudgetManager：`record_usage` 向 token_usage 表插入 eval_id、tokens、timestamp。
76. 排错 agents 未发现问题：运行 `foundry-ctl list-rules --corpus /etc/foundry/rules/codeguard` 验证规则加载。
77. 排错 agents 未发现问题：运行 `foundry-ctl test-rule CWE-89 --file sample.py` 测试规则。
78. 排错 agents 未发现问题：提高 explorer hypothesis 生成的 temperature 至 0.8。
79. 排错 claims 停滞：确保 `HEARTBEAT_INTERVAL = 60` 秒小于 `STALL_THRESHOLD = 300` 秒的一半。
80. 排错 claims 停滞：用 SQL 查询 `claims` 表中 `status = 'in_progress'` 且 `last_heartbeat < NOW() - INTERVAL '5 minutes'` 的记录。
81. 排错 findings 未发布：检查 finding.verdict 是否为 confirmed；非 confirmed 不能发布，需要先 validation。
82. 排错 findings 未发布：验证 fingerprint 是确定性的，同一 finding 两次生成结果相同。
83. 排错低覆盖率：检查 coverage.scope 是否包含所有目标代码，如 `src/**/*.py`、`lib/**/*.{js,ts}`，并排除 tests、vendor。
84. 排错低覆盖率：检查 planner 创建的 claims 数量和 surface area，确保 claims 覆盖所有 in-scope 文件。
85. 集成 CodeGuard：用 `RuleEngine.load(rules_path)` 加载 portable CodeGuard rules。
86. 集成 CodeGuard：在 scan 中调用 `rules.evaluate(code, language)` 执行确定性规则。
87. 集成 CodeGuard：把 rule gap 转成 CodeGuard rule JSON，包含 id、name、description、pattern、severity、languages，写入 `rules/corpus/custom/`。
88. 最佳实践：先只启用 8 个核心角色，打好基础流水线后再加扩展。
89. 最佳实践：宪法不可协商，每条原则都防止真实生产故障。
90. 最佳实践：证据门控一切，没有证据就没有 finding，无论置信度多高。
91. 最佳实践：fingerprint 必须稳定，同一问题同一位置永远相同指纹。
92. 最佳实践：设置并执行 token 预算，耗尽时自动停止，防止失控。
93. 最佳实践：完成前必须通过 coverage gate，否则不要标记 evaluation complete。
94. 最佳实践：rule gaps 反哺规则语料，explorer 找到而 detector 漏掉的问题要生成新规则。
95. 最佳实践：所有执行都沙箱隔离，绝不在 evaluation 环境中直接执行。

适用边界 · 注意事项

• 只想安装一个现成安全扫描器或直接运行漏洞扫描，而不是按规范构建多智能体安全评估系统。
• 没有源代码授权、无法使用隔离沙箱执行验证，或不能接受 LLM/API 调用成本与持久化存储维护。
• 不想实现多角色协调、预算、覆盖率、证据门控和指纹去重等治理机制。