---
name: redmirror
description: Scan a codebase for security and correctness bugs with RedMirror from the command line, and (its distinctive power) CHECK A CUSTOM RULE you state in plain English. Use when the user asks to scan, audit, or security-review code, find vulnerabilities, check a subsystem (auth, billing, permissions), OR verify that a specific property/requirement holds, e.g. "a user can never see another tenant's data", "a refund can never exceed the original charge", "deleting an account removes all its records". RedMirror turns each such `--focus` rule into a checkable invariant and searches the real code for a counterexample; it also reproduces candidate bugs to cut false positives and returns findings ranked by impact with a confidence band. The source stays on the user's machine. Trigger on "scan this repo", "audit the auth code", "find security bugs in X", "check that <requirement> holds in <code>", or "/redmirror".
---

# RedMirror — drive security scans from the CLI

RedMirror is a hosted code-scanning service you drive from the terminal. You point it at a
path and a scope; it reviews the code, **reproduces** each candidate bug to filter out false
positives, and returns a ranked list of findings — each with a file:line, a short explanation,
a confidence band, and an impact rank. Your job as the coding agent is to pick a good **scope**
and **angle**, run the scan, then **triage** the findings against the real code before acting.

**The most valuable thing you can do is lead with a `--focus`.** RedMirror is not limited to a
fixed bug catalog: it turns a rule you state in **plain English** into a checkable invariant and
searches the real code for an input that breaks it, returning the exact sequence that does. Security
rules *and* business/functional requirements both work, e.g. `--focus "a user can never withdraw more
than their balance"`, `--focus "deleting a task removes it for every user"`,
`--focus "only the owner can change the fee"`. **When the user states a requirement, that IS the
scan**; pass it verbatim as `--focus`. This custom-angle ability is RedMirror's core power; reach
for it before a generic no-focus scan whenever the user cares about a specific property.

## 1. Setup (once)

```bash
# install the native CLI (self-updating binary, NOT pip)
curl -fsSL https://redmirror.io/install.sh | sh        # macOS / Linux
#   Windows (PowerShell):  irm https://redmirror.io/install.ps1 | iex

# sign up in the browser at https://redmirror.io/wallet, mint an API key, then:
redmirror login --key rm_live_xxx
#   ...or in CI / non-interactive:  export REDMIRROR_API_KEY=rm_live_xxx
redmirror balance              # check funds + spend
```

Scans are **billed per token**. Estimate first with `redmirror estimate <path> --subsystem <dir>`
(local, free, no tokens); check `redmirror balance` before and after; a scan prints its own cost
at the end. Keep the CLI current with `redmirror update`.

## 2. Run a scan

```bash
redmirror scan <path> --subsystem <dir> --focus "<a requirement in plain English>"
```

| flag | what it does |
|---|---|
| `<path>` | a local repo path **or** a git URL (cloned shallowly, scanned, discarded) |
| `--subsystem <dir>` | **scope to one directory** (default `.` = whole repo). This is the most important flag — see §4. Must be a directory, not a single file. |
| `--focus "<text>"` | a custom angle: any security rule **or functional requirement** in plain English. Repeatable. The scan looks hardest for code that violates it. |
| `-o, --out <file>` | write the Markdown findings report here (default `redmirror-findings.md`). It explains the confidence bands and, for confirmed findings, why they're reachable. |
| `--no-sandbox` | skip the local sandbox reproduction step — faster + cheaper, but more false positives. Reproduction is **on by default** when the sandbox is available. |

**Examples**

```bash
# Audit one subsystem against a concrete security property
redmirror scan ./api --subsystem src/auth \
  --focus "a request must never be authorized beyond the API key's own permissions, budget, or scope"

# Check a functional requirement (angles aren't only security)
redmirror scan ./app --subsystem src/tasks \
  --focus "deleting a task must remove it for every user, with no orphaned references"

# Scan a remote repo, save the Markdown report for triage
redmirror scan https://github.com/org/repo --subsystem services/billing -o findings.md
```

## 3. Read the results

Findings are printed **ranked by impact** (confidence × severity). Each carries a **confidence band**:

- **high / medium / low** — a candidate bug, banded by how strongly it held up.
- **refuted** — a candidate that RedMirror argued *against* (e.g. it's defined elsewhere, a guard
  already handles it, or it's by-design). Refuted findings are **down-ranked, not hidden** — a
  wrongly-refuted real bug is still listed, just low. Scan these last.

Treat the output as a **prioritized worklist**, not a verdict. For each high/medium finding, open the
cited `file:line` and confirm the path is real before you act on it. A custom `--focus` requirement
that's violated is tagged highest — start there.

## 4. Scope deliberately (this controls cost and signal)

Cost scales with the **size and complexity of the scope you pick**, not the size of the repo. The
right pattern for a large codebase is **one security-dense subsystem at a time**, prioritized:

```bash
redmirror scan ./repo --subsystem src/auth            # first: the auth boundary
redmirror scan ./repo --subsystem src/billing         # then: money / quotas
redmirror scan ./repo --subsystem src/permissions     # then: access control
```

Pointing `--subsystem` at a giant directory (hundreds of files) is the expensive mode — it reviews
everything. A focused subsystem is both **cheaper** and **higher signal**. If a scan is interrupted
(network, Ctrl-C), just **re-run the same command** — it resumes from where it stopped.

## 5. What leaves your machine (data handling)

When you scan, the in-scope source (the subsystem you scope to) is uploaded to the analysis engine,
processed in memory, and **deleted as soon as the scan finishes**. **RedMirror's servers keep no copy
of your code** (only token counts, for billing); prompts and source are never persisted. You control
exactly what is sent by scoping with `--subsystem`. Within that scope, a review fetches only the specific code windows it needs.

## 6. Good agent habits

- **Lead with a `--focus`** drawn from the user's actual requirement — it sharpens recall on the bug
  they care about and tags it highest.
- **Scope to the subsystem under discussion**, not the whole repo, unless the user asks for a sweep.
- **Triage before reporting**: open each high/medium finding's `file:line` and verify it's reachable;
  don't forward a finding you haven't read.
- **Save the report with `-o`** so you can cite exact `file:line` locations back to the user; findings also stream to the terminal as they're found, with periodic progress while a scan runs.
- If the user worries about cost, run `redmirror balance` first and scope tighter; a scan prints its
  cost when it finishes.