Edit on GitHub docs/en/security.md ↗
Security model and risks
The short version: this system is serious about keeping credentials in the control plane and execution in containers; it is not a strongly isolated multi-tenant system. The single largest risk is that the manager holds the host Docker socket.
1. Cryptographic primitives
src/core/security.ts is verifiable and does not invent algorithms:
| Purpose | Implementation |
|---|---|
| Password hashing | scrypt(N=16384, r=8, p=1), 16-byte random salt, scrypt$16384$salt$hash (:28-39) |
| Password compare | timingSafeEqual (:39) |
| Webhook signature | HMAC-SHA256, sha256= + 64 hex, timingSafeEqual (:41-45) |
| Secret encryption | AES-256-GCM, 12-byte random IV, AAD bound to the record scope (:47-61) |
| Random ID | 24 random bytes → 48 hex (:3) |
The AAD binding in SecretBox matters: a ciphertext cannot be transplanted from one account/model row to another and decrypted. The master key is 32 bytes, generated by key-init into the bot-keys volume; lose it and every saved App private key and model key becomes unreadable.
2. Credential layers
| Credential | Storage | Lifetime | Exposure |
|---|---|---|---|
| master.key | bot-keys volume, read-only |
deployment | control plane only |
| GitHub App key / token / model key | SQLite ciphertext | admin update | control plane only |
| manager token | internal-keys volume |
deployment | control plane → manager |
| installation token | memory | short | control plane; read-only tokens on demand |
run token rrt_… |
hash only | 15 min, renewable | one RoleRun |
| user OAuth token | ciphertext | login | /user and identity binding only |
A task container never holds a long-lived GitHub write credential or a model key. When the model needs GitHub, it exchanges a read-only token through the loopback mailbox (github_read_token); the run token is bound to tenant/project/task/run/epoch/capabilities.
3. Isolation
3.1 Containers
- Project computer: read-only root, non-root user 10001,
cap_drop: [ALL],no-new-privileges, controlled work volumes. - Each RoleRun can get its own container and network (
manager/run-environments.mjs). - Limits: default 2 CPU, 4096 MiB, 1024 processes, 1024 MiB
/tmp, adjustable per repository. - Egress:
BOT_PROJECT_EGRESS=falsedisables outbound network for project containers. - Networks:
controlandedgeare separate; the tunnel joins onlyedgeand reachesbot:8791through thewebhookgateway, never manager directly.
3.2 Paths and commands
The runner only accepts controlled JSON; the caller cannot choose exec argv or a user. Paths are workspace-relative; 48 KiB per write, 1 MiB per read, 1 MiB of output. Path escape, hash mismatch or a replaced workspace stops the task.
3.3 Secrets never reach logs
assertSecretFreeruns before writing RunContext, events and checkpoints; secret-shaped keys/values are rejected, not redacted afterwards.- Traces are redacted again by shape. Logs contain error codes, messages and positions, never request bodies or credentials.
- The cost ledger stores model name, token counts, price snapshot and estimate — never prompt/response text.
4. Trust boundaries
[untrusted] repository content, issue/PR text, comments, CI logs, external executor input
│
▼ filtering + read-only tokens + controlled tools
[semi-trusted] model output (injectable)
│ create_pull_request validation / policy tests / QA
▼
[trusted] control plane (credentials, authority, publishing)
│ Bearer manager token
▼
[high privilege] manager (Docker socket)
│
▼
[isolated] project containers (no long-lived credentials)
Facts at the boundary:
- Model output is untrusted. It cannot write GitHub directly;
create_pull_requestvalidates diff, head and branch ownership before the control plane pushes. - Repository content is untrusted. Prompt injection is possible; author filtering, read-only tokens, controlled tools and QA are mitigations, not formal guarantees.
- External executors are untrusted. Signatures, temporary tokens, identity binding and forwarding allowlists are the boundary; they gain no control-plane authority.
5. Threats and risks
| # | Risk | Impact | Current state | Recommendation |
|---|---|---|---|---|
| 1 | manager holds /var/run/docker.sock |
a compromised manager ≈ host root | internal network, Bearer, deployment labels, path validation | dedicated host/user namespace; expose only the needed Docker API; audit every container operation; treat manager as a T0 asset |
| 2 | prompt injection (issues/PRs/code/logs) | model is tricked into widening changes or leaking context | author filtering, read-only tokens, tool allowlist, create_pull_request validation, QA |
isolate untrusted content in prompts; block "read then execute" commands; keep red-team cases |
| 3 | model provider URL is an SSRF surface | control plane fetches an arbitrary URL | URL is entered by an admin/project admin; form validation | restrict scheme/private networks/redirects; re-resolve DNS; egress proxy + allowlist |
| 4 | image supply chain | malicious image steals volumes/credentials | official GHCR images, BOT_IMAGE_TAG pin |
pin digests in production; verify signatures; review upgrades |
| 5 | executor supply chain | a third-party Agent/bridge gets tool access | ACP/Codex/Claude Code versions pinned | pin versions and checksums; run external executors on separate hosts; least privilege |
| 6 | single-writer SQLite | write stalls or corruption under load | WAL + FULL + busy timeout | one control-plane instance; back up regularly; monitor WAL growth |
| 7 | public board | private repository data published by mistake | explicit consent table and settings | off by default; preview before publish; audit |
| 8 | release automation | wrong release | version must exceed the previous reachable tag; draft only | keep the human publish click; restrict who can operate |
| 9 | audit coverage | incidents cannot be reconstructed | audit / audit_records + deliveries |
define retention, export and tamper-evident storage |
| 10 | multiple instances on one host | resource contention / mistakes | deployment-scoped names; Compose project isolation | one Docker daemon or host per instance; resource limits |
6. Secure defaults for operations
BOT_COOKIE_SECURE=true+ HTTPS single entry.BOT_BIND_ADDRESS=127.0.0.1, reachable only through the proxy/tunnel.- Pin
BOT_IMAGE_TAGto a version, not a floatinglatest. - Never commit
.env, private keys or model keys; never print a secret. - Back up four volumes:
bot-data,bot-keys,internal-keys,manager-data;tunnel-keysholds only the Tunnel token. - Upgrade with
pull+up -d; neverdown -v, which deletes the master key and database.
7. Conclusion
- Done well: credential layers, AES-GCM + AAD, persist-before-ack, idempotency, lease fencing, read-only tokens, pure-function automation, secret scanning, audit.
- Accepted premises: you trust the host Docker daemon; you trust the deployed images and executors; you accept that repository content can influence the model.
- Not claimed: OS-level sandboxing, hard multi-tenant isolation, or a guarantee that the model never makes a bad change.