Skip to main content

​
Safe Command Execution

Rafter validates shell commands before execution to prevent dangerous operations.

​
Quick Start

Execute a command with security checks: 
rafter agent exec "npm install"

​
How It Works

When you run rafter agent exec, Rafter:
  1. Evaluates the command against security policies
  2. Scans staged files (for git commands)
  3. Assesses risk level (low/medium/high/critical)
  4. Blocks or requires approval based on risk
  5. Logs the execution to audit log

​
Risk Levels

Commands that can cause catastrophic damage:
  • rm -rf / - Delete entire filesystem
  • :(){ :|:& };: - Fork bomb
  • dd if=/dev/zero of=/dev/sda - Wipe disk
  • mkfs.* - Format filesystems
  • > /dev/sda - Overwrite disk
These are always blocked, even with --force.
Commands with significant risk:
  • rm -rf <directory> - Recursive deletion
  • sudo rm - Delete with elevated privileges
  • chmod 777 - Insecure permissions
  • curl ... | sh - Pipe to shell
  • git push --force - Force push
  • npm publish - Publish packages
  • docker system prune - Delete Docker data
Requires user approval unless --force flag is used.
Commands that need elevated privileges:
  • sudo - Any sudo command
  • chmod - Change permissions
  • kill -9 - Force kill processes
  • systemctl - System service management
Moderate risk level: Requires approval, allowed in minimal mode.
Standard commands with minimal risk:
  • npm install - Install packages
  • git commit - Commit changes
  • ls, cat, grep - Read operations
  • echo, touch - Basic file operations
Allowed immediately across all risk levels.

​
Usage Examples

​
Safe Command

Executes immediately: 
rafter agent exec "npm install express"

​
Git Commit with Auto-Scan

Scans staged files before committing: 
rafter agent exec "git commit -m 'Add authentication'"
If secrets are detected in staged files, the commit is blocked: 
⚠️  Secrets detected in staged files!

Found 2 secret(s) in 1 file(s)

Run 'rafter agent scan' for details.

​
High-Risk Command

Requires approval: 
rafter agent exec "sudo rm /var/log/old-logs/*.log"
You’ll see: 
⚠️  Command requires approval

Risk Level: HIGH
Command: sudo rm /var/log/old-logs/*.log
Reason: Matches approval pattern: sudo rm

Approve this command? (yes/no):

​
Force Execution

Skip approval with --force (logged in audit): 
rafter agent exec "sudo systemctl restart nginx" --force
The --force flag skips approval but is logged in the audit trail. Use responsibly.

​
Skip File Scanning

Skip pre-execution scanning for git commands: 
rafter agent exec "git commit -m 'Fix typo'" --skip-scan

​
Command Policies

Configure how Rafter handles commands:

​
Policy Modes

# Requires approval for high/critical commands
rafter agent config set agent.commandPolicy.mode approve-dangerous

​
Custom Blocked Patterns

Add patterns to always block: 
# View current blocked patterns
rafter agent config get agent.commandPolicy.blockedPatterns

# Add custom pattern (requires manual config edit)
# Edit ~/.rafter/config.json:
{
  "agent": {
    "commandPolicy": {
      "blockedPatterns": [
        "rm -rf /",
        "custom-dangerous-command"
      ]
    }
  }
}

​
Custom Approval Patterns

Patterns requiring approval: 
{
  "agent": {
    "commandPolicy": {
      "requireApproval": [
        "rm -rf",
        "sudo rm",
        "git push --force",
        "npm publish"
      ]
    }
  }
}

​
Audit Logging

All command executions are logged: 
# View command executions
rafter agent audit --event command_intercepted

# View blocked commands
rafter agent audit --event command_intercepted | grep BLOCKED

# View overrides
rafter agent audit --event policy_override
Audit entries include:
  • Timestamp
  • Command executed
  • Risk level
  • Action taken (allowed/blocked/overridden)
  • User justification (for overrides)

​
Integration with Agents

​
OpenClaw

When integrated with OpenClaw, commands are automatically routed through Rafter: 
User: "Commit the changes"
OpenClaw: rafter agent exec "git commit -m '...'"
Rafter: Scans staged files → Allows if clean

​
Claude Code

Coming soon: MCP server integration.

​
Exit Codes

Rafter uses standard exit codes:
  • 0 - Success
  • 1 - Command blocked or execution failed
Use in scripts: 
if rafter agent exec "dangerous-command"; then
    echo "Command succeeded"
else
    echo "Command blocked or failed"
fi

​
Best Practices

Recommended Practices

  1. Always use for git commits: Auto-scans staged files
  2. Never bypass with --force in production: Use only when necessary
  3. Review audit logs: Check rafter agent audit after suspicious activity
  4. Configure policies: Adjust commandPolicy.mode for your environment
  5. Test in development: Ensure policies work before deploying to agents

​
Advanced Configuration

​
Risk Level vs Policy Mode

Understanding the Difference

  • Risk Level (agent.riskLevel): Controls overall security stance
  • Policy Mode (agent.commandPolicy.mode): Controls specific command handling
Example:
  • riskLevel: aggressive + mode: approve-dangerous = Very secure
  • riskLevel: minimal + mode: allow-all = Permissive

​
Custom Risk Assessment

Future feature: Define custom risk patterns and severity levels.

​
Troubleshooting

​
Command Incorrectly Blocked

If a safe command is blocked:
  1. Check current policy: 
    rafter agent config get agent.commandPolicy
  2. Switch to a more permissive mode: 
    rafter agent config set agent.commandPolicy.mode allow-all
  3. Report false positive: rafter-cli/issues

​
Secrets Not Detected

If secrets aren’t caught during git commits:
  1. Ensure scanning is enabled (default): 
    rafter agent exec "git commit -m 'message'"
# (without --skip-scan)
  2. Test scanner separately: 
    rafter agent scan

​
Next Steps

OpenClaw Integration

Set up with OpenClaw agents

Command Reference

Complete CLI command reference