mirror/nanobot
1
0
Fork 0
mirror of https://github.com/HKUDS/nanobot.git synced 2026-06-23 11:13:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify bwrap sandbox is Linux-only

Browse Source
This commit is contained in:
Xubin Ren 2026-04-05 19:28:46 +00:00
parent 9f96be6e9b
commit 9823130432
2 changed files with 22 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -1434,16 +1434,19 @@ MCP tools are automatically discovered and registered on startup. The LLM can us
### Security ### Security
> [!TIP] > [!TIP]
> For production deployments, set `"restrictToWorkspace": true` in your config to sandbox the agent. > For production deployments, set `"restrictToWorkspace": true` and `"tools.exec.sandbox": "bwrap"` in your config to sandbox the agent.
> In `v0.1.4.post3` and earlier, an empty `allowFrom` allowed all senders. Since `v0.1.4.post4`, empty `allowFrom` denies all access by default. To allow all senders, set `"allowFrom": ["*"]`. > In `v0.1.4.post3` and earlier, an empty `allowFrom` allowed all senders. Since `v0.1.4.post4`, empty `allowFrom` denies all access by default. To allow all senders, set `"allowFrom": ["*"]`.
| Option | Default | Description | | Option | Default | Description |
|--------|---------|-------------| |--------|---------|-------------|
| `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. | | `tools.restrictToWorkspace` | `false` | When `true`, restricts **all** agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access. |
| `tools.exec.sandbox` | `""` | Sandbox backend for shell commands. Set to `"bwrap"` to wrap exec calls in a [bubblewrap](https://github.com/containers/bubblewrap) sandbox — the process can only see the workspace (read-write) and media directory (read-only); config files and API keys are hidden. Automatically enables `restrictToWorkspace` for file tools. **Linux only** — requires `bwrap` installed (`apt install bubblewrap`; pre-installed in the Docker image). Not available on macOS or Windows (bwrap depends on Linux kernel namespaces). |
| `tools.exec.enable` | `true` | When `false`, the shell `exec` tool is not registered at all. Use this to completely disable shell command execution. | | `tools.exec.enable` | `true` | When `false`, the shell `exec` tool is not registered at all. Use this to completely disable shell command execution. |
| `tools.exec.pathAppend` | `""` | Extra directories to append to `PATH` when running shell commands (e.g. `/usr/sbin` for `ufw`). | | `tools.exec.pathAppend` | `""` | Extra directories to append to `PATH` when running shell commands (e.g. `/usr/sbin` for `ufw`). |
| `channels.*.allowFrom` | `[]` (deny all) | Whitelist of user IDs. Empty denies all; use `["*"]` to allow everyone. | | `channels.*.allowFrom` | `[]` (deny all) | Whitelist of user IDs. Empty denies all; use `["*"]` to allow everyone. |
**Docker security**: The official Docker image runs as a non-root user (`nanobot`, UID 1000) with bubblewrap pre-installed. When using `docker-compose.yml`, the container drops all Linux capabilities except `SYS_ADMIN` (required for bwrap's namespace isolation).
### Timezone ### Timezone

20
SECURITY.md
View File

@ -64,6 +64,7 @@ chmod 600 ~/.nanobot/config.json
The `exec` tool can execute shell commands. While dangerous command patterns are blocked, you should: The `exec` tool can execute shell commands. While dangerous command patterns are blocked, you should:
- ✅ **Enable the bwrap sandbox** (`"tools.exec.sandbox": "bwrap"`) for kernel-level isolation (Linux only)
- ✅ Review all tool usage in agent logs - ✅ Review all tool usage in agent logs
- ✅ Understand what commands the agent is running - ✅ Understand what commands the agent is running
- ✅ Use a dedicated user account with limited privileges - ✅ Use a dedicated user account with limited privileges
@ -71,6 +72,19 @@ The `exec` tool can execute shell commands. While dangerous command patterns are
- ❌ Don't disable security checks - ❌ Don't disable security checks
- ❌ Don't run on systems with sensitive data without careful review - ❌ Don't run on systems with sensitive data without careful review
**Exec sandbox (bwrap):**
On Linux, set `"tools.exec.sandbox": "bwrap"` to wrap every shell command in a [bubblewrap](https://github.com/containers/bubblewrap) sandbox. This uses Linux kernel namespaces to restrict what the process can see:
- Workspace directory → **read-write** (agent works normally)
- Media directory → **read-only** (can read uploaded attachments)
- System directories (`/usr`, `/bin`, `/lib`) → **read-only** (commands still work)
- Config files and API keys (`~/.nanobot/config.json`) → **hidden** (masked by tmpfs)
Requires `bwrap` installed (`apt install bubblewrap`). Pre-installed in the official Docker image. **Not available on macOS or Windows** — bubblewrap depends on Linux kernel namespaces.
Enabling the sandbox also automatically activates `restrictToWorkspace` for file tools.
**Blocked patterns:** **Blocked patterns:**
- `rm -rf /` - Root filesystem deletion - `rm -rf /` - Root filesystem deletion
- Fork bombs - Fork bombs
@ -82,6 +96,7 @@ The `exec` tool can execute shell commands. While dangerous command patterns are
File operations have path traversal protection, but: File operations have path traversal protection, but:
- ✅ Enable `restrictToWorkspace` or the bwrap sandbox to confine file access
- ✅ Run nanobot with a dedicated user account - ✅ Run nanobot with a dedicated user account
- ✅ Use filesystem permissions to protect sensitive directories - ✅ Use filesystem permissions to protect sensitive directories
- ✅ Regularly audit file operations in logs - ✅ Regularly audit file operations in logs
@ -232,7 +247,7 @@ If you suspect a security breach:
1. **No Rate Limiting** - Users can send unlimited messages (add your own if needed) 1. **No Rate Limiting** - Users can send unlimited messages (add your own if needed)
2. **Plain Text Config** - API keys stored in plain text (use keyring for production) 2. **Plain Text Config** - API keys stored in plain text (use keyring for production)
3. **No Session Management** - No automatic session expiry 3. **No Session Management** - No automatic session expiry
4. **Limited Command Filtering** - Only blocks obvious dangerous patterns 4. **Limited Command Filtering** - Only blocks obvious dangerous patterns (enable the bwrap sandbox for kernel-level isolation on Linux)
5. **No Audit Trail** - Limited security event logging (enhance as needed) 5. **No Audit Trail** - Limited security event logging (enhance as needed)
## Security Checklist ## Security Checklist
@ -243,6 +258,7 @@ Before deploying nanobot:
- [ ] Config file permissions set to 0600 - [ ] Config file permissions set to 0600
- [ ] `allowFrom` lists configured for all channels - [ ] `allowFrom` lists configured for all channels
- [ ] Running as non-root user - [ ] Running as non-root user
- [ ] Exec sandbox enabled (`"tools.exec.sandbox": "bwrap"`) on Linux deployments
- [ ] File system permissions properly restricted - [ ] File system permissions properly restricted
- [ ] Dependencies updated to latest secure versions - [ ] Dependencies updated to latest secure versions
- [ ] Logs monitored for security events - [ ] Logs monitored for security events
@ -252,7 +268,7 @@ Before deploying nanobot:
## Updates ## Updates
**Last Updated**: 2026-02-03 **Last Updated**: 2026-04-05
For the latest security updates and announcements, check: For the latest security updates and announcements, check:
- GitHub Security Advisories: https://github.com/HKUDS/nanobot/security/advisories - GitHub Security Advisories: https://github.com/HKUDS/nanobot/security/advisories