@rafter-security/cli 0.6.6 → 0.7.1

package/resources/skills/rafter/docs/cli-reference.md

@@ -0,0 +1,199 @@
+# Rafter CLI Reference
+
+Full command tree for the `rafter` CLI. Commands group by concern: **scanning**, **agent** (local security primitives), **hook** (platform bridges), **policy**, **ci**, **mcp**, **docs/brief**, **notify**, **report**.
+
+Global flags:
+- `-a, --agent` — plain output (no colors/emoji) for AI consumers.
+- `--version`, `version` — print version.
+
+Exit codes (consistent across commands):
+- `0` — success / no findings
+- `1` — findings detected OR general error
+- `2` — invalid input / scan not found
+
+All scan commands write results as JSON on stdout and status on stderr; safe to pipe.
+
+---
+
+## Scanning
+
+### `rafter run [opts]` · `rafter scan [opts]` · `rafter scan remote [opts]`
+
+Trigger a remote security scan on a GitHub repo. Auto-detects current repo/branch.
+
+When to reach for it:
+- "Is this branch safe to merge?"
+- Pre-deploy / post-dependency-update gating.
+- Any request for SAST, SCA, or "security audit" of a repo.
+
+Key options: `--repo org/repo`, `--branch <name>`, `--mode fast|plus`, `--format json|md`, `--api-key <key>`, `--github-token <pat>` (private repos), `--skip-interactive`, `--quiet`.
+
+Example: `rafter run --repo myorg/api --branch feature/auth --mode plus --format json`
+
+### `rafter scan local [path]`
+
+Local secret scan. Deterministic, offline, no API key. Dual-engine: Gitleaks binary if present, built-in regex fallback (21+ patterns).
+
+When: pre-commit, pre-push, fast first pass before remote scan, air-gapped envs.
+
+Useful flags: `--history` (scan git history with Gitleaks), `--format json`, `--quiet`.
+
+Example: `rafter scan local . --format json`
+
+### `rafter get <scan-id>`
+
+Retrieve results of a previously triggered remote scan.
+
+When: after `rafter run --skip-interactive`, or when a scan id was shown and you need the report.
+
+Example: `rafter get scan_abc123xyz --format json`
+
+### `rafter usage`
+
+Show API quota / usage for `RAFTER_API_KEY`.
+
+When: before firing multiple remote scans, or when the user asks about limits.
+
+---
+
+## Agent (Local Security Primitives)
+
+### `rafter agent exec -- <command>`
+
+Classify and optionally run a shell command through Rafter's risk tiers (critical / high / medium / low).
+
+When: any time a destructive-looking command is about to be executed by an agent. Use `--dry-run` to classify without running.
+
+Example: `rafter agent exec --dry-run -- rm -rf $WORK_DIR`
+
+### `rafter agent audit [path]`
+
+Audit a directory for suspicious or risky code patterns — focused on plugins, skills, extensions, and tooling a user might install.
+
+When: vetting a third-party skill, MCP server, or CLI plugin before install.
+
+### `rafter agent audit-skill <path>`
+
+Audit a single skill file (SKILL.md). Flags prompt-injection, unbounded tool use, exfiltration patterns.
+
+### `rafter agent scan [path]`
+
+Alias for `rafter scan local` kept for back-compat. Prefer `rafter scan local`.
+
+### `rafter agent status` · `rafter agent verify`
+
+`status`: dump config, hook state, gitleaks availability, audit log location.
+`verify`: sanity-check installation; exit non-zero if anything is broken.
+
+### `rafter agent init [--with-<platform>]`
+
+Install rafter skills and/or hooks into a supported agent (`claude-code`, `codex`, `gemini`, `cursor`, `windsurf`, `aider`, `openclaw`, `continue`). See `rafter brief setup/<platform>`.
+
+### `rafter agent init-project`
+
+Scaffold `.rafter.yml` and a baseline for the current repo.
+
+### `rafter agent install-hook`
+
+Install a pre-commit hook that runs `rafter scan local` before every commit.
+
+### `rafter agent config [get|set|list]`
+
+Read/write Rafter config (global `~/.rafter/config.yml` and local `.rafter.yml`).
+
+### `rafter agent baseline`
+
+Snapshot current findings so only *new* ones fail future scans.
+
+### `rafter agent instruction-block`
+
+Emit a ready-to-paste instruction block for an agent's system prompt.
+
+### `rafter agent update-gitleaks`
+
+Download / upgrade the Gitleaks binary Rafter uses for local scans.
+
+---
+
+## Hooks (Agent Platform Bridges)
+
+### `rafter hook pretool`
+
+Stdin → JSON pretool event from an agent (e.g. Claude Code). Classifies the pending tool call and returns approve/block with reasoning.
+
+### `rafter hook posttool`
+
+Stdin → JSON posttool event. Logs to audit trail, optionally post-scans written files for secrets.
+
+See `docs/guardrails.md` for how these plug into Claude Code / other platforms.
+
+---
+
+## Policy
+
+### `rafter policy export [--format yml|json]`
+
+Emit the effective merged policy (defaults + global + `.rafter.yml`).
+
+### `rafter policy validate <file>`
+
+Lint a policy file. Non-zero exit on invalid structure.
+
+---
+
+## CI
+
+### `rafter ci init [--provider github|gitlab|circle|...]`
+
+Generate a CI workflow that runs `rafter scan` on PR + main, with sensible defaults (caching, JSON artifact, comment-on-PR where supported).
+
+---
+
+## MCP
+
+### `rafter mcp serve`
+
+Start the Rafter MCP server over stdio. Exposes:
+- Tools: `scan_secrets`, `evaluate_command`, `read_audit_log`, `get_config`
+- Resources: `rafter://config`, `rafter://policy`
+
+Use from any MCP-capable client (Gemini, Cursor, Windsurf, Aider, Continue.dev). See `rafter brief setup/<platform>`.
+
+---
+
+## Knowledge / Meta
+
+### `rafter brief [topic]`
+
+Print rafter knowledge for any agent. Topics include: `security`, `scanning`, `commands`, `pricing`, `setup`, `setup/<platform>`, `all`, plus sub-doc topics (`cli-reference`, `guardrails`, `backend`, `shift-left`, `finding-triage`).
+
+### `rafter notify --scan-id <id> --to <slack|discord-webhook>`
+
+Post a scan summary to Slack or Discord.
+
+### `rafter report --scan-id <id> [--out report.html]`
+
+Generate a self-contained HTML security report for sharing.
+
+### `rafter issues sync --scan-id <id>`
+
+Open / update GitHub Issues from scan findings (one issue per rule).
+
+### `rafter completion <bash|zsh|fish>`
+
+Emit shell completion script.
+
+---
+
+## Quick Decision Table
+
+| User intent | Command |
+|---|---|
+| Fast secret check locally | `rafter scan local .` |
+| Full repo security review | `rafter run` (then `rafter get <id>`) |
+| "Is this command safe?" | `rafter agent exec --dry-run -- <cmd>` |
+| "Is this skill safe to install?" | `rafter agent audit <path>` |
+| Add pre-commit protection | `rafter agent install-hook` |
+| Wire up CI | `rafter ci init` |
+| Connect an agent | `rafter agent init --with-<platform>` |
+| Share a report | `rafter report --scan-id <id>` |

package/resources/skills/rafter/docs/finding-triage.md

@@ -0,0 +1,79 @@
+# Finding Triage — Reading a Rafter Finding
+
+How to go from a raw Rafter finding to a decision: **fix now**, **fix later**, **suppress**, or **escalate**.
+
+## Anatomy of a Finding
+
+Every finding (local or remote) has this shape:
+
+```jsonc
+{
+  "ruleId": "HARDCODED_API_KEY",       // stable ID — use in overrides / baselines
+  "severity": "critical",               // critical | high | medium | low | info
+  "confidence": "high",                 // high | medium | low
+  "file": "src/config/prod.ts",
+  "line": 42,
+  "title": "Hardcoded API key",
+  "description": "...",
+  "recommendation": "...",              // suggested fix, when available
+  "evidence": "API_KEY = \"sk-...\""    // snippet (may be redacted)
+}
+```
+
+Three fields do most of the work: **severity**, **confidence**, and **ruleId**.
+
+## Decision Flow
+
+1. **Severity `critical` + confidence `high`** → fix before merge. Non-negotiable. Examples: hardcoded production secrets, SQL injection, RCE via unsafe deserialization.
+2. **Severity `high` + confidence `high`** → fix this PR unless there's a specific reason not to (document it in the baseline).
+3. **`high` + confidence `medium/low`** → investigate. Often a real issue in a weird codepath; sometimes a pattern false-positive.
+4. **`medium`** → fix within a reasonable window; batch with related work.
+5. **`low` / `info`** → style/hygiene. Suppress at the rule level if consistently noisy.
+
+Confidence matters: a `high`-severity, `low`-confidence finding is a hypothesis, not a verdict. Confirm by reading the evidence + surrounding code before acting.
+
+## Common Rule Categories
+
+| Rule family | What it means | First move |
+|---|---|---|
+| `HARDCODED_*` (secrets, tokens, keys) | A literal credential is in source | Rotate the credential, then remove from code & git history |
+| `SQL_INJECTION`, `COMMAND_INJECTION` | Unsanitized input reaches a sink | Parameterize / use a safe API; fix at the source, not by escaping at the sink |
+| `INSECURE_DESERIALIZATION` | `pickle`, `yaml.load`, `Marshal`, untrusted JSON → `eval` | Switch to safe loader; never deserialize untrusted data into native objects |
+| `WEAK_CRYPTO` (`MD5`, `SHA1`, `DES`, `ECB`) | Algorithm/mode doesn't meet modern threat model | Swap algorithm; check for backwards-compat constraints |
+| `PATH_TRAVERSAL` | User input flows into filesystem path | Canonicalize + verify within allow-rooted dir |
+| `SSRF` | User input controls outbound URL | Allowlist hosts; resolve IPs and block internal ranges |
+| `DEPENDENCY_CVE` (SCA) | Transitive/direct dep has known CVE | Bump to a patched version; if none, check if the vulnerable code path is reachable |
+
+## Before Rotating or Nuking Something
+
+If the finding is a leaked secret that was committed:
+1. **Rotate first.** Assume the secret is compromised the moment it touched git history.
+2. Remove from history if the repo is private *and* short-lived; otherwise rotation is the real fix.
+3. Add the pattern to pre-commit (`rafter agent install-hook`) so it doesn't happen again.
+
+## Suppression — When It's OK
+
+Suppress only when the finding is a real false positive *for this context*, with a written reason. Two mechanisms:
+
+- **Inline**: `// rafter-ignore: HARDCODED_API_KEY — test fixture, not a real key`
+- **Baseline**: `rafter agent baseline` snapshots current findings; only *new* findings fail future scans. Good for adopting Rafter on a legacy codebase without a big bang.
+
+Never suppress by:
+- Commenting out the rule globally.
+- Broadening an allow-pattern beyond the specific file/context.
+- Deleting the scan step from CI.
+
+## Escalation
+
+Escalate a finding (to security team, or back to the user) when:
+- It implicates production credentials or customer data.
+- It's a design-level issue the local fix can't address (e.g. "the auth model is wrong").
+- The fix requires coordination across services or a rotation playbook.
+
+Provide `scanId`, `ruleId`, file + line, and the evidence snippet. Exit code + JSON makes this a copy-paste to a ticket.
+
+## Tie-Backs
+
+- Want depth on a single finding? Rerun with `--mode plus` (see `docs/backend.md`).
+- Want to prevent the class of finding? See `docs/shift-left.md` → `rafter-secure-design`.
+- Want structured review around the finding? See `docs/shift-left.md` → `rafter-code-review`.

package/resources/skills/rafter/docs/guardrails.md

@@ -0,0 +1,91 @@
+# Rafter Guardrails — PreToolUse Hooks & Command Risk
+
+How Rafter intercepts agent tool calls before they execute, how it decides what to block, and how to override safely.
+
+## The Shape
+
+Rafter exposes two hook handlers over stdio:
+
+- `rafter hook pretool` — read a JSON event on stdin (from Claude Code, etc.), emit an approve/block decision on stdout.
+- `rafter hook posttool` — read a JSON event after a tool ran; log to audit trail, optionally rescan written files for secrets.
+
+For platforms without hooks, the same classifier is reachable as:
+- `rafter agent exec --dry-run -- <command>` (returns risk, exits 0/1)
+- `rafter mcp serve` → MCP tool `evaluate_command`
+
+## Risk Tiers
+
+Every command (Bash-like tool call) gets classified into one of four tiers by `src/core/risk-rules.ts`:
+
+| Tier | What it means | Default hook behavior |
+|---|---|---|
+| `low` | Read-only, safe prefix (`ls`, `cat`, `grep`, `git status` …), no chaining | **approve** silently |
+| `medium` | State-changing but recoverable (package installs, git commits on current branch) | **approve with note** in audit log |
+| `high` | Destructive or privileged (force push, `sudo`, broad file deletion, curl | sh) | **prompt** the agent / user for approval |
+| `critical` | Likely irreversible damage (`rm -rf /`, DB drop, wiping .git, repo-wide chmod) | **block** hard |
+
+Tiers are derived from regex patterns in `risk-rules.ts` (`CRITICAL_PATTERNS`, `HIGH_PATTERNS`, `MEDIUM_PATTERNS`) plus a `SAFE_PREFIX` allowlist. Presence of chain operators (`&&`, `||`, `;`, `|`) disqualifies the safe-prefix shortcut.
+
+## Policy Overrides
+
+`.rafter.yml` (project) and `~/.rafter/config.yml` (global) can override defaults:
+
+```yaml
+risk:
+  blocked_patterns:
+    - "terraform destroy"
+  require_approval:
+    - "^npm publish"
+  allow:
+    - "^pnpm run test"     # force low regardless of content
+```
+
+Merge order (most specific wins): project `.rafter.yml` > global config > built-in defaults. Dump the effective merged policy with `rafter policy export`.
+
+## How to Interpret a Block
+
+When a hook blocks a command, the JSON response includes:
+
+- `decision`: `"block" | "approve" | "ask"`
+- `riskLevel`: `"critical" | "high" | "medium" | "low"`
+- `reason`: the matched pattern or policy rule
+- `ruleId`: stable ID you can reference in overrides / suppressions
+
+**Before overriding, ask: is there a safer form of this command?** Example:
+- `rm -rf $DIR` with unvalidated `$DIR` → use explicit path or `--one-file-system`.
+- `curl <url> | sh` → download, inspect, then run.
+- `git push --force` → `git push --force-with-lease`.
+
+## How to Request an Override
+
+If the block is a false positive **for this specific context**, the right path is:
+
+1. Add an allow pattern scoped to the project in `.rafter.yml`:
+   ```yaml
+   risk:
+     allow:
+       - "^terraform destroy -target=module\\.sandbox"
+   ```
+2. Or run once with an explicit ack flag: `rafter agent exec --force -- <command>` (logged to audit trail; still shows up in `rafter agent audit` history).
+3. Never disable the hook globally to get past one command — that silently drops protection for every future call.
+
+## Audit Trail
+
+Every hook decision (approve / ask / block) is appended to the JSONL audit log:
+
+- Location: `rafter agent status` prints the path.
+- Read: `rafter agent audit --log` (or MCP `read_audit_log`).
+- Use it for postmortems: *why did this command run?*, *what did the agent try before the block?*
+
+## Platform Notes
+
+- **Claude Code**: `rafter agent init --with-claude-code` wires `pretool` + `posttool` into `~/.claude/settings.json`. Hook timeout is 5s; long scans defer to the async posttool path.
+- **MCP clients (Gemini, Cursor, …)**: no native hook; use the `evaluate_command` MCP tool from your agent's system prompt ("before Bash, call rafter.evaluate_command").
+- **CI**: hooks don't fire in CI. Use `rafter scan` + `rafter policy validate` in the pipeline instead.
+
+## Common Pitfalls
+
+- A `low` classification is not a safety guarantee — it means "no known-bad pattern matched". Still review unusual commands.
+- Chaining defeats the safe-prefix allowlist on purpose (`ls && rm -rf /` is not low-risk).
+- `sudo` always escalates to at least `high` regardless of the wrapped command.
+- Secret leaks in arguments (`curl -H "Authorization: Bearer abc..."`) are flagged by posttool scanning, not by the pretool risk classifier.

package/resources/skills/rafter/docs/shift-left.md

@@ -0,0 +1,64 @@
+# Shift-Left — Secure Design & Code Review Skills
+
+`rafter` (this skill) handles **detection**: scanners, hooks, risk classifiers. Two sibling skills cover the earlier stages of the lifecycle — use them when prevention or structured review is more valuable than another scan pass.
+
+## Decision Tree
+
+| You're trying to … | Reach for |
+|---|---|
+| Write code that **doesn't have the flaw in the first place** (design phase, picking primitives, shaping APIs) | `rafter-secure-design` |
+| **Review existing code** against OWASP Top 10 / MITRE ATT&CK / ASVS with a structured walkthrough | `rafter-code-review` |
+| Find concrete bugs / leaks / CVEs automatically | stay in this skill — see branch (a) in SKILL.md |
+
+The three skills compose: design well (secure-design) → write it → review it (code-review) → detect what slipped through (rafter scan + guardrails).
+
+## `rafter-secure-design` (filed as rf-bcr)
+
+Use at feature kickoff or during architecture review, *before* code exists. It's a CYOA over design decisions:
+
+- Authn / authz primitives: which to pick, which to refuse (e.g. homegrown JWT signing).
+- Input boundaries: where to validate, where to escape, where to parameterize.
+- Secrets handling: storage, rotation, scoping of least-privilege credentials.
+- Data-in-transit / data-at-rest defaults per language/framework.
+- Threat modeling prompts: STRIDE-style walks you can run with an agent.
+
+Invoke it by name in platforms that auto-trigger skills, or:
+```bash
+rafter brief shift-left      # this doc
+# and then load the sibling:
+#   Read skills/rafter-secure-design/SKILL.md
+```
+
+## `rafter-code-review` (landed)
+
+Use during code review — your own or an AI's. A CYOA router into OWASP / MITRE / ASVS walkthroughs phrased as *questions*, not as monolithic audits. It's the *analysis* counterpart to automated scanning.
+
+Pick the category that matches the code in front of you:
+
+- **Web app** → `rafter-code-review/docs/web-app.md` (OWASP Top 10 2021).
+- **REST / GraphQL / gRPC API** → `rafter-code-review/docs/api.md` (OWASP API Top 10 2023).
+- **LLM-integrated feature** → `rafter-code-review/docs/llm.md` (OWASP LLM Top 10 2025).
+- **CLI / library / IaC** → `rafter-code-review/docs/cwe-top25.md` (MITRE CWE Top 25, keyed by language).
+- **Need to pick review depth** → `rafter-code-review/docs/asvs.md` (ASVS L1/L2/L3 selection + spot-checks).
+- **Single suspicious finding to chase** → `rafter-code-review/docs/investigation-playbook.md`.
+
+Start at `rafter-code-review/SKILL.md` — it's a router; Read only the one sub-doc you need so you don't flood context.
+
+Pair with `rafter run --mode plus` when you want both a human-style walkthrough and the backend's deep pass on the same diff.
+
+## When to use which (cheat sheet)
+
+- Designing a new service → **secure-design**.
+- Reviewing a teammate's PR by eye → **code-review**.
+- CI gate / pre-push / scheduled scan → **rafter** (this skill), `rafter run` / `rafter scan local`.
+- "I have a finding, now what?" → **rafter**, `docs/finding-triage.md`.
+- "I have a risky command, is it safe?" → **rafter**, `docs/guardrails.md`.
+
+Do not duplicate. If a sibling skill already owns the topic, Read it and stop — don't re-derive the checklist here.
+
+## Status
+
+- `rafter-code-review` — **landed** (rf-z7j). Ships alongside this skill; invoke directly.
+- `rafter-secure-design` — **landed** (rf-bcr). Ships alongside this skill; invoke directly. Router skill with sub-docs for auth, data storage, API design, ingestion, deployment, dependencies, threat modeling, and standards pointers.
+
+Both are installed — prefer invoking them directly for structured output over re-deriving checklists here.

package/resources/skills/rafter-agent-security/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rafter-agent-security
 description: "Rafter local security tools — deterministic secret scanning, command risk assessment, skill auditing, and audit log review. Use when: checking for leaked credentials or API keys, evaluating whether code is safe to push, auditing skills before installation, reviewing security events. Works offline, no API key needed. Run `rafter brief security` for full capabilities."
-version: 0.6.5
+version: 0.7.0
 allowed-tools: [Bash, Read, Glob, Grep]
 ---
 

package/resources/skills/rafter-code-review/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: rafter-code-review
+description: "Structured security code review — OWASP / MITRE / ASVS walkthroughs as questions, not audits. Router skill: pick what kind of code you're reviewing (web app, REST/GraphQL API, LLM-integrated, CLI/library/IaC) and Read the matching sub-doc. Designed to pair with `rafter scan` / `rafter run` — the scanner finds known-bad patterns, this skill asks the questions that patterns miss. Use during PR review, refactoring risky modules, or pre-release hardening."
+version: 0.7.0
+allowed-tools: [Bash, Read, Glob, Grep]
+---
+
+# Rafter Code Review — Structured Security Walkthroughs
+
+A reviewer's skill, not an audit generator. Each sub-doc is a set of **questions** to run against the code — what to grep for, what to trace, what to ask before you sign off. No monolithic reports.
+
+> Pair with the `rafter` skill (detection: `rafter scan`, `rafter run`) and `rafter-secure-design` (prevention: design-phase walks). This skill is the middle stage — review before merge.
+
+## How to use this skill
+
+1. Identify the category of code in front of you (below).
+2. `Read` only the matching sub-doc — do not preload them all.
+3. Work through its questions against the specific files/diff. Cite file:line evidence as you go.
+4. When in doubt on a single finding, jump to `docs/investigation-playbook.md` for canonical follow-up questions.
+5. Finish with `rafter run --mode plus` on the same diff if the stakes warrant a deep automated pass.
+
+---
+
+## Choose Your Adventure
+
+### (1) Web application (server-rendered, session-based, or SPA backend)
+
+For: login flows, session/cookie handling, form handlers, template rendering, admin panels, anything browser-facing.
+
+- **Read `docs/web-app.md`** — OWASP Top 10 (2021) walk: broken access control, crypto failures, injection, insecure design, misconfig, vulnerable components, authn failures, integrity failures, logging gaps, SSRF.
+
+### (2) REST / GraphQL / gRPC API (machine-to-machine, mobile backend, public API)
+
+For: endpoint surface that isn't primarily rendering HTML — tokens instead of sessions, authz-per-endpoint, rate limiting.
+
+- **Read `docs/api.md`** — OWASP API Security Top 10 (2023): BOLA, broken authn, BOPLA, unrestricted resource consumption, BFLA, unrestricted access to sensitive business flows, SSRF, misconfig, improper inventory, unsafe consumption of third-party APIs.
+
+### (3) LLM-integrated feature (prompts, agents, tools, RAG, embeddings)
+
+For: anything that sends user text to a model, uses tool calls, retrieves untrusted context, or ships model output to a downstream system.
+
+- **Read `docs/llm.md`** — OWASP LLM Top 10 (2025): prompt injection, sensitive info disclosure, supply chain, data/model poisoning, improper output handling, excessive agency, system prompt leakage, vector/embedding weaknesses, misinformation, unbounded consumption.
+
+### (4) CLI, library, or infra-as-code
+
+For: build tooling, developer CLIs, shared SDK packages, Terraform / CloudFormation / Kubernetes manifests, shell scripts.
+
+- **Read `docs/cwe-top25.md`** — MITRE CWE Top 25, keyed by language (Python / JS / Go / Rust / Java) and by IaC primitive. Focus on injection, memory safety, path traversal, race conditions, privilege mismanagement.
+
+### (5) I need to pick the right depth for this review
+
+For: "how hard should I look?", scoping a review before starting, compliance-adjacent changes.
+
+- **Read `docs/asvs.md`** — OWASP ASVS L1 / L2 / L3. Picks the level based on risk tier of the code, then gives spot-check questions per level.
+
+### (6) I have one specific question to investigate
+
+For: single-finding follow-up, tracing a suspicious call, "is this input reachable from outside?".
+
+- **Read `docs/investigation-playbook.md`** — canonical questions: reachability, authz coverage, data-flow direction, trust boundary placement.
+
+---
+
+## What this skill will NOT do
+
+- It will not generate a monolithic "security audit report". If you need a report, run `rafter run --mode plus` — the backend is better at that.
+- It will not replace automated scanning. Always pair with `rafter scan local .` (secrets) and `rafter run` (SAST/SCA) before review.
+- It will not produce recommendations without evidence. Every question expects a file:line answer before moving on.
+
+---
+
+## Fast path for a typical PR review
+
+```bash
+# 1. Run deterministic checks first — cheap, catches the obvious
+rafter scan local .
+rafter run                    # remote SAST/SCA, if RAFTER_API_KEY set
+
+# 2. Then pick the category and walk the questions
+#    Read docs/<category>.md
+```
+
+If the diff spans categories (e.g. a web app that also has an LLM feature), Read both sub-docs and walk them sequentially. Don't try to merge the checklists.
+
+---
+
+## Tie-backs
+
+- Finding from the scanner you don't understand? → `rafter` skill, `docs/finding-triage.md`.
+- Designing a new feature instead of reviewing one? → `rafter-secure-design`.
+- Risky command came up mid-review? → `rafter` skill, `docs/guardrails.md`.

package/resources/skills/rafter-code-review/docs/api.md

@@ -0,0 +1,90 @@
+# API Review — OWASP API Security Top 10 (2023)
+
+REST / GraphQL / gRPC review: authz-per-endpoint, per-object and per-field; rate limiting; bulk operations. Walk each category as questions. Cite file:line before moving on.
+
+## API1 — Broken Object Level Authorization (BOLA)
+
+The most common API vuln. Per-object authz, not per-endpoint.
+
+- For every handler that takes an id (`/orders/:id`, `/users/:user_id/settings`), is there a check that the id belongs to the caller? "Authenticated" is not "authorized".
+- Grep patterns: `findById`, `SELECT ... WHERE id = ?`, `get_object_or_404`. Is the caller's identity in the query, or compared after?
+- GraphQL: authz at the resolver level for *each* field that returns a user-owned object. Schema-level auth is not enough if resolvers fan out.
+- UUIDs do not save you. They only slow discovery; they do not provide authorization.
+
+## API2 — Broken Authentication
+
+- Every unauthenticated endpoint — is it supposed to be? List them: grep for `@AnonymousAllowed`, `permission_classes = []`, middleware skips.
+- Token lifetime, refresh, and revocation: where is a token invalidated on logout / password change / user deletion?
+- JWT-specific: is `alg` pinned? Is the key rotated? Is `iss` / `aud` checked? Is clock skew bounded?
+- API keys: how are they generated (entropy), stored (hashed?), scoped (per-tenant? per-capability?), rotated?
+- Credential endpoints (login, reset, MFA enroll) — rate-limited separately from normal endpoints? Return generic errors? Constant-time compare?
+
+## API3 — Broken Object Property Level Authorization (BOPLA)
+
+Covers both mass-assignment and excessive data exposure.
+
+- Serialization: when returning an object, are sensitive fields (`password_hash`, `mfa_secret`, `internal_notes`, `role`) explicitly excluded? "Return the model" is a red flag; "return a DTO" is the fix.
+- Mass assignment: can the client set fields they shouldn't? `User.objects.update(**request.data)`, `req.body` spread into an ORM constructor, Rails `params.permit!`. Check every update/create path.
+- GraphQL: schema exposes fields; are resolvers authz-checked per field? Can a non-admin introspect admin-only fields?
+
+## API4 — Unrestricted Resource Consumption
+
+- Pagination on every list endpoint? Max page size enforced server-side (not just a default)?
+- Rate limits: per-user, per-IP, per-endpoint. Token bucket? What happens at the limit — 429 with `Retry-After`, or silent 500?
+- Request size limits: body size, file upload size, JSON depth, GraphQL query depth / complexity.
+- Expensive operations: image processing, PDF generation, report export — are they queued, timeboxed, cost-accounted?
+- Amplification: does one API call trigger N outbound calls (email, SMS, push)? Can that N be user-controlled?
+
+## API5 — Broken Function Level Authorization (BFLA)
+
+Different from BOLA — this is "can a regular user invoke an admin function at all?", not "can user A touch user B's data?".
+
+- List admin / privileged endpoints. For each, is there a role check? Is the role from a trusted source (session/token claim) or from the request (`X-Role: admin`)?
+- HTTP verb confusion: does the handler accept PUT/PATCH/DELETE when only GET was authz'd? Are method restrictions on the router or in the handler?
+- Feature flags: does the flag gate *access* or only *visibility*? If the endpoint is reachable when the flag is off, the flag isn't security.
+
+## API6 — Unrestricted Access to Sensitive Business Flows
+
+- Identify flows worth abusing: signup, promo code redemption, ticket/inventory purchase, "add friend", "send invite".
+- Per-flow: is there anti-automation (captcha, proof of work, device fingerprint, delay between steps)? Rate limit per account *and* per payment instrument *and* per IP range?
+- Does the flow leak enumeration? Signup "email already registered" is a known tradeoff — is it the right one here?
+
+## API7 — Server-Side Request Forgery
+
+(Same question set as web-app A10 — see `web-app.md`.)
+
+- Webhook configurators, URL-based imports, OAuth discovery endpoints, image fetchers: any user-supplied URL that the server fetches?
+- DNS rebinding: is the URL resolved once and then reused, or re-resolved on each redirect? Are redirects followed blindly?
+- Cloud metadata (`169.254.169.254`, `metadata.google.internal`) explicitly blocked?
+
+## API8 — Security Misconfiguration
+
+- Error responses: do they include stack traces, SQL fragments, internal hostnames? Production should return stable error shapes only.
+- CORS per-endpoint: any endpoint with `Allow-Credentials: true` *and* a reflected / wildcard origin?
+- Default routes from frameworks still mounted (`/actuator/*`, `/debug/*`, `/_next/*` in dev mode)?
+- Are OPTIONS responses correctly restrictive? Do HEAD and OPTIONS follow the same authz as GET?
+- TLS: are older APIs allowed to accept plain HTTP for backwards compat? If yes — is that documented and scoped?
+
+## API9 — Improper Inventory Management
+
+A governance issue, but reviewable:
+
+- Is there an API version registry? When this PR adds or changes an endpoint, is it documented (OpenAPI / GraphQL schema committed)?
+- Are deprecated endpoints marked and scheduled for removal? Still reachable in production?
+- Non-prod environments (staging, sandbox) — do they share data, credentials, or network paths with prod? Often the weakest link.
+
+## API10 — Unsafe Consumption of Third-Party APIs
+
+- Outbound API calls: is the response validated before use (schema, size, type)? "Trust the third party" is the failure mode.
+- Credentials to third parties: scoped to least privilege? Rotated? Not shared across tenants?
+- What happens on timeout / 5xx from the third party? Fallback to cached data? Log and surface?
+- If the third party is compromised, what is the blast radius here? Does our data flow into untrusted callbacks?
+
+---
+
+## Exit criteria
+
+- Every endpoint touched by the diff has a documented answer for API1 (per-object authz) and API5 (per-function authz).
+- Every new third-party integration has answers for API10.
+- Every new flow has a rate-limit story (API4) and an abuse story (API6).
+- Scanner cross-check: run `rafter run` and reconcile SAST findings against this walk.