메뉴
Audits production source code files based on the strategy in workspace/plan.json. Use when a review plan exists and you need to perform static analysis and deep-dive reviews of targeted files. Don't use for planning, deduplicating, or writing patches.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/google/mantis --skill mantis-researcher명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Proactive security advisor and guardrail assistant for secure code development. Use to query threat models, historical vulnerability lineages, verified patch patterns, triaged false positives, and learned trajectory invariants before and during code edits to prevent repeat mistakes. Don't use for automated multi-pass red-team exploitation or fuzzing.
Assesses the production viability of findings, filtering out debug-only features and assertion traps. Use when findings have been validated and you need to confirm they are triggerable in production release builds (with assertions disabled). Don't use for writing reproduction scripts or patches.
Interactively guides the design and implementation of custom deterministic orchestrator harnesses. Use when a user wants to build their own pipeline to wrap and run Mantis skills reliably. Don't use for executing the default pipeline directly.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | mantis-researcher |
| description | Audits production source code files based on the strategy in workspace/plan.json. Use when a review plan exists and you need to perform static analysis and deep-dive reviews of targeted files. Don't use for planning, deduplicating, or writing patches. |
Resilience Code Auditor. Performs rapid triage and deep-dive reviews of source files to identify boundary checks, preconditions, missing sanitization, and interface violations.
/mantis-researcherworkspace/plan.json.--snapshot_root / SNAPSHOT_ROOT: absolute path to the pinned, read-only
code snapshot for this pass. This is the CODE_ROOT that all
snapshot-relative path fields resolve against (Block A step 1b).--snapshot_id / SNAPSHOT_ID: the pass snapshot identifier. Used for the
sentinel check (Block A step 2) and stamped verbatim into every finding's
discovery_commit.--state_root: absolute path to the workspace/ state directory
(plan.json, .mantis_state.json, findings/, kb/). State paths are
STATE-RELATIVE and are NEVER prefixed with CODE_ROOT (Block A step 3).--target_root (authoritative override, Block A step 1a) is also honored if
supplied.snapshot_pinned is treated as false, and behavior
matches today's exactly (no discovery_commit is written).workspace/plan.json (falls back to codebase sweep if missing/empty).workspace/.mantis_state.json (to track current loop pass)."kb_references" (e.g.
workspace/kb/entities/*.md).workspace/kb/structural_index/manifest.json (to check structural index
availability/status).workspace/helpers/query_structural_index.py (to invoke bounded
structural-index queries).workspace/findings/<uuid>.json (creates
workspace/findings/ if missing).mantis-dedupe to cluster and merge duplicate findings on subsequent steps.Run this BEFORE the numbered research steps below. It fixes the single CODE_ROOT
that every target_files / code_paths reference in this stage resolves
against, so all sub-agents audit the same pinned snapshot.
LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
(used when a caller hands you a prepared tree, e.g. a patched shadow).
b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
c. Else read state_root/workspace/.mantis_state.json (state_root from
--state_root if passed, else ./workspace/... relative to the current dir)
-> active_snapshot.root / .snapshot_id / .snapshot_pinned.
d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
- SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
NOT of the form <existing-path>:<integer> is a non-source LOCATOR
(symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
line-range and line-existence logic.
- STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
kb_references, repro_file_path, reattack_file_path, helper scripts, report
files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
(mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
(the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
that call. Do NOT assume the working directory persists between calls.
Skill-specific notes for the researcher:
workspace/plan.json target_files and finding code_paths are
SNAPSHOT-RELATIVE: resolve them under CODE_ROOT (Block A step 3).kb_references, workspace/plan.json, workspace/.mantis_state.json, and
everything under workspace/findings/ are STATE-RELATIVE: read/write them
under --state_root, NEVER under CODE_ROOT.Perform a thorough memory-safety, logical-correctness, and robustness review of the targeted codebase.
Execute the research stage as follows:
Load Reviewing Plan & Context: Read the active pass number from
workspace/.mantis_state.json and resolve the current ISO 8601 timestamp.
Read the workspace/plan.json file to retrieve the target investigations. If
workspace/plan.json is missing or empty, perform a general list of the
directories and review any primary source files. If the investigation
contains a "kb_references" array, explicitly read those Markdown files
(e.g., workspace/kb/entities/auth.md) to gain compounded historical context
before you begin auditing the "target_files". Also read active_snapshot
from workspace/.mantis_state.json (root, snapshot_id,
snapshot_pinned). Hold active_snapshot.snapshot_id in memory: it is the
value you will stamp into every finding's discovery_commit (see Findings
Schema Format). If active_snapshot is absent or snapshot_pinned is false,
you are in DEGRADED/legacy mode — do NOT stop (Block A step 1d); you will
simply omit discovery_commit.
Sub-Agent Delegation (Wave-Based Swarm Parallelization): If the CLI or agent platform supports spawning sub-agents (e.g., using specialized sub-agent tools or multi-agent orchestrator directives):
Do not execute investigations sequentially if sub-agents are supported.
Split the investigations in workspace/plan.json into parallel waves to
maximize throughput and context efficiency.
Wave 1: Lightweight Rapid Triage (Concurrency Peak): Spawn concurrent,
lightweight sub-agents (e.g. up to 10-20 in parallel) to sweep all files
listed in workspace/plan.json. Each sub-agent should only output a fast
classification: {"potentially_flawed": true/false, "reason": "..."}.
Wave 2: Deep Security Flaw Hotspot Audits & Parallel Trajectory Search: Collect all files flagged in Wave 1. Spawn a wave of concurrent deep auditor sub-agents (e.g. up to 4-8 in parallel) to focus exclusively on those identified hotspots. For particularly complex files, spawn multiple subagents targeting the same file using either different prompt constraints or a diverse set of less expensive LLMs to explore parallel attack vectors. Rely on the subsequent deduplication stage to merge any overlapping findings.
Instruct the Wave 2 sub-agents to generate unique UUIDs and write their findings directly to individual files on disk. Do not ask them to return the full JSON payload in their messages back to you, as aggregating them will blow out your context window. Ask them to only return the list of UUIDs they created.
{
"id": "A unique identifier generated for this finding (e.g., a UUID or random hash). This must be included and match the filename.",
"title": "Authorization bypass or Memory bounds violation in [function_name]",
"description": "Thorough root cause analysis detailing why the function is flawed under untrusted input.",
"impact": "Exploit outcome (e.g., Privilege escalation, Memory corruption, Data exfiltration).",
"severity": "CRITICAL / HIGH / MEDIUM / LOW",
"privileges_required": "NONE / LOW / HIGH",
"attacker_position": "EXTERNAL / INTERNAL_NETWORK / IN_CLUSTER / LOCAL / HOST_SYSTEM / SUPPLY_CHAIN / PHYSICAL_TEMPORARY / PHYSICAL_LONG_TERM",
"user_interaction": "NONE / REQUIRED",
"status": "PROVISIONALLY_VALID",
"code_paths": ["SNAPSHOT-RELATIVE path under CODE_ROOT, e.g. 'relative/file/path.c:145'. For a NON-SOURCE target (binary/firmware/URL, per Block A step 3) use a STABLE LOCATOR (symbol name, offset, or bare path) WITHOUT a fabricated ':line'. Never invent a line number."],
"discovery_commit"
<current_pass_number>
discovery_commit rule (set once, at creation): This stage is the creation
site for discovery_commit. When the snapshot is pinned, every finding you (or
your Wave-2 sub-agents) write MUST carry a non-empty discovery_commit equal to
active_snapshot.snapshot_id. Downstream stages treat an absent
discovery_commit as NOT_MATCHED (the conservative branch), so writing an empty
string or a wrong value would silently corrupt matching — never do it. In
DEGRADED/legacy mode (no active_snapshot, or snapshot_pinned false) omit the
key so behavior matches today's pipeline.
signature/lineage_id rule (set once, at creation): These fields are
ALWAYS computed (unlike discovery_commit, which is omitted in degraded mode).
The signature is a deterministic hash of the finding's content identity; the
lineage_id chains the finding to its archived ancestors. Downstream consumers
(dedupe, chain, report, reproduce) key on signature/lineage with UUID fallback:
absent signature → today's UUID behavior exactly (no silent wrong result).
Ensure all individual finding files are written to the workspace/findings/
directory. When complete, notify the user.
workspace/findings/<id>.jsonSnapshot Isolation (Wave Pinning) — MANDATORY: Pass the SAME
--snapshot_root (CODE_ROOT resolved in Step 0) and the same
--snapshot_id value to EVERY Wave-1 and Wave-2 sub-agent, and instruct
each of them to obey Block A (resolve target_files/code_paths under
that CODE_ROOT, honor the sentinel). Any Wave-2 sub-agent that writes a
finding MUST stamp discovery_commit with that snapshot_id, exactly as
specified in the Findings Schema Format. Sub-agents MUST NOT run
git pull/fetch/ checkout/reset, hg pull/update, repo sync, or
any command that changes the working tree or switches revisions — the
snapshot is immutable for the whole pass. A sub-agent that cannot see the
snapshot must report that, not re-sync.
If sub-agents or concurrency are not supported by the current environment, fall back to performing the sweeps and deep-dives sequentially.
Structural Index (HINT-only enhancement): When a structural index is
available (workspace/kb/structural_index/manifest.json exists), use it to
SUPPLEMENT the wave-based swarm above. The structural index decides ORDER,
never MEMBERSHIP. It MUST NEVER replace the exhaustive Step-3 call-site
sweep.
Resolution-first protocol (MANDATORY before any structural query):
python3 workspace/helpers/query_structural_index.py resolve_symbol --name "<function_name>" [--language "<lang>"] [--file "<path>"] --state_root <state_root>ambiguous: true, investigate ALL matched symbols
— never silently pick one. Narrow with --file/--language if
possible, or schedule investigations for every matched symbol.symbol_id for bounded queries:
python3 workspace/helpers/query_structural_index.py find_callers --symbol_id "<id>" --limit 100 --offset 0 --state_root <state_root>Coverage-aware interpretation: Check coverage.partition_status in
every structural index response:
complete + precision == semantic + empty results = "no indexed
callers" (authoritative for indexed code — still run grep per the
HINT-only rule).complete + precision != semantic + empty results = "no indexed
callers" — NOT authoritative. MUST run exhaustive grep.partial / empty / failed + empty results = "not fully indexed" —
MUST run exhaustive grep.precision and backend fields on every result to weight
trust (semantic > typecheck > ast > symbol-only > heuristic >
deferred > coverage-only).Wave 1 (Rapid Triage): Use find_callers() to SUPPLEMENT grep as a
ranking HINT — ORDER, never MEMBERSHIP. Structural index results
prioritize which files to flag as potentially_flawed; they MUST NEVER
replace the exhaustive Step-3 call-site sweep. Audit the union of grep
results and structural index results.
Wave 2 (Deep Audit): Use get_function_boundary(file, line) to start
with the enclosing function, then expand to callers/callees/file as
needed for deep dive context.
Graceful degradation: If the structural index is absent (no
manifest.json), empty, or the query helper is missing, fall back to
grep-based discovery (today's behavior). The structural index is a
coverage HINT only.
Exhaustive Interface and Call-Site Reviewing: If a target source file defines public or API functions (such as numeric parsers, decoders, encoders, or converters) that document explicit size constraints or safety requirements (e.g., expecting callers to allocate buffers of a certain size):
resolve_symbol then find_callers) to RANK and
prioritize which call-sites to audit first (the index distinguishes actual
calls from comments/strings/variable names). Audit the union of both result
sets — the structural index may miss macro-based calls, function pointers,
and dynamic dispatch, so grep remains the floor.Unconstrained / Exploratory Investigations: If the investigation plan in
workspace/plan.json contains instructions or a question explicitly asking
for an unconstrained sweep, adversarial audit, or random exploration:
workspace/kb/THREAT_MODEL.md.Compile and Write Findings: Instead of a single monolithic file, create a
workspace/findings/ directory if it does not exist. For each potential
finding, generate a unique UUID and write a valid JSON object into an
individual file named workspace/findings/<id>.json. This keeps findings
isolated and prevents token limit issues during subsequent analysis. Do not
include any text before or after the JSON in the files.
Signature & Lineage Computation (Step 5a):
For each finding, compute signature, lineage_id, and optionally cwe
BEFORE writing the JSON file:
cwe (optional): If the vulnerability maps to a known CWE, set the
cwe field to the identifier (e.g., "CWE-787", "CWE-416"). If no CWE
applies, omit the field. This is an input to the signature.
Compute signature (deterministic content-identity hash):
normalized_title = finding title, lowercased, with ALL
non-alphanumeric characters stripped (ASCII [a-zA-Z0-9] only; all
other characters including Unicode letters, punctuation, and spaces are
removed). If stripping leaves normalized_title EMPTY (e.g. a title
composed entirely of non-ASCII/Unicode characters), set
normalized_title = the first 16 hex chars of
sha256(<original raw title as UTF-8 bytes>) so two distinct non-ASCII
titles do not collide on the empty string.cwe_part = the finding's cwe field if present and non-null, else the
empty string.primary_target = first code_paths entry with trailing :line
stripped (e.g., src/auth.c:145 → src/auth.c). If code_paths is
empty, or the first entry is a non-source LOCATOR (URL containing ://,
or a non-file symbol/offset per Block A step 3), use the empty string.
Order code_paths deterministically (primary sink first, kept stable
across passes) so primary_target — and thus the signature — does not
drift between passes. (If the order is unstable the only cost is a
missed lineage inheritance → the finding is over-reported as new, never
hidden — but stable order preserves the cross-pass fold.)primary_target is non-empty: signature = first 16 hex characters
of sha256(normalized_title + "|" + cwe_part + "|" + primary_target).primary_target is empty: signature = first 16 hex characters of
sha256(normalized_title + "|" + cwe_part + "|" + sorted(code_paths).join(",")).discovery_commit).Compute lineage_id (cross-pass lineage chain):
workspace/archive/findings_pass_*/ and
workspace/archive/loop*_findings/ for any archived finding JSON whose
signature field equals this finding's computed signature.lineage_id = the archived ancestor's lineage_id
(inherit the lineage chain so consumers can fold across passes). If
MULTIPLE archived findings share the same signature, inherit from the
MOST RECENT (highest pass number) ancestor. All ancestors with the same
signature SHOULD share the same lineage_id; if they don't, inherit from
the most recent one and log a warning.primary_target (the
first code_paths entry with trailing :line stripped, already
computed for the signature at step 2) and take its basename (e.g.
src/auth.c → auth.c). If primary_target is empty (non-source
LOCATOR or empty code_paths), SKIP this fallback — go to fresh UUIDv4
below.code_paths[0] (strip the trailing :line, take the basename — e.g.
lib/old_auth.c:88 → old_auth.c). Do NOT recompute the archived
finding's signature and do NOT compare signatures; compare the two
basenames as STRINGS.lineage_id via this fallback ONLY IF (i) the
basenames match AND (ii) the ancestor's full primary_target (its
code_paths[0] with :line stripped) NO LONGER EXISTS on the
current snapshot (check that the old full path is absent under
CODE_ROOT — this distinguishes a real rename from a second,
independent file that merely shares a basename). If MULTIPLE archived
ancestors satisfy (i) and (ii), inherit from the MOST RECENT (highest
pass number). When you inherit via basename, ALSO add a finding
history note lineage-via-basename-rename so downstream consumers
treat the link as basename-derived (the report folds two findings
only when their full signatures ALSO match per the SAME-BUG
predicate, so a basename-derived lineage link never collapses
distinct bugs).Write all three fields (cwe, signature, lineage_id) into the
finding JSON alongside discovery_commit.
Mode-independence: Unlike discovery_commit (which is omitted in
DEGRADED/legacy mode), signature and lineage_id are ALWAYS computed —
they are content-identity fields, not snapshot-identity. They work regardless
of whether the snapshot is pinned, unpinned, or absent (MODE-OFF). This is a
deliberate Phase-3 improvement: in MODE-OFF, the finding JSON now carries 2–3
extra optional keys (cwe, signature, lineage_id) that did not exist in
Phase 1. This does NOT change the snapshot model (no active_snapshot, no
sync, no pin — the 3-state rule is unaffected). The dedupe MODE-OFF fallback
now prefers signature over stable_key when present, which is strictly
MORE discriminating (signature adds cwe to the title+path mix), so it can
only SPLIT entries that stable_key would have merged (fresh budgets, more
conservative = safe) — it can never produce a false merge or suppress a
legitimate finding. Absent signature → today's stable_key behavior
exactly.
Missing or unreadable target file: If a path in target_files does not
exist or cannot be read under CODE_ROOT (e.g. it was deleted or renamed since
the plan was written), do NOT fabricate a finding, a line number, or file
contents. Skip that target and record the skip plainly in the description
of any finding it relates to (or omit it entirely). Never invent code you did
not read.
Non-source targets: For a non-source LOCATOR (binary, firmware, or a URL
endpoint — see Block A step 3), the code_paths entry MUST be a STABLE
LOCATOR (symbol name, offset, or the bare path) WITHOUT a :line suffix. Do
not attach a fabricated line number to a target you cannot open as text.
lineage_id =
a fresh UUIDv4.--state_root/workspace/archive/, NEVER under CODE_ROOT.