Mantis HistorySAFE

A modular, stack-agnostic toolkit for AI coding agents to autonomously find, reproduce, and patch vulnerabilities.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: mantis-history
description: >-
  Analyzes the repository's version control system (VCS) history to extract past vulnerabilities, security fixes, and vulnerability patterns.
  Use as an initial pre-processing step to build a historical vulnerabilities database (workspace/historical_learnings.jsonl) that informs subsequent stages about past issues and fixes.
  Don't use for code reviews, writing test scripts, or patching code.
---

# History Analyzer (/mantis-history)

## System Goal

Historical Vulnerability Extractor. Analyzes repository's version control system
(VCS) history to extract past vulnerabilities, security-related fixes, patches,
and associated files, creating a historical learnings database to inform
downstream skills.

## Command Definition

- **Command:** `/mantis-history`
- **Description:** Analyzes repository's version control system (VCS) history to
  extract past vulnerabilities and fixes, producing a structured historical
  learnings file (`workspace/historical_learnings.jsonl`).
- **Arguments (optional; supplied by the orchestrator, consumed by Block A):**
  `--snapshot_root`/`--snapshot_id`/`--state_root`. History reads VCS logs from
  the LIVE repository root (Block A step 5), not the snapshot; it uses
  `--state_root` only to place its cache/output/script. All absent -> DEGRADED
  (behaves as today, live cwd).

## Input/Output Contract

- **Reads**:
  - `workspace/.mantis_state.json` (to track current loop pass).
  - Codebase directory structure and key files (to determine stack).
  - VCS history logs (commit messages, titles, diffs).
  - `mantis-summary.md` (optional, if available).
  - Internal history analysis cache (optional, if exists).
- **Writes**:
  - VCS extraction script (written on-the-fly to workspace).
  - `workspace/historical_learnings.jsonl`.
  - Internal history analysis cache.
  - All under `--state_root/workspace/` (cache, `historical_learnings.jsonl`,
    extraction script): kept outside the target tree. Optional `history_status`
    marker (`UNSUPPORTED_VCS` / `PARTIAL_SHALLOW`).
- **Preconditions**:
  - Target repository and VCS logs must be accessible.
- **Idempotency Guarantee**:
  - The cache is the source of truth: the output DB is rebuilt from it every run
    and is never truncated to empty while the cache is non-empty. The cache is
    invalidated on VCS-history rewrite (`_analyzed_head` no longer reachable) or
    a vcs_type/repo-identity change. On `none`/`unknown` VCS the stage writes an
    empty DB + `history_status=UNSUPPORTED_VCS` and exits.

## Instructions

### Step 0: Locator Resolution (run first)

```
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.
```

CRITICAL for history: the pinned snapshot copy STRIPS `.git`/`.hg`/`.repo`, so
per Block A step 5 you MUST run every VCS log / diff / blame command in the LIVE
repository root (the working directory Mantis was launched in), NOT under
CODE_ROOT. Do NOT stop because CODE_ROOT lacks VCS metadata. Write the cache,
`workspace/historical_learnings.jsonl`, and your generated extraction script
under `--state_root/workspace/` (STATE-RELATIVE) — never into the target tree,
so a sync/clean cannot wipe them. Record `active_snapshot.snapshot_id` on
entries only for provenance.

Your task is to analyze the codebase architecture, determine what constitutes
security-relevant history, and write a script on-t

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Mantis History](https://modelsatlas.com/skills/google/mantis-history/badge.svg)](https://modelsatlas.com/skills/google/mantis-history/)

Not your listing, or something out of date? Claim or update your listing.