编码或重构前查询 Mantis 安全知识并生成架构修复方案

在开发、重构或修复已确认漏洞前，用 /mantis-advise 查询威胁模型、历史漏洞谱系、已验证补丁、误报上下文和不变式，并生成可沙箱验证的安全修复计划。

适用场景

解决思路

1. 使用 /mantis-advise：查询给定目标文件或模块的安全知识，评估拟议变更是否触碰已知威胁边界，并提供已验证的安全实现指导或架构修复计划。
2. 执行命令：`python3 "${MANTIS_HOME:-/path/to/mantis}/reference/scripts/advise.py" --file <target_file> [--db knowledge.db]`。
3. 可选参数 `--file` / `-f`（或 `--target` / `-t`）：指定目标源码文件或组件路径，例如 `src/auth.py` 或 `api/app.py`；省略时默认仓库范围。
4. 可选参数 `--remediate` / `-r`：传入 finding ID、lineage UUID 或文件，生成架构修复档案与验证计划。
5. 可选参数 `--db` / `-d`：指定 Mantis SQLite 数据库路径；默认自动发现 `knowledge.db` 或 `workspace/knowledge.db`。
6. 可选参数 `--lineage` / `-l`：按 lineage UUID 查询生命周期与复发情况。
7. 可选参数 `--signature` / `-s`：按内容签名哈希查询生命周期。
8. 可选参数 `--json`：输出结构化 JSON，而不是格式化 markdown。
9. 可选参数 `--full`：输出未删节的 OKF markdown 正文和未截断 diff。
10. 所有 Mantis 知识（威胁模型、历史发现、已验证补丁、已分诊误报、学习到的不变式）都存放在 SQLite 数据库 `knowledge.db`；不要查找磁盘上的扁平文件，如 `learnings.jsonl` 或 `workspace/findings/*.json`。
11. 机制 1（推荐给有标准 bash 访问的编码代理）：用安装锚定的绝对路径运行 `advise.py`。
12. 路径锚定要求（关键）：必须通过绝对路径或 `$MANTIS_HOME` 调用脚本；绝不要在受审计目标仓库内执行相对路径 `python3 reference/scripts/advise.py`，因为不可信仓库可能伪造脚本或导致命令失败。
13. 查询目标文件安全指导：`python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py`，它会打印可执行安全建议 markdown，包含活跃威胁模型、历史漏洞、已验证补丁 diff、已分诊误报和不变式。
14. 查询特定 bug 谱系与复发：`python3 "$MANTIS_HOME/reference/scripts/advise.py" --lineage c3a5e982-1234-5678-9abc-def012345678`。
15. 输出机器可读 JSON：`python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py --json`。
16. 为某个 finding 生成架构修复档案：`python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id>`。
17. 机制 2（在 pipeline 或 harness 内）：使用 Python 调用 `from core.database import query_security_guidance`，再执行 `guidance = query_security_guidance(db_path="knowledge.db", filepath="src/auth.py")`，并读取 `print(guidance["guidance_summary"])`。
18. 或使用工具辅助函数：`get_security_guidance(filepath="src/auth.py")`。
19. 读取：`knowledge.db` 中的 `findings`、`campaign_artifacts`、`learnings`、`risk_scores` 表，以及仓库根目录下的目标源码文件。
20. 写入：面向当前开发者或编码代理的结构化安全建议与 guardrail 建议。
21. 协议 1：实现前安全检查——在编写代码或重构现有模块前，运行 `python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>`。
22. 协议 1：审阅建议上下文——信任边界：确认谁与该模块交互（不可信公网、已认证用户、内部微服务）。
23. 协议 1：审阅历史陷阱——查看该文件上所有曾确认或复现过的漏洞，特别关注反复出现的 `lineage_id` 链。
24. 协议 1：审阅已验证安全惯用法——查看先前标记为 `VERIFIED_SECURE` 的已验证补丁 diff。
25. 协议 1：审阅已分诊误报——查看曾被归类为误报的模式，理解有意设计选择，避免破坏合法功能。
26. 协议 2：信任边界验证——在引入新端点、参数、数据解析或子进程执行时执行以下检查。
27. 协议 2：输入规范化与验证——绝不信任外部边界输入，除非已做规范化并强制严格 schema。
28. 协议 2：文件路径——使用严格的 `os.path.abspath` 或 `Path.resolve()` 检查（`startswith(jail_dir)`）对 jail 边界解析路径。
29. 协议 2：OS 命令执行——严格使用 `shlex.quote`，或使用数组式 `subprocess.run(["cmd", arg])` 且不要 `shell=True`。
30. 协议 2：纵深防御——即使存在客户端验证，也要确保服务端验证。
31. 协议 2：纵深防御——确保零权限假设，例如不要不必要 IAM 权限，并设置有限执行超时。
32. 协议 3：谱系与复发防御——修复已报告漏洞或重构易受攻击组件时，通过 `python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>` 检查 bug 的 `lineage_id`。
33. 协议 3：确保新实现完全关闭先前 re-attack 验证测试套件演示过的所有攻击向量。
34. 协议 4：架构漏洞修复与沙箱验证——解决已确认安全缺陷时，先查询 `python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id>`（或 `get_security_guidance(filepath=...)`）。
35. 协议 4：提取活跃的 OKF Threat Boundaries 和 Security Invariants。
36. 协议 4：检查匹配 lineage 历史中的先前已验证安全模式。
37. 协议 4：架构综合——不要生成表面化的点状补丁，例如 `return None`、硬编码 `False` 或注释掉端点，这类做法会阉割功能。
38. 协议 4：架构综合——使用安全惯用法重构根因 sink，例如参数化、严格边界、数组 argv、规范化路径。
39. 协议 4：沙箱验证（INV-1 和 INV-2）——将 unified diff patch 应用到 guest workspace（`apply_patch`）。
40. 协议 4：运行 finding reproducer（`run_sandbox_with_evidence`）。
41. 协议 4：验证攻击无法到达 sink（`reattack_status == "failed_to_bypass"`）。
42. 协议 4：验证现有功能测试套件通过且无回归。
43. 输出格式：生成干净、可执行的建议，包含 `# Security Advisory: <target_file>`。
44. 输出格式：第 1 节 `Threat Model & Trust Boundaries`，列出 Entry Points（不可信网络 / RPC / CLI）和 Sensitive Assets（凭据、文件系统、租户数据）。
45. 输出格式：第 2 节 `Known Pitfalls & Historical Lineages`，列出 `[CWE-XX] <Title>`（Lineage: `<uuid>`）、发生与解决方式，以及 Verified Safe Pattern 的安全实现惯用法代码。
46. 输出格式：第 3 节 `False Positive Context (Intentional Behavior)`，说明该模式为何在此特定架构中被视为安全。
47. 输出格式：第 4 节 `Implementation Checklist`，检查是否验证了 path traversal / injection / deserialization、是否遵循已验证补丁模式、是否尊重信任边界隔离。

适用边界 · 注意事项

• 不要用于自动化多轮红队利用或 fuzzing。
• 不要查找磁盘上的扁平知识文件（如 `learnings.jsonl` 或 `workspace/findings/*.json`），应查询 SQLite `knowledge.db`。
• 不要在受审计目标仓库内使用相对路径执行 `python3 reference/scripts/advise.py`。