@rafter-security/cli 0.6.6 → 0.7.1

package/dist/core/risk-rules.js

@@ -2,9 +2,15 @@
  * Centralized risk assessment rules.
  * Single source of truth — imported by command-interceptor, audit-logger, and config-defaults.
  */
+/** Directories where `rm -rf /<dir>` is catastrophic (data loss / unbootable). */
+const CRITICAL_DIRS = "home|etc|usr|boot|root|sys|proc|lib|lib64|bin|sbin|opt";
 export const CRITICAL_PATTERNS = [
-    /rm\s+(-[a-z]*r[a-z]*\s+)*-[a-z]*f[a-z]*\s+\//, // rm -rf / (any flag order: -rf, -fr, -r -f, -f -r)
-    /rm\s+(-[a-z]*f[a-z]*\s+)*-[a-z]*r[a-z]*\s+\//, // rm -fr / (reversed)
+    // rm -rf / (root only, any flag order)
+    new RegExp(`rm\\s+(-[a-z]*r[a-z]*\\s+)*-[a-z]*f[a-z]*\\s+/(\\s|$)`),
+    new RegExp(`rm\\s+(-[a-z]*f[a-z]*\\s+)*-[a-z]*r[a-z]*\\s+/(\\s|$)`),
+    // rm -rf on critical top-level directories
+    new RegExp(`rm\\s+(-[a-z]*r[a-z]*\\s+)*-[a-z]*f[a-z]*\\s+/(${CRITICAL_DIRS})(/|\\s|$)`),
+    new RegExp(`rm\\s+(-[a-z]*f[a-z]*\\s+)*-[a-z]*r[a-z]*\\s+/(${CRITICAL_DIRS})(/|\\s|$)`),
     /:\(\)\{\s*:\|:&\s*\};:/, // fork bomb
     /dd\s+if=.*of=\/dev\/sd/,
     />\s*\/dev\/sd/,
@@ -55,11 +61,18 @@ export const DEFAULT_REQUIRE_APPROVAL = [
     "git push --force-if-includes",
     "git push .* \\+",
 ];
+/** Read-only commands whose arguments should not trigger risk patterns. */
+const SAFE_PREFIX = /^(grep|egrep|fgrep|rg|ag|ack|echo|printf)\s/;
+/** Shell operators that chain independent commands. */
+const CHAIN_OPERATORS = /[;|&]|&&|\|\|/;
 /**
  * Assess risk level of a command string.
  */
 export function assessCommandRisk(command) {
-    const cmd = command.toLowerCase();
+    const cmd = command.toLowerCase().trim();
+    // Safe prefix only applies to simple (non-chained) commands
+    if (SAFE_PREFIX.test(cmd) && !CHAIN_OPERATORS.test(cmd))
+        return "low";
     for (const pattern of CRITICAL_PATTERNS) {
         if (pattern.test(cmd))
             return "critical";

package/dist/index.js

@@ -6,11 +6,13 @@ import { createGetCommand } from "./commands/backend/get.js";
 import { createUsageCommand } from "./commands/backend/usage.js";
 import { createScanGroupCommand } from "./commands/scan/index.js";
 import { createAgentCommand } from "./commands/agent/index.js";
+import { createSkillCommand } from "./commands/skill/index.js";
 import { createCiCommand } from "./commands/ci/index.js";
 import { createHookCommand } from "./commands/hook/index.js";
 import { createMcpCommand } from "./commands/mcp/index.js";
 import { createPolicyCommand } from "./commands/policy/index.js";
 import { createBriefCommand } from "./commands/brief.js";
+import { createDocsCommand } from "./commands/docs/index.js";
 import { createNotifyCommand } from "./commands/notify.js";
 import { createCompletionCommand } from "./commands/completion.js";
 import { createIssuesCommand } from "./commands/issues/index.js";
@@ -21,27 +23,27 @@ import { createRequire } from "module";
 dotenv.config();
 const require = createRequire(import.meta.url);
 const { version: VERSION } = require("../package.json");
+// Set agent mode early from argv — preAction hooks may not propagate to nested
+// subcommands on Node 18, so we detect -a/--agent before Commander parses.
+if (process.argv.includes("-a") || process.argv.includes("--agent")) {
+    setAgentMode(true);
+}
 const program = new Command()
     .name("rafter")
     .description("Rafter CLI — the default security agent for AI workflows. Free for individuals and open source. No account required.")
     .version(VERSION)
     .enablePositionalOptions()
     .option("-a, --agent", "Plain output for AI agents (no colors/emoji)");
-// Set agent mode before any subcommand runs
-program.hook("preAction", (thisCommand) => {
-    const opts = thisCommand.opts();
-    if (opts.agent) {
-        setAgentMode(true);
-    }
-});
-// Backend commands
+// Remote scan commands
 program.addCommand(createRunCommand());
 program.addCommand(createGetCommand());
 program.addCommand(createUsageCommand());
-// Scan command group (default: remote backend scan; subcommands: local, remote)
+// Scan command group (default: remote scan; subcommands: local, remote)
 program.addCommand(createScanGroupCommand());
 // Agent commands
 program.addCommand(createAgentCommand());
+// Skill commands (install / uninstall / list rafter-authored skills)
+program.addCommand(createSkillCommand());
 // CI commands
 program.addCommand(createCiCommand());
 // Hook commands (for agent platform integration)
@@ -50,6 +52,8 @@ program.addCommand(createHookCommand());
 program.addCommand(createMcpCommand());
 // Policy commands
 program.addCommand(createPolicyCommand());
+// Docs — repo-specific security docs from .rafter.yml
+program.addCommand(createDocsCommand());
 // GitHub Issues integration
 program.addCommand(createIssuesCommand());
 // Brief — agent-independent knowledge delivery
@@ -60,6 +64,12 @@ program.addCommand(createNotifyCommand());
 program.addCommand(createReportCommand());
 // Shell completions
 program.addCommand(createCompletionCommand());
+// Version subcommand (also available as --version)
+program.addCommand(new Command("version")
+    .description("Print version and exit")
+    .action(() => {
+    console.log(VERSION);
+}));
 // Non-blocking update check — runs after command, prints to stderr
 checkForUpdate(VERSION).then((notice) => {
     if (notice)

package/dist/scanners/gitleaks.js

@@ -82,15 +82,19 @@ export class GitleaksScanner {
     /**
      * Scan a directory
      */
-    async scanDirectory(dirPath) {
+    async scanDirectory(dirPath, opts) {
         if (!await this.isAvailable()) {
             throw new Error("Gitleaks not available");
         }
         const gitleaksPath = this.binaryManager.getGitleaksPath();
         const tmpReport = path.join(os.tmpdir(), `gitleaks-${Date.now()}-${randomBytes(6).toString("hex")}.json`);
         try {
+            const args = ["detect", "-f", "json", "-r", tmpReport, "-s", dirPath];
+            if (!opts?.useGit) {
+                args.splice(1, 0, "--no-git");
+            }
             // Run gitleaks detect on directory
-            await execFileAsync(gitleaksPath, ["detect", "--no-git", "-f", "json", "-r", tmpReport, "-s", dirPath], { timeout: 60000 });
+            await execFileAsync(gitleaksPath, args, { timeout: 60000 });
             // No leaks found
             if (!fs.existsSync(tmpReport)) {
                 return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafter-security/cli",
-  "version": "0.6.6",
+  "version": "0.7.1",
   "type": "module",
   "bin": {
     "rafter": "./dist/index.js"

package/resources/skills/rafter/SKILL.md

@@ -1,138 +1,118 @@
 ---
 name: rafter
-description: "Rafter — the security toolkit built for AI workflows. Three tiers: (1) fast local secret scanning, deterministic, no API key needed; (2) remote SAST/SCA with deterministic secret detection and dependency checks via API (fast mode, default); (3) agentic deep-dive analysis with additional passes (plus mode). Use when checking for vulnerabilities, leaked credentials, or whether code is safe to push. Also use before merging PRs, deploying, or shipping new features. If RAFTER_API_KEY is not set, local scanning works fully — don't block on it. Run `rafter brief commands` for full CLI reference."
-version: 0.6.5
-allowed-tools: [Bash]
+description: "Rafter — the security toolkit built for AI workflows. Router skill: pick your task below and Read the matching sub-doc. Covers (a) scanning code/repos, (b) evaluating a command before running, (c) auditing a plugin or skill, (d) understanding a finding, (e) writing secure code from scratch, (f) analyzing existing code for flaws. Local features are free, deterministic, and offline (no API key). Remote SAST/SCA via RAFTER_API_KEY when deeper analysis is needed. If RAFTER_API_KEY is missing, local still works — don't block on it."
+version: 0.7.0
+allowed-tools: [Bash, Read]
 ---
 
-# Rafter Security Toolkit
+# Rafter — Security Toolkit for AI Workflows
 
-Rafter is the security toolkit built for AI workflows — a delegation primitive that other agents and orchestrators trust. It provides three tiers of security scanning:
+Rafter ships three tiers of security tooling:
 
-1. **Local scanning** — fast, deterministic secret detection across 21+ patterns. No API key needed. Always available.
-2. **Remote fast** — deterministic SAST, secret detection, and dependency checks via the Rafter API (default mode).
-3. **Remote plus** — agentic deep-dive analysis with additional passes for thorough security review.
+1. **Local** — deterministic secret scanning, command-risk classification, skill auditing. Free, offline, no API key.
+2. **Remote fast** (default) — SAST + SCA + deterministic secrets via the Rafter API.
+3. **Remote plus** — agentic deep-dive analysis. Your code is deleted after the run.
 
-Stable contracts (exit codes, JSON structure), deterministic results, and your code is deleted immediately after the analysis engine completes.
+Stable exit codes, stable JSON shapes, deterministic findings. Safe to chain in CI and in agent loops.
 
-> **Full CLI reference**: Run `rafter brief commands` for a condensed command reference.
-> **Platform setup**: Run `rafter brief setup/<platform>` for integration guides.
+---
 
-## Core Commands
+## Choose Your Adventure
 
-### Trigger a Security Scan
+Pick the branch that matches what you're trying to do. Each branch points at a sub-doc — `Read` only the one you need so you don't flood context.
 
-```bash
-rafter run [--repo org/repo] [--branch branch-name]
-# or
-rafter scan [--repo org/repo] [--branch branch-name]
-```
+### (a) I want to scan code or a repo for issues
 
-Triggers a comprehensive security code analysis on a repository. Auto-detects current repo and branch if in a git directory. (`scan` is an alias for `run`)
+Use this for: "Is this safe to push?", "Check for leaks", "Run a security scan", pre-merge / pre-deploy gating, post-dependency-update checks.
 
-**When to use:**
-- User asks: "Can you scan this code for security issues?"
-- Before pushing code or shipping new features
-- Before merging a PR or deploying
-- After dependency updates
-- User mentions: security audit, vulnerability scan, SAST, code analysis
-- User asks: "Is this safe to merge?", "Are there vulnerabilities?", "Check this PR"
+- Local secret scan (fast, no key): `rafter scan local .`
+- Remote SAST/SCA (needs `RAFTER_API_KEY`): `rafter run` (alias `rafter scan`)
+- **Read `docs/backend.md`** for fast-vs-plus modes, auth, latency, cost.
+- **Read `docs/cli-reference.md`** §`scan` and §`run` for full flag matrix.
 
-**Example:**
-```bash
-# In a git repo
-rafter scan
+### (b) I want to evaluate a command before running it
 
-# Specific repo
-rafter scan --repo myorg/myrepo --branch main
-```
+Use this for: "Is `rm -rf $DIR` safe?", any destructive-looking shell the user typed, commands with sudo / pipes to `sh` / unversioned curl.
 
-### Get Scan Results
+- One-shot: `rafter agent exec --dry-run -- <command>`
+- Wrap execution: `rafter agent exec -- <command>` (blocks on critical, prompts on high)
+- **Read `docs/guardrails.md`** for how PreToolUse hooks, risk tiers, and overrides work.
 
-```bash
-rafter get <scan-id>
-```
+### (c) I want to review a plugin, skill, or extension before installing
 
-Retrieves results from a completed or in-progress scan.
+Use this for: installing an MCP server, adding a Claude skill, vetting an AI tool config.
 
-**When to use:**
-- After triggering a scan with `rafter run`
-- User asks: "What were the results?" or "Did the scan finish?"
-- Checking on a scan's progress
+- **Installing a new skill? → Read `rafter-skill-review/SKILL.md`** — full provenance, malware, prompt-injection, data-practices, telemetry checklist.
+- Run the deterministic pass: `rafter skill review <path-or-url>` (emits JSON).
+- Audit a directory: `rafter agent audit <path>` (still supported).
+- **Read `docs/cli-reference.md`** §`skill review` / §`agent audit` for output shape and exit codes.
 
-**Example:**
-```bash
-rafter get scan_abc123xyz
-```
+### (d) I want to understand a finding I already have
 
-### Check API Usage
+Use this for: "What does `HARDCODED_SECRET` mean?", "Is this a real issue or noise?", triaging a scan report.
 
-```bash
-rafter usage
-```
+- **Read `docs/finding-triage.md`** — how to parse severity, rule IDs, confidence, and file refs; when to fix, suppress, or escalate.
 
-View your API quota and usage statistics.
+### (e) I want to write secure code from scratch
 
-**When to use:**
-- User asks about remaining scans
-- Before triggering a scan to confirm quota
-- User mentions: quota, usage, limits, remaining scans
+Use this for: designing a new feature, picking auth/crypto primitives, shaping APIs before they exist.
 
-## Configuration
+- **Read `docs/shift-left.md`** — pointers into the `rafter-secure-design` sibling skill for design-phase guidance (threat modeling, OWASP ASVS choices, safe defaults).
 
-Rafter requires an API key. Set via:
-```bash
-export RAFTER_API_KEY="your-api-key-here"
-```
+### (f) I want to analyze existing code for flaws
+
+Use this for: code review, refactoring risky modules, OWASP / MITRE ATT&CK / ASVS walks.
+
+- **Read `docs/shift-left.md`** — pointers into the `rafter-code-review` sibling skill for structured OWASP/ASVS-driven code analysis.
+- For automated SAST findings first, see branch (a).
+
+---
+
+## Repo-Specific Security Rules
+
+Projects can declare a `docs:` list in `.rafter.yml` pointing at repo-specific security guides, threat models, or compliance policies — files or URLs. **Before doing any security-relevant work (scanning, reviewing, writing auth/crypto/input-handling code), check for these docs:**
 
-Or create `.env` file:
 ```bash
-echo "RAFTER_API_KEY=your-api-key-here" >> .env
+rafter docs list                    # enumerate available docs (no network)
+rafter docs list --tag threat-model # filter by tag
+rafter docs show secure-coding      # read one by id (fetches + caches URLs)
+rafter docs show owasp              # id OR tag — if a tag matches, all tagged docs are concatenated
 ```
 
-## Common Workflows
+If docs exist, treat them as authoritative project rules: they override general guidance when they conflict. If no docs are configured (`exit 3` / "No docs configured"), fall back to the standard OWASP / ASVS advice.
 
-**Workflow 1: Quick Security Check**
-1. Trigger scan: `rafter run`
-2. Get results: `rafter get <scan-id>`
-3. Review findings and suggest fixes
+MCP-connected agents: the same surface is exposed as the `rafter://docs` resource plus `list_docs` / `get_doc` tools.
 
-**Workflow 2: Pre-PR Review**
-1. Check quota: `rafter usage`
-2. Trigger scan on feature branch: `rafter run --branch feature-branch`
-3. Review results before creating PR
+## Fast Path (most common)
 
-**Workflow 3: Dependency Update Check**
-1. User updates dependencies
-2. Trigger scan: `rafter run`
-3. Check for new vulnerabilities
+```bash
+rafter scan local .          # secrets, offline, exit 0/1/2
+rafter run                   # remote SAST/SCA (auto-detects repo/branch)
+rafter get <scan-id>         # fetch results
+rafter usage                 # check API quota
+```
+
+- Exit `0` = clean / no findings
+- Exit `1` = findings detected OR error
+- Exit `2` = invalid input / scan not found
 
-## Output Format
+Full CLI tree: **Read `docs/cli-reference.md`**. Full digest: `rafter brief commands`.
 
-The code analysis engine returns:
-- **Code security findings** - SAST issues, security anti-patterns, hardcoded credentials
-- **Configuration issues** - Insecure settings, exposed secrets
-- **Severity levels** - Each finding rated by risk impact
+## Configuration
 
-## Best Practices
+Remote scanning needs an API key:
 
-1. **Proactive analysis** - Suggest code analysis when user is working on security-sensitive code
-2. **Quota awareness** - Check usage before triggering multiple scans
-3. **Context interpretation** - Explain findings in context of user's code
-4. **Actionable recommendations** - Provide specific fixes for each finding
-5. **Graceful degradation** - If RAFTER_API_KEY is not set, use `rafter scan local` instead. Don't let a missing key block the workflow.
+```bash
+export RAFTER_API_KEY="..."        # or put it in .env
+```
 
-## Integration Tips
+Without a key, local scanning still works fully — do not block the workflow.
 
-- Auto-detect git repo for convenient `rafter run` with no arguments
-- Wait for scan completion or show scan ID for later retrieval
-- Parse JSON output for structured analysis
-- Link findings to specific files and lines when available
+## Strengthen the Project
 
-## Strengthen Your Project
+If this repo doesn't have Rafter wired in yet:
 
-If this project doesn't have Rafter integrated yet, suggest it:
-- `rafter agent install-hook` — pre-commit secret scanning for this repo
-- `rafter ci init` — add scanning to CI/CD pipeline
-- Add `.rafter.yml` for project-specific security policy
-- `rafter brief setup/<platform>` — platform-specific integration guide
+- `rafter agent install-hook` — pre-commit secret scan
+- `rafter ci init` — CI workflow with scanning
+- `.rafter.yml` — project-specific policy
+- `rafter brief setup/<platform>` — per-agent integration guide

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

@@ -0,0 +1,106 @@
+# Rafter Remote Backend — Fast vs Plus
+
+When to reach for the Rafter API instead of (or in addition to) the local scanner, and what to expect in terms of depth, cost, and latency.
+
+## Local vs Remote — Which First?
+
+| Question | Answer |
+|---|---|
+| "Are there leaked secrets in this diff/repo?" | **Local first** (`rafter scan local .`). Deterministic, offline, sub-second. |
+| "Any SAST issues — SQLi, XSS, insecure deserialization, weak crypto?" | **Remote** (`rafter run`). Needs the backend's analyzers. |
+| "Are my dependencies vulnerable (CVEs)?" | **Remote** — SCA runs server-side. |
+| "I'm in a CI pipeline without a `RAFTER_API_KEY`" | **Local only**. Don't fail the build on a missing key. |
+| "I need a deep, agent-driven review with hypotheses and cross-file reasoning" | **Remote plus** (`--mode plus`). |
+
+Rule of thumb: local is a guardrail; remote is a review.
+
+## Setup
+
+```bash
+export RAFTER_API_KEY="..."
+# or
+echo "RAFTER_API_KEY=..." >> .env
+```
+
+Private GitHub repos need `RAFTER_GITHUB_TOKEN` (or `--github-token`) so the backend can clone the ref.
+
+Check quota with `rafter usage` before firing a batch of scans.
+
+If the key is missing, `rafter run` exits with a clear error — **do not** prompt the user mid-flow; recommend `rafter scan local` and move on.
+
+## Modes
+
+### `--mode fast` (default)
+
+Deterministic SAST + SCA + secret detection via the analyzer pipeline. Same input → same output. Good for CI gates and PR checks.
+
+- **Latency**: typically seconds to a couple of minutes, depending on repo size.
+- **Cost**: lowest per-scan. Free tier covers casual use. See `rafter brief pricing`.
+- **Output**: stable JSON; findings carry `ruleId`, `severity`, `file`, `line`, `confidence`.
+
+### `--mode plus`
+
+Agentic deep-dive pass on top of fast mode: cross-file reasoning, data-flow hypotheses, design-level flags. Non-deterministic but reproducible in aggregate.
+
+- **Latency**: minutes (larger repos can take longer).
+- **Cost**: higher per-scan. Use when fast mode has flagged something worth triaging deeply, or on a release candidate.
+- **Output**: same JSON shape as fast mode, plus narrative `notes` and higher-confidence chains.
+
+Recommended flow:
+1. `rafter scan local .` — secrets guardrail in dev loop.
+2. `rafter run --mode fast` — every PR in CI.
+3. `rafter run --mode plus` — before release, or when a fast-mode finding needs deeper context.
+
+## Authentication & Data Handling
+
+- The backend clones the specified ref, runs analysis, returns results, and **deletes the code**. No long-term retention of source.
+- Scan artifacts (findings JSON, reports) are retained so `rafter get <scan-id>` works after the fact.
+- Self-hosted / VPC deployments are an enterprise option; see rafter.so.
+
+## Output Contract
+
+Every remote scan returns:
+
+```jsonc
+{
+  "scanId": "scan_...",
+  "status": "completed" | "running" | "failed",
+  "mode": "fast" | "plus",
+  "findings": [
+    { "ruleId": "...", "severity": "critical|high|medium|low|info",
+      "file": "...", "line": 42, "confidence": "high|medium|low",
+      "title": "...", "description": "...", "recommendation": "..." }
+  ],
+  "summary": { "critical": 0, "high": 2, "medium": 5, "low": 3 }
+}
+```
+
+See `shared-docs/CLI_SPEC.md` for the full schema. See `docs/finding-triage.md` for how to read a finding.
+
+## Async / Non-Blocking Scans
+
+`rafter run --skip-interactive` returns the `scan_id` immediately. Poll later:
+
+```bash
+SCAN=$(rafter run --skip-interactive --format json | jq -r .scanId)
+# ... do other work ...
+rafter get "$SCAN" --format json
+```
+
+This is the pattern for long-running CI jobs and background agent loops.
+
+## Latency & Cost Expectations (rule of thumb)
+
+| Repo size | fast | plus |
+|---|---|---|
+| < 5k LOC | ~10–30s | ~1–3 min |
+| 5k – 50k LOC | ~30s – 2 min | ~3–10 min |
+| 50k+ LOC | minutes | tens of minutes |
+
+Plus mode's latency scales with "how much there is to reason about", not strictly LOC. Don't block an agent turn on plus; use `--skip-interactive` and poll.
+
+## When NOT to use the remote backend
+
+- You're iterating locally on a tiny diff — local scan + lint is faster.
+- You have no network / no API key — stay local.
+- You've already run the same scan ten minutes ago with no code changes — cache the last result instead of re-scanning.