docs: add security sandbox documentation
Add comprehensive documentation about the security sandbox feature, including default configuration, protected tools, exec tool protection, error examples, and security boundary consistency. Also remove outdated config.openrouter.json sample file.
This commit is contained in:
yinwm
92
README.ja.md
92
README.ja.md
@@ -330,6 +330,98 @@ PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw
|
|||||||
└── USER.md # ユーザー設定
|
└── USER.md # ユーザー設定
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 🔒 セキュリティサンドボックス
|
||||||
|
|
||||||
|
PicoClaw はデフォルトでサンドボックス環境で実行されます。エージェントは設定されたワークスペース内のファイルにのみアクセスし、コマンドを実行できます。
|
||||||
|
|
||||||
|
#### デフォルト設定
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"workspace": "~/.picoclaw/workspace",
|
||||||
|
"restrict_to_workspace": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| オプション | デフォルト | 説明 |
|
||||||
|
|-----------|-----------|------|
|
||||||
|
| `workspace` | `~/.picoclaw/workspace` | エージェントの作業ディレクトリ |
|
||||||
|
| `restrict_to_workspace` | `true` | ファイル/コマンドアクセスをワークスペースに制限 |
|
||||||
|
|
||||||
|
#### 保護対象ツール
|
||||||
|
|
||||||
|
`restrict_to_workspace: true` の場合、以下のツールがサンドボックス化されます：
|
||||||
|
|
||||||
|
| ツール | 機能 | 制限 |
|
||||||
|
|-------|------|------|
|
||||||
|
| `read_file` | ファイル読み込み | ワークスペース内のファイルのみ |
|
||||||
|
| `write_file` | ファイル書き込み | ワークスペース内のファイルのみ |
|
||||||
|
| `list_dir` | ディレクトリ一覧 | ワークスペース内のディレクトリのみ |
|
||||||
|
| `edit_file` | ファイル編集 | ワークスペース内のファイルのみ |
|
||||||
|
| `append_file` | ファイル追記 | ワークスペース内のファイルのみ |
|
||||||
|
| `exec` | コマンド実行 | コマンドパスはワークスペース内である必要あり |
|
||||||
|
|
||||||
|
#### exec ツールの追加保護
|
||||||
|
|
||||||
|
`restrict_to_workspace: false` でも、`exec` ツールは以下の危険なコマンドをブロックします：
|
||||||
|
|
||||||
|
- `rm -rf`, `del /f`, `rmdir /s` — 一括削除
|
||||||
|
- `format`, `mkfs`, `diskpart` — ディスクフォーマット
|
||||||
|
- `dd if=` — ディスクイメージング
|
||||||
|
- `/dev/sd[a-z]` への書き込み — 直接ディスク書き込み
|
||||||
|
- `shutdown`, `reboot`, `poweroff` — システムシャットダウン
|
||||||
|
- フォークボム `:(){ :|:& };:`
|
||||||
|
|
||||||
|
#### エラー例
|
||||||
|
|
||||||
|
```
|
||||||
|
[ERROR] tool: Tool execution failed
|
||||||
|
{tool=exec, error=Command blocked by safety guard (path outside working dir)}
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
[ERROR] tool: Tool execution failed
|
||||||
|
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 制限の無効化（セキュリティリスク）
|
||||||
|
|
||||||
|
エージェントにワークスペース外のパスへのアクセスが必要な場合：
|
||||||
|
|
||||||
|
**方法1: 設定ファイル**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"restrict_to_workspace": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**方法2: 環境変数**
|
||||||
|
```bash
|
||||||
|
export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⚠️ **警告**: この制限を無効にすると、エージェントはシステム上の任意のパスにアクセスできるようになります。制御された環境でのみ慎重に使用してください。
|
||||||
|
|
||||||
|
#### セキュリティ境界の一貫性
|
||||||
|
|
||||||
|
`restrict_to_workspace` 設定は、すべての実行パスで一貫して適用されます：
|
||||||
|
|
||||||
|
| 実行パス | セキュリティ境界 |
|
||||||
|
|---------|-----------------|
|
||||||
|
| メインエージェント | `restrict_to_workspace` ✅ |
|
||||||
|
| サブエージェント / Spawn | 同じ制限を継承 ✅ |
|
||||||
|
| ハートビートタスク | 同じ制限を継承 ✅ |
|
||||||
|
|
||||||
|
すべてのパスで同じワークスペース制限が適用されます — サブエージェントやスケジュールタスクを通じてセキュリティ境界をバイパスする方法はありません。
|
||||||
|
|
||||||
### ハートビート（定期タスク）
|
### ハートビート（定期タスク）
|
||||||
|
|
||||||
PicoClaw は自動的に定期タスクを実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成します：
|
PicoClaw は自動的に定期タスクを実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成します：
|
||||||
|
|||||||
92
README.md
92
README.md
@@ -410,6 +410,98 @@ PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspa
|
|||||||
└── USER.md # User preferences
|
└── USER.md # User preferences
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 🔒 Security Sandbox
|
||||||
|
|
||||||
|
PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
|
||||||
|
|
||||||
|
#### Default Configuration
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"workspace": "~/.picoclaw/workspace",
|
||||||
|
"restrict_to_workspace": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Option | Default | Description |
|
||||||
|
|--------|---------|-------------|
|
||||||
|
| `workspace` | `~/.picoclaw/workspace` | Working directory for the agent |
|
||||||
|
| `restrict_to_workspace` | `true` | Restrict file/command access to workspace |
|
||||||
|
|
||||||
|
#### Protected Tools
|
||||||
|
|
||||||
|
When `restrict_to_workspace: true`, the following tools are sandboxed:
|
||||||
|
|
||||||
|
| Tool | Function | Restriction |
|
||||||
|
|------|----------|-------------|
|
||||||
|
| `read_file` | Read files | Only files within workspace |
|
||||||
|
| `write_file` | Write files | Only files within workspace |
|
||||||
|
| `list_dir` | List directories | Only directories within workspace |
|
||||||
|
| `edit_file` | Edit files | Only files within workspace |
|
||||||
|
| `append_file` | Append to files | Only files within workspace |
|
||||||
|
| `exec` | Execute commands | Command paths must be within workspace |
|
||||||
|
|
||||||
|
#### Additional Exec Protection
|
||||||
|
|
||||||
|
Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands:
|
||||||
|
|
||||||
|
- `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion
|
||||||
|
- `format`, `mkfs`, `diskpart` — Disk formatting
|
||||||
|
- `dd if=` — Disk imaging
|
||||||
|
- Writing to `/dev/sd[a-z]` — Direct disk writes
|
||||||
|
- `shutdown`, `reboot`, `poweroff` — System shutdown
|
||||||
|
- Fork bomb `:(){ :|:& };:`
|
||||||
|
|
||||||
|
#### Error Examples
|
||||||
|
|
||||||
|
```
|
||||||
|
[ERROR] tool: Tool execution failed
|
||||||
|
{tool=exec, error=Command blocked by safety guard (path outside working dir)}
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
[ERROR] tool: Tool execution failed
|
||||||
|
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Disabling Restrictions (Security Risk)
|
||||||
|
|
||||||
|
If you need the agent to access paths outside the workspace:
|
||||||
|
|
||||||
|
**Method 1: Config file**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"restrict_to_workspace": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Method 2: Environment variable**
|
||||||
|
```bash
|
||||||
|
export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
|
||||||
|
```
|
||||||
|
|
||||||
|
> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only.
|
||||||
|
|
||||||
|
#### Security Boundary Consistency
|
||||||
|
|
||||||
|
The `restrict_to_workspace` setting applies consistently across all execution paths:
|
||||||
|
|
||||||
|
| Execution Path | Security Boundary |
|
||||||
|
|----------------|-------------------|
|
||||||
|
| Main Agent | `restrict_to_workspace` ✅ |
|
||||||
|
| Subagent / Spawn | Inherits same restriction ✅ |
|
||||||
|
| Heartbeat tasks | Inherits same restriction ✅ |
|
||||||
|
|
||||||
|
All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks.
|
||||||
|
|
||||||
### Heartbeat (Periodic Tasks)
|
### Heartbeat (Periodic Tasks)
|
||||||
|
|
||||||
PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace:
|
PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace:
|
||||||
|
|||||||
@@ -1,86 +0,0 @@
|
|||||||
{
|
|
||||||
"agents": {
|
|
||||||
"defaults": {
|
|
||||||
"workspace": "~/.picoclaw/workspace",
|
|
||||||
"model": "arcee-ai/trinity-large-preview:free",
|
|
||||||
"max_tokens": 8192,
|
|
||||||
"temperature": 0.7,
|
|
||||||
"max_tool_iterations": 20
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"channels": {
|
|
||||||
"telegram": {
|
|
||||||
"enabled": false,
|
|
||||||
"token": "YOUR_TELEGRAM_BOT_TOKEN",
|
|
||||||
"allow_from": [
|
|
||||||
"YOUR_USER_ID"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"discord": {
|
|
||||||
"enabled": true,
|
|
||||||
"token": "YOUR_DISCORD_BOT_TOKEN",
|
|
||||||
"allow_from": []
|
|
||||||
},
|
|
||||||
"maixcam": {
|
|
||||||
"enabled": false,
|
|
||||||
"host": "0.0.0.0",
|
|
||||||
"port": 18790,
|
|
||||||
"allow_from": []
|
|
||||||
},
|
|
||||||
"whatsapp": {
|
|
||||||
"enabled": false,
|
|
||||||
"bridge_url": "ws://localhost:3001",
|
|
||||||
"allow_from": []
|
|
||||||
},
|
|
||||||
"feishu": {
|
|
||||||
"enabled": false,
|
|
||||||
"app_id": "",
|
|
||||||
"app_secret": "",
|
|
||||||
"encrypt_key": "",
|
|
||||||
"verification_token": "",
|
|
||||||
"allow_from": []
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"providers": {
|
|
||||||
"anthropic": {
|
|
||||||
"api_key": "",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"openai": {
|
|
||||||
"api_key": "",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"openrouter": {
|
|
||||||
"api_key": "sk-or-v1-xxx",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"groq": {
|
|
||||||
"api_key": "gsk_xxx",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"zhipu": {
|
|
||||||
"api_key": "YOUR_ZHIPU_API_KEY",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"gemini": {
|
|
||||||
"api_key": "",
|
|
||||||
"api_base": ""
|
|
||||||
},
|
|
||||||
"vllm": {
|
|
||||||
"api_key": "",
|
|
||||||
"api_base": ""
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"tools": {
|
|
||||||
"web": {
|
|
||||||
"search": {
|
|
||||||
"api_key": "YOUR_BRAVE_API_KEY",
|
|
||||||
"max_results": 5
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"gateway": {
|
|
||||||
"host": "0.0.0.0",
|
|
||||||
"port": 18790
|
|
||||||
}
|
|
||||||
}
|
|
||||||
Reference in New Issue
Block a user