Mantis PatchSAFE

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-patch
description: >-
  Generates minimal security fixes using transactional isolation (shadow directories or file backups), applies patches, and verifies them.
  Use when security findings are successfully reproduced and need patches applied and verified.
  Don't use for initial vulnerability research or reproduction payload generation.
---

# Patcher (/mantis-patch)

## System Goal

Security Patching Expert. Generates minimal, correct code fixes, applies them to
source code files, and verifies them inside isolated sandboxes before appending
logs to long-term memory.

## Command Definition

- **Command:**
  `/mantis-patch [--target_root=<path>] [--state_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<id>] [--snapshot_pinned=<true|false>]`
- **Description:** Generates minimal security fixes using transactional
  isolation (shadow directories or file backups), applies patches, and verifies
  them.
- **Parameters (all optional; absent ⇒ today's behavior):**
  - `--target_root`: Root of the code snapshot to read (CODE_ROOT). When the
    orchestrator pins a snapshot it passes `--snapshot_root`; `--target_root` is
    reserved for a caller that hands you an already-prepared tree.
  - `--snapshot_root`: Root of the pinned immutable snapshot for this pass.
  - `--snapshot_id`: The SNAPSHOT_ID string of the pinned snapshot (used by the
    Snapshot Match Check).
  - `--snapshot_pinned`: `true` when a pinned immutable snapshot exists this
    pass; `false`/absent ⇒ degraded/legacy (see Backward-compat).
  - `--state_root`: Root of the Mantis state directory that contains
    `workspace/` (defaults to the current directory). ALL `workspace/...` paths
    in this file are STATE-RELATIVE and resolve under
    `<state_root>/workspace/...`.

## Input/Output Contract

- **Reads**:
  - `workspace/findings/` (reproduced finding JSON files where `patch_status` is
    not `"VERIFIED_SECURE"` or `"MITIGATION_PROPOSED"`).
  - `workspace/.mantis_state.json` (to track current loop pass).
  - `workspace/.mantis_state.json` `active_snapshot` (`root`, `snapshot_id`,
    `snapshot_pinned`) — resolved via Block A; supplies CODE_ROOT and the
    SNAPSHOT_ID used by the Snapshot Match Check when no `--snapshot_*` flag is
    passed.
  - Target source code files.
  - Reproducer script path (`repro_file_path`) and command (`run_command`) from
    findings.
  - Pre-existing backup files matching finding ID (if Option B is used).
- **Writes**:
  - Source code modifications (applied transactionally and rolled back).
  - Updates finding JSON files in-place (sets `"patch_status"`, `"patch_diff"`,
    re-attack details including `"reattack_status"` and `"reattack_variants"`,
    and history).
  - Appends to `workspace/learnings.jsonl`.
  - Reusable helper script `workspace/helpers/append_patch.py`.
- **Preconditions**:
  - Findings must exist in `workspace/findings/`.
- **Idempotency Guarantee**:
  - **Snapshot-aware skip:** Skips a finding whose `patch_status` is already
    `"VERIFIED_SECURE"` or `"MITIGATION_PROPOSED"` ONLY when its recorded
    `patch_base_snapshot` equals the current SNAPSHOT_ID (i.e. it was verified
    against THIS snapshot). If `patch_base_snapshot` is absent, empty, or
    different from the current SNAPSHOT_ID, the terminal status is stale — do
    NOT skip; re-open and re-verify the finding against the current snapshot. In
    legacy mode (no `active_snapshot` and no `--snapshot_*` flags) skip exactly
    as today (by `patch_status` alone).
  - Transactional isolation: modifies code inside uniquely generated temporary
    directories or creates temporary file backups (`target.c.bak-[id]`),
    restoring baseline state upon completion (using `try...finally` rollback
    mechanisms).
  - Reuses the existing `append_patch.py` script once created.

## Instructions

Fix successfully reproduced security flaws without breaking standard code
behavior.

Execute the patching and verification stage as follows:

0. **Snapshot & Locator Resolution (run once, before touching any code):**

   0a. Resolve CODE_ROOT, SNAPSHOT_ID, snapshot_pinned, and state_root via
   **Block A** (Locator Resolution):

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

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 Patch](https://modelsatlas.com/skills/google/mantis-patch/badge.svg)](https://modelsatlas.com/skills/google/mantis-patch/)

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