mantis-advise

用途

Mantis 安全顾问与架构修复引擎（命令 /mantis-advise）是一个主动式安全开发与架构修复引擎，充当开发者与编码智能体的安全护栏、咨询助手和架构修复器。其目标是在新代码与重构中从一开始就安全实现，并为已确认的漏洞合成稳健的架构修复方案。

主要能力

查询 Mantis 威胁模型、历史漏洞谱系、已验证的修复模式、已分诊的误报以及学习到的轨迹不变量。
针对给定目标文件或模块查询安全知识，评估拟议变更是否触及已知威胁边界。
提供已验证的安全实现指导或架构修复计划。
支持按漏洞谱系 UUID、内容签名哈希查询生命周期与复发情况。
支持为具体发现（finding）生成架构修复档案与验证计划。
支持结构化 JSON 输出与完整未截断的 OKF markdown 正文及差异。

使用方式

所有 Mantis 知识（威胁模型、历史发现、已验证补丁、已分诊误报、学习到的不变量）都存放在 SQLite 数据库（knowledge.db）中，不应在磁盘上查找 learnings.jsonl 或 workspace/findings/*.json 等平面文件。

机制一：CLI 执行（推荐用于编码智能体）

具备标准 bash 访问权限的编码智能体应使用安装锚定的绝对路径运行 advise.py。

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

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

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

输出：可执行的安全建议 markdown，包含活动威胁模型、历史漏洞、已验证补丁差异、已分诊误报和不变量。

查询特定缺陷谱系与复发：

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

机器可读 JSON：

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

针对某个发现的架构修复档案：

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

机制二：Python 工具调用（在流水线 / 测试框架内）

在智能体测试框架或 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")

参数

--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 正文与未截断的差异。

输入 / 输出契约

读取：knowledge.db（findings、campaign_artifacts、learnings 和 risk_scores 表）；目标源代码文件（位于仓库根目录下）。

写入：为当前开发者或编码智能体格式化的结构化安全建议与护栏推荐。

核心顾问协议

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

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

运行顾问：执行 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file>。
审阅顾问上下文：
- 信任边界：识别与该模块交互的对象（不受信任的公共互联网、已认证用户、内部微服务）。
- 历史陷阱：审阅此前在该文件上确认或复现的所有漏洞，特别关注反复出现的 lineage_id 链。
- 已验证安全惯用法：审阅此前标记为 VERIFIED_SECURE 的已验证补丁差异。
- 已分诊误报：审阅此前被归类为误报的模式，以理解有意设计选择并避免破坏合法功能。

协议 2：信任边界验证

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

输入规范化与验证：
- 绝不在未经规范化与严格模式强制的情况下信任来自外部边界的输入。
- 对于文件路径：使用严格的 os.path.abspath 或 Path.resolve() 检查（startswith(jail_dir)）针对 jail 边界进行解析。
- 对于操作系统命令执行：严格使用 shlex.quote 或基于数组的 subprocess.run(["cmd", arg])，不使用 shell=True。
纵深防御：
- 即使存在客户端验证，也要确保服务端验证。
- 确保零特权假设（例如无不必要的 IAM 权限、有界执行超时）。

协议 3：谱系与复发防御

在修复报告的漏洞或重构易受攻击的组件时，通过 python3 "$MANTIS_HOME/reference/scripts/advise.py" --file <target_file> 检查缺陷的 lineage_id。确保新实现完全关闭此前再攻击验证测试套件中演示的所有攻击向量。

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

在解决已确认的安全缺陷时（流水线内或独立运行）：

基础上下文：
- 查询 python3 "$MANTIS_HOME/reference/scripts/advise.py" --remediate <finding_id>（或 get_security_guidance(filepath=...)）。
- 提取活动 OKF 威胁边界与安全不变量。
- 检查匹配谱系历史中此前已验证的安全模式。
架构合成：
- 不要产生表面化的点式修补（例如 return None、硬编码 False 或注释掉端点）而使功能瘫痪。
- 使用安全惯用法（参数化、严格边界、数组 argv、规范化路径）重构根因汇聚点。
沙箱验证（INV-1 与 INV-2）：
- 将统一差异补丁应用到客户工作区（apply_patch）。
- 运行发现复现器（run_sandbox_with_evidence）。
- 验证攻击无法到达汇聚点（reattack_status == "failed_to_bypass"）。
- 验证现有功能测试套件通过且无回归。

输出格式

顾问输出干净、可执行的建议：

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:
```
# Safe implementation idiom
```

False Positive Context (Intentional Behavior)

Implementation Checklist

Validated against path traversal / injection / deserialization.

Adheres to verified patch patterns.

Respects trust boundary isolation.

适用场景

编码智能体在编写或重构代码前查询安全上下文。
开发者在引入新端点、参数、数据解析或子进程执行时验证信任边界。
修复已确认漏洞时查询谱系与复发历史，确保完全关闭攻击向量。
为具体发现生成架构修复档案并进行沙箱验证。

限制

所有知识均来自 SQLite 数据库（knowledge.db），不提供平面文件形式的知识。
必须通过绝对路径或 $MANTIS_HOME 调用脚本，不得在目标仓库内使用相对路径。
具体收费、价格、平台支持范围等资料暂未提供。