Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
6 changes: 4 additions & 2 deletions docs/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,15 +60,17 @@ 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.

**Recursive validation for command-wrapping utilities.** `xargs` is allowlisted, but its inner command is extracted and validated recursively against the same allowlist — `xargs rm` still fails, because the check doesn't stop at `xargs` itself.

**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.

Expand Down
Loading
Loading