Secret Scanning

Rafter scans your code for secrets and credentials to prevent accidental leaks.

Quick Start

Scan a directory for secrets:

rafter secrets .

Note: rafter agent scan still works but is deprecated — it will be removed in a future major version.

Detected Secret Types

Rafter detects 21+ types of secrets:

Cloud Providers

AWS Access Keys & Secret Keys
Google API Keys & OAuth credentials
Azure credentials

Version Control

GitHub Personal Access Tokens
GitHub OAuth Tokens
GitHub App Tokens
GitHub Refresh Tokens

Payment & SaaS

Stripe API Keys (live & restricted)
Slack Tokens & Webhooks
Twilio API Keys

Package Registries

npm Access Tokens
PyPI API Tokens

Databases & Keys

Database connection strings (postgres, mysql, mongodb)
Private keys (RSA, DSA, EC, OpenSSH)
JWT tokens
Generic API keys

Usage Examples

Scan Specific File

rafter secrets ./config.js

Scan Directory

rafter secrets ./src

Quiet Mode (CI/CD)

Only output if secrets are found:

rafter secrets --quiet

Exits with code 1 if secrets found, perfect for CI pipelines.

JSON Output

Get machine-readable results:

rafter secrets --json > scan-results.json

Watch Mode

Watch a path for file changes and re-scan automatically:

rafter secrets --watch .

Findings are printed inline and logged to audit.jsonl in real time. Press Ctrl+C to stop. Watch mode does not exit on findings — it keeps watching.

Requires chokidar (Node, bundled) or watchdog (Python: pip install watchdog).

Diff Scanning

Scan only files changed since a git ref:

# Scan changes since last commit
rafter secrets --diff HEAD~1

# Scan changes since a branch point
rafter secrets --diff main

# Scan changes since a tag
rafter secrets --diff v1.0.0

Useful for CI pipelines that only need to check new or modified files.

Output Format

When secrets are found, Rafter shows:

⚠️  Found secrets in 1 file(s):

📄 src/config.js
  🔴 [CRITICAL] AWS Access Key ID
     Location: Line 12
     Pattern: AWS Access Key ID detected
     Redacted: AKIA************MPLE

  🔴 [CRITICAL] GitHub Personal Access Token
     Location: Line 18
     Pattern: GitHub Personal Access Token detected
     Redacted: ghp_****************************stuv

Severity Levels

Severity Indicators

🔴 Critical: Immediate security risk (AWS keys, database passwords)
🟠 High: Significant risk (generic API keys, bearer tokens)
🟡 Medium: Moderate risk (connection strings without credentials)
🟢 Low: Low risk (public keys, non-sensitive patterns)

Smart Redaction

Rafter uses smart redaction to show context without exposing secrets:

Short secrets (≤8 chars): Fully redacted (********)
Long secrets (>8 chars): Show first 4 and last 4 characters

Example: AKIAIOSFODNN7EXAMPLE → AKIA************MPLE

Pre-Commit Scanning

Integrate with git commits:

# Before committing
rafter secrets

# Or use rafter agent exec (scans automatically)
rafter agent exec "git commit -m 'Add feature'"

Excluding Files

Rafter automatically skips:

Binary files (images, PDFs, executables)
Build directories (node_modules, dist, build, .next)
Version control (.git)
IDE folders (.vscode, .idea)

CI/CD Integration

GitHub Actions

- name: Scan for secrets
  run: |
    npm install -g @rafter-security/cli
    rafter secrets --quiet

Exit code 1 will fail the pipeline if secrets are detected.

GitLab CI

scan-secrets:
  script:
    - npm install -g @rafter-security/cli
    - rafter secrets --quiet

Audit Trail

All scans are logged to ~/.rafter/audit.jsonl:

# View recent scans
rafter agent audit --event scan_executed

# View secret detections
rafter agent audit --event secret_detected

False Positives

If you encounter false positives:

Exclude patterns via config:

rafter agent config set agent.patterns.exclude '["test_key_*"]'

Report issues: Help improve detection at rafter-cli/issues

Advanced Usage

Scan with Custom Patterns

Define custom patterns in .rafter.yml:

scan:
  custom_patterns:
    - name: "Internal API Key"
      regex: "INTERNAL_[A-Z0-9]{32}"
      severity: critical

See Policy File for full configuration options.

Engine Selection

Rafter ships two scan engines, selectable via --engine:

rafter secrets --engine patterns      # built-in regex (21+ patterns)
rafter secrets --engine betterleaks   # Betterleaks binary (more patterns; v0.8.0+)
rafter secrets --engine auto          # default: try Betterleaks, fall back to patterns

Install Betterleaks (the gitleaks successor maintained by the same authors) via rafter agent init --with-betterleaks for enhanced detection.

Respecting `.gitignore`

When the scan target sits inside a git work tree, Rafter honors .gitignore by default — files the repo has excluded (build outputs, vendored deps, scratch envs) are not scanned. Every gitignore semantic git itself supports is honored: nested .gitignore files, negations, .git/info/exclude, and the configured global excludes file.

rafter secrets .                    # default — respects .gitignore
rafter secrets . --no-gitignore     # scan everything, ignore .gitignore

Scans against directories outside a git work tree (a plain unversioned folder) fall back to scanning every candidate file, since there’s no work tree for the filter to consult. The betterleaks engine has always honored .gitignore (gitleaks ancestry); the built-in patterns engine reached parity in the same release that introduced --no-gitignore.

Best Practices

Recommended Workflow

Run rafter secrets before every commit
Configure pre-commit hooks for automation
Use --quiet mode in CI/CD pipelines
Review audit logs regularly
Report false positives to improve accuracy

Get Started

CLI Guides

Local Security

References

Secret Scanning

Secret Scanning

Quick Start

Detected Secret Types

Usage Examples

Scan Specific File

Scan Directory

Quiet Mode (CI/CD)

JSON Output

Watch Mode

Diff Scanning

Output Format

Severity Levels

Severity Indicators

Smart Redaction

Pre-Commit Scanning

Excluding Files

CI/CD Integration

GitHub Actions

GitLab CI

Audit Trail

False Positives

Advanced Usage

Scan with Custom Patterns

Engine Selection

Respecting `.gitignore`

Best Practices

Recommended Workflow

Next Steps

Command Execution

Command Reference

​Secret Scanning

​Quick Start

​Detected Secret Types

​Usage Examples

​Scan Specific File

​Scan Directory

​Quiet Mode (CI/CD)

​JSON Output

​Watch Mode

​Diff Scanning

​Output Format

​Severity Levels

Severity Indicators

​Smart Redaction

​Pre-Commit Scanning

​Excluding Files

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Audit Trail

​False Positives

​Advanced Usage

​Scan with Custom Patterns

​Engine Selection

​Respecting .gitignore

​Best Practices

Recommended Workflow

​Next Steps

Command Execution

Command Reference

Secret Scanning

Quick Start

Detected Secret Types

Usage Examples

Scan Specific File

Scan Directory

Quiet Mode (CI/CD)

JSON Output

Watch Mode

Diff Scanning

Output Format

Severity Levels

Smart Redaction

Pre-Commit Scanning

Excluding Files

CI/CD Integration

GitHub Actions

GitLab CI

Audit Trail

False Positives

Advanced Usage

Scan with Custom Patterns

Engine Selection

Respecting `.gitignore`

Best Practices

Next Steps