Skip to main content
ClaudeWave
Slash Command304 repo starsupdated 2d ago

mantis-annotate

The mantis-annotate command manages per-function markdown annotations attached to source files, enabling operators to record audit notes, security findings, and CWE labels on individual functions. Use it to document code review observations, mark functions as clean or suspicious, track manual annotations separately from automated analysis, and maintain a staleness index by hashing source line ranges for change detection.

Install in Claude Code
Copy
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/deonmenezes/mantishack/HEAD/.claude/commands/mantis-annotate.md -o ~/.claude/commands/mantis-annotate.md
Then start a new Claude Code session; the slash command loads automatically.

mantis-annotate.md

# /annotate

Per-function prose annotations stored as markdown mirroring the source tree.
Annotations capture audit-style notes on individual functions: a manual
"reviewed clean", a hypothesis-then-validate finding, a CWE label, or any
free-form prose.

Operator-driven adds default to ``metadata.source=human``, so subsequent
LLM passes (`/agentic`, `/understand` post-processor) that pass
``overwrite=respect-manual`` will not silently clobber operator notes.

## Usage

```
/annotate add <file> <function> [options]
/annotate ls [options]
/annotate show <file> <function> [options]
/annotate edit <file> <function> [options]
/annotate rm <file> <function> [options]
/annotate stale [options]
```

## Subcommands

| Subcommand | What it does |
|---|---|
| `add <file> <function>` | Write or update an annotation |
| `ls` | List annotations (filterable by file/status/source) |
| `show <file> <function>` | Render one annotation |
| `edit <file> <function>` | Open the source file's annotation .md in `$EDITOR` |
| `rm <file> <function>` | Remove an annotation; cleans up empty .md files |
| `stale` | List annotations whose stored source-line hash no longer matches |

## Add options

| Option | Purpose |
|---|---|
| `--status VALUE` | `clean` / `suspicious` / `finding` / `error` |
| `--cwe CWE-XX` | CWE identifier |
| `-m, --body TEXT` | Annotation prose |
| `--body-file PATH` | Read body from file (`-` for stdin) |
| `--lines N-M` | Source line range; computes `metadata.hash` for staleness |
| `--target REPO_ROOT` | Where to find source for hash (default: cwd) |
| `--meta KEY=VALUE` | Extra metadata (repeatable) |
| `--source VALUE` | Defaults to `human`; set `llm` only for scripted adds |
| `--overwrite MODE` | `all` (default) or `respect-manual` |

## ls options

| Option | Purpose |
|---|---|
| `--file PATH` | Show only annotations for one source file |
| `--status VALUE` | Filter by `metadata.status` |
| `--source VALUE` | Filter by `metadata.source` |
| `--cwe CWE-XX` | Filter by `metadata.cwe` (exact match) |
| `--rule-id PATTERN` | Filter by `metadata.rule_id` substring (e.g. `py/`) |
| `--grep TEXT` | Case-insensitive substring search across body + metadata |
| `--since 7d` | Annotation file mtime within window (`Nd`/`Nh`/`Nm`/`Ns`/`Nw`) |

## stale options

| Option | Purpose |
|---|---|
| `--target REPO_ROOT` | Source-tree root for hash recomputation (default: cwd) |

## Common option

`--base PATH` — annotation base directory. Defaults to the active project's
`<output_dir>/annotations`. Required if no project is active.

## Examples

```
# Manual clean review
/annotate add src/auth.py check_password \
    --status clean -m "Reviewed: constant-time compare, no taint"

# Manual finding with CWE + staleness hash
/annotate add src/exec.py run_cmd \
    --status finding --cwe CWE-78 \
    --lines 42-58 --target ~/repos/myproj \
    -m "Confirmed shell injection via subprocess(shell=True)"

# Quick listing
/annotate ls
/annotate ls --status finding
/annotate ls --source human

# Inspect one record
/annotate show src/auth.py check_password

# Edit (opens .md in $EDITOR)
/annotate edit src/auth.py check_password

# Remove a record
/annotate rm src/auth.py old_function

# Find stale annotations after source edits
/annotate stale --target ~/repos/myproj
```

## Execution

Run via the Bash tool:

```bash
libexec/mantishack-annotate <subcommand> [args]
```

For `add` calls invoked through this slash command, the operator's intent
is implicit — keep the default `--source human`. Do **not** pass
`--source llm` from `/annotate` unless the operator explicitly asks for
scripted, non-human-attributable behaviour.

## Output

Output the result verbatim in a fenced code block. Do not summarise — the
operator wants exact paths, exact metadata values, and exact bodies.

## Base-dir resolution

The CLI resolves the annotation base in this order:

1. Explicit `--base PATH` argument
2. Active project's `<output_dir>/annotations`
3. Exit 2 with a hint to set `--base` or activate a project

So when a project is active (`/project use foo`), `/annotate ls` "just
works" without arguments.

## Conventions

- **`metadata.source=human`** marks a manual entry. LLM-driven callers
  (e.g. `/agentic`'s annotation emitter) pass `overwrite=respect-manual`
  so they will skip rather than overwrite a human-source record.
- **`metadata.hash`**: a short sha256 prefix of the function's source
  lines, captured at add time when `--lines N-M --target REPO_ROOT` is
  provided. Used by `/annotate stale` to detect annotations whose source
  has drifted.
- **Function names**: top-level functions use bare names (`process`);
  class methods use dotted form (`MyClass.process`).
- **Path traversal**: `../etc/passwd` is rejected before any filesystem
  access, regardless of `--base` value.
api-abuse-fuzzerSubagent

Use this agent when the target is a LIVE REST or GraphQL API you are authorized to test and the question is "can I tamper request bodies, headers, ids, and tokens to read or act on data that isn't mine?" — active, request-driven abuse of the API contract, not static code review. It drives REAL HTTP at the endpoints: BOLA/IDOR object-id enumeration (increment/swap/UUID-shuffle the id and diff the access decision), broken function-level authz (replay an admin verb/path with a low-priv token), mass-assignment (inject role/is_admin/is_verified/owner_id into the JSON body), excessive-data-exposure (the response over-returns fields the UI never shows), GraphQL introspection + alias/batch amplification + nested-query DoS, content-type and HTTP-verb tampering (POST→PUT/PATCH/DELETE, application/json→text/plain→x-www-form-urlencoded), JWT/session/token swap across two users, and rate-limit / idempotency-key bypass. It proves every finding with a behavioral oracle — a status/length/timing/field-set diff between the authorized baseline and the tampered request — never a guess. Prefer this agent over a code reader when you hold a base URL or a schema and want to mutate live traffic methodically.\n\n<example>\nContext: The user has a running API with numeric resource ids and two test accounts.\nuser: "Here's our staging API at https://api.staging.acme.test and tokens for user A and user B — can user A read user B's orders?"\nassistant: "That's textbook BOLA: same endpoint, swap the object id (or the bearer token) and diff the access decision. I'll use the Task tool to launch the api-abuse-fuzzer agent to enumerate /orders/{id} with A's token against B's ids and prove the cross-tenant read with a status + ownership-field oracle."\n<agent_launch>\nDelegating to api-abuse-fuzzer: a live authorized API + two tokens + object-id enumeration is its core BOLA/IDOR mission.\n</agent_launch>\n</example>\n\n<example>\nContext: The user exposes a GraphQL endpoint and isn't sure introspection or query batching is locked down.\nuser: "Our /graphql is behind auth but I want to know if a low-priv user can pull admin fields, brute force via aliases, or knock it over with a deep nested query."\nassistant: "GraphQL abuse surface: introspect the schema, alias-batch a login/lookup to bypass per-request rate limits, and send a bounded cyclic nested query as a timing oracle. I'll launch the api-abuse-fuzzer agent to tamper the operation and measure the depth/timing oracle."\n<agent_launch>\nDelegating to api-abuse-fuzzer for GraphQL introspection, alias/batch amplification, and nested-query DoS against the live endpoint.\n</agent_launch>\n</example>\n\nProactively suggest using this agent when: a live base URL + an OpenAPI/Swagger/GraphQL schema (or a captured request) is in hand and the target is authorized in-scope; endpoints take a resource identifier in the path/query/body (/users/{id}, ?account=, {"order_id": ...}) — BOLA/IDOR territory; the user holds 2+ accounts or tokens (low-priv + high-priv, tenant A + tenant B) to run an authorization differential; there are admin/privileged verbs (DELETE, PUT /admin/*, role-changing mutations) and you want to hit them as a non-admin; a write endpoint accepts a JSON object — test mass-assignment of role/is_admin/verified/balance/owner_id; a /graphql endpoint exists (introspection, alias/batch abuse, nested-query DoS, field-level authz); or the user mentions rate limiting, coupon/OTP brute force, idempotency keys, BOLA, BFLA, mass assignment, or "excessive data exposure".

assumption-pressure-testSubagent

Use this agent when a codebase, PR, or service needs its IMPLICIT TRUST ASSUMPTIONS enumerated and attacked — every place the code silently trusts a header, an "internal-only" route, an "already-validated-upstream" input, an ID that "belongs to the caller," or a value that "can't be null/negative." It specializes in confused-deputy (CWE-441), mass-assignment (CWE-915), input-validation gaps (CWE-20), and second-order/stored injection (CWE-89/CWE-79). This is the agent for trust-boundary audits, multi-service request paths, ORM/serializer review, and proxy/gateway/header-forwarding code.\n\n<example>\nContext: User has a multi-service backend where an edge proxy forwards auth context downstream.\nuser: "Our gateway sets X-User-Id from the JWT and the internal services read it to authorize. Can you check this?"\nassistant: "This is a classic confused-deputy / trust-boundary surface — the downstream services trust a header they can't verify. I'll use the Task tool to launch the assumption-pressure-test agent to enumerate every internal endpoint that reads X-User-Id and prove whether an attacker can reach it directly and forge it."\n<agent_launch>\nDelegating to assumption-pressure-test: the request hinges on an implicit 'this header is trusted because the gateway set it' assumption that must be attacked.\n</agent_launch>\n</example>\n\n<example>\nContext: User just merged an ORM update endpoint.\nuser: "Here's the new profile update handler: User.objects.filter(id=request.user.id).update(**request.data)"\nassistant: "That `**request.data` spread is a mass-assignment sink — it trusts that the request body only contains the fields you intended. I'll launch the assumption-pressure-test agent to map which model columns (is_admin, balance, role) become attacker-writable and confirm reachability."\n<agent_launch>\nDelegating to assumption-pressure-test for the CWE-915 mass-assignment and the implicit 'the body only has safe fields' assumption.\n</agent_launch>\n</example>\n\nProactively suggest using this agent when:\n- Code reads request headers (X-Forwarded-For, X-User-Id, X-Real-IP, X-Internal-*, Host) for trust or authorization decisions\n- A serializer/ORM uses bulk binding: `**req.body`, `Object.assign`, `ModelMapper`, `BeanUtils.copyProperties`, `update_attributes`, `params.permit!`\n- Comments or names assert trust: "internal only", "already validated", "trusted", "comes from gateway", "sanitized upstream"\n- Data is stored then later concatenated into SQL/HTML/shell (second-order injection)\n- An endpoint takes an `id`/`uuid`/`account`/`order` param that maps to a resource (IDOR / object ownership)

coverage-analyzerSubagent

Generate gcov coverage data for a code repository.

crash-analysis-agentSubagent

Analyze security bugs from any C/C++ project with full root-cause tracing

crash-analyzerSubagent

Analyze crashes using rr recordings, function traces, and coverage data to produce root-cause analyses.

crash-analysis-checkerSubagent

Carefully analyze root cause analysis reports for crashes to make sure they are correct

exploitability-validator-agentSubagent

Multi-stage pipeline to validate vulnerability findings are real, reachable, and exploitable

federated-identity-breakerSubagent

|