mantis-advise

安全顾问与修复引擎（/mantis-advise）

系统目标

主动式安全开发与架构修复引擎。作为开发者和编码 Agent 的安全护栏、顾问助手和架构修复器。查询 Mantis 威胁模型、历史漏洞脉络、已验证的修复模式、已分流的误报以及学习到的轨迹不变量，确保从一开始就安全地实现新代码和重构，并为已确认的漏洞综合制定可靠的架构修复方案。

命令定义

• 命令： /mantis-advise
• 说明： 查询指定目标文件或模块的安全知识，根据已知威胁边界评估拟议的更改，并提供经验证的安全实现指导或架构修复计划。
• 执行命令：

  python3 "${MANTIS_HOME:-/path/to/mantis}/reference/scripts/advise.py" --file <target_file> [--db knowledge.db]
  

• 参数（可选）：
  • --file / -f（或 --target / -t）：目标源文件或组件路径（例如 src/auth.py 或 api/app.py）。省略时默认为整个仓库范围。
  • --remediate / -r：发现项 ID、脉络 UUID 或文件，用于生成架构修复档案和验证计划。
  • --db / -d：Mantis SQLite 数据库路径（默认：自动查找 knowledge.db 或 workspace/knowledge.db）。
  • --lineage / -l：查询指定脉络 UUID 的生命周期和复发情况。
  • --signature / -s：查询指定内容签名哈希的生命周期。
  • --json：输出结构化 JSON，而不是格式化的 Markdown。
  • --full：输出未经删节的 OKF Markdown 正文和未截断的差异。

如何获取指导

所有 Mantis 知识（威胁模型、历史发现、已验证补丁、已分流的误报和学习到的不变量）都存储在 SQLite 数据库（knowledge.db）中。不要查找磁盘上的独立文件（如 learnings.jsonl 或 workspace/findings/*.json）。请使用以下两种执行方式之一：

方式 1：CLI 执行（推荐用于编码 Agent）

具备标准 bash 访问权限的编码 Agent 应使用以安装目录为锚点的绝对路径运行 advise.py。

路径锚定要求（重要）：顾问脚本位于 Mantis 安装目录下的 reference/scripts/advise.py。必须通过绝对路径或 $MANTIS_HOME 调用此脚本。切勿在受审计的目标仓库中使用相对路径运行 python3 reference/scripts/advise.py，因为不可信的仓库可能会伪造脚本或导致命令失败。

1. 查询目标文件的安全指导：

   python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py
   

   输出：可执行的安全顾问 Markdown，包含当前威胁模型、历史漏洞、已验证的补丁差异、已分流的误报和不变量。

2. 查询特定 Bug 脉络与复发情况：

   python3 "$MANTIS_HOME/reference/scripts/advise.py" --lineage c3a5e982-1234-5678-9abc-def012345678
   

3. 机器可读 JSON：

   python3 "$MANTIS_HOME/reference/scripts/advise.py" --file src/auth.py --json
   

4. 针对某项发现的架构修复档案：

   python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id>
   

方式 2：Python 工具调用（在流水线 / 测试框架内）

在 Agent 测试框架或 Python 环境中运行时：

from core.database import query_security_guidance

guidance = query_security_guidance(db_path="knowledge.db", filepath="src/auth.py")
print(guidance["guidance_summary"])

也可以通过工具辅助函数调用：

get_security_guidance(filepath="src/auth.py")

输入/输出约定

• 读取：
  • knowledge.db（findings、campaign_artifacts、learnings 和 risk_scores 表）。
  • 目标源代码文件（位于仓库根目录下）。
• 写入：
  • 为当前开发者或编码 Agent 编写的结构化安全顾问与护栏建议。

核心顾问协议

协议 1：实现前安全上下文检查

在编写代码或重构现有模块之前：

1. 运行 Advisor：执行 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>。
2. 审查建议上下文：
   • 信任边界：确定哪些主体会与此模块交互（不受信任的公共互联网、已认证用户、内部微服务）。
   • 历史陷阱：审查此文件中此前已确认或复现的所有漏洞。特别留意重复出现的 lineage_id 链。
   • 已验证的安全惯用模式：审查此前轮次中标记为 VERIFIED_SECURE 的已验证补丁差异。
   • 已分类的误报：审查此前被归类为误报的模式，了解有意的设计选择，避免破坏合法功能。

协议 2：信任边界验证

引入新端点、参数、数据解析或子进程执行时：

1. 输入规范化与验证：

   • 未经规范化和严格的架构校验，绝不信任来自外部边界的输入。
   • 对于文件路径：使用严格的 os.path.abspath 或 Path.resolve() 检查（startswith(jail_dir)），确保路径位于隔离边界内。
   • 对于操作系统命令执行：严格使用 shlex.quote，或使用基于数组的 subprocess.run(["cmd", arg])，且不设置 shell=True。

2. 纵深防御：

   • 即使存在客户端验证，也要确保服务端验证。
   • 确保遵循零权限假设（例如，不授予不必要的 IAM 权限、限制执行超时时间）。

协议 3：溯源与复发防御

1. 修复已报告的漏洞或重构易受攻击的组件时，通过 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file> 检查该漏洞的 lineage_id。
2. 确保新实现彻底封堵此前重新攻击验证测试套件所展示的所有攻击向量。

协议 4：架构级漏洞修复与沙箱验证

解决已确认的安全缺陷（在流水线中或独立修复）时：

1. 依据上下文：

   • 查询 python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id> （或 get_security_guidance(filepath=...)）。
   • 提取有效的 OKF 威胁边界和安全不变量。
   • 检查匹配的溯源历史中此前已验证的安全模式。

2. 架构综合：

   • 不要采用表面化的局部修补手段（例如 return None、硬编码 False 或注释掉端点），使功能形同虚设。
   • 使用安全惯用模式（参数化、严格边界、数组形式的 argv、规范化路径）重构根因接收点。

3. 沙箱验证（INV-1 与 INV-2）：

   • 将统一差异补丁应用到来宾工作区（apply_patch）。
   • 运行漏洞复现器（run_sandbox_with_evidence）。
   • 确认攻击无法到达接收点（reattack_status == "failed_to_bypass"）。
   • 确认现有功能测试套件通过，且无回归。

输出格式

Advisor 会输出清晰、可执行的建议：

# Security Advisory: <target_file>

### 1. Threat Model & Trust Boundaries
- **Entry Points**: <untrusted network / RPC / CLI>
- **Sensitive Assets**: <credentials, filesystem, tenant data>

### 2. Known Pitfalls & Historical Lineages
- **[CWE-XX] <Title>** (Lineage: `<uuid>`): <How it occurred and how it was resolved>
- **Verified Safe Pattern**:
  ```python
  # Safe implementation idiom

3. 误报上下文（有意行为）

• <模式>： <说明为什么此模式在此特定架构中被视为安全>

4. 实施检查清单

• 已针对路径遍历／注入／反序列化进行验证。
• 遵循已验证的补丁模式。
• 遵守信任边界隔离。