Skip to content

README.md

Latest commit

 

History

History
690 lines (511 loc) · 20 KB

README.md

File metadata and controls

690 lines (511 loc) · 20 KB

@rafter-security/cli

Node.js CLI for Rafter — the security toolkit for developers. This is the full-featured package with both local security and remote code analysis.

Local security toolkit — Fast, deterministic secret scanning (21+ patterns, Gitleaks), policy enforcement with risk-tiered rules, pre-commit hooks, extension auditing, custom rule authoring, and full audit logging. Works with Claude Code, Codex CLI, OpenClaw, and 5 more platforms. No API key required. No data leaves your machine.

Remote code analysis — Deep security audits that combine agentic analysis with a full SAST/SCA toolchain. The engine examines your codebase the way a professional cybersecurity auditor would — tracing data flows, reasoning about business logic, and surfacing vulnerabilities that static rules alone miss — then cross-references findings with industry-standard static analysis and dependency scanning. Structured JSON reports with documented exit codes. Your code is deleted immediately after analysis completes.

Installation

# Using npm
npm install -g @rafter-security/cli

# Using pnpm
pnpm add -g @rafter-security/cli

# Using yarn
yarn global add @rafter-security/cli

Quick Start

Getting an API Key

To use remote code analysis features, you'll need a Rafter API key:

  1. Sign up: Create an account at rafter.so
  2. Get API key: Navigate to Dashboard → Settings → API Keys
  3. Set environment variable: 
    export RAFTER_API_KEY="your-api-key-here"
  4. Or use .env file: 
    echo "RAFTER_API_KEY=your-api-key-here" >> .env

Note: Agent security features (secret scanning, command execution) work without an API key. Only remote code analysis requires authentication.

Remote Code Analysis

# Set your API key (from above)
export RAFTER_API_KEY="your-api-key-here"

# Run a security scan (can also use 'rafter scan')
rafter run

# Get scan results
rafter get <scan-id>

# Check API usage
rafter usage

Local Security

# Initialize local security
rafter agent init

# Scan files for secrets
rafter agent scan .

# Execute commands safely
rafter agent exec "git commit -m 'Add feature'"

# View audit logs
rafter agent audit

# Manage configuration
rafter agent config show

Global Options

Flag Description
-a, --agent Plain output (no colors, no emoji)
-V, --version Print version
-h, --help Show help

Commands

rafter run [options]

Alias: rafter scan

Trigger a new security scan for your repository.

Options:

  • -r, --repo <repo> - Repository in format org/repo (default: auto-detected)
  • -b, --branch <branch> - Branch name (default: auto-detected)
  • -k, --api-key <key> - API key (or set RAFTER_API_KEY env var)
  • -f, --format <format> - Output format: json or md (default: md)
  • --skip-interactive - Don't wait for scan completion
  • --quiet - Suppress status messages

Examples:

# Basic scan with auto-detection
rafter run
# or
rafter scan

# Scan specific repo/branch
rafter scan --repo myorg/myrepo --branch feature-branch

# Non-interactive scan
rafter scan --skip-interactive

rafter get <scan-id> [options]

Retrieve results from a completed scan.

Options:

  • -k, --api-key <key> - API key (or set RAFTER_API_KEY env var)
  • -f, --format <format> - Output format: json or md (default: md)
  • --interactive - Poll until scan completes
  • --quiet - Suppress status messages

Examples:

# Get scan results
rafter get <scan-id>

# Wait for scan completion
rafter get <scan-id> --interactive

rafter usage [options]

Check your API quota and usage.

Options:

  • -k, --api-key <key> - API key (or set RAFTER_API_KEY env var)

Example:

rafter usage

Local Security Commands

Rafter is a security primitive that any developer or tool can call and trust. Stable exit codes, deterministic findings, and structured output mean any workflow can integrate Rafter without reading prose.

rafter agent init [options]

Initialize local security system.

Options:

  • --risk-level <level> - Set risk level: minimal, moderate, or aggressive (default: moderate)
  • --with-openclaw - Install OpenClaw integration
  • --with-claude-code - Install Claude Code integration
  • --with-codex - Install Codex CLI integration
  • --with-gemini - Install Gemini CLI integration
  • --with-aider - Install Aider integration
  • --with-cursor - Install Cursor integration
  • --with-windsurf - Install Windsurf integration
  • --with-continue - Install Continue.dev integration
  • --with-gitleaks - Download and install Gitleaks binary
  • --all - Install all detected integrations and download Gitleaks

What it does:

  • Creates ~/.rafter/config.json configuration
  • Initializes directory structure
  • Detects installed platforms
  • Installs opted-in integrations (skills, hooks, MCP servers)
  • Sets up audit logging

Example:

rafter agent init                      # Config only, detect environments
rafter agent init --all                # Install all detected integrations
rafter agent init --with-claude-code   # Install Claude Code integration only
rafter agent init --risk-level aggressive

rafter agent scan [path] [options]

Scan files or directories for secrets.

Arguments:

  • path - File or directory to scan (default: current directory)

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.)
  • Shows severity levels (critical/high/medium/low)
  • Displays line and column numbers
  • Smart redaction (shows first/last 4 chars)
  • Exits with code 1 if secrets found (CI-friendly)

Examples:

# Scan current directory
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

# JSON output for processing
rafter agent scan --json

Detected patterns:

  • AWS Access Keys & Secret Keys
  • GitHub Personal Access Tokens
  • Google API Keys
  • Slack Tokens & Webhooks
  • Stripe API Keys
  • Database connection strings
  • JWT tokens
  • npm & PyPI tokens
  • Private keys (RSA, DSA, EC)
  • Generic API keys and secrets

rafter agent exec <command> [options]

Execute shell command with security validation.

Arguments:

  • command - Shell command to execute

Options:

  • --skip-scan - Skip pre-execution file scanning
  • --force - Skip approval prompts (use with caution, logged in audit)

Features:

  • Blocks critical commands automatically (rm -rf /, fork bombs)
  • Requires approval for high-risk operations
  • Scans staged files before git commits
  • Logs all executions to audit log
  • Risk assessment for all commands

Command risk levels:

  • Critical (blocked): rm -rf /, fork bombs, dd to /dev, mkfs
  • High (requires approval): rm -rf, sudo rm, chmod 777, curl|sh, git push --force
  • Medium (requires approval on moderate+): sudo, chmod, kill -9
  • Low (allowed): Most other commands

Examples:

# Safe command - executes immediately
rafter agent exec "npm install"

# Git commit - scans staged files first
rafter agent exec "git commit -m 'Add feature'"

# High-risk command - requires approval
rafter agent exec "sudo rm /tmp/old-files"

# Critical command - blocked
rafter agent exec "rm -rf /"

rafter agent config <subcommand>

Manage agent configuration.

Subcommands:

  • show - Display full configuration
  • get <key> - Get specific configuration value
  • set <key> <value> - Set configuration value

Configuration keys:

  • agent.riskLevel - Risk level: minimal, moderate, aggressive
  • agent.commandPolicy.mode - Policy mode: allow-all, approve-dangerous, deny-list
  • agent.outputFiltering.redactSecrets - Redact secrets in output: true or false
  • agent.audit.logAllActions - Log all actions: true or false
  • agent.audit.retentionDays - Log retention period (days)

Examples:

# View all configuration
rafter agent config show

# Get risk level
rafter agent config get agent.riskLevel

# Set to aggressive mode
rafter agent config set agent.riskLevel aggressive

# Change command policy
rafter agent config set agent.commandPolicy.mode deny-list

rafter agent audit [options]

View security audit logs.

Options:

  • --last <n> - Show last N entries (default: 10)
  • --event <type> - Filter by event type
  • --agent <type> - Filter by agent type (openclaw, claude-code)
  • --since <date> - Show entries since date (YYYY-MM-DD)

Event types:

  • command_intercepted - Command execution attempts
  • secret_detected - Secret found in files
  • content_sanitized - Output redacted
  • policy_override - User override of security policy
  • scan_executed - File scan performed
  • config_changed - Configuration modified

Examples:

# Show recent audit logs
rafter agent audit

# Show last 20 entries
rafter agent audit --last 20

# Filter by event type
rafter agent audit --event secret_detected

# Show logs since date
rafter agent audit --since 2026-02-01

rafter agent install-hook [options]

Install git pre-commit hook to automatically scan for secrets before commits.

Options:

  • --global - Install globally for all repos (via git config)

Features:

  • Automatically scans staged files before each commit
  • Blocks commits if secrets are detected
  • Zero-configuration security for git workflows
  • Can be bypassed with git commit --no-verify (not recommended)

Examples:

# Install for current repository
cd my-repo
rafter agent install-hook

# Install globally for all repositories
rafter agent install-hook --global

# Uninstall global hook
git config --global --unset core.hooksPath

What it does:

# When you commit:
git add .env
git commit -m "Update config"

# Rafter automatically scans:
🔍 Rafter: Scanning staged files for secrets...
❌ Commit blocked: Secrets detected in staged files

   Run: rafter agent scan --staged
   To see details and remediate.

Why use pre-commit hooks?

Pre-commit hooks provide the most effective protection against accidentally committing secrets to git:

  • Automatic: No need to remember to scan manually
  • Fail-safe: Prevents secrets from entering version control
  • CI-friendly: Works locally before code reaches CI/CD
  • Team-wide: Can be committed to .git/hooks or distributed via git config

Always install pre-commit hooks for repositories handling sensitive data.

rafter agent audit-skill <skill-path> [options]

Security audit of a Claude Code skill file before installation.

Arguments:

  • skill-path - Path to skill file to audit

Options:

  • --skip-openclaw - Skip OpenClaw integration, show manual review prompt
  • --json - Output results as JSON

Features:

  • Quick Scan: Detects secrets, external URLs, high-risk commands
  • Deep Analysis: Uses OpenClaw's skill-auditor for comprehensive review (if installed)
  • 12 Security Dimensions: Trust, network security, command safety, file access, credentials, input validation, data exfiltration, obfuscation, scope alignment, error handling, dependencies, environment manipulation
  • Risk Rating: LOW/MEDIUM/HIGH/CRITICAL assessment
  • Actionable Recommendations: Clear install/don't install guidance

Security Dimensions Analyzed:

  1. Trust & Attribution - Source verification
  2. Network Security - External communication
  3. Command Execution - Shell command safety
  4. File System Access - Read/write patterns
  5. Credential Handling - Secret management
  6. Input Validation - Injection risks
  7. Data Exfiltration - What leaves the system
  8. Obfuscation - Hidden behavior detection
  9. Scope Alignment - Matches stated purpose
  10. Error Handling - Information disclosure
  11. Dependencies - Supply chain risks
  12. Environment Manipulation - System modifications

Examples:

# Audit a skill file
rafter agent audit-skill ~/.openclaw/skills/untrusted-skill.md

# Audit with OpenClaw (comprehensive)
rafter agent audit-skill skill.md
# Then in OpenClaw: /rafter-audit-skill /path/to/skill.md

# Manual review prompt (no OpenClaw)
rafter agent audit-skill skill.md --skip-openclaw

# JSON output for automation
rafter agent audit-skill skill.md --json

Example Output:

🔍 Auditing skill: untrusted-skill.md
═══════════════════════════════════════════════════════════
📊 Quick Scan Results
⚠️  Secrets: 1 found
⚠️  External URLs: 2 found
   • https://api.example.com/v1/data
   • https://untrusted-cdn.com/script.js
⚠️  High-risk commands: 1 found
   • curl | bash (line 45)

🤖 For comprehensive security review:
   1. Open OpenClaw
   2. Run: /rafter-audit-skill /path/to/skill.md

Why audit skills?

Claude Code skills can:

  • Execute shell commands
  • Access sensitive files
  • Make network requests
  • Handle credentials
  • Process user input

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:

{
  "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-remote - Include remote security audit job (requires RAFTER_API_KEY)

Auto-detection: Checks for .github/, .gitlab-ci.yml, .circleci/ in the current directory.

Examples:

# Auto-detect platform
rafter ci init

# Generate GitHub Actions workflow
rafter ci init --platform github

# Include remote scanning job
rafter ci init --with-remote

# 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.

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

Environment Variables

  • RAFTER_API_KEY - Your Rafter API key (alternative to --api-key flag)

Git Auto-Detection

The CLI automatically detects your repository and branch from the current Git repository:

  1. Repository: Extracted from Git remote URL
  2. Branch: Current branch name, or main if on detached HEAD

Note: The CLI only scans remote repositories, not your current local branch.

Local Security Configuration

Security settings are stored in ~/.rafter/config.json. Key settings:

Risk Levels:

  • minimal - Basic guidance only, most commands allowed
  • moderate - Standard protections, approval for high-risk commands (recommended)
  • aggressive - Maximum security, requires approval for most operations

Command Policy Modes:

  • allow-all - Allow all commands (not recommended for production)
  • approve-dangerous - Require approval for high/critical risk commands (default)
  • deny-list - Block specific patterns, allow everything else

File Locations:

  • Config: ~/.rafter/config.json
  • Audit log: ~/.rafter/audit.jsonl
  • Binaries: ~/.rafter/bin/
  • Patterns: ~/.rafter/patterns/

OpenClaw Integration

Rafter integrates seamlessly with OpenClaw.

Setup

When OpenClaw is detected, rafter agent init automatically installs a skill to ~/.openclaw/skills/rafter-security.md.

What the skill provides:

  • /rafter-scan - Scan files before commits
  • /rafter-bash - Execute commands with validation (via rafter agent exec)
  • /rafter-audit-skill - Comprehensive security audit of Claude Code skills
  • /rafter-audit - View security logs

Usage in OpenClaw

# In OpenClaw, use Rafter commands naturally:
"Scan this directory for secrets"
# OpenClaw will call: rafter agent scan .

"Audit this skill for security issues"
# OpenClaw will call: /rafter-audit-skill <path>
# Provides comprehensive 12-dimension security analysis

"Commit these changes"
# OpenClaw will call: rafter agent exec "git commit -m '...'"
# Rafter scans staged files first, blocks if secrets found

Best Practices

  1. Install pre-commit hooks: Run rafter agent install-hook to automatically scan before commits (recommended)
  2. Audit untrusted skills: Run /rafter-audit-skill before installing skills from unknown sources
  3. Review blocked commands: Check rafter agent audit when commands are blocked
  4. Configure appropriately: Use moderate risk level for most use cases
  5. Keep patterns updated: Patterns are updated automatically with CLI updates

Claude Code Integration

Rafter provides TWO skills for Claude Code:

1. Remote Code Analysis Skill (Core Feature)

Automatic Integration - Claude can proactively suggest security scans

Commands:

  • rafter run - Trigger security scan
  • rafter get <scan-id> - Get results
  • rafter usage - Check quota

Installation:

rafter agent init
# Auto-detects Claude Code and installs both skills

Or manually:

cp -r node/.claude/skills/rafter ~/.claude/skills/

Usage: Claude will automatically suggest Rafter scans when you mention security, vulnerabilities, or code analysis. You can also invoke manually:

Can you run a Rafter security scan on this repo?

2. Local Security Skill

User-Invoked - Requires explicit commands for safety

Commands:

  • /rafter-scan - Scan files for secrets
  • /rafter-bash - Execute commands safely
  • /rafter-audit-skill - Audit skills before installing
  • /rafter-audit - View security logs

Installation:

rafter agent init
# Installs automatically if Claude Code detected

Or manually:

cp -r node/.claude/skills/rafter-agent-security ~/.claude/skills/

Usage: Explicitly invoke commands:

/rafter-scan .
/rafter-audit-skill untrusted-skill.md

Why Two Skills?

  • Remote code analysis skill - Safe for Claude to auto-invoke (read-only API calls)
  • Agent security skill - Requires user permission (local file access, command execution)

This separation emphasizes Rafter's core remote code analysis capabilities while keeping local security features safely behind user control.

Documentation

For comprehensive documentation, API reference, and examples, see https://docs.rafter.so.