Skip to main content

​
Policy File (.rafter.yml)

The .rafter.yml file defines project-level security policies that override your global ~/.rafter/config.json settings. Place it in your project root and Rafter picks it up automatically.

​
How It Works

When any rafter agent command runs, the CLI walks from your current directory up to the git root looking for .rafter.yml or .rafter.yaml. If found, its values merge into the loaded config with policy file winning on conflicts. Arrays like blocked_patterns replace the corresponding ~/.rafter/config.json values entirely rather than appending. Note that hardcoded defaults (e.g. the built-in exclusion list and 21+ secret patterns) always apply regardless of what the policy file sets.

​
Full Schema

version: "1"

# Override global risk level for this project
risk_level: moderate  # minimal | moderate | aggressive

# Command interception policy
command_policy:
  mode: approve-dangerous  # allow-all | approve-dangerous | deny-list
  blocked_patterns:
    - "rm -rf /"
    - "curl.*|.*sh"
  require_approval:
    - "npm publish"
    - "git push --force"

# Secret scanning configuration
scan:
  exclude_paths:
    - "vendor/"
    - "third_party/"
    - "fixtures/"
  custom_patterns:
    - name: "Internal API Key"
      regex: "INTERNAL_[A-Z0-9]{32}"
      severity: critical
    - name: "Staging Token"
      regex: "stg_[a-zA-Z0-9]{24}"
      severity: high

# Audit log settings
audit:
  retention_days: 90
  log_level: info  # debug | info | warn | error
All fields are optional. Only specify what you need to override.

​
Custom Scan Patterns

Add organization-specific secret patterns that the default 21 patterns don’t cover: 
scan:
  custom_patterns:
    - name: "Internal API Key"
      regex: "INTERNAL_[A-Z0-9]{32}"
      severity: critical
    - name: "Deploy Token"
      regex: "deploy_[a-f0-9]{40}"
      severity: high
Each pattern requires:
  • name: Human-readable identifier shown in scan output
  • regex: JavaScript-compatible regular expression
  • severity: critical, high, medium, or low
Custom patterns are added alongside the default patterns, not replacing them.

​
Exclude Paths

Skip directories during secret scanning: 
scan:
  exclude_paths:
    - "vendor/"
    - "third_party/"
    - "test/fixtures/"
These are directory names matched against path segments. The default exclusions (node_modules, .git, dist, build, .next, coverage, .vscode, .idea) always apply. Your exclude_paths add to that list.

​
Command Policy Overrides

Lock down command execution rules per project: 
command_policy:
  mode: deny-list
  blocked_patterns:
    - "rm -rf /"
    - "docker system prune"
  require_approval:
    - "npm publish"
    - "terraform apply"
This is useful for monorepos or shared projects where different teams need different security boundaries.

​
Precedence Rules

SettingSourcePriority
Risk level.rafter.ymlWins
Risk level~/.rafter/config.jsonDefault
Blocked patterns.rafter.ymlReplaces config.json
Custom patterns.rafter.ymlAdded to built-in 21+
Exclude paths.rafter.ymlAdded to built-in exclusions

​
Best Practices

Recommendations

  1. Commit .rafter.yml to version control so the whole team gets the same policies
  2. Start with risk_level: moderate and tighten as needed
  3. Add custom patterns for any organization-specific secret formats
  4. Use exclude_paths for vendored code or generated files

​
Next Steps

Secret Scanning

Learn about scan options and output

Command Execution

Configure command interception