secure-sandbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Secure Sandbox Execution Skill

Secure Sandbox执行Skill

A security-focused execution environment inspired by OpenClaw's exec-approvals and ZeroClaw's secure-by-default runtime. This skill provides guardrails for running commands safely with approval workflows, allowlisting, and comprehensive audit logging.

一款聚焦安全的执行环境，灵感来源于OpenClaw的exec-approvals和ZeroClaw的默认安全运行时。该Skill提供安全防护机制，支持通过审批工作流、白名单机制和全面的审计日志来安全运行命令。

Purpose

用途

When enabled, this skill intercepts command execution and:

Detects dangerous operations (destructive commands, system modifications)
Enforces allowlists (only pre-approved commands run automatically)
Queues approvals (suspicious commands wait for user review)
Creates audit trails (every command is logged with context)
Provides dry-run mode (preview effects before execution)

启用后，该Skill会拦截命令执行并：

检测危险操作（破坏性命令、系统修改操作）
强制执行白名单（仅预先批准的命令可自动运行）
排队等待审批（可疑命令需等待用户审核）
生成审计追踪（每条命令都会附带上下文信息被记录）
提供试运行模式（执行前预览操作效果）

Architecture

架构

┌─────────────────────────────────────────────────────────────────┐
│                     Command Execution Flow                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  User Command → Parse → Classify → Decision → Execute/Queue     │
│                          │                                      │
│              ┌───────────┼───────────┐                         │
│              ▼           ▼           ▼                         │
│         [SAFE]      [DANGEROUS]   [DISALLOWED]                  │
│              │           │           │                         │
│              ▼           ▼           ▼                         │
│         Execute     Requires      Blocked                       │
│         + Log       Approval       + Alert                      │
│                     + Queue                                     │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Approval Queue                          │   │
│  │  Commands awaiting user review with full context          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Audit Log                               │   │
│  │  Timestamp | Command | User | Status | Output | Risk      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                     Command Execution Flow                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  User Command → Parse → Classify → Decision → Execute/Queue     │
│                          │                                      │
│              ┌───────────┼───────────┐                         │
│              ▼           ▼           ▼                         │
│         [SAFE]      [DANGEROUS]   [DISALLOWED]                  │
│              │           │           │                         │
│              ▼           ▼           ▼                         │
│         Execute     Requires      Blocked                       │
│         + Log       Approval       + Alert                      │
│                     + Queue                                     │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Approval Queue                          │   │
│  │  Commands awaiting user review with full context          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   Audit Log                               │   │
│  │  Timestamp | Command | User | Status | Output | Risk      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Setup

安装步骤

bash

cd /job/.pi/skills/secure-sandbox
npm install

bash

cd /job/.pi/skills/secure-sandbox
npm install

Configuration

配置

Create

SANDBOX.md

in your workspace root to configure the sandbox:

markdown

undefined

在工作区根目录创建

SANDBOX.md

文件来配置沙箱：

markdown

undefined

Secure Sandbox Configuration

Security Level

Level: allowlist

Allowed Commands (Auto-execute)

ls
pwd
cat
echo
grep
rg
node --version
npm list

ls
pwd
cat
echo
grep
rg
node --version
npm list

Dangerous Patterns (Require Approval)

rm -rf
dd if=
mkfs
sudo
chmod 777

rm -rf
dd if=
mkfs
sudo
chmod 777

Disallowed Commands (Block)

curl http://
wget http://
nc -l
bash -c
eval

curl http://
wget http://
nc -l
bash -c
eval

Approval Settings

Auto-approve safe: true
Dry-run by default: false
Audit retention: 30 days

undefined

Auto-approve safe: true
Dry-run by default: false
Audit retention: 30 days

undefined

Commands

命令

Check Command Safety

检查命令安全性

bash

undefined

bash

undefined

Analyze a command's risk level

sandbox-check "rm -rf /tmp/*"


Output:
```json
{
  "command": "rm -rf /tmp/*",
  "risk_level": "dangerous",
  "risk_reasons": ["Recursive deletion", "Wildcard pattern"],
  "requires_approval": true,
  "suggested_action": "queue_for_approval"
}

sandbox-check "rm -rf /tmp/*"


输出：
```json
{
  "command": "rm -rf /tmp/*",
  "risk_level": "dangerous",
  "risk_reasons": ["Recursive deletion", "Wildcard pattern"],
  "requires_approval": true,
  "suggested_action": "queue_for_approval"
}

Execute with Approval

带审批执行

bash

undefined

bash

undefined

Run with automatic safety checks

sandbox-exec "npm install --save express"

Force approval even for safe commands

sandbox-exec --require-approval "cat ~/.ssh/id_rsa.pub"

Dry-run mode (show what would happen)

sandbox-exec --dry-run "rm -rf node_modules"

undefined

sandbox-exec --dry-run "rm -rf node_modules"

undefined

Manage Approval Queue

管理审批队列

bash

undefined

bash

undefined

List pending approvals

sandbox-queue list

Approve a command

sandbox-queue approve <id>

Reject a command

sandbox-queue reject <id> --reason "Too risky"

Clear old approvals

sandbox-queue clear --older-than 7d

undefined

sandbox-queue clear --older-than 7d

undefined

View Audit Log

查看审计日志

bash

undefined

bash

undefined

Show recent executions

sandbox-audit log --last 20

Show only dangerous commands

sandbox-audit log --risk-level dangerous

Export audit log

sandbox-audit export --format json --output /tmp/audit.json

Statistics

sandbox-audit stats

undefined

sandbox-audit stats

undefined

Manage Allowlist

管理白名单

bash

undefined

bash

undefined

Add command to allowlist

sandbox-allowlist add "cargo build" --reason "Safe build command"

Remove from allowlist

sandbox-allowlist remove "cargo build"

List all allowed patterns

sandbox-allowlist list

Test if a command matches allowlist

sandbox-allowlist test "npm install"

undefined

sandbox-allowlist test "npm install"

undefined

Tools Added

新增工具

When this skill is active, the following tools are available:

启用该Skill后，可使用以下工具：

sandbox_check

sandbox_check

Analyze a command for safety before execution.

javascript

sandbox_check({
  command: "rm -rf /tmp/*",
  context: { working_dir: "/job", user: "agent" }
})

执行前分析命令的安全性。

javascript

sandbox_check({
  command: "rm -rf /tmp/*",
  context: { working_dir: "/job", user: "agent" }
})

sandbox_exec

sandbox_exec

Execute a command with safety checks and approval workflow.

javascript

sandbox_exec({
  command: "npm install express",
  require_approval: false,      // Force approval even if safe
  dry_run: false,                // Show what would happen
  timeout: 60000,               // Execution timeout
  env: { NODE_ENV: "production" } // Extra environment variables
})

通过安全检查和审批工作流执行命令。

javascript

sandbox_exec({
  command: "npm install express",
  require_approval: false,      // Force approval even if safe
  dry_run: false,                // Show what would happen
  timeout: 60000,               // Execution timeout
  env: { NODE_ENV: "production" } // Extra environment variables
})

sandbox_queue_list

sandbox_queue_list

List commands awaiting approval.

javascript

sandbox_queue_list({ status: "pending" })  // pending, approved, rejected, all

列出等待审批的命令。

javascript

sandbox_queue_list({ status: "pending" })  // pending, approved, rejected, all

sandbox_queue_approve

sandbox_queue_approve

Approve a queued command for execution.

javascript

sandbox_queue_approve({
  id: "cmd_abc123",
  approved_by: "user@example.com",
  notes: "Approved for deployment"
})

批准队列中的命令以执行。

javascript

sandbox_queue_approve({
  id: "cmd_abc123",
  approved_by: "user@example.com",
  notes: "Approved for deployment"
})

sandbox_queue_reject

sandbox_queue_reject

Reject a queued command.

javascript

sandbox_queue_reject({
  id: "cmd_abc123",
  rejected_by: "user@example.com",
  reason: "Security risk - deletes system files"
})

拒绝队列中的命令。

javascript

sandbox_queue_reject({
  id: "cmd_abc123",
  rejected_by: "user@example.com",
  reason: "Security risk - deletes system files"
})

sandbox_audit_log

sandbox_audit_log

Query the audit log.

javascript

sandbox_audit_log({
  limit: 50,
  risk_level: "dangerous",  // safe, normal, dangerous, critical
  since: "2026-02-01",
  command_pattern: "rm*"
})

查询审计日志。

javascript

sandbox_audit_log({
  limit: 50,
  risk_level: "dangerous",  // safe, normal, dangerous, critical
  since: "2026-02-01",
  command_pattern: "rm*"
})

sandbox_audit_stats

sandbox_audit_stats

Get execution statistics.

javascript

sandbox_audit_stats({
  period: "7d"  // 1d, 7d, 30d, all
})

获取执行统计数据。

javascript

sandbox_audit_stats({
  period: "7d"  // 1d, 7d, 30d, all
})

sandbox_allowlist_add

sandbox_allowlist_add

Add a command pattern to the allowlist.

javascript

sandbox_allowlist_add({
  pattern: "npm install *",
  description: "Install npm packages",
  auto_approve: true
})

将命令模式添加到白名单。

javascript

sandbox_allowlist_add({
  pattern: "npm install *",
  description: "Install npm packages",
  auto_approve: true
})

sandbox_allowlist_remove

sandbox_allowlist_remove

Remove a pattern from the allowlist.

javascript

sandbox_allowlist_remove({ pattern: "npm install *" })

从白名单中移除模式。

javascript

sandbox_allowlist_remove({ pattern: "npm install *" })

sandbox_allowlist_test

sandbox_allowlist_test

Test if a command matches the allowlist.

javascript

sandbox_allowlist_test({ command: "npm install express" })

测试命令是否匹配白名单。

javascript

sandbox_allowlist_test({ command: "npm install express" })

Risk Classification

风险分类

Commands are classified by risk level:

Level	Description	Examples	Default Action
`safe`	Read-only, informational	`ls` , `cat` , `pwd` , `echo`	Auto-execute
`normal`	Common operations	`npm install` , `git clone`	Auto-execute
`dangerous`	Destructive or system-modifying	`rm -rf` , `chmod 777`	Require approval
`critical`	High security risk	`curl	bash `,` eval`
`disallowed`	Explicitly forbidden	Patterns in denylist	Block

命令按风险等级分类：

等级	描述	示例	默认操作
`safe`	只读、信息查询类	`ls` , `cat` , `pwd` , `echo`	自动执行
`normal`	常见操作	`npm install` , `git clone`	自动执行
`dangerous`	破坏性或系统修改类	`rm -rf` , `chmod 777`	需要审批
`critical`	高安全风险	`curl	bash `,` eval`
`disallowed`	明确禁止	黑名单中的模式	拦截

Usage in Agent Prompt

在Agent提示词中使用

When this skill is active, include this context:

undefined

启用该Skill后，需包含以下上下文：

undefined

Secure Sandbox Execution

You have access to a secure command execution environment with safety guardrails.

When to Use

Always wrap potentially dangerous commands with sandbox tools:

File deletion (
```
rm
```
,
```
unlink
```
)
Permission changes (
```
chmod
```
,
```
chown
```
)
System modifications (
```
sudo
```
,
```
mount
```
)
Network downloads (
```
curl
```
,
```
wget
```
)
Code evaluation (
```
eval
```
,
```
exec
```
)

Always wrap potentially dangerous commands with sandbox tools:

File deletion (
```
rm
```
,
```
unlink
```
)
Permission changes (
```
chmod
```
,
```
chown
```
)
System modifications (
```
sudo
```
,
```
mount
```
)
Network downloads (
```
curl
```
,
```
wget
```
)
Code evaluation (
```
eval
```
,
```
exec
```
)

Available Commands

sandbox_check(command) - Analyze risk before execution sandbox_exec(command, options) - Execute with safety checks sandbox_queue_list(status?) - View pending approvals sandbox_queue_approve(id) - Approve a queued command sandbox_queue_reject(id, reason) - Reject a queued command sandbox_audit_log(options?) - Query execution history sandbox_audit_stats(period?) - Get execution statistics

Risk Levels

SAFE: Auto-executed (ls, cat, pwd)
NORMAL: Auto-executed (npm install, git clone)
DANGEROUS: Requires approval (rm -rf, chmod 777)
CRITICAL: Blocked (curl | bash, eval from network)
DISALLOWED: Explicitly forbidden

SAFE: Auto-executed (ls, cat, pwd)
NORMAL: Auto-executed (npm install, git clone)
DANGEROUS: Requires approval (rm -rf, chmod 777)
CRITICAL: Blocked (curl | bash, eval from network)
DISALLOWED: Explicitly forbidden

Best Practices

Check first: Use sandbox_check before dangerous operations
Dry run: Use --dry-run for destructive commands
Context matters: The sandbox considers working directory and user
Audit trail: Every command is logged - review regularly
Allowlisting: Pre-approve safe patterns for your workflow

Check first: Use sandbox_check before dangerous operations
Dry run: Use --dry-run for destructive commands
Context matters: The sandbox considers working directory and user
Audit trail: Every command is logged - review regularly
Allowlisting: Pre-approve safe patterns for your workflow

Example Workflow

javascript

// 1. Check if command is safe
const check = sandbox_check({ command: "rm -rf node_modules" });

// 2. If dangerous, use approval workflow
if (check.risk_level === "dangerous") {
  const result = sandbox_exec({
    command: "rm -rf node_modules",
    dry_run: true  // Preview first
  });
  
  // After review, execute for real
  sandbox_exec({ command: "rm -rf node_modules" });
}

// 3. Review audit log periodically
const stats = sandbox_audit_stats({ period: "7d" });
console.log(`Executed ${stats.total_commands} commands (${stats.dangerous} dangerous)`);

undefined

javascript

// 1. Check if command is safe
const check = sandbox_check({ command: "rm -rf node_modules" });

// 2. If dangerous, use approval workflow
if (check.risk_level === "dangerous") {
  const result = sandbox_exec({
    command: "rm -rf node_modules",
    dry_run: true  // Preview first
  });
  
  // After review, execute for real
  sandbox_exec({ command: "rm -rf node_modules" });
}

// 3. Review audit log periodically
const stats = sandbox_audit_stats({ period: "7d" });
console.log(`Executed ${stats.total_commands} commands (${stats.dangerous} dangerous)`);

undefined

File Structure

文件结构

.pi/skills/secure-sandbox/
├── SKILL.md                    # This file
├── package.json                # Dependencies
├── index.js                    # Main entry point
├── lib/
│   ├── classifier.js          # Risk classification engine
│   ├── allowlist.js         # Allowlist matching
│   ├── queue.js             # Approval queue management
│   ├── auditor.js           # Audit logging
│   └── sandbox.js           # Sandbox execution environment
├── bin/
│   ├── sandbox-check.js     # Check command safety
│   ├── sandbox-exec.js      # Execute with safety
│   ├── sandbox-queue.js     # Manage approval queue
│   └── sandbox-audit.js     # View audit logs
├── templates/
│   └── SANDBOX.md           # Example configuration
├── test/
│   └── sandbox.test.js      # Test suite
└── .sandbox/                 # Runtime data (gitignored)
    ├── queue.json           # Pending approvals
    └── audit/               # Audit log files
        ├── 2026-02-25.jsonl
        └── ...

.pi/skills/secure-sandbox/
├── SKILL.md                    # This file
├── package.json                # Dependencies
├── index.js                    # Main entry point
├── lib/
│   ├── classifier.js          # Risk classification engine
│   ├── allowlist.js         # Allowlist matching
│   ├── queue.js             # Approval queue management
│   ├── auditor.js           # Audit logging
│   └── sandbox.js           # Sandbox execution environment
├── bin/
│   ├── sandbox-check.js     # Check command safety
│   ├── sandbox-exec.js      # Execute with safety
│   ├── sandbox-queue.js     # Manage approval queue
│   └── sandbox-audit.js     # View audit logs
├── templates/
│   └── SANDBOX.md           # Example configuration
├── test/
│   └── sandbox.test.js      # Test suite
└── .sandbox/                 # Runtime data (gitignored)
    ├── queue.json           # Pending approvals
    └── audit/               # Audit log files
        ├── 2026-02-25.jsonl
        └── ...

Security Model

安全模型

Threats Addressed

应对的威胁

Accidental Destruction: Prevents unintentional
```
rm -rf /
```
type mistakes
Malicious Code: Blocks known dangerous patterns (eval, curl | bash)
Supply Chain: Flags installation of unverified packages
Privilege Escalation: Requires approval for sudo/root operations
Data Exfiltration: Alerts on suspicious network operations

意外破坏：防止
```
rm -rf /
```
这类无意的错误操作
恶意代码：拦截已知的危险模式（如eval、curl | bash）
供应链风险：标记未验证包的安装操作
权限提升：sudo/root操作需要审批
数据泄露：对可疑网络操作发出告警

Trust Boundaries

信任边界

Sandbox Config: Controlled by workspace owner (trusted)
Allowlist: Pre-approved commands from config (trusted)
Approval Queue: User-reviewed before execution (trusted after review)
Audit Log: Immutable record of all activity (verification)

沙箱配置：由工作区所有者控制（可信）
白名单：配置中的预先批准命令（可信）
审批队列：经用户审核后执行（审核后可信）
审计日志：所有活动的不可变记录（用于验证）

Integration with Other Skills

与其他Skill集成

With multi-agent-orchestrator

与multi-agent-orchestrator集成

Sub-agents can delegate dangerous operations to the sandbox:

javascript

parallel_delegates({
  tasks: [
    { agent: "security-checker", task: "scan for vulnerabilities" },
    { agent: "sandbox", task: "safely clean build artifacts" }
  ]
})

子Agent可将危险操作委托给沙箱：

javascript

parallel_delegates({
  tasks: [
    { agent: "security-checker", task: "scan for vulnerabilities" },
    { agent: "sandbox", task: "safely clean build artifacts" }
  ]
})

With code-intelligence

与code-intelligence集成

Analyze code changes before approving related commands:

javascript

const impact = code_impact_analysis({ files: changed });
if (impact.deletes_important_files) {
  sandbox_allowlist_remove("rm *");
}

在批准相关命令前分析代码变更：

javascript

const impact = code_impact_analysis({ files: changed });
if (impact.deletes_important_files) {
  sandbox_allowlist_remove("rm *");
}

Performance

性能

Metric	Expected
Classification	<10ms
Allowlist lookup	<5ms
Audit write	<20ms (async)
Sandboxed execution	Add ~50ms overhead
Queue operations	<50ms

指标	预期值
分类处理	<10ms
白名单查询	<5ms
审计日志写入	<20ms（异步）
沙箱执行	增加约50ms开销
队列操作	<50ms

Error Handling

错误处理

Classification failure: Conservative - treat as dangerous
Queue full: Reject new commands with alert
Audit write failure: Continue execution, alert user
Permission denied: Block with clear error message

分类失败：保守处理——视为危险命令
队列已满：拒绝新命令并发出告警
审计日志写入失败：继续执行，向用户发出告警
权限不足：拦截并返回清晰的错误信息

Future Enhancements

未来增强计划

Inspiration

灵感来源

This skill is inspired by:

OpenClaw's exec-approvals: Per-command security with allowlists
ZeroClaw's secure runtime: Secure-by-default philosophy
Linux capabilities: Fine-grained permission model
Docker security: Container isolation patterns

该Skill的灵感来源于：

OpenClaw的exec-approvals：基于命令的安全机制与白名单
ZeroClaw的安全运行时：默认安全的设计理念
Linux能力机制：细粒度权限模型
Docker安全：容器隔离模式

When NOT to Use

不适用场景

Don't use the secure sandbox when:

Running in a fully isolated throwaway environment
Performance is critical (<50ms overhead matters)
Commands are fully trusted and generated internally
The agent needs unrestricted system access

Use it when:

Commands come from user input or external sources
Running in production or persistent environments
Multiple users/agents share the system
Compliance requires audit trails

在以下场景请勿使用安全沙箱：

在完全隔离的一次性环境中运行
对性能要求极高（50ms开销不可接受）
命令完全可信且由内部生成
Agent需要不受限制的系统访问权限

建议使用场景：

命令来自用户输入或外部来源
在生产环境或持久化环境中运行
多用户/Agent共享系统
合规要求需要审计追踪