diff --git a/AGENTS.md b/AGENTS.md index db70013..eaf2f98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,7 +82,7 @@ For sequence diagrams and the full state machines, see [docs/ARCHITECTURE.md](do ## Security posture -- **Shell allowlist** — `run_command` accepts only allowlisted binaries (`git` is allowed but restricted via `DENIED_ARGS` to read-only subcommands — `status`/`diff`/`log`/`show`/`blame`/etc. — mutating subcommands like `push`/`commit`/`reset`/`checkout` are rejected). Pipelines and `&&` chains are allowed, but each segment is `shlex`-tokenised, its head must be in `ALLOWED_COMMANDS`, and per-command `DENIED_ARGS` / `DENIED_ARG_PREFIXES` block known escape hatches (`find -exec`/`-delete`, `sed -i`, `awk -f`/`-i`, `xargs`' inner command validated recursively, etc.). Output redirects to real files require an active workspace and must resolve inside it; input redirects, subshells, backticks, brace expansion, line continuations, and non-`\n` control characters are rejected. Once an interpreter is allowlisted, its sandbox is advisory by design. +- **Shell allowlist** — `run_command` accepts only allowlisted binaries (`git` is allowed but restricted via `DENIED_ARGS` to read-only subcommands — `status`/`diff`/`log`/`show`/`blame`/etc. — mutating subcommands like `push`/`commit`/`reset`/`checkout` are rejected; `docker` is gated by an explicit read-only subcommand allowlist — `ps`/`images`/`logs`/`inspect`/`system df`/`compose ps`/`buildx du`/etc. — with `run`/`exec`/`build`/`rm`/`prune`/`compose up` rejected; `php` is in the runtime set). Pipelines and `&&` chains are allowed, but each segment is `shlex`-tokenised, its head must be in `ALLOWED_COMMANDS`, and per-command `DENIED_ARGS` / `DENIED_ARG_PREFIXES` block known escape hatches (`find -exec`/`-delete`, `sed -i`, `awk -f`/`-i`, `docker compose config -o`, `xargs`' inner command validated recursively, etc.). Output redirects to real files require an active workspace and must resolve inside it; input redirects, subshells, backticks, brace expansion, line continuations, and non-`\n` control characters are rejected. Once an interpreter is allowlisted, its sandbox is advisory by design. - **SSRF protection** — `oli_bot/tools/web._check_ssrf` gates every outbound HTTP call (fetch, download, upload, search_github, extract_article, the URL branch of `view_image`, and the fixed Open Library endpoint). Non-`http(s)` schemes refused; loopback, link-local (including cloud-metadata `169.254.169.254`), private (RFC 1918), reserved, multicast, and unspecified addresses rejected after DNS resolution. - **Sensitive-file gating** — `Session.needs_permission` requires approval for `read_file` on `.env*`, `.ssh/`, `.aws/`, `*.pem/.key/.crt`, and the other patterns in `_SENSITIVE_FILE_NAMES` / `_SENSITIVE_PATH_COMPONENTS`. Sensitive `glob`/`grep` patterns escalate to the `workspace_sensitive` scope. - **Offline mode** — enabled by default; blocks web tools and MCP HTTP transports. diff --git a/README.md b/README.md index 0e801bd..221669e 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ A lightweight, terminal-based AI agent harness for local-first, vendor-agnostic - **Declarative sub-agent pooling (optional)** — with `--use-pool`, the root agent can fan tasks out concurrently to vendor-agnostic sub-agents defined in an optional [agents.yaml](agents.yaml) file via a `dispatch` tool. Each pool entry binds a model _and_ a backend, so dispatch decisions are also compute-location decisions — a frontier model can plan while sensitive work stays on a local model, or a local root can fan out to faster remote SLMs for latency-sensitive tool calls. - **Agent profiles** — drop-in system prompts with permission manifests, base-profile inheritance, and auto-generated profiles via `/profile create`. Bundled profiles: `default`, `coder`, `reviewer`, `editor`, `writer`, `planner`, `researcher`, `analyst`. -- **Rich built-in tool set** — file ops, shell access, web search/fetch, Wikipedia/GitHub/arXiv search, task tracking, reasoning scratchpad, notebook, interactive user-question modals, and more. Sandbox-locked with shell allowlists, SSRF protection, and sensitive-file gating. +- **Rich built-in tool set** — file ops, shell access (including PHP and read-only Docker inspection), web search/fetch, Wikipedia/GitHub/arXiv search, task tracking, reasoning scratchpad, notebook, interactive user-question modals, and more. Sandbox-locked with shell allowlists, SSRF protection, and sensitive-file gating. - **Permission system** — write operations and sensitive reads require user approval. Session grants, workspace scoping, and profile-level allow/deny lists. - **OpenAI-compatible API server** — run the same agent harness behind `/v1/models` and `/v1/chat/completions` (streaming + non-streaming) so any workflow that speaks the OpenAI wire protocol (the `openai` Python SDK, curl, or plain REST) can drive the agent. - **Voice mode (optional, experimental)** — `/voice` toggles a hands-free mic → STT → LLM → TTS loop (faster-whisper, Piper TTS, WebRTC VAD) for the TUI. Fully local; requires the `voice` extras and a downloaded Piper model. diff --git a/docs/SECURITY.md b/docs/SECURITY.md index e76281e..b6c7b3d 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -60,7 +60,7 @@ This manifest is evaluated independently of, and prior to, the runtime prompt ti `run_command` is the highest-risk built-in tool, and has the most layered set of defenses. -**Allowlist composition.** Only binaries present in `ALLOWED_COMMANDS` may run at all. This set is a union of grouped frozensets (`_ALLOWED_FILESYSTEM_READ`, `_ALLOWED_TEXT_SEARCH`, `_ALLOWED_TEXT_PROCESSING`, `_ALLOWED_ENCODING_COMPRESSION`, `_ALLOWED_UTILITIES`, `_ALLOWED_SYSTEM_INFO`, `_ALLOWED_RUNTIME_COMMANDS`, `_ALLOWED_VCS`) defined in `tools/shell.py`. Broadly: read-only filesystem/text utilities, common language runtimes (Python, Node, Ruby, Go, Rust, Deno, Bun, Perl, Lua, and their package managers), and read-only Git. +**Allowlist composition.** Only binaries present in `ALLOWED_COMMANDS` may run at all. This set is a union of grouped frozensets (`_ALLOWED_FILESYSTEM_READ`, `_ALLOWED_TEXT_SEARCH`, `_ALLOWED_TEXT_PROCESSING`, `_ALLOWED_ENCODING_COMPRESSION`, `_ALLOWED_UTILITIES`, `_ALLOWED_SYSTEM_INFO`, `_ALLOWED_RUNTIME_COMMANDS`, `_ALLOWED_VCS`, `_ALLOWED_CONTAINERS`) defined in `tools/shell.py`. Broadly: read-only filesystem/text utilities, common language runtimes (Python, Node, Ruby, Go, Rust, Deno, Bun, Perl, Lua, PHP, and their package managers), read-only Git, and read-only Docker inspection. **Command composition is validated per-segment, not as a whole string.** Pipes (`|`) and logical operators (`&&`, `||`, `;`) are permitted specifically because each segment on either side is independently checked against the allowlist. `grep pattern file | head -20` passes because both halves are allowed; `grep pattern file | rm -rf /` fails because `rm` is not in the allowlist, regardless of what it's piped from. @@ -68,7 +68,9 @@ This manifest is evaluated independently of, and prior to, the runtime prompt ti **Git is allowed, but read-only.** Inspection subcommands (`status`, `diff`, `log`, `show`, `blame`, etc.) are permitted. Mutating subcommands (`push`, `pull`, `commit`, `reset`, `checkout`, `clean`, `rebase`, `merge`, etc.) are blocked via `DENIED_ARGS`. -**Denylisted escape hatches on otherwise-safe binaries.** Certain flags are blocked even on allowlisted commands because they turn a read-only tool into a write primitive: `find -exec`, `find -delete`, `find -execdir`, `-fprint*`, `-ok*`, `sed -i` / `sed -i.bak`, `awk -f`, `awk -i` / `--in-place=` (and gawk/nawk equivalents). +**Docker is allowed, but only through an explicit read-only subcommand allowlist.** Unlike Git's denylist, Docker uses a fail-closed set of permitted command paths (`ps`, `images`, `logs`, `inspect`, `stats`, `history`, `diff`, `top`, `port`, `version`, `info`, `search`, `system df`/`info`, `image`/`container`/`volume`/`network`/`context` `ls`/`inspect`, `manifest inspect`, `compose ps`/`logs`/`config`/`images`/`version`/`ls`/`top`, and `buildx ls`/`inspect`/`du`). Global docker flags (`--context`, `-H`, `--config`, `-D`, `--tls*`, etc.) and common Compose flags (`-f`, `-p`, `--env-file`, `--profile`, etc.) are skipped before matching. Anything not listed is rejected, including `run`, `exec`, `build`, `rm`, `prune`, `cp`, `save`, `push`, `pull`, `compose up`/`down`/`run`, and `buildx build`. Docker's argument denylist also blocks `compose config -o`/`--output` (file write) and `buildx inspect --bootstrap` (builder creation). + +**Denylisted escape hatches on otherwise-safe binaries.** Certain flags are blocked even on allowlisted commands because they turn a read-only tool into a write primitive: `find -exec`, `find -delete`, `find -execdir`, `-fprint*`, `-ok*`, `sed -i` / `sed -i.bak`, `awk -f`, `awk -i` / `--in-place=` (and gawk/nawk equivalents), `docker compose config -o`/`--output`, and `docker buildx inspect --bootstrap`. **Metacharacter and redirect blocking.** `$`, `` ` ``, `()`, `{}`, `!`, input redirects (`<`), and line-continuations are rejected outright, as are control characters. Output redirects (`>`, `>>`) to real files are permitted _only_ when a workspace is configured and the resolved target path falls inside it; writes to `/dev/null`, `/dev/stderr`, `/dev/stdout` and stderr fd duplication (`2>&1`, `2>&-`) are always allowed regardless of workspace state. Any other real-file redirect attempt is rejected with guidance to use `tee` instead. diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 86e7790..262ba59 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -10,7 +10,7 @@ All built-in tools are exposed to the model as `builtin__`. | **view_image** | Load an image from a local path or `http(s)` URL and attach it for visual analysis. Uses Pillow to sniff the format, downscale to `max_edge_px` (default 1568), and re-encode. The image reaches the model as vision input on Ollama vision models and OpenAI (`gpt-4o` etc.); on text-only backends the follow-up user message carries a bracketed placeholder describing the attachment. Optional `question` seeds the caption on the synthetic user message. Rejects files over 20 MB and non-image `Content-Type` on URL fetches. Local paths follow the same workspace gating as `read_file`; URL fetches are blocked by offline mode and always pass through the SSRF guard. | | **write_file** | Create or overwrite files (up to 100k chars), auto-creates parent directories. | | **edit_file** | Surgical find-and-replace on existing files; rejects ambiguous multi-matches. | -| **run_command** | Execute shell commands from a grouped allowlist. Read-only utilities (grep/rg/ag, sed, awk, xargs, jq/yq, tee, find, ls, cat, head/tail, wc, sort, uniq, sha\*sum, base64) plus language runtimes (python/python3/pytest, node/npm/npx, ruby, go, cargo/rustc, deno, bun, perl, lua, pip/uv/poetry/pipx). Pipes (`\|`) and logical operators (`&&`, `\|\|`) are **allowed and safe** — each piped command is independently validated. Output redirects (`>`, `>>`) to real files are permitted only when a workspace is set and the target resolves inside it; stderr fd duplication (`2>&1`, `2>&-`) and writes to `/dev/null`, `/dev/stderr`, `/dev/stdout` are always allowed. `xargs`' inner command is validated recursively against the allowlist so `xargs rm` still fails. `git` is allowed for read-only inspection (`status`/`diff`/`log`/`show`/`blame`/etc.) but mutating subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.) are blocked via `DENIED_ARGS`. Per-command `DENIED_ARGS` / `DENIED_ARG_PREFIXES` also block escape hatches (`find -exec`/`-delete`, `sed -i`, `awk -f`/`-i`). Input redirects (`<`), subshells, backticks, unquoted `{}`, and line-continuations are rejected. Use the `workdir` parameter to change directory — `cd` does not persist across invocations. | +| **run_command** | Execute shell commands from a grouped allowlist. Read-only utilities (grep/rg/ag, sed, awk, xargs, jq/yq, tee, find, ls, cat, head/tail, wc, sort, uniq, sha\*sum, base64) plus language runtimes (python/python3/pytest, node/npm/npx, ruby, go, cargo/rustc, deno, bun, perl, lua, php, pip/uv/poetry/pipx). `docker` is restricted to an explicit read-only subcommand allowlist (`ps`, `images`, `logs`, `inspect`, `stats`, `system df`, `image`/`container`/`volume`/`network`/`context` `ls`/`inspect`, `compose ps`/`logs`/`config`/`images`/`version`, `buildx ls`/`inspect`/`du`); mutating subcommands (`run`/`exec`/`build`/`rm`/`prune`/`compose up`/etc.) are rejected, as are `compose config -o` and `buildx inspect --bootstrap`. Pipes (`\|`) and logical operators (`&&`, `\|\|`) are **allowed and safe** — each piped command is independently validated. Output redirects (`>`, `>>`) to real files are permitted only when a workspace is set and the target resolves inside it; stderr fd duplication (`2>&1`, `2>&-`) and writes to `/dev/null`, `/dev/stderr`, `/dev/stdout` are always allowed. `xargs`' inner command is validated recursively against the allowlist so `xargs rm` still fails. `git` is allowed for read-only inspection (`status`/`diff`/`log`/`show`/`blame`/etc.) but mutating subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.) are blocked via `DENIED_ARGS`. Per-command `DENIED_ARGS` / `DENIED_ARG_PREFIXES` also block escape hatches (`find -exec`/`-delete`, `sed -i`, `awk -f`/`-i`). Input redirects (`<`), subshells, backticks, unquoted `{}`, and line-continuations are rejected. Use the `workdir` parameter to change directory — `cd` does not persist across invocations. | | **glob** | Recursive file search by glob pattern (e.g. `**/*.py`, `*.json`), capped at 200 results. | | **grep** | Regex content search with optional `include` file filter, returns `file:line:match`, capped at 50 results. | | **list_directory** | Structured directory listing with type, modification time, and size; dirs-first sort. | @@ -49,7 +49,7 @@ Each permission prompt offers three choices: **Allow once**, **Allow for session oli defends against malicious or confused agents exfiltrating secrets or reaching internal infrastructure: -- **Shell allowlist** -- `run_command` only executes binaries in `ALLOWED_COMMANDS`, composed by unioning grouped frozensets (`_ALLOWED_FILESYSTEM_READ`, `_ALLOWED_TEXT_SEARCH`, `_ALLOWED_TEXT_PROCESSING`, `_ALLOWED_ENCODING_COMPRESSION`, `_ALLOWED_UTILITIES`, `_ALLOWED_SYSTEM_INFO`, `_ALLOWED_RUNTIME_COMMANDS`, `_ALLOWED_VCS`) in `tools/shell.py`. Pipes (`|`) and logical operators (`&&`, `||`, `;`) are allowed and safe because each segment is independently validated. `xargs` is allowlisted but its **inner** command is validated recursively — `xargs rm` still fails. `git` is allowed but restricted via `DENIED_ARGS` to read-only subcommands (`status`/`diff`/`log`/`show`/`blame`/etc.) -- mutating subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.) are rejected. Once an interpreter is allowlisted, the sandbox for that binary is advisory — `python -c '…'`, `node -e '…'`, `pytest` fixtures etc. can execute arbitrary code by design. +- **Shell allowlist** -- `run_command` only executes binaries in `ALLOWED_COMMANDS`, composed by unioning grouped frozensets (`_ALLOWED_FILESYSTEM_READ`, `_ALLOWED_TEXT_SEARCH`, `_ALLOWED_TEXT_PROCESSING`, `_ALLOWED_ENCODING_COMPRESSION`, `_ALLOWED_UTILITIES`, `_ALLOWED_SYSTEM_INFO`, `_ALLOWED_RUNTIME_COMMANDS`, `_ALLOWED_VCS`, `_ALLOWED_CONTAINERS`) in `tools/shell.py`. Pipes (`|`) and logical operators (`&&`, `||`, `;`) are allowed and safe because each segment is independently validated. `xargs` is allowlisted but its **inner** command is validated recursively — `xargs rm` still fails. `git` is allowed but restricted via `DENIED_ARGS` to read-only subcommands (`status`/`diff`/`log`/`show`/`blame`/etc.) -- mutating subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.) are rejected. `docker` is gated by an explicit read-only **subcommand allowlist** (fail-closed): `ps`, `images`, `logs`, `inspect`, `stats`, `history`, `diff`, `top`, `port`, `version`, `info`, `search`, `system df`/`info`, `image`/`container`/`volume`/`network`/`context` `ls`/`inspect`, `manifest inspect`, `compose ps`/`logs`/`config`/`images`/`version`/`ls`/`top`, and `buildx ls`/`inspect`/`du`. Global docker/compose flags are skipped before matching; unlisted subcommands (`run`/`exec`/`build`/`rm`/`prune`/`save`/`push`/`pull`/`compose up`/`down`/`run`/`buildx build`/etc.) are rejected, as are the write escapes `compose config -o`/`--output` and `buildx inspect --bootstrap`. Runtimes include `php`. Once an interpreter is allowlisted, the sandbox for that binary is advisory — `python -c '…'`, `node -e '…'`, `php -r '…'`, `pytest` fixtures etc. can execute arbitrary code by design. - **Argument denylist** -- known escape hatches on otherwise-safe binaries are rejected (`find -exec`, `find -delete`, `find -execdir`, `-fprint*`, `-ok*`, `sed -i` / `sed -i.bak`, `awk -f`, `awk -i` / `--in-place=`, plus gawk/nawk equivalents). - **Shell metacharacter blocking** -- dangerous characters (`$`, `` ` ``, `()`, `{}`, `!`), input redirects (`<`), and line-continuations (`\` + newline) are rejected. Control characters are also blocked. Output redirects (`>`, `>>`) to real files are permitted only when a workspace is set (`/workspace set`) **and** the target path resolves inside it; fd duplication (`2>&1`, `2>&-`) and writes to `/dev/null`/`/dev/stderr`/`/dev/stdout` are always allowed. Otherwise real-file redirects are rejected with guidance to use `tee`. - **SSRF guard** -- `_check_ssrf` in `tools/web.py` inspects every outbound URL reachable from user input (`fetch`, `download_file`, `upload_file`, `search_github`, `extract_article`, `view_image` URL branch, and the fixed Open Library endpoint). Non-`http(s)` schemes are refused; hostnames are resolved and any address that is loopback, link-local (incl. `169.254.169.254`), private (RFC 1918), reserved, multicast, or unspecified is blocked. diff --git a/oli_bot/profiles/default/AGENTS.md b/oli_bot/profiles/default/AGENTS.md index 74bd46a..ff58145 100644 --- a/oli_bot/profiles/default/AGENTS.md +++ b/oli_bot/profiles/default/AGENTS.md @@ -14,7 +14,7 @@ All built-in tools are called via `builtin__`. | `builtin__edit_file` | `file_path: string`, `old_string: string`, `new_string: string` | **always requires permission** | Find-and-replace edit (first match only; include surrounding context if ambiguous) | | `builtin__download_file` | `url: string`, `file_path: string` | **always requires permission** | Download a file from a URL and save it locally | | `builtin__upload_file` | `url: string`, `file_path: string`, `method?: string`, `field_name?: string` | **always requires permission** | Upload a local file to an external server via HTTP PUT/POST | -| `builtin__run_command` | `command: string`, `timeout?: number` (default 30), `workdir?: string` | same as read tools | Run allowlisted shell commands + language runtimes (python, node, pytest, ...) with pipes (`\|`) and logical operators (`&&`, `\|\|`) supported. Dangerous metacharacters ($, `, (), {}, !) blocked — even inside double quotes. | +| `builtin__run_command` | `command: string`, `timeout?: number` (default 30), `workdir?: string` | same as read tools | Run allowlisted shell commands + language runtimes (python, node, php, pytest, ...) plus read-only Docker inspection (`docker ps`, `docker logs`, `docker inspect`, `docker compose ps`, `docker buildx du`, ...) with pipes (`\|`) and logical operators (`&&`, `\|\|`) supported. Dangerous metacharacters ($, `, (), {}, !) blocked — even inside double quotes. | | `builtin__glob` | `pattern: string`, `path?: string` | same as read tools | Recursive file search by glob pattern (e.g. `**/*.py`, `src/**/*.ts`) | | `builtin__grep` | `pattern: string`, `path?: string`, `include?: string`, `max_results?: number` (default 50) | same as read tools | Regex content search across files with line numbers | | `builtin__list_directory` | `path?: string`, `show_hidden?: boolean` | same as read tools | Directory listing with metadata (type, mtime, size) | @@ -50,9 +50,15 @@ All built-in tools are called via `builtin__`. - **Encoding & compression (`_ALLOWED_ENCODING_COMPRESSION`):** `md5sum`, `sha1sum`, `sha256sum`, `sha512sum`, `shasum`, `b2sum`, `base64`, `zcat`, `gzcat`, `bzcat`, `xzcat`, `zgrep`, `zless` - **Utilities (`_ALLOWED_UTILITIES`):** `echo`, `printf`, `seq`, `date`, `cal`, `expr`, `which`, `getconf`, `whatis`, `apropos`, `tput`, `stty`, `tty` - **System info (`_ALLOWED_SYSTEM_INFO`):** `ps`, `top`, `htop`, `pgrep`, `uname`, `hostname`, `whoami`, `id`, `groups`, `who`, `w`, `uptime`, `free`, `lsblk`, `lscpu`, `lsmem`, `nproc`, `arch`, `ss`, `netstat` -- **Language runtimes (`_ALLOWED_RUNTIME_COMMANDS`):** `python`, `python3`, `pytest`, `node`, `npm`, `npx`, `ruby`, `go`, `cargo`, `rustc`, `deno`, `bun`, `perl`, `lua`, `pip`, `pip3`, `uv`, `poetry`, `pipx` +- **Language runtimes (`_ALLOWED_RUNTIME_COMMANDS`):** `python`, `python3`, `pytest`, `node`, `npm`, `npx`, `ruby`, `go`, `cargo`, `rustc`, `deno`, `bun`, `perl`, `lua`, `php`, `pip`, `pip3`, `uv`, `poetry`, `pipx` +- **Version control (`_ALLOWED_VCS`):** `git` (read-only subcommands only — mutating verbs are blocked) +- **Containers (`_ALLOWED_CONTAINERS`):** `docker` (read-only subcommands only — see below) -Runtimes are provided so you can run tests and scripts (`python -m pytest tests/`, `pytest -q`, `node script.js`). Once an interpreter is allowlisted, the sandbox for that binary is advisory — `python -c '…'`, `node -e '…'` and pytest fixtures can execute arbitrary code by design. +Runtimes are provided so you can run tests and scripts (`python -m pytest tests/`, `pytest -q`, `node script.js`, `php script.php`). Once an interpreter is allowlisted, the sandbox for that binary is advisory — `python -c '…'`, `node -e '…'`, `php -r '…'` and pytest fixtures can execute arbitrary code by design. + +### Docker (read-only) + +`docker` uses an explicit, fail-closed subcommand allowlist — anything not listed is rejected. Allowed: `ps`, `images`, `logs`, `inspect`, `stats`, `history`, `diff`, `top`, `port`, `version`, `info`, `search`, `system df`/`info`, `image`/`container`/`volume`/`network`/`context` `ls`/`inspect`, `manifest inspect`, `compose ps`/`logs`/`config`/`images`/`version`/`ls`/`top`, and `buildx ls`/`inspect`/`du`. Global docker flags (`--context`, `-H`, `--config`, `--tls*`, ...) and common Compose flags (`-f`, `-p`, `--env-file`, `--profile`, ...) may precede the subcommand. Mutating subcommands (`run`, `exec`, `build`, `rm`, `prune`, `cp`, `save`, `push`, `pull`, `compose up`/`down`/`run`, `buildx build`, etc.) are rejected, as are `compose config -o`/`--output` and `buildx inspect --bootstrap`. Use the `workdir` parameter to change directory. `cd` does not persist since each command runs in a fresh subshell. @@ -90,7 +96,13 @@ Example safe commands: - ✓ `grep pattern file && echo "Found"` — conditional execution - ✓ `pytest tests/ -q 2>&1 | tail -20` — run tests with stderr merged - ✓ `python -m pytest tests/test_security.py` — run a single test file +- ✓ `php script.php` — run a PHP script +- ✓ `docker ps -a` — list all containers +- ✓ `docker compose ps && docker compose logs --tail 20` — inspect a Compose project +- ✓ `docker inspect web | jq '.[0].State.Status'` — inspect container state - ✗ `cat file | rm -rf /` — rm not allowlisted +- ✗ `docker run --rm alpine` — mutating Docker subcommand +- ✗ `docker compose up -d` — mutating Compose subcommand - ✗ `echo $(whoami)` — command substitution blocked ## MCP server tools diff --git a/oli_bot/profiles/default/SKILLS.md b/oli_bot/profiles/default/SKILLS.md index 00c4466..8e80f01 100644 --- a/oli_bot/profiles/default/SKILLS.md +++ b/oli_bot/profiles/default/SKILLS.md @@ -12,7 +12,7 @@ | Analyze an image | `builtin__view_image` | Accepts a local path or `http(s)` URL. On vision-capable models (Ollama `llava`/`llama3.2-vision`/`qwen2-vl`, OpenAI `gpt-4o`, etc.) the actual image is attached and the model can describe it. On text-only backends the tool result plus a bracketed text placeholder still lets you reason about the file. Pass `question` to prime the vision model. URL fetches are blocked when offline mode is on and always go through SSRF checks. | | Edit existing files | `builtin__edit_file` | Surgical find-replace. **Always requires permission.** Prefer over write_file. | | Create/overwrite files | `builtin__write_file` | **Always requires permission.** Creates parent dirs. | -| Run CLI checks | `builtin__run_command` | Workspace-gated (same as read tools). Allowlist covers read-only utilities (`grep`/`rg`/`ag`, `sed`, `awk`, `xargs`, `jq`/`yq`, `tee`, `find`, `ls`, `cat`, `head`/`tail`, `wc`, `sort`, `uniq`, `sha*sum`, `base64`), `git` (read-only subcommands only — `status`/`diff`/`log`/`show`/`blame`/etc.), and language runtimes (`python`/`python3`/`pytest`, `node`/`npm`/`npx`, `ruby`, `go`, `cargo`/`rustc`, `deno`, `bun`, `perl`, `lua`, plus `pip`/`uv`/`poetry`/`pipx`). Compose with pipes (`\|`) and `&&`/`\|\|`; e.g. `pytest tests/ -q 2>&1 \| tail -20`, `grep -rn TODO src/ \| head -20`, `find . -name '*.py' \| xargs grep -l TODO`, `cat data.json \| jq '.items[].name'`. Use the `workdir` parameter to change directory (`cd` does not persist across invocations). File redirects (`>`, `>>`) work only when a workspace is set (`/workspace set`) and the target resolves inside it; stderr fd duplication (`2>&1`, `2>&-`) and writes to `/dev/null`/`/dev/stderr`/`/dev/stdout` are always allowed. Blocked: shell expansion (`$`, backticks, `{}`, `!`) even inside double quotes, `sed -i`, `awk -f`, `find -exec`, subshells, and mutating `git` subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.). Quote `xargs -I` placeholders: `xargs -I '{}' cat '{}'`. | +| Run CLI checks | `builtin__run_command` | Workspace-gated (same as read tools). Allowlist covers read-only utilities (`grep`/`rg`/`ag`, `sed`, `awk`, `xargs`, `jq`/`yq`, `tee`, `find`, `ls`, `cat`, `head`/`tail`, `wc`, `sort`, `uniq`, `sha*sum`, `base64`), `git` (read-only subcommands only — `status`/`diff`/`log`/`show`/`blame`/etc.), and language runtimes (`python`/`python3`/`pytest`, `node`/`npm`/`npx`, `ruby`, `go`, `cargo`/`rustc`, `deno`, `bun`, `perl`, `lua`, `php`, plus `pip`/`uv`/`poetry`/`pipx`), and read-only Docker inspection (`docker ps`/`images`/`logs`/`inspect`/`stats`/`system df`, `docker image`/`container`/`volume`/`network`/`context` `ls`/`inspect`, `docker compose ps`/`logs`/`config`/`images`/`version`, `docker buildx ls`/`inspect`/`du`). Compose with pipes (`\|`) and `&&`/`\|\|`; e.g. `pytest tests/ -q 2>&1 \| tail -20`, `grep -rn TODO src/ \| head -20`, `find . -name '*.py' \| xargs grep -l TODO`, `cat data.json \| jq '.items[].name'`. Use the `workdir` parameter to change directory (`cd` does not persist across invocations). File redirects (`>`, `>>`) work only when a workspace is set (`/workspace set`) and the target resolves inside it; stderr fd duplication (`2>&1`, `2>&-`) and writes to `/dev/null`/`/dev/stderr`/`/dev/stdout` are always allowed. Blocked: shell expansion (`$`, backticks, `{}`, `!`) even inside double quotes, `sed -i`, `awk -f`, `find -exec`, subshells, mutating `git` subcommands (`push`/`pull`/`commit`/`reset`/`checkout`/`clean`/`rebase`/`merge`/etc.), and non-read-only Docker subcommands (`run`/`exec`/`build`/`rm`/`prune`/`compose up`/`buildx build`/etc.). Quote `xargs -I` placeholders: `xargs -I '{}' cat '{}'`. | | General web research | `builtin__websearch`, `builtin__fetch` | No permission needed. Fetch extracts page content as Markdown; websearch for finding pages. | | Wikipedia research | `builtin__search_wikipedia` | Targeted Wikipedia lookups. Returns article titles, URLs, and summaries. | | Repository discovery | `builtin__search_github` | Find repos by topic/name with stars, language, description. | diff --git a/oli_bot/tools/shell.py b/oli_bot/tools/shell.py index a46abda..f31386c 100644 --- a/oli_bot/tools/shell.py +++ b/oli_bot/tools/shell.py @@ -41,6 +41,10 @@ # Read-only VCS inspection. Mutating subcommands are blocked via DENIED_ARGS below. _ALLOWED_VCS: frozenset[str] = frozenset({"git"}) +# Container inspection. Only explicitly allowlisted read-only subcommand paths +# may run — see _DOCKER_READ_ONLY_SUBCOMMANDS. +_ALLOWED_CONTAINERS: frozenset[str] = frozenset({"docker"}) + # Text/data manipulation. In-place edit flags are blocked in DENIED_ARGS. _ALLOWED_TEXT_PROCESSING: frozenset[str] = frozenset( { @@ -155,6 +159,7 @@ "bun", "perl", "lua", + "php", "pip", "pip3", "uv", @@ -169,6 +174,89 @@ {"-n", "-P", "-I", "-i", "-L", "-s", "-E", "-d", "-a", "-J", "-R", "-S"} ) +# Docker global flags that consume a value. _docker_command_path skips these +# (and their value) so ``docker --context prod ps`` resolves to ``ps``. +_DOCKER_GLOBAL_VALUE_FLAGS: frozenset[str] = frozenset( + { + "--config", + "-c", + "--context", + "-H", + "--host", + "-l", + "--log-level", + "--tlscacert", + "--tlscert", + "--tlskey", + } +) + +# Compose global flags that consume a value, handled after the ``compose`` verb. +_COMPOSE_GLOBAL_VALUE_FLAGS: frozenset[str] = frozenset( + { + "-f", + "--file", + "-p", + "--project-name", + "--env-file", + "--profile", + "--project-directory", + "--ansi", + "--progress", + "--parallel", + } +) + +# Read-only docker subcommand paths. Nested groups (image/container/...) are +# listed explicitly so a mutating sibling such as ``image rm`` is rejected. +# Matching is longest-path-first, and fail-closed for anything unlisted. +_DOCKER_READ_ONLY_SUBCOMMANDS: frozenset[str] = frozenset( + { + "ps", + "images", + "logs", + "inspect", + "version", + "info", + "stats", + "top", + "port", + "diff", + "history", + "search", + "system df", + "system info", + "image ls", + "image inspect", + "image history", + "container ls", + "container inspect", + "container logs", + "container stats", + "container top", + "container port", + "container diff", + "volume ls", + "volume inspect", + "network ls", + "network inspect", + "context ls", + "context inspect", + "context show", + "manifest inspect", + "compose ps", + "compose logs", + "compose config", + "compose images", + "compose version", + "compose ls", + "compose top", + "buildx ls", + "buildx inspect", + "buildx du", + } +) + ALLOWED_COMMANDS: frozenset[str] = ( _ALLOWED_FILESYSTEM_READ @@ -179,6 +267,7 @@ | _ALLOWED_SYSTEM_INFO | _ALLOWED_RUNTIME_COMMANDS | _ALLOWED_VCS + | _ALLOWED_CONTAINERS ) # Per-command argument denylist. Any occurrence of a denied argument in the @@ -235,6 +324,9 @@ "init", "clone", ), + # ``compose config -o`` writes a file and ``buildx inspect --bootstrap`` + # can create/start a builder; both escape the read-only subcommand set. + "docker": ("-o", "--output", "--bootstrap"), } # Commands whose in-place edit or scripting flags have a prefix form we must @@ -245,6 +337,8 @@ "awk": ("--in-place=",), "gawk": ("--in-place=",), "nawk": ("--in-place=",), + # pflag accepts attached shorthand values (``-oFILE``) as well as ``-o``. + "docker": ("-o", "--output="), } # Characters that must never appear anywhere in the raw command string, quoted @@ -288,8 +382,8 @@ async def run_command_handler(command, timeout=30, workdir=None): "head, tail, wc, sort, uniq, cut, tr, ps, df, du, diff, file, stat, sha*sum, " "base64, echo, pwd. " "Language runtimes: python/python3/pytest, node/npm/npx, ruby, go, cargo/rustc, " - "deno, bun, perl, lua, plus pip/pip3/uv/poetry/pipx — e.g. `python -m pytest tests/`, " - "`pytest -q`, `node script.js`. " + "deno, bun, perl, lua, php, plus pip/pip3/uv/poetry/pipx — e.g. `python -m pytest tests/`, " + "`pytest -q`, `node script.js`, `php script.php`. " "Pipes (|) and logical operators (&&, ||) are allowed and encouraged: " "e.g. `grep -rn TODO src/ | head -20`, `find . -name '*.py' | xargs grep -l TODO`, " "`cat data.json | jq '.items[].name'`. " @@ -305,6 +399,12 @@ async def run_command_handler(command, timeout=30, workdir=None): "restore, clean, rebase, merge, cherry-pick, revert, add, rm, mv, stash, tag, " "branch, remote, config, submodule, apply, am, gc, reflog, worktree, init, clone) " "are blocked. " + "`docker` is allowed for read-only inspection only — ps, images, logs, inspect, " + "stats, history, diff, top, port, version, info, search, system df/info, " + "image/container/volume/network/context ls/inspect, manifest inspect, " + "compose ps/logs/config/images/version/ls/top, and buildx ls/inspect/du. " + "Mutating Docker subcommands (run, exec, build, rm, prune, cp, save, push, " + "pull, compose up/down/run, buildx build, etc.) are rejected. " "Blocked: input redirects (<), subshells `()`, and shell expansion " "(`$`, backticks, `$()`, `${...}`, `{}`, `!`) — including when the " "expansion is wrapped in double quotes — plus sed/awk in-place edit " @@ -451,6 +551,55 @@ def _tokenize_with_redirects(segment: str) -> list[str]: return list(lexer) +def _skip_flags(args: list[str], value_flags: frozenset[str]) -> int: + """Return the index of the first non-flag token, skipping known flags.""" + i = 0 + while i < len(args): + arg = args[i] + if arg == "--": + return i + 1 + if arg in value_flags: + i += 2 + continue + if arg.startswith("--") and "=" in arg: + i += 1 + continue + if arg.startswith("-") and arg != "-": + i += 1 + continue + return i + return i + + +def _docker_command_path(args: list[str]) -> list[str]: + """Extract the docker subcommand path, stripping global flags.""" + idx = _skip_flags(args, _DOCKER_GLOBAL_VALUE_FLAGS) + rest = args[idx:] + if rest and rest[0] == "compose": + sub_idx = _skip_flags(rest[1:], _COMPOSE_GLOBAL_VALUE_FLAGS) + return ["compose", *rest[1 + sub_idx :]] + return rest + + +def _check_docker_argv(args: list[str]) -> Optional[str]: + """Reject docker invocations that are not in the read-only subcommand set.""" + path = _docker_command_path(args) + if not path: + if any(arg in ("--version", "-v") for arg in args): + return None + return "Error: Docker requires an explicit read-only subcommand." + + if len(path) >= 2: + two = f"{path[0]} {path[1]}" + if two in _DOCKER_READ_ONLY_SUBCOMMANDS: + return None + if path[0] in _DOCKER_READ_ONLY_SUBCOMMANDS: + return None + + label = " ".join(path[:2]) if len(path) >= 2 else path[0] + return f"Error: Docker subcommand '{label}' is not read-only." + + def _check_command_argv(tokens: list[str]) -> Optional[str]: """Validate the argv of a single command (no redirects) against the allowlist. @@ -483,6 +632,11 @@ def _check_command_argv(tokens: list[str]) -> Optional[str]: f"(escape-hatch protection)." ) + if base == "docker": + err = _check_docker_argv(tokens[1:]) + if err is not None: + return err + if base == "xargs": inner = _extract_xargs_inner_command(tokens[1:]) if inner is not None: diff --git a/tests/unit/test_security.py b/tests/unit/test_security.py index 74c024c..06a1435 100644 --- a/tests/unit/test_security.py +++ b/tests/unit/test_security.py @@ -459,3 +459,130 @@ def test_shell_allows_double_quoted_paren_content(): # `python -c "print(1)"` / awk patterns. Must stay allowed. assert _is_command_allowed('python -c "print(1)"') is None assert _is_command_allowed('python3 -c "import json; d=(1,2); print(d)"') is None + + +# --------------------------------------------------------------------------- # +# PHP runtime # +# --------------------------------------------------------------------------- # + + +def test_shell_allows_php_runtime(): + assert _is_command_allowed("php -v") is None + assert _is_command_allowed("php script.php") is None + # Once an interpreter is allowlisted the sandbox is advisory by design. + assert _is_command_allowed("php -r 'echo 1;'") is None + + +# --------------------------------------------------------------------------- # +# Docker read-only subcommands # +# --------------------------------------------------------------------------- # + + +def test_docker_read_only_subcommands_are_allowed(): + allowed = [ + "docker ps", + "docker ps -a --no-trunc", + "docker images", + "docker logs web", + "docker inspect web", + "docker stats --no-stream", + "docker history web", + "docker diff web", + "docker top web", + "docker port web", + "docker version", + "docker info", + "docker search alpine", + "docker system df", + "docker system info", + "docker image ls", + "docker image inspect alpine", + "docker container inspect web", + "docker volume ls", + "docker network inspect bridge", + "docker context show", + "docker manifest inspect alpine", + "docker compose ps", + "docker compose logs", + "docker compose config", + "docker compose images", + "docker compose version", + "docker compose ls", + "docker compose top", + "docker buildx ls", + "docker buildx inspect", + "docker buildx du", + ] + for cmd in allowed: + assert _is_command_allowed(cmd) is None, cmd + + +def test_docker_global_and_compose_flags_are_skipped(): + assert _is_command_allowed("docker --version") is None + assert _is_command_allowed("docker -v") is None + assert _is_command_allowed("docker --context default ps") is None + assert _is_command_allowed("docker --context=default ps") is None + assert _is_command_allowed("docker -H tcp://example:2375 ps") is None + assert _is_command_allowed("docker -Htcp://example:2375 ps") is None + assert _is_command_allowed("docker compose -f docker-compose.yml ps") is None + assert _is_command_allowed("docker compose --profile dev logs") is None + assert _is_command_allowed("docker compose -p demo images") is None + + +def test_docker_mutating_subcommands_are_rejected(): + rejected = [ + "docker run --rm alpine", + "docker exec -it web sh", + "docker build .", + "docker rm web", + "docker rmi alpine", + "docker kill web", + "docker stop web", + "docker create alpine", + "docker cp web:/etc/passwd out.txt", + "docker load -i out.tar", + "docker push alpine", + "docker pull alpine", + "docker login", + "docker system prune -af", + "docker image rm alpine", + "docker container run alpine", + "docker volume prune", + "docker network connect bridge web", + "docker context use default", + "docker compose up -d", + "docker compose down", + "docker compose run web sh", + "docker compose build", + "docker buildx build .", + ] + for cmd in rejected: + err = _is_command_allowed(cmd) + assert err is not None, cmd + assert "not read-only" in err, (cmd, err) + + +def test_docker_requires_explicit_subcommand(): + err = _is_command_allowed("docker") + assert err is not None and "explicit read-only subcommand" in err + + +def test_docker_write_escapes_are_rejected(): + # compose config can write via -o/--output, save writes an archive, and + # buildx inspect --bootstrap can create/start a builder container. + for cmd in ( + "docker save -o out.tar alpine", + "docker compose config -o out.yml", + "docker compose config --output out.yml", + "docker compose config --output=out.yml", + "docker compose config -oout.yml", + "docker buildx inspect --bootstrap", + ): + err = _is_command_allowed(cmd) + assert err is not None, cmd + assert "escape-hatch" in err, (cmd, err) + + +def test_xargs_docker_mutating_subcommand_is_rejected(): + err = _is_command_allowed("echo alpine | xargs docker run") + assert err is not None and "xargs cannot invoke 'docker'" in err