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:

Evaluates the command against security policies
Scans staged files (for git commands)
Assesses risk level (low/medium/high/critical)
Blocks or requires approval based on risk
Logs the execution to audit log

Risk Levels

🔴 Critical (Blocked)

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.

🟠 High (Requires Approval)

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.

🟡 Medium (Context-Dependent)

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.

🟢 Low (Allowed)

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 secrets' for details.

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

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

# Block specific patterns, allow everything else
rafter agent config set agent.commandPolicy.mode deny-list

# Allow all commands (not recommended)
rafter agent config set agent.commandPolicy.mode allow-all

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: Evaluates command risk → Scans staged files for secrets → Allows if clean

Claude Code

Claude Code integration uses PreToolUse hooks to intercept commands before execution, plus MCP tools for agent-initiated scans. See Claude Code Integration for setup, and MCP Integration for the MCP server.

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

Always use for git commits: Evaluates risk and scans staged files
Never bypass with --force in production: Use only when necessary
Review audit logs: Check rafter agent audit after suspicious activity
Configure policies: Adjust commandPolicy.mode for your environment
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:

Check current policy:

rafter agent config get agent.commandPolicy

Switch to a more permissive mode:

rafter agent config set agent.commandPolicy.mode allow-all

Report false positive: rafter-cli/issues

Secrets Not Detected

If secrets aren’t caught during git commits:

Ensure scanning is enabled (default):

rafter agent exec "git commit -m 'message'"
# (without --skip-scan)

Test scanner separately:
rafter secrets

Next Steps

OpenClaw Integration

Set up with OpenClaw agents

Command Reference

Complete CLI command reference

Get Started

CLI Guides

Local Security

References

Safe Command Execution

Safe Command Execution

Quick Start

How It Works

Risk Levels

Usage Examples

Safe Command

Git Commit with Auto-Scan

High-Risk Command

Force Execution

Skip File Scanning

Command Policies

Policy Modes

Custom Blocked Patterns

Custom Approval Patterns

Audit Logging

Integration with Agents

OpenClaw

Claude Code

Exit Codes

Best Practices

Recommended Practices

Advanced Configuration

Risk Level vs Policy Mode

Understanding the Difference

Custom Risk Assessment

Troubleshooting

Command Incorrectly Blocked

Secrets Not Detected

Next Steps

OpenClaw Integration

Command Reference

​Safe Command Execution

​Quick Start

​How It Works

​Risk Levels

​Usage Examples

​Safe Command

​Git Commit with Auto-Scan

​High-Risk Command

​Force Execution

​Skip File Scanning

​Command Policies

​Policy Modes

​Custom Blocked Patterns

​Custom Approval Patterns

​Audit Logging

​Integration with Agents

​OpenClaw

​Claude Code

​Exit Codes

​Best Practices

Recommended Practices

​Advanced Configuration

​Risk Level vs Policy Mode

Understanding the Difference

​Custom Risk Assessment

​Troubleshooting

​Command Incorrectly Blocked

​Secrets Not Detected

​Next Steps

OpenClaw Integration

Command Reference

Safe Command Execution

Quick Start

How It Works

Risk Levels

Usage Examples

Safe Command

Git Commit with Auto-Scan

High-Risk Command

Force Execution

Skip File Scanning

Command Policies

Policy Modes

Custom Blocked Patterns

Custom Approval Patterns

Audit Logging

Integration with Agents

OpenClaw

Claude Code

Exit Codes

Best Practices

Advanced Configuration

Risk Level vs Policy Mode

Custom Risk Assessment

Troubleshooting

Command Incorrectly Blocked

Secrets Not Detected

Next Steps