mantis-advise

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Security Advisor (/mantis-advise)

安全顾问（/mantis-advise）

System Goal

系统目标

Proactive Secure Development Advisor. Functions as a security guardrail and advisory assistant for developers and coding agents. Queries Mantis threat models, historical vulnerability lineages, verified remediation patterns, triaged false positives, and learned trajectory invariants to ensure that new code and refactors are implemented securely from the start.

主动式安全开发顾问。为开发人员和编码Agent提供安全护栏与咨询辅助功能。查询Mantis威胁模型、历史漏洞谱系、已验证修复模式、已分类误报以及习得的轨迹不变量，确保新代码与重构从一开始就以安全方式实现。

Command Definition

命令定义

Command:
```
/mantis-advise
```
Description: Queries security knowledge for a given target file or module, evaluates proposed changes against known threat boundaries, and provides verified secure implementation guidance.

Execution Command:

bash

python3 reference/scripts/advise.py --file <target_file> [--db knowledge.db]

Arguments (optional):
- ```
--file
```
  /
```
-f
```
  (or
```
--target
```
  /
```
-t
```
  ): Target source file or component path (e.g.
```
src/auth.py
```
  or
```
api/app.py
```
  ). Defaults to repo-wide scope if omitted.
- ```
--db
```
  /
```
-d
```
  : Path to Mantis SQLite database (default: auto-discovers
```
knowledge.db
```
  or
```
workspace/knowledge.db
```
  ).
- ```
--lineage
```
  /
```
-l
```
  : Query lifecycle and recurrence for a specific lineage UUID.
- ```
--signature
```
  /
```
-s
```
  : Query lifecycle for a specific content signature hash.
- ```
--json
```
  : Emit structured JSON output instead of formatted markdown.

命令：
```
/mantis-advise
```
描述： 查询指定目标文件或模块的安全知识，对照已知威胁边界评估拟议变更，并提供经过验证的安全实现指导。

执行命令：

bash

python3 reference/scripts/advise.py --file <target_file> [--db knowledge.db]

可选参数：
- ```
--file
```
  /
```
-f
```
  （或
```
--target
```
  /
```
-t
```
  ）：目标源文件或组件路径（例如
```
src/auth.py
```
  或
```
api/app.py
```
  ）。若省略则默认覆盖整个仓库范围。
- ```
--db
```
  /
```
-d
```
  ：Mantis SQLite数据库路径（默认：自动发现
```
knowledge.db
```
  或
```
workspace/knowledge.db
```
  ）。
- ```
--lineage
```
  /
```
-l
```
  ：查询特定谱系UUID的生命周期与复发情况。
- ```
--signature
```
  /
```
-s
```
  ：查询特定内容签名哈希的生命周期。
- ```
--json
```
  ：输出结构化JSON格式，而非格式化markdown。

How to Fetch Guidance

如何获取指导

All Mantis knowledge (threat models, historical findings, verified patches, triaged false positives, and learned invariants) lives in the SQLite database (

knowledge.db

). Do not look for flat files on disk (like

learnings.jsonl

workspace/findings/*.json

). Use one of the two execution doors below:

所有Mantis知识（威胁模型、历史发现、已验证补丁、已分类误报以及习得的不变量）都存储在SQLite数据库（

knowledge.db

）中。请勿在磁盘上查找平面文件（如

learnings.jsonl

或

workspace/findings/*.json

）。请使用以下两种执行方式之一：

Mechanism 1: CLI Execution (Recommended for Coding Agents)

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

Coding agents with standard bash access should run

reference/scripts/advise.py

Query Security Guidance for Target File:
bash
```
python3 reference/scripts/advise.py --file src/auth.py
```
Prints: Actionable security advisory markdown with active threat model, historical vulnerabilities, verified patch diffs, triaged false positives, and invariants.

Query Specific Bug Lineage & Recurrence:

bash

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

Machine-Readable JSON:

bash

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

拥有标准bash访问权限的编码Agent应运行

reference/scripts/advise.py

：

查询目标文件的安全指导：
bash
```
python3 reference/scripts/advise.py --file src/auth.py
```
输出：可执行的安全咨询markdown内容，包含当前威胁模型、历史漏洞、已验证补丁差异、已分类误报以及不变量。

查询特定漏洞谱系与复发情况：

bash

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

机器可读JSON格式：

bash

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

Mechanism 2: Python Tool Invocation (Inside Pipeline / Harness)

方式2：Python工具调用（在流水线/工具内部使用）

When running inside an agent harness or Python environment:

python

from core.database import query_security_guidance

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

Or via tool helper:

python

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

在Agent工具或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"])

或通过工具助手调用：

python

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

Input/Output Contract

输入/输出约定

Reads:
- ```
knowledge.db
```
  (
```
findings
```
  ,
```
campaign_artifacts
```
  ,
```
learnings
```
  , and
```
risk_scores
```
  tables).
- Target source code files (under repository root).
Writes:
- Structured Security Advisory & Guardrail recommendations formatted for the active developer or coding agent.

读取：
- ```
knowledge.db
```
  （包含
```
findings
```
  、
```
campaign_artifacts
```
  、
```
learnings
```
  和
```
risk_scores
```
  表）。
- 目标源代码文件（位于仓库根目录下）。
写入：
- 为当前开发人员或编码Agent格式化的结构化安全咨询与护栏建议。

Core Advisory Protocols

核心咨询协议

Protocol 1: Pre-Implementation Security Context Check

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

Before authoring code or refactoring an existing module:

Run the Advisor: Execute

python3 reference/scripts/advise.py --file <target_file>

Review Advisory Context:
- Trust Boundaries: Identify who interacts with this module (untrusted public internet, authenticated users, internal microservices).
- Historical Pitfalls: Review all vulnerabilities previously confirmed or reproduced on this file. Pay specific attention to recurring
```
lineage_id
```
  chains.
- Verified Safe Idioms: Review verified patch diffs from prior passes marked
```
VERIFIED_SECURE
```
  .
- Triaged False Positives: Review patterns previously classified as false positives to understand intentional design choices and avoid breaking legitimate functionality.

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

运行顾问工具：执行

python3 reference/scripts/advise.py --file <target_file>

。

查看咨询上下文：
- 信任边界：确定与该模块交互的对象（不可信公共互联网、已认证用户、内部微服务）。
- 历史陷阱：查看该文件之前确认或重现的所有漏洞。特别注意重复出现的
```
lineage_id
```
  链。
- 已验证安全范式：查看之前标记为
```
VERIFIED_SECURE
```
  的已验证补丁差异。
- 已分类误报：查看之前被归类为误报的模式，了解有意的设计选择，避免破坏合法功能。

Protocol 2: Trust Boundary Verification

协议2：信任边界验证

When introducing new endpoints, parameters, data parsing, or subprocess execution:

Input Normalization & Validation:
- Never trust input from external boundaries without canonicalization and strict schema enforcement.
- For file paths: resolve against jail boundaries using strict
```
os.path.abspath
```
  or
```
Path.resolve()
```
  checks (
```
startswith(jail_dir)
```
  ).
- For OS command execution: strictly use
```
shlex.quote
```
  or array-based
```
subprocess.run(["cmd", arg])
```
  without
```
shell=True
```
  .
Defense-in-Depth:
- Ensure server-side validation even if client-side validation is present.
- Ensure zero-privilege assumptions (e.g. no unnecessary IAM permissions, bounded execution timeouts).

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

输入规范化与验证：
- 对于来自外部边界的输入，必须经过规范化处理和严格的模式校验，切勿直接信任。
- 对于文件路径：使用严格的
```
os.path.abspath
```
  或
```
Path.resolve()
```
  检查（
```
startswith(jail_dir)
```
  ），确保路径在沙箱边界内。
- 对于OS命令执行：严格使用
```
shlex.quote
```
  或基于数组的
```
subprocess.run(["cmd", arg])
```
  ，禁止使用
```
shell=True
```
  。
纵深防御：
- 即使存在客户端验证，也要确保服务器端验证生效。
- 遵循零权限假设（例如，无不必要的IAM权限、设置执行超时时间）。

Protocol 3: Lineage & Recurrence Defense

协议3：谱系与复发防御

When fixing a reported vulnerability or refactoring a vulnerable component, check the bug's
```
lineage_id
```
via
```
python3 reference/scripts/advise.py --file <target_file>
```
.
Ensure the new implementation completely closes all attack vectors demonstrated in prior re-attack verification test suites.

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

Output Format

输出格式

The Advisor outputs clean, actionable recommendations:

markdown

undefined

顾问工具输出清晰、可执行的建议：

markdown

undefined

Security Advisory: <target_file>

安全咨询：<target_file>

1. Threat Model & Trust Boundaries

1. 威胁模型与信任边界

Entry Points: <untrusted network / RPC / CLI>
Sensitive Assets: <credentials, filesystem, tenant data>

入口点：<不可信网络 / RPC / CLI>
敏感资产：<凭证、文件系统、租户数据>

2. Known Pitfalls & Historical Lineages

2. 已知陷阱与历史谱系

[CWE-XX] <Title> (Lineage:
```
<uuid>
```
): <How it occurred and how it was resolved>
Verified Safe Pattern:
python
```
# Safe implementation idiom
```

undefined

[CWE-XX] <标题>（谱系：
```
<uuid>
```
）：<漏洞发生原因及修复方式>
已验证安全模式：
python
```
# 安全实现范式
```

undefined

3. False Positive Context (Intentional Behavior)

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

<Pattern>: <Why this pattern is considered safe in this specific architecture>

<模式>： <为何该模式在此特定架构中被视为安全>

4. Implementation Checklist

4. 实现检查清单

Validated against path traversal / injection / deserialization.
Adheres to verified patch patterns.
Respects trust boundary isolation.

undefined

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

undefined