@rafter-security/cli 0.4.2 → 0.5.3

package/README.md

@@ -73,6 +73,14 @@ rafter agent audit
 rafter agent config show
 ```
 
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-a, --agent` | Plain output for AI agents (no colors, no emoji) |
+| `-V, --version` | Print version |
+| `-h, --help` | Show help |
+
 ## Commands
 
 ### `rafter run [options]`
@@ -169,6 +177,7 @@ Scan files or directories for secrets.
 **Options:**
 - `-q, --quiet` - Only output if secrets found
 - `--json` - Output results as JSON
+- `--diff <ref>` - Scan files changed since a git ref (e.g., `HEAD~1`, `main`, `v1.0.0`)
 
 **Features:**
 - Detects 21+ secret types (AWS, GitHub, Stripe, Google, Slack, etc.)
@@ -185,6 +194,10 @@ rafter agent scan
 # Scan specific file
 rafter agent scan ./config.js
 
+# Scan files changed since a ref
+rafter agent scan --diff HEAD~1
+rafter agent scan --diff main
+
 # Scan for CI (quiet mode)
 rafter agent scan --quiet
 
@@ -433,6 +446,93 @@ Claude Code skills can:
 
 Always audit skills from untrusted sources before installation. The skill-auditor provides systematic analysis to identify security risks.
 
+### `rafter mcp serve [options]`
+
+Start an MCP server exposing Rafter security tools over stdio transport. Any MCP-compatible client (Cursor, Windsurf, Claude Desktop, Cline, etc.) can connect.
+
+**Options:**
+- `--transport <type>` - Transport type (default: `stdio`)
+
+**MCP client config:**
+```json
+{
+  "rafter": {
+    "command": "rafter",
+    "args": ["mcp", "serve"]
+  }
+}
+```
+
+**Tools provided:**
+
+| Tool | Description |
+|------|-------------|
+| `scan_secrets` | Scan files/directories for hardcoded secrets. Params: `path` (required), `engine` (auto/gitleaks/patterns) |
+| `evaluate_command` | Check if a shell command is allowed by Rafter policy. Params: `command` (required) |
+| `read_audit_log` | Read audit log entries. Params: `limit`, `event_type`, `since` |
+| `get_config` | Read Rafter config. Params: `key` (optional dot-path) |
+
+**Resources provided:**
+
+| URI | Description |
+|-----|-------------|
+| `rafter://config` | Current Rafter configuration (JSON) |
+| `rafter://policy` | Active security policy — merged `.rafter.yml` + config (JSON) |
+
+---
+
+### `rafter ci init [options]`
+
+Generate CI/CD pipeline configuration for secret scanning.
+
+**Options:**
+- `--platform <platform>` - CI platform: `github`, `gitlab`, `circleci` (default: auto-detect)
+- `--output <path>` - Output file path (default: platform-specific)
+- `--with-backend` - Include backend security audit job (requires `RAFTER_API_KEY`)
+
+**Auto-detection:** Checks for `.github/`, `.gitlab-ci.yml`, `.circleci/` in the current directory.
+
+**Examples:**
+```bash
+# Auto-detect platform
+rafter ci init
+
+# Generate GitHub Actions workflow
+rafter ci init --platform github
+
+# Include backend scanning job
+rafter ci init --with-backend
+
+# Custom output path
+rafter ci init --output .github/workflows/security.yml
+```
+
+---
+
+## Policy File (`.rafter.yml`)
+
+Define per-project security policies by placing a `.rafter.yml` in your project root. The CLI walks from cwd up to git root looking for it.
+
+```yaml
+version: "1"
+risk_level: moderate
+command_policy:
+  mode: approve-dangerous
+  blocked_patterns: ["rm -rf /"]
+  require_approval: ["npm publish"]
+scan:
+  exclude_paths: ["vendor/", "third_party/"]
+  custom_patterns:
+    - name: "Internal API Key"
+      regex: "INTERNAL_[A-Z0-9]{32}"
+      severity: critical
+audit:
+  retention_days: 90
+  log_level: info
+```
+
+**Precedence:** Policy file values override `~/.rafter/config.json`. Arrays replace, not append.
+
 ---
 
 ## Configuration
@@ -466,7 +566,7 @@ Agent security settings are stored in `~/.rafter/config.json`. Key settings:
 
 **File Locations:**
 - Config: `~/.rafter/config.json`
-- Audit log: `~/.rafter/audit.log`
+- Audit log: `~/.rafter/audit.jsonl`
 - Binaries: `~/.rafter/bin/`
 - Patterns: `~/.rafter/patterns/`
 

package/dist/commands/agent/audit-skill.js

@@ -48,6 +48,9 @@ async function auditSkill(skillPath, opts) {
             rafterSkillInstalled
         };
         console.log(JSON.stringify(result, null, 2));
+        if (quickScan.secrets > 0 || quickScan.highRiskCommands.length > 0) {
+            process.exit(1);
+        }
         return;
     }
     // Check if we can use OpenClaw
@@ -85,6 +88,9 @@ async function auditSkill(skillPath, opts) {
         console.log("─".repeat(60));
     }
     console.log();
+    if (quickScan.secrets > 0 || quickScan.highRiskCommands.length > 0) {
+        process.exit(1);
+    }
 }
 async function runQuickScan(content) {
     // 1. Scan for secrets

package/dist/commands/agent/audit.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { AuditLogger } from "../../core/audit-logger.js";
+import { isAgentMode } from "../../utils/formatter.js";
 export function createAuditCommand() {
     return new Command("audit")
         .description("View audit log entries")
@@ -29,8 +30,8 @@ export function createAuditCommand() {
         console.log(`\nShowing ${entries.length} audit log entries:\n`);
         for (const entry of entries) {
             const timestamp = new Date(entry.timestamp).toLocaleString();
-            const emoji = getEventEmoji(entry.eventType);
-            console.log(`${emoji} [${timestamp}] ${entry.eventType}`);
+            const indicator = getEventIndicator(entry.eventType);
+            console.log(`${indicator} [${timestamp}] ${entry.eventType}`);
             if (entry.agentType) {
                 console.log(`   Agent: ${entry.agentType}`);
             }
@@ -52,7 +53,18 @@ export function createAuditCommand() {
         }
     });
 }
-function getEventEmoji(eventType) {
+function getEventIndicator(eventType) {
+    if (isAgentMode()) {
+        const tagMap = {
+            command_intercepted: "[INTERCEPT]",
+            secret_detected: "[SECRET]",
+            content_sanitized: "[SANITIZE]",
+            policy_override: "[OVERRIDE]",
+            scan_executed: "[SCAN]",
+            config_changed: "[CONFIG]",
+        };
+        return tagMap[eventType] || "[EVENT]";
+    }
     const emojiMap = {
         command_intercepted: "🛡️",
         secret_detected: "🔑",

package/dist/commands/agent/exec.js

@@ -3,6 +3,7 @@ import { CommandInterceptor } from "../../core/command-interceptor.js";
 import { RegexScanner } from "../../scanners/regex-scanner.js";
 import { execSync } from "child_process";
 import readline from "readline";
+import { fmt } from "../../utils/formatter.js";
 export function createExecCommand() {
     return new Command("exec")
         .description("Execute command with security validation")
@@ -15,7 +16,7 @@ export function createExecCommand() {
         const evaluation = interceptor.evaluate(command);
         // Step 2: Handle blocked commands
         if (!evaluation.allowed && !evaluation.requiresApproval) {
-            console.error(`\n🚫 Command BLOCKED\n`);
+            console.error(`\n${fmt.error("Command BLOCKED")}\n`);
             console.error(`Risk Level: ${evaluation.riskLevel.toUpperCase()}`);
             console.error(`Reason: ${evaluation.reason}`);
             console.error(`Command: ${command}\n`);
@@ -26,7 +27,7 @@ export function createExecCommand() {
         if (!opts.skipScan && isGitCommand(command)) {
             const scanResult = await scanStagedFiles();
             if (scanResult.secretsFound) {
-                console.error(`\n⚠️  Secrets detected in staged files!\n`);
+                console.error(`\n${fmt.warning("Secrets detected in staged files!")}\n`);
                 console.error(`Found ${scanResult.count} secret(s) in ${scanResult.files} file(s)`);
                 console.error(`\nRun 'rafter agent scan' for details.\n`);
                 interceptor.logEvaluation(evaluation, "blocked");
@@ -35,7 +36,7 @@ export function createExecCommand() {
         }
         // Step 4: Handle approval required
         if (evaluation.requiresApproval && !opts.force) {
-            console.log(`\n⚠️  Command requires approval\n`);
+            console.log(`\n${fmt.warning("Command requires approval")}\n`);
             console.log(`Risk Level: ${evaluation.riskLevel.toUpperCase()}`);
             console.log(`Command: ${command}`);
             if (evaluation.reason) {
@@ -44,15 +45,15 @@ export function createExecCommand() {
             console.log();
             const approved = await promptApproval();
             if (!approved) {
-                console.log("\n❌ Command cancelled\n");
+                console.log(`\n${fmt.error("Command cancelled")}\n`);
                 interceptor.logEvaluation(evaluation, "blocked");
                 process.exit(1);
             }
-            console.log("\n✓ Command approved by user\n");
+            console.log(`\n${fmt.success("Command approved by user")}\n`);
             interceptor.logEvaluation(evaluation, "overridden");
         }
         else if (opts.force && evaluation.requiresApproval) {
-            console.log(`\n⚠️  Forcing execution (--force flag)\n`);
+            console.log(`\n${fmt.warning("Forcing execution (--force flag)")}\n`);
             interceptor.logEvaluation(evaluation, "overridden");
         }
         else {
@@ -64,11 +65,11 @@ export function createExecCommand() {
                 stdio: "inherit",
                 encoding: "utf-8"
             });
-            console.log(`\n✓ Command executed successfully\n`);
+            console.log(`\n${fmt.success("Command executed successfully")}\n`);
             process.exit(0);
         }
         catch (e) {
-            console.error(`\n❌ Command failed with exit code ${e.status}\n`);
+            console.error(`\n${fmt.error(`Command failed with exit code ${e.status}`)}\n`);
             process.exit(e.status || 1);
         }
     });

package/dist/commands/agent/index.js

@@ -6,6 +6,8 @@ import { createConfigCommand } from "./config.js";
 import { createExecCommand } from "./exec.js";
 import { createAuditSkillCommand } from "./audit-skill.js";
 import { createInstallHookCommand } from "./install-hook.js";
+import { createVerifyCommand } from "./verify.js";
+import { createStatusCommand } from "./status.js";
 export function createAgentCommand() {
     const agent = new Command("agent")
         .description("Agent security features");
@@ -17,5 +19,7 @@ export function createAgentCommand() {
     agent.addCommand(createAuditCommand());
     agent.addCommand(createAuditSkillCommand());
     agent.addCommand(createInstallHookCommand());
+    agent.addCommand(createVerifyCommand());
+    agent.addCommand(createStatusCommand());
     return agent;
 }

package/dist/commands/agent/init.js

@@ -6,8 +6,52 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
+import { fmt } from "../../utils/formatter.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+function installClaudeCodeHooks() {
+    const homeDir = os.homedir();
+    const settingsPath = path.join(homeDir, ".claude", "settings.json");
+    const claudeDir = path.join(homeDir, ".claude");
+    if (!fs.existsSync(claudeDir)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+    }
+    // Read existing settings or start fresh
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        }
+        catch {
+            // Corrupted file — start fresh but warn
+            console.log(fmt.warning("Existing settings.json was unreadable, creating new one"));
+        }
+    }
+    // Merge hooks — don't overwrite existing non-Rafter hooks
+    if (!settings.hooks)
+        settings.hooks = {};
+    if (!settings.hooks.PreToolUse)
+        settings.hooks.PreToolUse = [];
+    if (!settings.hooks.PostToolUse)
+        settings.hooks.PostToolUse = [];
+    const preHook = { type: "command", command: "rafter hook pretool" };
+    const postHook = { type: "command", command: "rafter hook posttool" };
+    // Remove any existing Rafter hooks to avoid duplicates
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter((entry) => {
+        const hooks = entry.hooks || [];
+        return !hooks.some((h) => h.command === "rafter hook pretool");
+    });
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter((entry) => {
+        const hooks = entry.hooks || [];
+        return !hooks.some((h) => h.command === "rafter hook posttool");
+    });
+    // Add Rafter hooks
+    settings.hooks.PreToolUse.push({ matcher: "Bash", hooks: [preHook] }, { matcher: "Write|Edit", hooks: [preHook] });
+    settings.hooks.PostToolUse.push({ matcher: ".*", hooks: [postHook] });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    console.log(fmt.success(`Installed PreToolUse hooks to ${settingsPath}`));
+    console.log(fmt.success(`Installed PostToolUse hooks to ${settingsPath}`));
+}
 async function installClaudeCodeSkills() {
     const homeDir = os.homedir();
     const claudeSkillsDir = path.join(homeDir, ".claude", "skills");
@@ -24,10 +68,10 @@ async function installClaudeCodeSkills() {
     }
     if (fs.existsSync(backendTemplatePath)) {
         fs.copyFileSync(backendTemplatePath, backendSkillPath);
-        console.log(`✓ Installed Rafter Backend skill to ${backendSkillPath}`);
+        console.log(fmt.success(`Installed Rafter Backend skill to ${backendSkillPath}`));
     }
     else {
-        console.log(`⚠️  Backend skill template not found at ${backendTemplatePath}`);
+        console.log(fmt.warning(`Backend skill template not found at ${backendTemplatePath}`));
     }
     // Install Agent Security Skill
     const agentSkillDir = path.join(claudeSkillsDir, "rafter-agent-security");
@@ -38,10 +82,10 @@ async function installClaudeCodeSkills() {
     }
     if (fs.existsSync(agentTemplatePath)) {
         fs.copyFileSync(agentTemplatePath, agentSkillPath);
-        console.log(`✓ Installed Rafter Agent Security skill to ${agentSkillPath}`);
+        console.log(fmt.success(`Installed Rafter Agent Security skill to ${agentSkillPath}`));
     }
     else {
-        console.log(`⚠️  Agent Security skill template not found at ${agentTemplatePath}`);
+        console.log(fmt.warning(`Agent Security skill template not found at ${agentTemplatePath}`));
     }
 }
 export function createInitCommand() {
@@ -53,100 +97,141 @@ export function createInitCommand() {
         .option("--claude-code", "Force Claude Code skill installation")
         .option("--skip-gitleaks", "Skip Gitleaks binary download")
         .action(async (opts) => {
-        console.log("\n🛡️  Rafter Agent Security Setup");
-        console.log("━".repeat(40));
+        console.log(fmt.header("Rafter Agent Security Setup"));
+        console.log(fmt.divider());
         console.log();
         const manager = new ConfigManager();
         // Detect environments
         const hasOpenClaw = fs.existsSync(path.join(os.homedir(), ".openclaw"));
         const hasClaudeCode = opts.claudeCode || fs.existsSync(path.join(os.homedir(), ".claude"));
         if (hasOpenClaw) {
-            console.log("✓ Detected environment: OpenClaw");
+            console.log(fmt.success("Detected environment: OpenClaw"));
         }
         else {
-            console.log("ℹ️  OpenClaw not detected");
+            console.log(fmt.info("OpenClaw not detected"));
         }
         if (hasClaudeCode) {
-            console.log("✓ Detected environment: Claude Code");
+            console.log(fmt.success("Detected environment: Claude Code"));
         }
         else {
-            console.log("ℹ️  Claude Code not detected");
+            console.log(fmt.info("Claude Code not detected"));
         }
         // Initialize directory structure
         try {
             await manager.initialize();
-            console.log(`✓ Created config at ~/.rafter/config.json`);
+            console.log(fmt.success("Created config at ~/.rafter/config.json"));
         }
         catch (e) {
-            console.error(`Failed to initialize: ${e}`);
+            console.error(fmt.error(`Failed to initialize: ${e}`));
             process.exit(1);
         }
         // Set risk level
         const validRiskLevels = ["minimal", "moderate", "aggressive"];
         if (!validRiskLevels.includes(opts.riskLevel)) {
-            console.error(`Invalid risk level: ${opts.riskLevel}`);
+            console.error(fmt.error(`Invalid risk level: ${opts.riskLevel}`));
             console.error(`Valid options: ${validRiskLevels.join(", ")}`);
             process.exit(1);
         }
         manager.set("agent.riskLevel", opts.riskLevel);
-        console.log(`✓ Set risk level: ${opts.riskLevel}`);
-        // Download Gitleaks binary (optional)
+        console.log(fmt.success(`Set risk level: ${opts.riskLevel}`));
+        // Check / download Gitleaks binary (optional)
         if (!opts.skipGitleaks) {
             const binaryManager = new BinaryManager();
             const platformInfo = binaryManager.getPlatformInfo();
-            if (!platformInfo.supported) {
-                console.log(`ℹ️  Gitleaks not available for ${platformInfo.platform}/${platformInfo.arch}`);
-                console.log("✓ Using pattern-based scanning (21 patterns)");
-            }
-            else if (binaryManager.isGitleaksInstalled()) {
-                const version = await binaryManager.getGitleaksVersion();
-                console.log(`✓ Gitleaks already installed (${version})`);
+            // Helper: show diagnostics for a failing binary (mirrors Python's agent init)
+            const showDiagnostics = async (binaryPath, verResult) => {
+                if (verResult.stderr) {
+                    console.log(fmt.info(`  stderr: ${verResult.stderr}`));
+                }
+                const diag = await binaryManager.collectBinaryDiagnostics(binaryPath);
+                if (diag) {
+                    console.log(fmt.info("Diagnostics:"));
+                    console.log(diag);
+                }
+                console.log(fmt.info("To fix: install gitleaks (https://github.com/gitleaks/gitleaks/releases) and ensure it is on PATH, then re-run 'rafter agent init'."));
+                console.log();
+            };
+            if (binaryManager.isGitleaksInstalled()) {
+                // Local binary exists — verify it actually works
+                const verResult = await binaryManager.verifyGitleaksVerbose();
+                if (verResult.ok) {
+                    console.log(fmt.success(`Gitleaks already installed (${verResult.stdout})`));
+                }
+                else {
+                    console.log(fmt.warning("Gitleaks binary found locally but failed to execute."));
+                    console.log(fmt.info(`  Binary: ${binaryManager.getGitleaksPath()}`));
+                    await showDiagnostics(binaryManager.getGitleaksPath(), verResult);
+                }
             }
             else {
-                console.log();
-                console.log("📦 Downloading Gitleaks (enhanced secret detection)...");
-                try {
-                    await binaryManager.downloadGitleaks((msg) => {
-                        console.log(`   ${msg}`);
-                    });
-                    console.log();
+                // Not installed locally — check PATH (mirrors Python's shutil.which)
+                const pathBinary = binaryManager.findGitleaksOnPath();
+                if (pathBinary) {
+                    const verResult = await binaryManager.verifyGitleaksVerbose(pathBinary);
+                    if (verResult.ok) {
+                        console.log(fmt.success(`Gitleaks available on PATH (${verResult.stdout})`));
+                    }
+                    else {
+                        console.log(fmt.warning("Gitleaks found on PATH but failed to execute."));
+                        console.log(fmt.info(`  Binary: ${pathBinary}`));
+                        await showDiagnostics(pathBinary, verResult);
+                    }
                 }
-                catch (e) {
-                    console.log(`⚠️  Failed to download Gitleaks: ${e}`);
-                    console.log("✓ Falling back to pattern-based scanning");
+                else if (!platformInfo.supported) {
+                    console.log(fmt.info(`Gitleaks not available for ${platformInfo.platform}/${platformInfo.arch}`));
+                    console.log(fmt.success("Using pattern-based scanning (21 patterns)"));
+                }
+                else {
+                    // Not on PATH, not installed locally — download
                     console.log();
+                    console.log(fmt.info("Downloading Gitleaks (enhanced secret detection)..."));
+                    try {
+                        await binaryManager.downloadGitleaks((msg) => {
+                            console.log(`   ${msg}`);
+                        });
+                        console.log();
+                    }
+                    catch (e) {
+                        console.log();
+                        console.log(fmt.error(`Gitleaks setup failed — pattern-based scanning will be used instead.`));
+                        console.log(fmt.warning(String(e)));
+                        console.log();
+                        console.log(fmt.info("To fix: install gitleaks manually (https://github.com/gitleaks/gitleaks/releases) and ensure it is on PATH, then re-run 'rafter agent init'."));
+                        console.log();
+                    }
                 }
             }
         }
         // Install OpenClaw skill if applicable
         if (hasOpenClaw && !opts.skipOpenclaw) {
-            try {
-                const skillManager = new SkillManager();
-                const installed = await skillManager.installRafterSkill();
-                if (installed) {
-                    console.log("✓ Installed Rafter Security skill to ~/.openclaw/skills/rafter-security.md");
-                    manager.set("agent.environments.openclaw.enabled", true);
-                }
-                else {
-                    console.log("⚠️  Failed to install Rafter Security skill");
-                }
+            const skillManager = new SkillManager();
+            const result = await skillManager.installRafterSkillVerbose();
+            if (result.ok) {
+                console.log(fmt.success("Installed Rafter Security skill to ~/.openclaw/skills/rafter-security.md"));
+                manager.set("agent.environments.openclaw.enabled", true);
             }
-            catch (e) {
-                console.error(`Failed to install OpenClaw skill: ${e}`);
+            else {
+                console.log(fmt.error("Failed to install Rafter Security skill"));
+                console.log(fmt.warning(`  Source: ${result.sourcePath}`));
+                console.log(fmt.warning(`  Destination: ${result.destPath}`));
+                if (result.error) {
+                    console.log(fmt.warning(`  Error: ${result.error}`));
+                }
             }
         }
-        // Install Claude Code skills if applicable
+        // Install Claude Code skills + hooks if applicable
         if (hasClaudeCode && !opts.skipClaudeCode) {
             try {
                 await installClaudeCodeSkills();
+                installClaudeCodeHooks();
                 manager.set("agent.environments.claudeCode.enabled", true);
             }
             catch (e) {
-                console.error(`Failed to install Claude Code skills: ${e}`);
+                console.error(fmt.error(`Failed to install Claude Code integration: ${e}`));
             }
         }
         console.log();
-        console.log("✓ Agent security initialized!");
+        console.log(fmt.success("Agent security initialized!"));
         console.log();
         console.log("Next steps:");
         if (hasOpenClaw && !opts.skipOpenclaw) {

package/dist/commands/agent/install-hook.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import fs from "fs";
+import os from "os";
 import path from "path";
 import { execSync } from "child_process";
 import { fileURLToPath } from 'url';
@@ -81,7 +82,7 @@ async function installLocalHook() {
  */
 async function installGlobalHook() {
     // Create global hooks directory
-    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    const homeDir = os.homedir();
     if (!homeDir) {
         console.error("❌ Error: Could not determine home directory");
         process.exit(1);