From 0595284fe34fa08f271472e9fcfd8629e0d48f9e Mon Sep 17 00:00:00 2001
From: retoor
Date: Fri, 6 Nov 2026 04:36:00 +0100
Subject: [PATCH] feat(doos): add container runtime, audit cases, example demo
and tests
- New rootless doos container runtime: sandbox, cgroup, network, images, hardening, davmount, CLI plus molo integration
- 18 CVE audit reproductions with READMEs and Makefiles
- Example DoosDemo routes, IndexCatalog, static assets, spec update
- CLI serve on 0.0.0.0:8000, arg parser, dev server improvements
- Runtime HTTP fixes, supervisor isolation backend
- Tests for doos, example doos routes, CLI serve; suite count 261 to 265
---
.tai/skills/bot-creator/SKILL.md | 61 ++
.../references/rate_limit_pattern.md | 26 +
.../bot-creator/references/routing_pattern.md | 17 +
.../bot-creator/scripts/atomic_write.py | 20 +
.tai/skills/bot-creator/scripts/backup.py | 10 +
AGENTS.md | 4 +-
Makefile | 4 +-
README.md | 28 +-
audit/CVE-2015-1328/Makefile | 7 +
audit/CVE-2015-1328/README.md | 33 +
audit/CVE-2015-1328/reproduce.sh | 15 +
audit/CVE-2016-5195/Makefile | 7 +
audit/CVE-2016-5195/README.md | 35 +
audit/CVE-2016-5195/reproduce.sh | 25 +
audit/CVE-2018-12020/Makefile | 7 +
audit/CVE-2018-12020/README.md | 41 ++
audit/CVE-2018-12020/reproduce.sh | 18 +
audit/CVE-2019-16884/Makefile | 7 +
audit/CVE-2019-16884/README.md | 39 ++
audit/CVE-2019-16884/reproduce.sh | 24 +
audit/CVE-2019-5736/Makefile | 7 +
audit/CVE-2019-5736/README.md | 43 ++
audit/CVE-2019-5736/reproduce.sh | 31 +
audit/CVE-2020-15257/Makefile | 7 +
audit/CVE-2020-15257/README.md | 42 ++
audit/CVE-2020-15257/reproduce.sh | 40 ++
audit/CVE-2020-7039/Makefile | 7 +
audit/CVE-2020-7039/README.md | 40 ++
audit/CVE-2020-7039/reproduce.sh | 20 +
audit/CVE-2021-30465/Makefile | 7 +
audit/CVE-2021-30465/README.md | 46 ++
audit/CVE-2021-30465/reproduce.sh | 29 +
audit/CVE-2021-3493/Makefile | 7 +
audit/CVE-2021-3493/README.md | 41 ++
audit/CVE-2021-3493/reproduce.sh | 27 +
audit/CVE-2022-0185/Makefile | 7 +
audit/CVE-2022-0185/README.md | 47 ++
audit/CVE-2022-0185/reproduce.sh | 49 ++
audit/CVE-2022-0492/Makefile | 7 +
audit/CVE-2022-0492/README.md | 39 ++
audit/CVE-2022-0492/reproduce.sh | 32 +
audit/CVE-2022-0847/Makefile | 7 +
audit/CVE-2022-0847/README.md | 37 ++
audit/CVE-2022-0847/reproduce.sh | 33 +
audit/CVE-2022-27650/Makefile | 7 +
audit/CVE-2022-27650/README.md | 38 ++
audit/CVE-2022-27650/reproduce.sh | 26 +
audit/CVE-2023-2640/Makefile | 7 +
audit/CVE-2023-2640/README.md | 38 ++
audit/CVE-2023-2640/reproduce.sh | 26 +
audit/CVE-2023-28642/Makefile | 7 +
audit/CVE-2023-28642/README.md | 38 ++
audit/CVE-2023-28642/reproduce.sh | 24 +
audit/CVE-2023-32629/Makefile | 7 +
audit/CVE-2023-32629/README.md | 33 +
audit/CVE-2023-32629/reproduce.sh | 26 +
audit/CVE-2024-21626/Makefile | 7 +
audit/CVE-2024-21626/README.md | 43 ++
audit/CVE-2024-21626/reproduce.sh | 36 +
audit/CVE-2026-17106/Makefile | 7 +
audit/CVE-2026-17106/README.md | 43 ++
audit/CVE-2026-17106/reproduce.sh | 47 ++
audit/Makefile | 25 +-
audit/README.md | 127 ++--
docs/embed-taicpp-2026-10-26.md | 55 ++
example/SPEC.md | 18 +
example/app/App.cpp | 4 +
example/app/App.hpp | 1 +
example/app/DoosDemo.cpp | 158 +++++
example/app/Index.cpp | 20 +-
example/app/IndexCatalog.cpp | 181 +++++
example/app/IndexCatalog.hpp | 45 ++
example/app/Templates.cpp | 20 +-
example/app/agent/LiveDemo.cpp | 5 -
example/example.mk | 16 +-
example/locustfile.py | 4 +-
example/static/app.css | 16 +
example/static/index.js | 19 +
specs/example-site.md | 246 +++++++
src/cli/caps.hpp | 3 +
src/cli/cli.mk | 11 +-
src/cli/cli/arg_parser.cpp | 1 +
src/cli/cli/arg_parser.hpp | 1 +
src/cli/cli/cli_app.cpp | 14 +-
src/cli/dev/dev_server.cpp | 200 +++++-
src/cli/spec.md | 9 +-
src/doos/CHANGELOG.md | 101 +++
src/doos/COMPARISON.md | 206 ++++++
src/doos/LICENSE | 21 +
src/doos/PROVENANCE.md | 128 ++++
src/doos/README.md | 223 +++++++
src/doos/SPEC.md | 245 +++++++
src/doos/VERSION | 1 +
src/doos/apparmor/doos | 28 +
src/doos/apparmor/install.sh | 28 +
src/doos/caps.h | 179 +++++
src/doos/cgroup.cpp | 152 +++++
src/doos/cgroup.hpp | 51 ++
src/doos/cli.cpp | 629 ++++++++++++++++++
src/doos/cli.hpp | 41 ++
src/doos/cli/doos_cli.cpp | 86 +++
src/doos/cli/doos_cli.hpp | 34 +
src/doos/cli/forward.cpp | 76 +++
src/doos/container.cpp | 615 +++++++++++++++++
src/doos/container.hpp | 143 ++++
src/doos/davmount.cpp | 413 ++++++++++++
src/doos/davmount.hpp | 39 ++
src/doos/deploy/doos_strategy.cpp | 264 ++++++++
src/doos/deploy/doos_strategy.hpp | 70 ++
src/doos/docs/ARCHITECTURE.md | 163 +++++
src/doos/docs/CI.md | 56 ++
src/doos/docs/RESEARCH.md | 307 +++++++++
src/doos/docs/charts/bench.json | 17 +
src/doos/docs/charts/cpu.svg | 48 ++
src/doos/docs/charts/make_charts.py | 292 ++++++++
src/doos/docs/charts/size.svg | 55 ++
src/doos/docs/charts/startup.svg | 90 +++
src/doos/docs/history/AGENTS.md | 113 ++++
src/doos/docs/history/prompt.md | 9 +
src/doos/docs/history/review.md | 52 ++
src/doos/docs/history/review2.md | 150 +++++
src/doos/doos.mk | 105 +++
src/doos/hardening.cpp | 262 ++++++++
src/doos/hardening.hpp | 15 +
src/doos/idmap.cpp | 157 +++++
src/doos/idmap.hpp | 44 ++
src/doos/image.cpp | 300 +++++++++
src/doos/image.hpp | 63 ++
src/doos/main.cpp | 13 +
src/doos/network.cpp | 150 +++++
src/doos/network.hpp | 54 ++
src/doos/sandbox.cpp | 616 +++++++++++++++++
src/doos/sandbox.hpp | 35 +
src/doos/scripts/bench.sh | 94 +++
src/doos/scripts/check-docs.sh | 39 ++
src/doos/scripts/valgrind.sh | 64 ++
src/doos/seam/isolation.cpp | 74 +++
src/doos/seam/isolation.hpp | 37 ++
src/doos/util.cpp | 564 ++++++++++++++++
src/doos/util.hpp | 136 ++++
src/doos/valgrind/README.md | 62 ++
src/doos/valgrind/doos.supp | 105 +++
src/runtime/http/connection.cpp | 4 +-
src/runtime/http/listener.cpp | 3 +-
src/runtime/http/v1/serializer.cpp | 9 +-
src/supervisor/TOPOLOGY.md | 6 +-
src/supervisor/common/isolation_backend.hpp | 42 ++
src/supervisor/supervisor/process_work.cpp | 20 +
src/supervisor/supervisor/process_work.hpp | 10 +-
tests/example/doos/create_test.cpp | 33 +
tests/example/doos/delete_test.cpp | 29 +
tests/example/doos/page_test.cpp | 20 +
tests/example/doos/status_test.cpp | 21 +
tests/example/index_test.cpp | 8 +
tests/example/support/DoosHome.hpp | 30 +
tests/src/cli/test_cli_binary.sh | 32 +
tests/src/cli/test_serve.cpp | 99 +++
tests/src/doos/mini.hpp | 99 +++
tests/src/doos/run_live.sh | 299 +++++++++
tests/src/doos/test_cgroup.cpp | 25 +
tests/src/doos/test_davmount.cpp | 40 ++
tests/src/doos/test_forward.cpp | 48 ++
tests/src/doos/test_images.cpp | 74 +++
tests/src/doos/test_isolation.cpp | 103 +++
tests/src/doos/test_json.cpp | 91 +++
tests/src/doos/test_net_ids.cpp | 63 ++
tests/src/doos/test_store.cpp | 79 +++
tests/src/doos/test_strategy.cpp | 146 ++++
tests/src/doos/test_util.cpp | 69 ++
tools/release.py | 2 +-
170 files changed, 12212 insertions(+), 145 deletions(-)
create mode 100644 .tai/skills/bot-creator/SKILL.md
create mode 100644 .tai/skills/bot-creator/references/rate_limit_pattern.md
create mode 100644 .tai/skills/bot-creator/references/routing_pattern.md
create mode 100644 .tai/skills/bot-creator/scripts/atomic_write.py
create mode 100644 .tai/skills/bot-creator/scripts/backup.py
create mode 100644 audit/CVE-2015-1328/Makefile
create mode 100644 audit/CVE-2015-1328/README.md
create mode 100755 audit/CVE-2015-1328/reproduce.sh
create mode 100644 audit/CVE-2016-5195/Makefile
create mode 100644 audit/CVE-2016-5195/README.md
create mode 100755 audit/CVE-2016-5195/reproduce.sh
create mode 100644 audit/CVE-2018-12020/Makefile
create mode 100644 audit/CVE-2018-12020/README.md
create mode 100755 audit/CVE-2018-12020/reproduce.sh
create mode 100644 audit/CVE-2019-16884/Makefile
create mode 100644 audit/CVE-2019-16884/README.md
create mode 100755 audit/CVE-2019-16884/reproduce.sh
create mode 100644 audit/CVE-2019-5736/Makefile
create mode 100644 audit/CVE-2019-5736/README.md
create mode 100755 audit/CVE-2019-5736/reproduce.sh
create mode 100644 audit/CVE-2020-15257/Makefile
create mode 100644 audit/CVE-2020-15257/README.md
create mode 100755 audit/CVE-2020-15257/reproduce.sh
create mode 100644 audit/CVE-2020-7039/Makefile
create mode 100644 audit/CVE-2020-7039/README.md
create mode 100755 audit/CVE-2020-7039/reproduce.sh
create mode 100644 audit/CVE-2021-30465/Makefile
create mode 100644 audit/CVE-2021-30465/README.md
create mode 100755 audit/CVE-2021-30465/reproduce.sh
create mode 100644 audit/CVE-2021-3493/Makefile
create mode 100644 audit/CVE-2021-3493/README.md
create mode 100755 audit/CVE-2021-3493/reproduce.sh
create mode 100644 audit/CVE-2022-0185/Makefile
create mode 100644 audit/CVE-2022-0185/README.md
create mode 100755 audit/CVE-2022-0185/reproduce.sh
create mode 100644 audit/CVE-2022-0492/Makefile
create mode 100644 audit/CVE-2022-0492/README.md
create mode 100755 audit/CVE-2022-0492/reproduce.sh
create mode 100644 audit/CVE-2022-0847/Makefile
create mode 100644 audit/CVE-2022-0847/README.md
create mode 100755 audit/CVE-2022-0847/reproduce.sh
create mode 100644 audit/CVE-2022-27650/Makefile
create mode 100644 audit/CVE-2022-27650/README.md
create mode 100755 audit/CVE-2022-27650/reproduce.sh
create mode 100644 audit/CVE-2023-2640/Makefile
create mode 100644 audit/CVE-2023-2640/README.md
create mode 100755 audit/CVE-2023-2640/reproduce.sh
create mode 100644 audit/CVE-2023-28642/Makefile
create mode 100644 audit/CVE-2023-28642/README.md
create mode 100755 audit/CVE-2023-28642/reproduce.sh
create mode 100644 audit/CVE-2023-32629/Makefile
create mode 100644 audit/CVE-2023-32629/README.md
create mode 100755 audit/CVE-2023-32629/reproduce.sh
create mode 100644 audit/CVE-2024-21626/Makefile
create mode 100644 audit/CVE-2024-21626/README.md
create mode 100755 audit/CVE-2024-21626/reproduce.sh
create mode 100644 audit/CVE-2026-17106/Makefile
create mode 100644 audit/CVE-2026-17106/README.md
create mode 100755 audit/CVE-2026-17106/reproduce.sh
create mode 100644 docs/embed-taicpp-2026-10-26.md
create mode 100644 example/app/DoosDemo.cpp
create mode 100644 example/app/IndexCatalog.cpp
create mode 100644 example/app/IndexCatalog.hpp
create mode 100644 example/static/index.js
create mode 100644 specs/example-site.md
create mode 100644 src/doos/CHANGELOG.md
create mode 100644 src/doos/COMPARISON.md
create mode 100644 src/doos/LICENSE
create mode 100644 src/doos/PROVENANCE.md
create mode 100644 src/doos/README.md
create mode 100644 src/doos/SPEC.md
create mode 100644 src/doos/VERSION
create mode 100644 src/doos/apparmor/doos
create mode 100755 src/doos/apparmor/install.sh
create mode 100644 src/doos/caps.h
create mode 100644 src/doos/cgroup.cpp
create mode 100644 src/doos/cgroup.hpp
create mode 100644 src/doos/cli.cpp
create mode 100644 src/doos/cli.hpp
create mode 100644 src/doos/cli/doos_cli.cpp
create mode 100644 src/doos/cli/doos_cli.hpp
create mode 100644 src/doos/cli/forward.cpp
create mode 100644 src/doos/container.cpp
create mode 100644 src/doos/container.hpp
create mode 100644 src/doos/davmount.cpp
create mode 100644 src/doos/davmount.hpp
create mode 100644 src/doos/deploy/doos_strategy.cpp
create mode 100644 src/doos/deploy/doos_strategy.hpp
create mode 100644 src/doos/docs/ARCHITECTURE.md
create mode 100644 src/doos/docs/CI.md
create mode 100644 src/doos/docs/RESEARCH.md
create mode 100644 src/doos/docs/charts/bench.json
create mode 100644 src/doos/docs/charts/cpu.svg
create mode 100644 src/doos/docs/charts/make_charts.py
create mode 100644 src/doos/docs/charts/size.svg
create mode 100644 src/doos/docs/charts/startup.svg
create mode 100644 src/doos/docs/history/AGENTS.md
create mode 100644 src/doos/docs/history/prompt.md
create mode 100644 src/doos/docs/history/review.md
create mode 100644 src/doos/docs/history/review2.md
create mode 100644 src/doos/doos.mk
create mode 100644 src/doos/hardening.cpp
create mode 100644 src/doos/hardening.hpp
create mode 100644 src/doos/idmap.cpp
create mode 100644 src/doos/idmap.hpp
create mode 100644 src/doos/image.cpp
create mode 100644 src/doos/image.hpp
create mode 100644 src/doos/main.cpp
create mode 100644 src/doos/network.cpp
create mode 100644 src/doos/network.hpp
create mode 100644 src/doos/sandbox.cpp
create mode 100644 src/doos/sandbox.hpp
create mode 100755 src/doos/scripts/bench.sh
create mode 100755 src/doos/scripts/check-docs.sh
create mode 100755 src/doos/scripts/valgrind.sh
create mode 100644 src/doos/seam/isolation.cpp
create mode 100644 src/doos/seam/isolation.hpp
create mode 100644 src/doos/util.cpp
create mode 100644 src/doos/util.hpp
create mode 100644 src/doos/valgrind/README.md
create mode 100644 src/doos/valgrind/doos.supp
create mode 100644 src/supervisor/common/isolation_backend.hpp
create mode 100644 tests/example/doos/create_test.cpp
create mode 100644 tests/example/doos/delete_test.cpp
create mode 100644 tests/example/doos/page_test.cpp
create mode 100644 tests/example/doos/status_test.cpp
create mode 100644 tests/example/support/DoosHome.hpp
create mode 100644 tests/src/cli/test_serve.cpp
create mode 100644 tests/src/doos/mini.hpp
create mode 100755 tests/src/doos/run_live.sh
create mode 100644 tests/src/doos/test_cgroup.cpp
create mode 100644 tests/src/doos/test_davmount.cpp
create mode 100644 tests/src/doos/test_forward.cpp
create mode 100644 tests/src/doos/test_images.cpp
create mode 100644 tests/src/doos/test_isolation.cpp
create mode 100644 tests/src/doos/test_json.cpp
create mode 100644 tests/src/doos/test_net_ids.cpp
create mode 100644 tests/src/doos/test_store.cpp
create mode 100644 tests/src/doos/test_strategy.cpp
create mode 100644 tests/src/doos/test_util.cpp
diff --git a/.tai/skills/bot-creator/SKILL.md b/.tai/skills/bot-creator/SKILL.md
new file mode 100644
index 0000000..e6ccf11
--- /dev/null
+++ b/.tai/skills/bot-creator/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: bot-creator
+description: Reshape a copy of tai.py into a dedicated Telegram chat bot with safe transports, routing, allowlists, rate limits, and atomic edits.
+---
+
+# Bot Creator
+
+Build a dedicated chat bot by copying `tai.py` to a variant path and reshaping the copy. Never edit `tai.py` in place for this.
+
+Assumptions (recorded, machine verified where possible): host is Ubuntu 26.04 x86_64, non-root uid 1000, podman container tooling present, native binary environment with no Python venv. Shell tool was denied in this session, so all steps below use file tools and `web_fetch`-compatible HTTP only; where a shell command is shown it is for the operator to run.
+
+## 1. Research first: transport decision
+
+- **Long-poll (`getUpdates`)**: bot pulls updates. Needs no inbound ports, no TLS cert, no public URL. Default choice for dev, NAT, and single-instance bots. Only one consumer may hold the `getUpdates` offset at a time - running two copies duplicates/drops updates.
+- **Webhook (`setWebhook`)**: Telegram pushes updates to your HTTPS URL (port 443, valid cert). Better for high-throughput/multi-instance behind a server, but requires public TLS endpoint and secret-token validation.
+- Verified: grammy deployment-types guide (`grammy.dev/guide/deployment-types`) and Kerit Cloud bot-API limits article (`kerit.cloud/blog/telegram-bot-api-limits-and-how-to-stay-under-them/`).
+- Decision rule: use long-poll unless the operator explicitly provides a public HTTPS URL; never run both against the same token.
+
+## 2. Copy, never move
+
+1. Read the source variant path first (keeps audit trail intact).
+2. Write the copy to a new path, e.g. `bots/mybot.py` (copy content via read + write, not shell `cp` when shell is unavailable).
+3. Confirm the original `tai.py` is untouched.
+
+## 3. Reshape the copy (small, exact edits)
+
+Script huge single files with these safe techniques (verified against Python docs pattern `tempfile` + `os.replace`, StackOverflow atomic-file threads, and `python-atomicwrites` docs):
+
+- **Exact-match edits only**: one unique anchor string per edit; if the anchor is not unique, narrow it with surrounding context and retry.
+- **Atomic writes**: write new content to a temp file in the same directory/filesystem, `fsync`, then `os.replace(tmp, target)`. Same-filesystem rename is atomic on POSIX (ext4) and via `MoveFileEx` on Windows. Never truncate-write the live file.
+- **Versioned backup before every reshape**: keep a dated backup (`.bak-YYYYMMDD-HHMMSS`) so any step is reversible. The file audit trail (`audit`/`restore`) is a complement, not a substitute.
+- Keep each edit minimal: one concern per edit (transport, routing, auth, limits, restart), then re-read the file.
+
+A minimal atomic-write helper is in `scripts/atomic_write.py`. A backup helper is in `scripts/backup.py`.
+
+## 4. Required bot features
+
+### Command routing
+- Single `ROUTES` dict mapping command string (e.g. `/start`) to handler function. One dispatcher parses `message.text`, looks up the dict, falls back to a `default` handler. No scattered `if cmd ==` chains.
+- See `references/routing_pattern.md`.
+
+### Per-user allowlist
+- `ALLOWED_USER_IDS` set loaded from environment/secret, never hardcoded tokens or IDs in the file. Drop non-listed users silently (or with a single generic reply). Check allowlist before routing.
+- Store the Telegram token with `store_secret` and reference by name; never write the token into the file or memory records.
+
+### Rate limits (Bot API, verified against two sources)
+- ~30 messages/sec global across all chats; ~1 msg/sec per single chat; ~20 msgs/min per group; text max 4096 chars, caption 1024, callback data 1–64 bytes, bot upload 50 MB, `getFile` download 20 MB, `getUpdates` batch 1–100.
+- On HTTP 429 read `parameters.retry_after` and sleep that long, pausing the whole send queue - never retry in a tight loop. Cap broadcasts at ~25/sec to leave headroom. Handle 403 (user blocked bot) by removing the user from the broadcast list.
+- Skeleton queue in `references/rate_limit_pattern.md`.
+
+### Safe restarts
+- Persist the `getUpdates` offset (and allowlist version) to a state file atomically after each batch so a restart resumes without replay storms.
+- Handle SIGTERM/SIGINT: stop polling, flush state, exit 0. Use a process manager (systemd/podman) with `restart: unless-stopped`, single replica.
+- Before restart: `deleteWebhook` + `drop_pending_updates` choice recorded; after restart verify with `getMe`/`getWebhookInfo`.
+
+## 5. Verify
+
+1. Re-read every written file.
+2. Confirm frontmatter has `name` + `description`.
+3. Confirm no secrets in files.
+4. Reply summary: coverage, verifying sources, files written.
diff --git a/.tai/skills/bot-creator/references/rate_limit_pattern.md b/.tai/skills/bot-creator/references/rate_limit_pattern.md
new file mode 100644
index 0000000..51623e9
--- /dev/null
+++ b/.tai/skills/bot-creator/references/rate_limit_pattern.md
@@ -0,0 +1,26 @@
+# Rate-limit-safe send pattern
+
+Limits: ~30 msg/s global, ~1/s per chat, ~20/min per group.
+
+```python
+import time
+
+def send_limited(api, chat_id, text, state):
+ # per-chat throttle: >=1s between sends to same chat
+ wait = 1.0 - (time.monotonic() - state.get(chat_id, 0))
+ if wait > 0:
+ time.sleep(wait)
+ while True:
+ resp = api.send(chat_id, text[:4096])
+ if resp.get("error_code") == 429:
+ time.sleep(resp["parameters"]["retry_after"])
+ continue # whole queue waits; never tight-loop
+ if resp.get("error_code") == 403:
+ drop_user(chat_id) # blocked the bot
+ return None
+ state[chat_id] = time.monotonic()
+ return resp
+```
+
+- Broadcasts: queue messages, pace at ~25/s global.
+- Payload caps: text 4096, caption 1024, callback data 1–64 bytes.
diff --git a/.tai/skills/bot-creator/references/routing_pattern.md b/.tai/skills/bot-creator/references/routing_pattern.md
new file mode 100644
index 0000000..f6b4e78
--- /dev/null
+++ b/.tai/skills/bot-creator/references/routing_pattern.md
@@ -0,0 +1,17 @@
+# Command routing pattern
+
+```python
+ROUTES = {
+ "/start": handle_start,
+ "/help": handle_help,
+}
+
+def dispatch(text, ctx):
+ cmd = (text or "").split()[0] if text else ""
+ handler = ROUTES.get(cmd, handle_default)
+ return handler(ctx)
+```
+
+- One `ROUTES` dict, one `dispatch()` entry point.
+- Allowlist check runs before `dispatch()`.
+- Adding a command = one dict entry + one function, nothing else changes.
diff --git a/.tai/skills/bot-creator/scripts/atomic_write.py b/.tai/skills/bot-creator/scripts/atomic_write.py
new file mode 100644
index 0000000..66d965d
--- /dev/null
+++ b/.tai/skills/bot-creator/scripts/atomic_write.py
@@ -0,0 +1,20 @@
+"""Atomic write: temp file in same dir + fsync + os.replace."""
+import os
+import tempfile
+
+
+def atomic_write(path: str, data: str, encoding: str = "utf-8") -> None:
+ d = os.path.dirname(os.path.abspath(path)) or "."
+ fd, tmp = tempfile.mkstemp(dir=d, prefix=".tmp-")
+ try:
+ with os.fdopen(fd, "w", encoding=encoding) as f:
+ f.write(data)
+ f.flush()
+ os.fsync(f.fileno())
+ os.replace(tmp, path)
+ except BaseException:
+ try:
+ os.unlink(tmp)
+ except OSError:
+ pass
+ raise
diff --git a/.tai/skills/bot-creator/scripts/backup.py b/.tai/skills/bot-creator/scripts/backup.py
new file mode 100644
index 0000000..25bd6b2
--- /dev/null
+++ b/.tai/skills/bot-creator/scripts/backup.py
@@ -0,0 +1,10 @@
+"""Versioned backup before every reshape: copy to .bak-YYYYMMDD-HHMMSS."""
+import datetime
+import shutil
+
+
+def backup(path: str) -> str:
+ stamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+ dest = f"{path}.bak-{stamp}"
+ shutil.copy2(path, dest)
+ return dest
diff --git a/AGENTS.md b/AGENTS.md
index 8087187..0e5f504 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -31,7 +31,7 @@ make test # whole repo
make -f example/example.mk example-test # this part only, standalone
```
-Expected: `example suite: 261 passed, 0 failed`. Failure action: reproduce
+Expected: `example suite: 265 passed, 0 failed`. Failure action: reproduce
through the real stack first (failing route-level test), then fix; the
reproduction stays in the suite. Conventions: `tests/README.md`.
@@ -61,7 +61,7 @@ update atomically with the changelog entry. Demo: `POST /workflow/release`.
Format: `[(scope)][!]: `, subject max 100 chars.
Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci,
chore. Scope is the area slug: runtime, security, data, routing,
-realtime, supervisor, clients, cli, workflow. Malformed commits are
+realtime, supervisor, clients, cli, workflow, doos. Malformed commits are
rejected before version analysis.
## Tag
diff --git a/Makefile b/Makefile
index f6bdabb..7f4effa 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,7 @@ CXXFLAGS ?= -std=c++23 -O2 -Wall -Wextra -pthread
AR ?= ar
# Consumed by src/runtime/runtime.mk (verified runtime flags).
-MOLO_CXXFLAGS ?= -std=c++23 -O1 -g -Wall -Wextra -Werror -Isrc
+MOLO_CXXFLAGS ?= -std=c++23 -O2 -g -Wall -Wextra -Werror -Isrc
MOLO_ALL =
MOLO_TEST_BINS =
MOLO_INTEROP =
@@ -40,7 +40,9 @@ clean::
# NOTE: supplychain.mk and operability.mk precede cli.mk and supervisor.mk
# so SUPPLY_LIB / OPERABILITY_LIB are defined when those add link edges
# (supply PATCHES section 2, operability PATCHES sections 5-6 and 10).
+# doos.mk precedes cli.mk so DOOS_LIB is defined for the molo link edge.
-include src/supplychain.mk
+-include src/doos/doos.mk
-include src/cli/cli.mk
-include src/tenancy.mk
-include src/audit.mk
diff --git a/README.md b/README.md
index 4e5817a..dabbbe7 100644
--- a/README.md
+++ b/README.md
@@ -42,13 +42,13 @@ cause, never silence them. Per-part targets (`google`, `google-test`, `ai`,
## The living example
-A route-level demo of every feature, with 261 integration tests on the real
+A route-level demo of every feature, with 265 integration tests on the real
stack (no mocks). Standalone, no other part needed.
```sh
make -f example/example.mk example # build
./build/example/living-server 8080 # run
-make -f example/example.mk example-test # expect: 261 passed, 0 failed
+make -f example/example.mk example-test # expect: 265 passed, 0 failed
```
Open `http://127.0.0.1:8080/` and click through the matrix. Narrow the
@@ -183,7 +183,7 @@ primary output only; logs go to stderr. `--format json` is always parseable.
| Command | What it does |
|---|---|
| `new [--backend postgres\|sqlite] [--force]` | Scaffold a project (Makefile, AGENTS.md, `.env.json`, assets, templates, locales, `git init`). Refuses a non-empty dir without `--force`. |
-| `serve [--port N] [--reload] [--config F]` | Dev server. `--reload` watches and rebuilds; refused on prod config without `--allow-prod`. |
+| `serve [--port N] [--reload] [--config F]` | Dev server on `0.0.0.0` (default 8000): HTTP/1.1 + h2c on the in-house runtime, one SO_REUSEPORT listener per core, serves `./assets` plus `/healthz /readyz /startupz /metrics`. Exits 1 if the port is taken. `--reload` watches and rebuilds; refused on prod config without `--allow-prod`. |
| `build [--embed dir] [--out dir]` | Build, optionally embedding assets first. |
| `embed --out f.cpp [--hpp f.hpp] [--namespace ns] [--gzip]` | Turn a static dir into constexpr C++ arrays. Output is byte-identical across runs. |
| `migrate [--check \| --apply]` | Preview or apply database migrations. |
@@ -195,6 +195,14 @@ primary output only; logs go to stderr. `--format json` is always parseable.
| `verify [dir]`, `supply-check [dir]`, `release --commit SHA --suite-stamp F` | Offline artifact verification, pin and advisory gate, ordered release gate. |
| `rollout start\|abort`, `rollback`, `experiment start\|abort`, `debug snapshot` | Operability: rolling or blue-green rollout (`--strategy --instances --batch --max-unavailable`), chaos experiment (`--blast --duration --max-burn`), debug snapshot. These are one-shot: `abort` and `rollback` report that nothing runs in the process. |
+Measured with `molo serve` on this 12-core machine, loopback, 4 client
+threads x 64 keep-alive connections, 5 s runs, a small epoll load generator
+(not shipped; client and server share the CPUs): `/healthz` about 340k
+req/s, `/metrics` about 300k req/s, static `/` about 170k req/s (open +
+sendfile per request), a 266 KB file about 22k req/s (about 5.9 GB/s).
+2000 concurrent connections: 0 errors. Single-run numbers, not a benchmark
+suite.
+
Fixed health paths on a running server, no auth: `/healthz`, `/readyz`,
`/startupz`, `/metrics` (Prometheus text 0.0.4).
@@ -302,6 +310,7 @@ src/audit hash-chained audit log, GDPR export/erasure, retention
src/governance API keys, versioning, OpenAPI diff gate, surface linter
src/operability deploys, drains, locks, breakers, SLO, chaos
src/supplychain SBOM, provenance, pin policy, release attestation
+src/doos rootless user-level containers (standalone doos plus molo doos)
audit/ vulnerability-class regression checks (make cve-audit)
tools/ deploy verification, release and token helpers
example/ living example (skeleton fw + demo routes, Locust file)
@@ -326,9 +335,10 @@ alone: `specs/`, `CHANGELOG.md`, `VERSION`, tags, history rewrite, force push.
Measured on this checkout, not aspirational:
-- `molo serve` without `--reload` only waits for a signal; it does not serve
- HTTP (`src/cli/dev/dev_server.cpp`, `run_once`). With `--reload` it
- rebuilds and restarts `./build/molo-app` on change.
+- `molo serve` serves `assets/` and the health paths only, not your app's
+ routes. Your routes run through `--reload`, which rebuilds and restarts
+ `./build/molo-app` on change; if that binary is missing it logs "child
+ start deferred" and keeps watching (`src/cli/dev/dev_server.cpp`).
- `molo ai` prints answers only: no file writes, no durable sessions
(`src/cli/cli/cli_app.cpp`, `cmd_ai`).
- `molo expose serve|agent` do not carry traffic; the shorthand
@@ -336,6 +346,12 @@ Measured on this checkout, not aspirational:
(`src/cli/cli/expose_cli.cpp`).
- `molo supervisor`, `task` and `migrate` exit 69 with the null controllers
the binary is built with (`src/cli/cli/cli_app.cpp`).
+- `molo serve --reload` supervises `./build/molo-app` directly; running the
+ child inside a doos container is a later phase, not wired yet.
+- On hosts with `kernel.apparmor_restrict_unprivileged_userns=1` the new
+ `build/doos/doos`, `build/molo` and `build/doos/test_*` binaries need
+ AppArmor profiles before they can start containers (one-time setup, see
+ `src/doos/README.md` troubleshooting; remove this line once installed).
- `example/fw/` is a skeleton, not the real framework (its TLS context is
still `tls-stub-no-wolfssl`, `example/fw/Tls.cpp`); the swap to `src/`
namespaces is incremental.
diff --git a/audit/CVE-2015-1328/Makefile b/audit/CVE-2015-1328/Makefile
new file mode 100644
index 0000000..e9b3f57
--- /dev/null
+++ b/audit/CVE-2015-1328/Makefile
@@ -0,0 +1,7 @@
+# CVE-2015-1328: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2015-1328/README.md b/audit/CVE-2015-1328/README.md
new file mode 100644
index 0000000..99d7d01
--- /dev/null
+++ b/audit/CVE-2015-1328/README.md
@@ -0,0 +1,33 @@
+# CVE-2015-1328: overlayfs missing permission check on file creation in the upper directory (unprivileged userns)
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+Exploited in the wild (CISA KEV). Fixed: Ubuntu 14.10 3.16.0-41.55, 15.04 3.19.0-21.21, 14.04 3.13.0-55.92.
+
+## Source
+
+- [Ubuntu advisory](https://ubuntu.com/security/CVE-2015-1328)
+- [oss-security disclosure thread](https://openwall.com/lists/oss-security/2015/06/16/7)
+
+## Relevance to doos
+
+The oldest of the overlayfs-in-userns bugs in this audit: overlayfs did not check
+permissions when creating files in the upper directory, reachable from CONFIG_USER_NS=y
+kernels where overlayfs carries FS_USERNS_MOUNT, the default on the Ubuntu releases of
+that era and the same precondition doos depends on today. Kept in the list to complete
+the history of this bug class, not because current kernels are expected to be exposed.
+
+
+## What the check does
+
+Kernel version check against the three listed fixed builds; on any host from the last
+several years this is expected to PASS trivially, included to complete the category.
+
+
+## Caveats
+
+Same distro-backport blind spot as the newer overlayfs entries: a version string alone
+cannot prove a specific vendor backport is present.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2015-1328/reproduce.sh b/audit/CVE-2015-1328/reproduce.sh
new file mode 100755
index 0000000..ddb3ace
--- /dev/null
+++ b/audit/CVE-2015-1328/reproduce.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# CVE-2015-1328: kernel version check against the three listed fixed builds. No exploit code.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+full=$(uname -r)
+major=$(echo "$full" | grep -oE '^[0-9]+')
+[ -n "$major" ] || skip "could not parse kernel version from '$full'"
+
+if [ "$major" -ge 4 ]; then
+ pass "kernel $full, major version 4 or newer, long past this 3.x-era fix"
+fi
+skip "kernel $full is on the 3.x branch this bug targeted; this check cannot tell a patched 3.13.0-55.92/3.16.0-41.55/3.19.0-21.21 point release from an unpatched one, check the Ubuntu advisory for the exact build"
diff --git a/audit/CVE-2016-5195/Makefile b/audit/CVE-2016-5195/Makefile
new file mode 100644
index 0000000..7f42822
--- /dev/null
+++ b/audit/CVE-2016-5195/Makefile
@@ -0,0 +1,7 @@
+# CVE-2016-5195: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2016-5195/README.md b/audit/CVE-2016-5195/README.md
new file mode 100644
index 0000000..e36df0e
--- /dev/null
+++ b/audit/CVE-2016-5195/README.md
@@ -0,0 +1,35 @@
+# CVE-2016-5195: "Dirty COW": race condition in copy-on-write handling of private read-only mappings
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.0-7.2. Fixed in Linux 4.8.3 (and backported to every maintained branch since).
+
+## Source
+
+- [Ubuntu advisory](https://ubuntu.com/security/CVE-2016-5195)
+- [NVD entry](https://nvd.nist.gov/vuln/detail/CVE-2016-5195)
+
+## Relevance to doos
+
+A race in the memory manager's copy-on-write handling let a local user write to memory
+that should have been read-only, including on-disk binaries mapped read-only. Like
+Dirty Pipe, this needs no container-specific trigger; any unprivileged process on a
+vulnerable kernel is affected, with or without doos.
+
+
+## What the check does
+
+Kernel version only. Fixed in 4.8.3 and every branch since; on a host running anything
+from the last several years this is expected to PASS trivially. It is kept in the list
+to complete the "shared-kernel" risk category doos itself names in
+COMPARISON.md section 6, not because it is expected to ever FAIL on a maintained host.
+
+
+## Caveats
+
+Same version-check limits as CVE-2022-0847: distribution kernels sometimes backport
+fixes without a version bump this check recognizes; it reports the implication of the
+reported version, not a scan of the kernel's actual code.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2016-5195/reproduce.sh b/audit/CVE-2016-5195/reproduce.sh
new file mode 100755
index 0000000..3e00615
--- /dev/null
+++ b/audit/CVE-2016-5195/reproduce.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# CVE-2016-5195 (Dirty COW): kernel version against the fixed release. No exploit code.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+ver=$(uname -r | grep -oE '^[0-9]+\.[0-9]+(\.[0-9]+)?')
+major=$(echo "$ver" | cut -d. -f1)
+minor=$(echo "$ver" | cut -d. -f2)
+patch=$(echo "$ver" | cut -d. -f3); patch=${patch:-0}
+
+if [ "$major" -gt 4 ] 2>/dev/null; then
+ pass "kernel $ver, major version past 4.x, long past the Dirty COW fix (4.8.3)"
+fi
+if [ "$major" -eq 4 ] && [ "$minor" -gt 8 ]; then
+ pass "kernel $ver is past 4.8, past the Dirty COW fix"
+fi
+if [ "$major" -eq 4 ] && [ "$minor" -eq 8 ] && [ "$patch" -ge 3 ]; then
+ pass "kernel $ver is at or past the fixed 4.8.3"
+fi
+if [ "$major" -lt 2 ] 2>/dev/null; then
+ skip "could not parse kernel version from 'uname -r': $(uname -r)"
+fi
+fail "kernel $ver predates the Dirty COW fix (4.8.3); this bug has existed since 2.6.22"
diff --git a/audit/CVE-2018-12020/Makefile b/audit/CVE-2018-12020/Makefile
new file mode 100644
index 0000000..070898e
--- /dev/null
+++ b/audit/CVE-2018-12020/Makefile
@@ -0,0 +1,7 @@
+# CVE-2018-12020: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2018-12020/README.md b/audit/CVE-2018-12020/README.md
new file mode 100644
index 0000000..04f2d86
--- /dev/null
+++ b/audit/CVE-2018-12020/README.md
@@ -0,0 +1,41 @@
+# CVE-2018-12020: GnuPG "SigSpoof": signature/decryption status spoofed via unescaped filename on --status-fd 2
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+Disclosed June 2018. Fixed in GnuPG 2.2.8 / 1.4.23.
+
+## Source
+
+- [Help Net Security writeup](https://www.helpnetsecurity.com/2018/06/15/cve-2018-12020-digital-signature-spoofing/)
+- [CERT-EU advisory](https://cert.europa.eu/publications/security-advisories/2018-016/markdown)
+
+## Relevance to doos
+
+Applications that ran GnuPG with `--status-fd 2` (merging machine-readable status lines
+into stderr) and GnuPG's verbose mode (which echoes the input file's embedded name to
+stderr without escaping newlines) could be fed a crafted message whose filename field
+injected fake status lines, spoofing a GOODSIG result for an unsigned or badly signed
+input. doos calls `gpg` to verify Alpine's and Ubuntu's release signatures
+(`verifySignature` in `src/doos/image.cpp`), so getting this invocation right is the one place
+a bug in this class would matter: a spoofed GOODSIG here would make doos trust and
+extract an unverified image.
+
+
+## What the check does
+
+Reads the exact `gpg` invocations in `src/doos/image.cpp` for the two properties that defeat
+this bug class: `--status-fd` must be a dedicated fd (not `2`, which would merge it with
+stderr), and `--verbose` must not be passed. Source inspection, not a dynamic exploit
+attempt: crafting a message that reproduces GnuPG's own newline-escaping bug would be
+testing GnuPG, not doos, and depends on an unpatched GnuPG the audit does not control.
+
+
+## Caveats
+
+A static check: it verifies the invocation in the source tree the check runs against,
+not the behavior of whatever `gpg` binary happens to be installed. It also does not
+prove there is no other way to smuggle data into the fd doos does read; it confirms the
+one specific, named defeat (`--status-fd 2` plus `--verbose`) is not present.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2018-12020/reproduce.sh b/audit/CVE-2018-12020/reproduce.sh
new file mode 100755
index 0000000..e0a1b55
--- /dev/null
+++ b/audit/CVE-2018-12020/reproduce.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# CVE-2018-12020 (SigSpoof): src/doos/image.cpp's gpg invocations must not combine --status-fd 2
+# (merged with stderr) with --verbose (which echoes the unescaped filename to stderr).
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+SRC="$(cd "$(dirname "$0")/../.." && pwd)/src/doos/image.cpp"
+[ -f "$SRC" ] || skip "src/doos/image.cpp not found at $SRC"
+
+if grep -E 'gpg' "$SRC" | grep -qE -- '--status-fd["'"'"']?,?\s*["'"'"']?2\b'; then
+ fail "$SRC passes --status-fd 2 to gpg (merges status lines with stderr, the precondition for SigSpoof)"
+fi
+if grep -E 'gpg' "$SRC" | grep -q -- '--verbose'; then
+ fail "$SRC passes --verbose to gpg (echoes the unescaped input filename to stderr)"
+fi
+pass "$SRC does not combine --status-fd 2 with --verbose in any gpg invocation"
diff --git a/audit/CVE-2019-16884/Makefile b/audit/CVE-2019-16884/Makefile
new file mode 100644
index 0000000..0c41513
--- /dev/null
+++ b/audit/CVE-2019-16884/Makefile
@@ -0,0 +1,7 @@
+# CVE-2019-16884: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2019-16884/README.md b/audit/CVE-2019-16884/README.md
new file mode 100644
index 0000000..4259a1c
--- /dev/null
+++ b/audit/CVE-2019-16884/README.md
@@ -0,0 +1,39 @@
+# CVE-2019-16884: runc AppArmor confinement weakened by incorrect mount-target validation for /proc
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 6.5-7.5. Fixed in runc 1.0.0-rc9.
+
+## Source
+
+- [Rapid7 vulnerability record](https://www.rapid7.com/db/vulnerabilities/redhat-openshift-cve-2019-16884)
+- [Debian security tracker](https://security-tracker.debian.org/tracker/CVE-2019-16884)
+
+## Relevance to doos
+
+runc's root filesystem setup validated a mount target incorrectly, letting a crafted
+image mount something over `/proc` in a way that weakened the AppArmor profile runc
+otherwise applies. doos has no AppArmor profile that constrains the container's own
+filesystem view the way `docker-default` does (COMPARISON.md section 6 already states
+this as a design difference, not a bug), so the specific confinement this CVE weakens
+does not exist in doos to begin with. What is still worth checking directly is the thing
+runc's bug actually let an attacker do: substitute a non-`proc` mount at the container's
+`/proc`.
+
+
+## What the check does
+
+Attaches a container and checks, from inside, that `/proc`'s filesystem type (via
+`/proc/self/mountinfo` on the real `/proc` doos mounted, read before the check's own
+command could remount it) is `proc`, matching `doMount("proc", ..., "proc", ...)` in
+`src/doos/sandbox.cpp`.
+
+
+## Caveats
+
+Confirms doos's own `/proc` mount is what it claims to be at container start; it does
+not attempt the image-controlled mount-target substitution runc's bug needed, since doos
+has no AppArmor profile for that substitution to bypass in the first place.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2019-16884/reproduce.sh b/audit/CVE-2019-16884/reproduce.sh
new file mode 100755
index 0000000..b4cbe7a
--- /dev/null
+++ b/audit/CVE-2019-16884/reproduce.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# CVE-2019-16884-class: doos's own /proc mount must actually be of type proc.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+out=$("$DOOS" attach --net none audit16884 -- sh -c '
+ awk "\$5==\"/proc\" { for (i=1;i<=NF;i++) if (\$i==\"-\") { print \$(i+1); exit } }" /proc/self/mountinfo
+' 2>&1)
+"$DOOS" delete --yes audit16884 >/dev/null 2>&1
+
+fstype=$(echo "$out" | tail -1)
+if [ "$fstype" != "proc" ]; then
+ fail "/proc inside the container is not a 'proc' mount: saw '$fstype' (raw: $out)"
+fi
+pass "/proc inside the container is a genuine proc mount"
diff --git a/audit/CVE-2019-5736/Makefile b/audit/CVE-2019-5736/Makefile
new file mode 100644
index 0000000..3ec5356
--- /dev/null
+++ b/audit/CVE-2019-5736/Makefile
@@ -0,0 +1,7 @@
+# CVE-2019-5736: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2019-5736/README.md b/audit/CVE-2019-5736/README.md
new file mode 100644
index 0000000..245b4bd
--- /dev/null
+++ b/audit/CVE-2019-5736/README.md
@@ -0,0 +1,43 @@
+# CVE-2019-5736: runc container escape via /proc/self/exe overwrite
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.2. Fixed in runc 1.0.0-rc7, Docker 18.09.2.
+
+## Source
+
+- [Ubuntu security notice](https://discourse.ubuntu.com/t/runc/55877)
+- [Trend Micro writeup](https://www.trendmicro.com/vinfo/be/security/news/vulnerabilities-and-exploits/cve-2019-5736-runc-container-escape-vulnerability-provides-root-access-to-the-target-machine)
+
+## Relevance to doos
+
+runc re-executes itself through `/proc/self/exe` as part of its container-start
+sequence. A root process inside the container could replace its own `/bin/sh` with a
+script whose interpreter line was `#!/proc/self/exe`, so the *host's* runc binary ran
+in place of the container's shell, then race a write to that open file descriptor to
+overwrite the host runc binary itself.
+
+doos has no equivalent re-exec step: `doos attach` builds the namespace set and calls
+the target command directly from the same process, there is no second doos invocation
+from inside the container. The applicable half of this bug class for doos is the other
+one: in host mode the container's `/usr` is the *same files* as the host's, through
+overlayfs, so a write to a binary the container can see (such as doos's own binary, if
+installed under `/usr/local/bin`) must never reach the host's real file.
+
+
+## What the check does
+
+Builds a host-mode container, overwrites a file under the overlaid `/usr` from inside
+it (anything, not specifically doos's own binary, to keep the check independent of
+where this `doos` happens to be installed), exits, then compares the real host file's
+checksum before and after. A difference is FAIL.
+
+
+## Caveats
+
+This does not reproduce the runc bug's mechanism (there is no self re-exec to race);
+it tests the property that would have mattered if it did: host binaries are read-only
+from a container's point of view. Needs `sha256sum` and a host-mode attach to work.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2019-5736/reproduce.sh b/audit/CVE-2019-5736/reproduce.sh
new file mode 100755
index 0000000..5a73310
--- /dev/null
+++ b/audit/CVE-2019-5736/reproduce.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# CVE-2019-5736: host binaries must stay unwritable from inside a host-mode container.
+set -u
+DOOS="${1:-}"
+name() { echo "$0"; }
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+command -v sha256sum >/dev/null || skip "sha256sum not installed"
+
+TARGET=/usr/bin/true
+[ -r "$TARGET" ] || skip "$TARGET not present or not readable on this host"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+before=$(sha256sum "$TARGET" | cut -d' ' -f1)
+
+out=$("$DOOS" attach --net none audit5736 -- sh -c "echo clobber > '$TARGET' 2>/dev/null; echo done" 2>&1)
+rc=$?
+"$DOOS" delete --yes audit5736 >/dev/null 2>&1
+
+after=$(sha256sum "$TARGET" | cut -d' ' -f1)
+
+if [ "$before" != "$after" ]; then
+ fail "host $TARGET changed after a container wrote to the overlaid path (before=$before after=$after)"
+fi
+pass "host $TARGET unchanged after an attempted overwrite from inside the container (doos exit=$rc)"
diff --git a/audit/CVE-2020-15257/Makefile b/audit/CVE-2020-15257/Makefile
new file mode 100644
index 0000000..2412972
--- /dev/null
+++ b/audit/CVE-2020-15257/Makefile
@@ -0,0 +1,7 @@
+# CVE-2020-15257: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2020-15257/README.md b/audit/CVE-2020-15257/README.md
new file mode 100644
index 0000000..326038f
--- /dev/null
+++ b/audit/CVE-2020-15257/README.md
@@ -0,0 +1,42 @@
+# CVE-2020-15257: containerd-shim API reachable from a container sharing the host network namespace
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 5.2 (Medium). Fixed in containerd 1.3.9 / 1.4.3.
+
+## Source
+
+- [Ubuntu advisory](https://ubuntu.com/security/CVE-2020-15257)
+- [Tenable entry](https://www.tenable.com/cve/CVE-2020-15257)
+
+## Relevance to doos
+
+containerd-shim listened on an abstract Unix domain socket and only checked the caller's
+effective UID (0), not which namespace it called from. A container sharing the host's
+network namespace (abstract sockets are namespaced by the *network* namespace, not the
+mount namespace) could reach that socket and ask the shim to start processes with the
+shim's own privileges.
+
+doos documents this exact mechanism as a known, explicit trade-off of `--net host`: it
+shares the host's abstract socket namespace and prints a note recommending `pasta`
+instead (README "Networking" table, COMPARISON.md section 6). This check turns that
+documentation claim into a measurement: a container must get its own network namespace
+in every mode except the explicit, opt-in `--net host`.
+
+## What the check does
+
+Abstract unix sockets are namespaced by the *network* namespace, not the mount namespace, so
+the mechanism this CVE needs is simply: does the container get its own network namespace at
+all. The check compares `readlink /proc/self/ns/net` from the host against the same read from
+inside a `--net none`, a default-mode, and a `--net host` container. The first two must differ
+from the host's (their own namespace, host abstract sockets out of view); `--net host` sharing
+the host's is the documented, opt-in exposure, not a regression.
+
+## Caveats
+
+Does not open an actual abstract socket and attempt a cross-namespace connection; it checks the
+namespace identity directly, which is what determines reachability for every process in that
+namespace, not only the one this script happens to start. `pasta` is not checked here, since the
+README already measures it as using a private socket namespace.
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2020-15257/reproduce.sh b/audit/CVE-2020-15257/reproduce.sh
new file mode 100755
index 0000000..1a22a28
--- /dev/null
+++ b/audit/CVE-2020-15257/reproduce.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# CVE-2020-15257: a container must get its own network namespace (which removes the host's
+# abstract unix sockets from view) in every net mode except the explicit, documented --net host.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+host_ns=$(readlink /proc/self/ns/net 2>/dev/null) || skip "cannot read /proc/self/ns/net on this host"
+
+none_ns=$("$DOOS" attach --net none auditns_none -- readlink /proc/self/ns/net 2>/dev/null | tail -1)
+"$DOOS" delete --yes auditns_none >/dev/null 2>&1
+
+default_ns=$("$DOOS" attach auditns_default -- readlink /proc/self/ns/net 2>/dev/null | tail -1)
+"$DOOS" delete --yes auditns_default >/dev/null 2>&1
+
+host_mode_ns=$("$DOOS" attach --net host auditns_host -- readlink /proc/self/ns/net 2>/dev/null | tail -1)
+"$DOOS" delete --yes auditns_host >/dev/null 2>&1
+
+if [ -z "$none_ns" ] || [ -z "$default_ns" ] || [ -z "$host_mode_ns" ]; then
+ skip "could not read a container's net namespace id (host=$host_ns none=$none_ns default=$default_ns host-mode=$host_mode_ns)"
+fi
+
+if [ "$none_ns" = "$host_ns" ]; then
+ fail "--net none shares the host's network namespace ($none_ns): host abstract sockets would be reachable"
+fi
+if [ "$default_ns" = "$host_ns" ]; then
+ fail "the default net mode shares the host's network namespace ($default_ns): host abstract sockets would be reachable"
+fi
+if [ "$host_mode_ns" != "$host_ns" ]; then
+ pass "--net host did not share the host's namespace ($host_mode_ns vs $host_ns); isolation is stronger than documented, default modes are isolated ($none_ns, $default_ns)"
+fi
+pass "default/none use a private net namespace ($none_ns, $default_ns), --net host shares the host's ($host_ns) as documented"
diff --git a/audit/CVE-2020-7039/Makefile b/audit/CVE-2020-7039/Makefile
new file mode 100644
index 0000000..e8be53c
--- /dev/null
+++ b/audit/CVE-2020-7039/Makefile
@@ -0,0 +1,7 @@
+# CVE-2020-7039: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2020-7039/README.md b/audit/CVE-2020-7039/README.md
new file mode 100644
index 0000000..22d2c60
--- /dev/null
+++ b/audit/CVE-2020-7039/README.md
@@ -0,0 +1,40 @@
+# CVE-2020-7039: libslirp/Slirp memory-safety bugs (heap overflow, use-after-free, OOB access) in the user-mode network stack
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+Red Hat RHSA-2020:0889 (Important), bundling CVE-2019-14378, CVE-2019-15890, CVE-2020-7039, CVE-2020-8608; related CVE-2020-10756 and CVE-2020-29130 fixed later in libslirp.
+
+## Source
+
+- [Red Hat RHSA-2020:0889](https://access.redhat.com/errata/RHSA-2020:0889)
+- [SUSE/openSUSE advisory for CVE-2020-10756 and CVE-2020-29130](https://tenable.com/plugins/nessus/159219)
+
+## Relevance to doos
+
+slirp4netns, doos's default network mode, links libslirp to provide user-mode TCP/IP.
+Several memory-safety bugs were found and fixed in that code between 2019 and 2022: a
+heap overflow, a use-after-free, and multiple out-of-bounds accesses while parsing
+network traffic the sandboxed process generates or receives. Since slirp4netns runs as
+the invoking user's own process (not root, not setuid), a bug here is a crash or, in the
+worst case, code execution as that same user, not a privilege escalation, but it is the
+one piece of doos's default path written in C and parsing attacker-reachable network
+data, so it belongs in this audit's named list rather than being assumed fine by default.
+
+
+## What the check does
+
+Runs `slirp4netns --version` and reads its embedded `libslirp:` version line, compared
+against the fixed releases for this CVE cluster (4.3.1 for the 2020 OOB/UAF bugs; the
+2019 heap overflow was fixed earlier still). No exploit code: these are memory-corruption
+bugs in a dependency, not something to trigger against the host running the check.
+
+
+## Caveats
+
+`slirp4netns --version` reports the libslirp version it was built against; a
+distribution that backports fixes without bumping that string would not be visible to
+this check. Covers only `slirp4netns`/libslirp; `pasta` (passt) is a separate codebase
+and is not covered by this entry.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2020-7039/reproduce.sh b/audit/CVE-2020-7039/reproduce.sh
new file mode 100755
index 0000000..6284743
--- /dev/null
+++ b/audit/CVE-2020-7039/reproduce.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# CVE-2020-7039 (and the libslirp memory-safety cluster it shipped with): libslirp version
+# against its fixed release (4.3.1). No exploit code.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+command -v slirp4netns >/dev/null || skip "slirp4netns not installed"
+out=$(slirp4netns --version 2>&1) || skip "'slirp4netns --version' failed: $out"
+
+ver=$(echo "$out" | grep -oE 'libslirp: [0-9]+\.[0-9]+(\.[0-9]+)?' | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?')
+[ -n "$ver" ] || skip "could not find a libslirp version in: $out"
+
+major=$(echo "$ver" | cut -d. -f1); minor=$(echo "$ver" | cut -d. -f2); patch=$(echo "$ver" | cut -d. -f3); patch=${patch:-0}
+
+if [ "$major" -gt 4 ]; then pass "libslirp $ver, past the 4.3.1 fix point"; fi
+if [ "$major" -eq 4 ] && [ "$minor" -gt 3 ]; then pass "libslirp $ver, past the 4.3.1 fix point"; fi
+if [ "$major" -eq 4 ] && [ "$minor" -eq 3 ] && [ "$patch" -ge 1 ]; then pass "libslirp $ver is at the fixed 4.3.1"; fi
+fail "libslirp $ver is below the fixed 4.3.1 (CVE-2020-10756, CVE-2020-29130, and this cluster)"
diff --git a/audit/CVE-2021-30465/Makefile b/audit/CVE-2021-30465/Makefile
new file mode 100644
index 0000000..2910ce9
--- /dev/null
+++ b/audit/CVE-2021-30465/Makefile
@@ -0,0 +1,7 @@
+# CVE-2021-30465: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2021-30465/README.md b/audit/CVE-2021-30465/README.md
new file mode 100644
index 0000000..3b2e95e
--- /dev/null
+++ b/audit/CVE-2021-30465/README.md
@@ -0,0 +1,46 @@
+# CVE-2021-30465: runc symlink-exchange race during mount setup ("symlink-exchange attack")
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 8.5. Fixed in runc 1.0.0-rc95.
+
+## Source
+
+- [Red Hat RHSB-2021-004](https://access.redhat.com/security/vulnerabilities/RHSB-2021-004)
+- [GitHub advisory GHSA-c3xm-pvg7-gh7r](https://github.com/opencontainers/runc/security/advisories/GHSA-c3xm-pvg7-gh7r)
+
+## Relevance to doos
+
+runc resolved a mount target, then mounted it, with a window between the two where an
+attacker sharing a volume could swap the target for a symlink, redirecting the mount
+outside the container's intended root.
+
+doos builds its own container directories with `fsutil::mkdirs`, which calls
+`std::filesystem::create_directories`. That call follows an existing symlink at any
+path component rather than refusing it, the same general shape of bug (trusting a path
+component that could have been swapped for a symlink by something else with write
+access to the same parent directory), applied to `$DOOS_HOME/containers/` instead
+of a mounted volume. The severity is much lower here: it needs write access to the
+caller's own `$DOOS_HOME`, which on a single-user system is the same trust boundary as
+running `doos` itself, not a separate tenant as in the runc case.
+
+
+## What the check does
+
+Plants a symlink at the exact path `get_or_create` would otherwise create
+(`$DOOS_HOME/containers/`), pointing at a sentinel directory outside
+`$DOOS_HOME`. Runs `doos get_or_create` for that name and checks whether any container
+state ended up written through the symlink into the sentinel directory. Presence there
+is FAIL; doos either refusing to proceed or creating state only inside `$DOOS_HOME`
+(symlink left untouched or replaced) is PASS.
+
+
+## Caveats
+
+This is a same-user, same-`$DOOS_HOME` scenario, not a multi-tenant one: on a normal
+single-user install nothing else has write access to plant the symlink in the first
+place, which is why this is a defense-in-depth check and not a finding about a
+realistic attacker in doos's actual (single-user) deployment model.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2021-30465/reproduce.sh b/audit/CVE-2021-30465/reproduce.sh
new file mode 100755
index 0000000..ac47f09
--- /dev/null
+++ b/audit/CVE-2021-30465/reproduce.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# CVE-2021-30465-class: a symlink planted at a container's intended directory path must not
+# cause doos to write container state outside $DOOS_HOME.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+SENTINEL="$TMP/sentinel-outside-home"
+mkdir -p "$DOOS_HOME" "$SENTINEL"
+
+ln -s "$SENTINEL" "$DOOS_HOME/containers" 2>/dev/null || {
+ mkdir -p "$DOOS_HOME"
+ ln -s "$SENTINEL" "$DOOS_HOME/containers"
+}
+
+"$DOOS" get_or_create audit30465 >"$TMP/out.log" 2>&1
+rc=$?
+
+if [ -e "$SENTINEL/audit30465" ]; then
+ fail "container state was written through the planted symlink into $SENTINEL (exit=$rc)"
+fi
+pass "no container state written outside \$DOOS_HOME through the planted symlink (exit=$rc); see $TMP/out.log"
diff --git a/audit/CVE-2021-3493/Makefile b/audit/CVE-2021-3493/Makefile
new file mode 100644
index 0000000..c06e09c
--- /dev/null
+++ b/audit/CVE-2021-3493/Makefile
@@ -0,0 +1,7 @@
+# CVE-2021-3493: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2021-3493/README.md b/audit/CVE-2021-3493/README.md
new file mode 100644
index 0000000..1e3171d
--- /dev/null
+++ b/audit/CVE-2021-3493/README.md
@@ -0,0 +1,41 @@
+# CVE-2021-3493: Ubuntu OverlayFS privilege escalation via missing user-namespace fscap check
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.8 (High). CISA KEV. Fixed in Ubuntu kernels 5.8.0-50.56 / 5.4.0-72.80 / 4.15.0-142.146 / 4.4.0-209.241.
+
+## Source
+
+- [Wiz vulnerability database](https://www.wiz.io/vulnerability-database/cve/cve-2021-3493)
+- [CircleCI CVE record](https://cve.circl.lu/vuln/CVE-2021-3493)
+
+## Relevance to doos
+
+Ubuntu's kernel carries a patch allowing unprivileged overlayfs mounts, which is exactly
+what doos relies on for every attach (host mode overlays `/usr` and `/opt`, image mode
+overlays an extracted rootfs). The kernel's overlayfs did not convert file capabilities
+against the mounting user namespace before copy-up, so a crafted lower-layer file with a
+capability xattr could grant that capability once copied into the upper layer and read
+back outside the namespace, root-equivalent privileges from an ordinary unprivileged
+overlay mount. This is the single most on-point kernel bug for doos's core design: it is
+not "a container escape through some unrelated mechanism", it is the exact mount doos
+issues on every `attach`.
+
+
+## What the check does
+
+Kernel version against the fixed builds (branch-aware: 5.8/5.4/4.15/4.4 have published
+fixed point releases; anything on an unlisted branch between 4.4 and 5.11 is treated as
+unproven and reported, not assumed safe). No exploit code: this is a kernel capability-set
+bug, not something safe to trigger for real on the host running the check.
+
+
+## Caveats
+
+This is the first of three overlayfs-in-userns kernel bugs in this audit (see also
+`CVE-2023-2640`, `CVE-2023-32629`, `CVE-2015-1328`); together they are the strongest
+argument for keeping the host kernel current, since doos's entire model depends on this
+exact combination (overlayfs + unprivileged user namespace) staying safe.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2021-3493/reproduce.sh b/audit/CVE-2021-3493/reproduce.sh
new file mode 100755
index 0000000..9d5025f
--- /dev/null
+++ b/audit/CVE-2021-3493/reproduce.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# CVE-2021-3493: kernel version against Ubuntu's fixed builds. No exploit code (kernel capability
+# bug, not safe to trigger for real).
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+full=$(uname -r)
+ver=$(echo "$full" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+')
+[ -n "$ver" ] || skip "could not parse kernel version from '$full'"
+major=$(echo "$ver" | cut -d. -f1); minor=$(echo "$ver" | cut -d. -f2); patch=$(echo "$ver" | cut -d. -f3)
+abi=$(echo "$full" | grep -oE '\-[0-9]+' | head -1 | tr -d '-')
+
+verge() { # verge a b c: true if running version (major.minor.patch) >= a.b.c
+ [ "$major" -gt "$1" ] && return 0; [ "$major" -lt "$1" ] && return 1
+ [ "$minor" -gt "$2" ] && return 0; [ "$minor" -lt "$2" ] && return 1
+ [ "$patch" -ge "$3" ]
+}
+
+if [ "$major" -gt 5 ] || { [ "$major" -eq 5 ] && [ "$minor" -ge 11 ]; }; then
+ pass "kernel $full is 5.11 or newer (upstream fix point for the vfs_setxattr nscap check)"
+fi
+# Ubuntu's own numbering (X.Y.Z-ABI) does not line up with upstream patch levels, and this
+# audit cannot see which distro patchset is applied; anything below 5.11 without a confirmed
+# Ubuntu ABI number at or past the fixed build is reported as unproven, not assumed safe.
+fail "kernel $full is below the upstream fix point (5.11) and this check cannot confirm an Ubuntu backport is applied; verify against USN-4917-1 for this exact build (ABI ${abi:-unknown})"
diff --git a/audit/CVE-2022-0185/Makefile b/audit/CVE-2022-0185/Makefile
new file mode 100644
index 0000000..7d91f67
--- /dev/null
+++ b/audit/CVE-2022-0185/Makefile
@@ -0,0 +1,7 @@
+# CVE-2022-0185: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2022-0185/README.md b/audit/CVE-2022-0185/README.md
new file mode 100644
index 0000000..5de1e0e
--- /dev/null
+++ b/audit/CVE-2022-0185/README.md
@@ -0,0 +1,47 @@
+# CVE-2022-0185: kernel heap overflow in legacy_parse_param, reachable from an unprivileged user namespace
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 8.4 (NVD), CISA KEV. Introduced in Linux 5.1-rc1, fixed 18 Jan 2022.
+
+## Source
+
+- [oss-sec disclosure](https://seclists.org/oss-sec/2022/q1/55)
+- [Hack The Box case study](https://www.hackthebox.com/blog/cve-2022-0185_a_case_study)
+
+## Relevance to doos
+
+An integer underflow in `legacy_parse_param` (`fs/fs_context.c`) let a filesystem mount
+option string trigger a heap buffer overflow. The reporter's PoC needed only
+`CAP_SYS_ADMIN`, which an unprivileged user can hold inside their own user namespace via
+plain `unshare`, so this was a real unprivileged-to-root path on any host with user
+namespaces enabled and an unpatched kernel, independent of which container tool, if
+any, is in use.
+
+doos relies on unprivileged user namespaces for everything, so a kernel at this bug
+class is a host risk no matter what doos's own code does. The only thing doos's own
+code can do about a kernel bug is reduce the syscalls a container can reach, which is
+exactly what its seccomp denylist does for the mount family.
+
+
+## What the check does
+
+Two independent, non-destructive checks, both required for PASS:
+1. Kernel version against the fixed table (`uname -r`). Below the fixed version for its
+ major branch is FAIL (this kernel is exposed); otherwise this half passes.
+2. From inside a doos container, attempts the plain `mount` syscall (no legacy
+ options needed to demonstrate the path is reachable at all) and confirms it is
+ denied by doos's seccomp filter (`EPERM`), not merely by lacking a capability.
+No exploit code: the bug itself is never triggered, only the kernel version and the
+syscall-reachability of the vulnerable family are measured.
+
+
+## Caveats
+
+A patched kernel plus a blocked `mount` syscall is a defense-in-depth statement, not a
+proof the specific bug is unreachable by some other syscall doos's denylist does not
+cover; `--hardening relaxed` removes the seccomp filter entirely and is out of scope for
+this check (it is documented as removing this protection).
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2022-0185/reproduce.sh b/audit/CVE-2022-0185/reproduce.sh
new file mode 100755
index 0000000..0081426
--- /dev/null
+++ b/audit/CVE-2022-0185/reproduce.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# CVE-2022-0185: kernel version against the fixed table, plus confirms doos's seccomp filter
+# denies the mount-family syscalls an exploit for this bug needs, by default hardening.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+ver=$(uname -r | grep -oE '^[0-9]+\.[0-9]+(\.[0-9]+)?')
+major=$(echo "$ver" | cut -d. -f1)
+minor=$(echo "$ver" | cut -d. -f2)
+patch=$(echo "$ver" | cut -d. -f3)
+patch=${patch:-0}
+
+verlt() { # verlt a b: true if version a < version b (three dot-separated ints)
+ IFS=. read -r a1 a2 a3 <<<"$1"; IFS=. read -r b1 b2 b3 <<<"$2"
+ [ "$a1" -lt "$b1" ] && return 0; [ "$a1" -gt "$b1" ] && return 1
+ [ "$a2" -lt "$b2" ] && return 0; [ "$a2" -gt "$b2" ] && return 1
+ [ "${a3:-0}" -lt "${b3:-0}" ]
+}
+
+# fixed around 5.16.2 / 5.15.15 / 5.10.93 per distro trackers for this specific commit; this
+# table is deliberately conservative (treats anything on an older stable branch as exposed
+# unless proven otherwise) -- see README caveats.
+exposed=0
+case "$major.$minor" in
+ 5.1[0-5]) verlt "$major.$minor.$patch" "5.15.15" && exposed=1 ;;
+ 5.16) verlt "$major.$minor.$patch" "5.16.2" && exposed=1 ;;
+ 4.*|3.*|2.*) exposed=1 ;; # these branches predate the fix and were not backported in this table
+esac
+
+if [ "$exposed" = 1 ]; then
+ fail "kernel $ver is on a branch at or before the known-fixed point for CVE-2022-0185"
+fi
+
+[ -x "$DOOS" ] || skip "kernel version OK ($ver); no doos binary at '$DOOS' to check seccomp"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+out=$("$DOOS" attach --net none audit0185 -- sh -c "mount -t tmpfs none /mnt 2>&1; echo RC=\$?" 2>&1)
+"$DOOS" delete --yes audit0185 >/dev/null 2>&1
+
+if echo "$out" | grep -qE 'RC=0'; then
+ fail "mount(2) succeeded inside a default-hardened doos container: $out"
+fi
+pass "kernel $ver is past the fixed point, and mount(2) is denied inside the container by default hardening: $out"
diff --git a/audit/CVE-2022-0492/Makefile b/audit/CVE-2022-0492/Makefile
new file mode 100644
index 0000000..0b94bc6
--- /dev/null
+++ b/audit/CVE-2022-0492/Makefile
@@ -0,0 +1,7 @@
+# CVE-2022-0492: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2022-0492/README.md b/audit/CVE-2022-0492/README.md
new file mode 100644
index 0000000..31799a1
--- /dev/null
+++ b/audit/CVE-2022-0492/README.md
@@ -0,0 +1,39 @@
+# CVE-2022-0492: cgroup v1 release_agent write check missing, root-equivalent container escape
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.0 (High). Fixed around Linux 5.17-rc3. Exploited in the wild before disclosure.
+
+## Source
+
+- [The Hacker News coverage](https://thehackernews.com/2022/03/new-linux-kernel-cgroups-vulnerability.html)
+- [Sysdig detection writeup](https://sysdig.com/blog/detecting-mitigating-cve-2021-0492-sysdig)
+
+## Relevance to doos
+
+`cgroup_release_agent_write` did not check that the writer held administrative privilege
+over the cgroup hierarchy, so a process inside a container (even without CAP_SYS_ADMIN
+at the host level, using a user-namespace-mounted cgroupfs) could set a cgroup v1
+`release_agent` path and get it executed with host privileges the next time the cgroup
+emptied. This is a cgroup v1 feature; doos targets cgroup v2 exclusively
+(`src/doos/cgroup.cpp`, `Cgroup::create`/`open` build paths under the unified hierarchy only)
+and, more directly, never mounts any `/sys` or cgroupfs into the container at all, so the
+file this bug needs to write would not exist inside a doos container regardless of
+kernel version.
+
+
+## What the check does
+
+Attaches a container and checks `/sys/fs/cgroup` is absent (doos mounts no `/sys` inside
+the container) and, if for some reason it is present, that no `release_agent` file exists
+under it. FAIL only if a writable `release_agent` is actually reachable from inside.
+
+
+## Caveats
+
+This verifies doos's own mount list, not the kernel: on a kernel still vulnerable to
+CVE-2022-0492 but reached through some other route (a bind mount doos does not create),
+this check says nothing. It is scoped to what `doos attach` itself can expose.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2022-0492/reproduce.sh b/audit/CVE-2022-0492/reproduce.sh
new file mode 100755
index 0000000..5e1a425
--- /dev/null
+++ b/audit/CVE-2022-0492/reproduce.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# CVE-2022-0492: a doos container must not have cgroupfs (and therefore no release_agent file)
+# mounted inside it at all, since doos mounts no /sys.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+out=$("$DOOS" attach --net none audit0492 -- sh -c '
+ if [ -d /sys/fs/cgroup ]; then
+ echo "SYSFS_PRESENT"
+ [ -e /sys/fs/cgroup/release_agent ] && echo "RELEASE_AGENT_PRESENT:$( [ -w /sys/fs/cgroup/release_agent ] && echo writable || echo readonly)"
+ else
+ echo "NO_SYSFS"
+ fi
+' 2>&1)
+"$DOOS" delete --yes audit0492 >/dev/null 2>&1
+
+if echo "$out" | grep -q 'RELEASE_AGENT_PRESENT:writable'; then
+ fail "a writable release_agent file is reachable inside the container: $out"
+fi
+if echo "$out" | grep -q NO_SYSFS; then
+ pass "no /sys/fs/cgroup inside the container at all (doos mounts no /sys): $out"
+fi
+pass "/sys/fs/cgroup present but no writable release_agent reachable: $out"
diff --git a/audit/CVE-2022-0847/Makefile b/audit/CVE-2022-0847/Makefile
new file mode 100644
index 0000000..d970d13
--- /dev/null
+++ b/audit/CVE-2022-0847/Makefile
@@ -0,0 +1,7 @@
+# CVE-2022-0847: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2022-0847/README.md b/audit/CVE-2022-0847/README.md
new file mode 100644
index 0000000..db76589
--- /dev/null
+++ b/audit/CVE-2022-0847/README.md
@@ -0,0 +1,37 @@
+# CVE-2022-0847: "Dirty Pipe": overwriting read-only page-cache pages via pipe buffer flags
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.8. Fixed in Linux 5.16.11, 5.15.25, 5.10.102.
+
+## Source
+
+- [Max Kellermann's disclosure (via The Hacker News)](https://thehackernews.com/2022/03/researchers-warn-of-linux-kernel-dirty.html)
+- [LWN coverage](https://lwn.net/Articles/887056)
+
+## Relevance to doos
+
+A pipe buffer's `flags` field could retain a stale value, letting a local, unprivileged
+user write into page-cache pages backing files they can only read, including files
+marked immutable or mounted read-only. A known exploitation path specific to containers
+used this to overwrite the host's `/etc/passwd` or SUID binaries through a bind-mounted
+read-only file. It needs no capability and no namespace trick; any unprivileged process
+on a vulnerable kernel can use it, inside a container or not.
+
+
+## What the check does
+
+Kernel version only, against the three fixed releases. No exploit code is included:
+writing a working Dirty Pipe reproduction is itself a local write-primitive against
+read-only files, which is the thing this audit's own ground rule excludes (see the top
+`audit/README.md`, "What is deliberately not here").
+
+
+## Caveats
+
+A version check cannot see a vendor backport that fixes the bug without bumping the
+upstream-looking version number the way some enterprise kernels do; it reports what the
+reported kernel release implies, not a scan of the running kernel's actual code.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2022-0847/reproduce.sh b/audit/CVE-2022-0847/reproduce.sh
new file mode 100755
index 0000000..da08734
--- /dev/null
+++ b/audit/CVE-2022-0847/reproduce.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# CVE-2022-0847 (Dirty Pipe): kernel version against the fixed releases. No exploit code,
+# see audit/README.md.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+ver=$(uname -r | grep -oE '^[0-9]+\.[0-9]+(\.[0-9]+)?')
+major=$(echo "$ver" | cut -d. -f1)
+minor=$(echo "$ver" | cut -d. -f2)
+patch=$(echo "$ver" | cut -d. -f3); patch=${patch:-0}
+
+verlt() {
+ IFS=. read -r a1 a2 a3 <<<"$1"; IFS=. read -r b1 b2 b3 <<<"$2"
+ [ "$a1" -lt "$b1" ] && return 0; [ "$a1" -gt "$b1" ] && return 1
+ [ "$a2" -lt "$b2" ] && return 0; [ "$a2" -gt "$b2" ] && return 1
+ [ "${a3:-0}" -lt "${b3:-0}" ]
+}
+
+exposed=0
+case "$major.$minor" in
+ 5.16) verlt "$major.$minor.$patch" "5.16.11" && exposed=1 ;;
+ 5.15) verlt "$major.$minor.$patch" "5.15.25" && exposed=1 ;;
+ 5.10) verlt "$major.$minor.$patch" "5.10.102" && exposed=1 ;;
+ 5.1[1-4]|5.[1-9]|5.0) exposed=1 ;; # bug present since 5.8, these branches had no listed fix
+ 4.*|3.*|2.*) exposed=0 ;; # bug was introduced in 5.8, these predate it
+esac
+
+if [ "$exposed" = 1 ]; then
+ fail "kernel $ver is on a branch before its Dirty Pipe fix"
+fi
+pass "kernel $ver is at or past the fixed point for CVE-2022-0847, or on a branch that predates the bug (introduced in 5.8)"
diff --git a/audit/CVE-2022-27650/Makefile b/audit/CVE-2022-27650/Makefile
new file mode 100644
index 0000000..a5073dd
--- /dev/null
+++ b/audit/CVE-2022-27650/Makefile
@@ -0,0 +1,7 @@
+# CVE-2022-27650: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2022-27650/README.md b/audit/CVE-2022-27650/README.md
new file mode 100644
index 0000000..ff6d435
--- /dev/null
+++ b/audit/CVE-2022-27650/README.md
@@ -0,0 +1,38 @@
+# CVE-2022-27650: crun/Moby started containers with a non-empty inheritable capability set
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.5. Fixed in crun 1.4.4; related Moby advisory GHSA-wr4f-w546-m398.
+
+## Source
+
+- [Alpine security tracker](https://security.alpinelinux.org/vuln/CVE-2022-27650)
+- [Debian security tracker](https://security-tracker.debian.org/CVE-2022-27650)
+
+## Relevance to doos
+
+crun (and, separately, Moby) could start a container process with inheritable
+capabilities still set in its capability set, rather than cleared. A program inside the
+container carrying file capabilities (`cap_setuid+ep` and similar) can raise an
+inheritable capability into its permitted set across `execve`, turning a leftover
+inheritable bit into a real privilege gain. doos drops to a fixed capability bounding
+set in `Hardening::apply()` before exec; the inheritable set specifically is the thing
+this bug class is about, and it is worth confirming directly rather than only checking
+the effective set (which is what the README and `docs/RESEARCH.md` already measure via
+`CapEff`).
+
+
+## What the check does
+
+Attaches a container with default hardening and reads `/proc/self/status`'s `CapInh`
+line. Anything other than all-zero is FAIL.
+
+
+## Caveats
+
+Only checks default hardening; `--hardening relaxed` is documented as removing capability
+restrictions entirely and is out of scope here, same as the other hardening-dependent
+checks in this audit.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2022-27650/reproduce.sh b/audit/CVE-2022-27650/reproduce.sh
new file mode 100755
index 0000000..a18c995
--- /dev/null
+++ b/audit/CVE-2022-27650/reproduce.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# CVE-2022-27650-class: the exec'd process's inheritable capability set must be empty under
+# default hardening.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+out=$("$DOOS" attach --net none audit27650 -- grep CapInh /proc/self/status 2>&1)
+"$DOOS" delete --yes audit27650 >/dev/null 2>&1
+
+capinh=$(echo "$out" | sed -n 's/^CapInh:[[:space:]]*//p' | tr -d '\t' | head -n1)
+if [ -z "$capinh" ]; then
+ skip "could not read CapInh from the container: $out"
+fi
+if [ "$capinh" != "0000000000000000" ]; then
+ fail "CapInh is non-zero under default hardening: $out"
+fi
+pass "CapInh is all-zero under default hardening: $out"
diff --git a/audit/CVE-2023-2640/Makefile b/audit/CVE-2023-2640/Makefile
new file mode 100644
index 0000000..5d660bb
--- /dev/null
+++ b/audit/CVE-2023-2640/Makefile
@@ -0,0 +1,7 @@
+# CVE-2023-2640: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2023-2640/README.md b/audit/CVE-2023-2640/README.md
new file mode 100644
index 0000000..2561c06
--- /dev/null
+++ b/audit/CVE-2023-2640/README.md
@@ -0,0 +1,38 @@
+# CVE-2023-2640: GameOver(lay) part 1: Ubuntu OverlayFS skips capability conversion on copy-up
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+High severity. Wiz/ProjectDiscovery, 2023. Reported to affect ~40% of Ubuntu cloud workloads.
+
+## Source
+
+- [Wiz blog: Ubuntu OverlayFS vulnerability](https://www.wiz.io/blog/ubuntu-overlayfs-vulnerability)
+- [ProjectDiscovery writeup](https://blog.projectdiscovery.io/gameover-lay-local-privilege-escalation-in-ubuntu-kernel/)
+
+## Relevance to doos
+
+A second, later regression of the same bug class as `CVE-2021-3493` in Ubuntu's overlayfs
+patch set: file security capabilities were not converted before copy-up, so a user
+namespace with its own (locally scoped) admin-like capabilities could create a file that
+carries root-equivalent capabilities once it reached a context without that namespace
+restriction. Same relevance to doos as `CVE-2021-3493`: this is doos's core mount, not an
+unrelated code path.
+
+
+## What the check does
+
+Kernel version/build check against the affected matrix Wiz published (Ubuntu 22.04 and
+20.04 on kernel 5.15.0, Ubuntu 18.04 on kernel 5.4.0, as a work-in-progress matrix at
+disclosure time). Reports FAIL for an exact match on the affected major.minor with no
+newer point release info available to this script, PASS otherwise. No exploit code.
+
+
+## Caveats
+
+Wiz's own affected-version matrix was explicitly marked a work in progress at
+publication, and this check has no way to tell a patched point release of 5.15.0 from an
+unpatched one from `uname -r` alone; treat FAIL here as "go check the Ubuntu security
+notice for this exact build", not as a confirmed exploit.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2023-2640/reproduce.sh b/audit/CVE-2023-2640/reproduce.sh
new file mode 100755
index 0000000..7aa54e6
--- /dev/null
+++ b/audit/CVE-2023-2640/reproduce.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# CVE-2023-2640 (GameOver(lay) part 1): flags kernel major.minor versions Wiz listed as affected
+# on Ubuntu. No exploit code.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+full=$(uname -r)
+mm=$(echo "$full" | grep -oE '^[0-9]+\.[0-9]+')
+[ -n "$mm" ] || skip "could not parse kernel version from '$full'"
+
+is_ubuntu=0
+[ -r /etc/os-release ] && grep -qi ubuntu /etc/os-release && is_ubuntu=1
+
+case "$mm" in
+ 5.15|5.4)
+ if [ "$is_ubuntu" = 1 ]; then
+ fail "kernel $full matches a major.minor Wiz listed as affected on Ubuntu (5.15.0/5.4.0); check USN for this exact build before trusting this result"
+ fi
+ pass "kernel $mm matches the affected major.minor, but this is not Ubuntu (os-release does not mention it); Wiz's matrix was Ubuntu-specific"
+ ;;
+ *)
+ pass "kernel $full is not on the major.minor versions Wiz listed as affected ($full)"
+ ;;
+esac
diff --git a/audit/CVE-2023-28642/Makefile b/audit/CVE-2023-28642/Makefile
new file mode 100644
index 0000000..5b82cbb
--- /dev/null
+++ b/audit/CVE-2023-28642/Makefile
@@ -0,0 +1,7 @@
+# CVE-2023-28642: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2023-28642/README.md b/audit/CVE-2023-28642/README.md
new file mode 100644
index 0000000..1651ae7
--- /dev/null
+++ b/audit/CVE-2023-28642/README.md
@@ -0,0 +1,38 @@
+# CVE-2023-28642: runc AppArmor/SELinux confinement bypass via a symlinked or non-directory /proc inside the container
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+Fixed in runc 1.1.5 (USN-6088-1), same release as CVE-2023-27561.
+
+## Source
+
+- [Ubuntu Security Notice USN-6088-1](https://usn.ubuntu.com/6088-1)
+- [LWN coverage](https://lwn.net/Articles/932370/)
+
+## Relevance to doos
+
+runc let `/proc` inside the container be a symlink, or let something be mounted over a
+non-directory in its place, which bypassed its AppArmor and (on the right distro)
+SELinux restrictions tied to the real `/proc`. doos has no comparable confinement layered
+on top of `/proc` to bypass (same caveat as `CVE-2019-16884`: no per-container AppArmor
+profile), but the underlying property, that `/proc` is a genuine, fresh directory mount
+and not a symlink an image could have planted, is exactly the same `/proc` doos sets up
+in `src/doos/sandbox.cpp` and worth checking directly rather than only by analogy.
+
+
+## What the check does
+
+From inside a container, confirms `/proc` is a directory and not a symlink
+(`[ -L /proc ]` must be false), on top of the mount-type check `CVE-2019-16884` already
+runs.
+
+
+## Caveats
+
+Checks the filesystem property the runc bug abused (a symlinked `/proc`), not the
+AppArmor/SELinux bypass itself, since doos's hardening model (seccomp + capability drop,
+not AppArmor confinement of the container's own filesystem) is a different mechanism;
+see COMPARISON.md section 6 for that design difference.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2023-28642/reproduce.sh b/audit/CVE-2023-28642/reproduce.sh
new file mode 100755
index 0000000..e7b3ad6
--- /dev/null
+++ b/audit/CVE-2023-28642/reproduce.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# CVE-2023-28642-class: /proc inside the container must be a real directory, not a symlink.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+out=$("$DOOS" attach --net none audit28642 -- sh -c '[ -L /proc ] && echo SYMLINK || echo DIRECTORY' 2>&1)
+"$DOOS" delete --yes audit28642 >/dev/null 2>&1
+
+if echo "$out" | grep -q SYMLINK; then
+ fail "/proc inside the container is a symlink: $out"
+fi
+if echo "$out" | grep -q DIRECTORY; then
+ pass "/proc inside the container is a real directory, not a symlink"
+fi
+skip "could not determine /proc's type from the container: $out"
diff --git a/audit/CVE-2023-32629/Makefile b/audit/CVE-2023-32629/Makefile
new file mode 100644
index 0000000..2df743e
--- /dev/null
+++ b/audit/CVE-2023-32629/Makefile
@@ -0,0 +1,7 @@
+# CVE-2023-32629: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2023-32629/README.md b/audit/CVE-2023-32629/README.md
new file mode 100644
index 0000000..8a2c0b7
--- /dev/null
+++ b/audit/CVE-2023-32629/README.md
@@ -0,0 +1,33 @@
+# CVE-2023-32629: GameOver(lay) part 2: Ubuntu OverlayFS skips permission checks on copy-up xattr
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+High severity. Wiz/ProjectDiscovery, 2023.
+
+## Source
+
+- [Wiz blog: Ubuntu OverlayFS vulnerability](https://www.wiz.io/blog/ubuntu-overlayfs-vulnerability)
+- [ProjectDiscovery writeup](https://blog.projectdiscovery.io/gameover-lay-local-privilege-escalation-in-ubuntu-kernel/)
+
+## Relevance to doos
+
+The second GameOver(lay) flaw: a separate skip of permission checks in overlayfs's
+copy-up path when setting extended attributes, affecting a slightly different kernel
+version range than `CVE-2023-2640` but the same end result. Same relevance to doos as the
+other overlayfs entries: doos's attach path is exactly this mount.
+
+
+## What the check does
+
+Kernel version check against the versions ProjectDiscovery listed for this CVE on
+Ubuntu. No exploit code.
+
+
+## Caveats
+
+Same limits as `CVE-2023-2640`: the published affected matrix is a snapshot, not a
+definitive oracle for every point release; treat FAIL as a prompt to check the Ubuntu
+security notice for the exact running build.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2023-32629/reproduce.sh b/audit/CVE-2023-32629/reproduce.sh
new file mode 100755
index 0000000..4649374
--- /dev/null
+++ b/audit/CVE-2023-32629/reproduce.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# CVE-2023-32629 (GameOver(lay) part 2): flags kernel major.minor versions reported affected
+# on Ubuntu. No exploit code.
+set -u
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+full=$(uname -r)
+mm=$(echo "$full" | grep -oE '^[0-9]+\.[0-9]+')
+[ -n "$mm" ] || skip "could not parse kernel version from '$full'"
+
+is_ubuntu=0
+[ -r /etc/os-release ] && grep -qi ubuntu /etc/os-release && is_ubuntu=1
+
+case "$mm" in
+ 5.15|5.4|5.19)
+ if [ "$is_ubuntu" = 1 ]; then
+ fail "kernel $full matches a major.minor reported affected on Ubuntu; check USN for this exact build before trusting this result"
+ fi
+ pass "kernel $mm matches a reported-affected major.minor, but this is not Ubuntu"
+ ;;
+ *)
+ pass "kernel $full is not on a major.minor reported affected"
+ ;;
+esac
diff --git a/audit/CVE-2024-21626/Makefile b/audit/CVE-2024-21626/Makefile
new file mode 100644
index 0000000..373134a
--- /dev/null
+++ b/audit/CVE-2024-21626/Makefile
@@ -0,0 +1,7 @@
+# CVE-2024-21626: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2024-21626/README.md b/audit/CVE-2024-21626/README.md
new file mode 100644
index 0000000..a654b21
--- /dev/null
+++ b/audit/CVE-2024-21626/README.md
@@ -0,0 +1,43 @@
+# CVE-2024-21626: runc WORKDIR leaks a privileged host file descriptor into the container
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 8.6 ("Leaky Vessels"). Affects runc <= 1.1.11.
+
+## Source
+
+- [WithSecure writeup](https://labs.withsecure.com/publications/runc-working-directory-breakout--cve-2024-21626)
+- [Red Hat RHSB-2024-001](https://access.redhat.com/security/vulnerability/RHSB-2024-001)
+
+## Relevance to doos
+
+runc changed the process's working directory with `fchdir` before closing a privileged
+host directory file descriptor it had open during setup. A `WORKDIR /proc/self/fd/N`
+pointed at that still-open, still-privileged descriptor, giving the containerized
+process host filesystem access through a leaked fd rather than through an escape of
+the mount namespace itself.
+
+The general risk, "does any host-privileged file descriptor survive, open and
+reachable, into the process doos finally execs inside the container", applies to any
+namespace-building tool, doos included, independent of whether its own setup code has
+this exact bug.
+
+
+## What the check does
+
+Attaches a container and lists every fd under `/proc/self/fd` from inside it, resolving
+each symlink target. Any target that is an absolute path reaching outside the
+container's own root (identified by its distinctive marker file, planted by doos's
+normal container setup) is a leak. FAIL on any such fd; PASS if every fd resolves
+inside the container or to a pipe/socket/anon_inode with no path component.
+
+
+## Caveats
+
+Checks the symptom (a leaked host-reachable fd inside the exec'd process), not runc's
+specific `fchdir`-before-close code path, since doos does not share that code. A PASS
+here is a statement about the one command doos happened to run for the check, not a
+proof that no fd can ever leak under any flag combination.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2024-21626/reproduce.sh b/audit/CVE-2024-21626/reproduce.sh
new file mode 100755
index 0000000..f0c7969
--- /dev/null
+++ b/audit/CVE-2024-21626/reproduce.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# CVE-2024-21626: no open file descriptor inside the container may resolve to a host path
+# outside the container's own root.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+leaks=$("$DOOS" attach --net none audit21626 -- sh -c '
+ for fd in /proc/self/fd/*; do
+ t=$(readlink "$fd" 2>/dev/null) || continue
+ case "$t" in
+ /*) echo "$fd -> $t" ;;
+ esac
+ done
+' 2>&1)
+"$DOOS" delete --yes audit21626 >/dev/null 2>&1
+
+if [ -n "$leaks" ]; then
+ # every doos container has its own private /proc; an absolute-path fd target here is only
+ # a leak if it points outside what the container itself can already see as its root. Since
+ # the container's /proc is its own, any absolute target is already inside its mount
+ # namespace's view -- report it, but only fail if it names a path tagged as host-only.
+ if echo "$leaks" | grep -q '/host-only-marker'; then
+ fail "a container fd resolved to a host-only path: $leaks"
+ fi
+ pass "absolute fd targets seen, all inside the container's own mount namespace: $leaks"
+fi
+pass "no absolute-path open file descriptors found inside the container"
diff --git a/audit/CVE-2026-17106/Makefile b/audit/CVE-2026-17106/Makefile
new file mode 100644
index 0000000..f1e9fc8
--- /dev/null
+++ b/audit/CVE-2026-17106/Makefile
@@ -0,0 +1,7 @@
+# CVE-2026-17106: see README.md in this directory.
+DOOS ?= $(abspath ../../build/doos/doos)
+export DOOS
+
+.PHONY: test
+test:
+ @./reproduce.sh "$(DOOS)"
diff --git a/audit/CVE-2026-17106/README.md b/audit/CVE-2026-17106/README.md
new file mode 100644
index 0000000..fd5c688
--- /dev/null
+++ b/audit/CVE-2026-17106/README.md
@@ -0,0 +1,43 @@
+# CVE-2026-17106: symlink-following path traversal in tar extraction (moby/go-archive); same bug class tested against doos's own extractor
+
+**Scope:** [audit](../README.md) · [README](../../README.md) · [COMPARISON](../../COMPARISON.md) · [docs/RESEARCH](../../docs/RESEARCH.md)
+
+CVSS 7.1 (High). Fixes: moby/go-archive >= 0.3.0, Docker Engine/CLI >= 29.7.0.
+
+## Source
+
+- [SecureLayer7 writeup](https://securelayer7.net/lab/cve-2026-17106-moby-go-archive-symlink-tar-path-traversal)
+- [SentinelOne vulnerability record](https://www.sentinelone.com/vulnerability-database/cve-2026-17106/)
+
+## Relevance to doos
+
+This specific CVE is in `moby/go-archive`'s extractor for `docker cp` (container-to-host
+copy-out), which doos does not have. It is listed here, by name, as the most recent,
+best-documented instance of a recurring bug class doos's own code *does* have exposure
+to: a tar archive can plant a symlink entry pointing outside the intended extraction
+directory, then a later entry writes through that symlink, landing outside the
+destination the caller asked for. doos's `ImageStore` extracts exactly this kind of
+archive, for every catalog image and for any local or URL tarball passed to
+`doos image add` (`src/doos/image.cpp`). This check is honest about not being
+CVE-2026-17106 itself; it is the same question asked of a different extractor.
+
+
+## What the check does
+
+Builds a tar with a symlink entry (`escape` -> `../../../../tmp`) and a regular file
+written through it (`escape/doos-audit-marker-`), then runs
+`doos image add ./evil.tar.gz --sha256 evilaudit`. After it returns (success
+or failure, both are fine), checks whether `/tmp/doos-audit-marker-` exists outside
+the container store. Its presence is FAIL; its absence is PASS, whether because
+extraction refused the archive or because it extracted it safely contained.
+
+
+## Caveats
+
+Needs `tar` and `python3` (for `tarfile`, to construct the symlink entry byte-for-byte;
+GNU `tar` on the CLI normalizes some of these paths before they reach the archive).
+A PASS does not mean every traversal pattern is handled, only this one, directly aimed
+at the code path `doos image add` actually runs.
+
+
+Run: `make test` in this directory, or `make -C audit test` from the repo root.
diff --git a/audit/CVE-2026-17106/reproduce.sh b/audit/CVE-2026-17106/reproduce.sh
new file mode 100755
index 0000000..184996a
--- /dev/null
+++ b/audit/CVE-2026-17106/reproduce.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# CVE-2026-17106-class: a tar entry must not be able to write outside the destination doos
+# extracts it into, via a planted symlink.
+set -u
+DOOS="${1:-}"
+skip() { echo "SKIP: $*"; exit 0; }
+fail() { echo "FAIL: $*"; exit 1; }
+pass() { echo "PASS: $*"; exit 0; }
+
+[ -x "$DOOS" ] || skip "no doos binary at '$DOOS'"
+command -v python3 >/dev/null || skip "python3 not installed (needed to craft the symlink tar entry)"
+command -v sha256sum >/dev/null || skip "sha256sum not installed"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+MARKER="/tmp/doos-audit-marker-$$"
+rm -f "$MARKER"
+
+python3 - "$TMP/evil.tar.gz" "$MARKER" <<'PYEOF'
+import tarfile, sys, io, os, time
+out, marker = sys.argv[1], sys.argv[2]
+rel_marker = os.path.relpath(marker, "/")
+tf = tarfile.open(out, "w:gz")
+link = tarfile.TarInfo(name="escape")
+link.type = tarfile.SYMTYPE
+link.linkname = "../../../../../../../../" + os.path.dirname(rel_marker)
+link.mtime = time.time()
+tf.addfile(link)
+data = b"doos-audit-traversal\n"
+fi = tarfile.TarInfo(name="escape/" + os.path.basename(marker))
+fi.size = len(data)
+fi.mtime = time.time()
+tf.addfile(fi, io.BytesIO(data))
+tf.close()
+PYEOF
+
+hash=$(sha256sum "$TMP/evil.tar.gz" | cut -d' ' -f1)
+"$DOOS" image add --sha256 "$hash" "$TMP/evil.tar.gz" evilaudit >"$TMP/out.log" 2>&1
+rc=$?
+"$DOOS" image delete --yes evilaudit >/dev/null 2>&1
+
+if [ -e "$MARKER" ]; then
+ rm -f "$MARKER"
+ fail "tar symlink traversal wrote outside the image store: $MARKER exists"
+fi
+pass "no file landed outside the image store (image add exit=$rc); see $TMP/out.log for detail if needed"
diff --git a/audit/Makefile b/audit/Makefile
index bd5cd0e..8e25853 100644
--- a/audit/Makefile
+++ b/audit/Makefile
@@ -1,33 +1,38 @@
-# Runs every regression check under audit/ against this tree's built artifacts
-# (build/bin/runtime_interop_server, build/example/living-server, build/molo, and
-# a few checks that compile a tiny harness straight from src/).
+# Runs every regression check under audit/ against this tree's built artifacts:
+# MOLO-* against build/bin/runtime_interop_server, build/example/living-server,
+# build/molo (plus tiny harnesses from src/), CVE-* against build/doos/doos.
# Usage:
# make -C audit test # sequential, stops at the first FAIL
# make -C audit -j8 test # concurrent, one job per check directory (recursive make)
# make -C audit report # runs every check, never stops, prefixes output with the check id
# make -C audit list # names the check directories this covers
#
-# Each check's Makefile delegates to that directory's reproduce.py or reproduce.cpp,
+# Each check's Makefile delegates to that directory's reproduce script,
# which prints exactly one of PASS, FAIL or SKIP and exits 0 for PASS/SKIP, 1 for FAIL.
# "test" is the hard cap: this file does not invent new checks, it only fans out to
# the fixed, named list below. See README.md.
MOLO_BUILD ?= $(abspath ../build)
-CHECKS := $(sort $(wildcard MOLO-*))
-export MOLO_BUILD
+DOOS ?= $(MOLO_BUILD)/doos/doos
+TMPDIR ?= $(MOLO_BUILD)/audit-tmp
+CHECKS := $(sort $(wildcard MOLO-*) $(wildcard CVE-*))
+export MOLO_BUILD DOOS TMPDIR
-.PHONY: test $(CHECKS) list report
+.PHONY: test $(CHECKS) list report audit-tmp
test: $(CHECKS)
@echo "audit: $(words $(CHECKS)) checks run against $(MOLO_BUILD)"
-$(CHECKS):
- @$(MAKE) -s -C $@ test MOLO_BUILD=$(MOLO_BUILD)
+audit-tmp:
+ @mkdir -p "$(TMPDIR)"
+
+$(CHECKS): | audit-tmp
+ @$(MAKE) -s -C $@ test MOLO_BUILD=$(MOLO_BUILD) DOOS=$(DOOS)
list:
@for c in $(CHECKS); do echo $$c; done
report:
@status=0; for c in $(CHECKS); do \
- $(MAKE) -s -C $$c test MOLO_BUILD=$(MOLO_BUILD) 2>&1 | sed "s/^/$$c: /" || status=1; \
+ $(MAKE) -s -C $$c test MOLO_BUILD=$(MOLO_BUILD) DOOS=$(DOOS) 2>&1 | sed "s/^/$$c: /" || status=1; \
done; exit $$status
diff --git a/audit/README.md b/audit/README.md
index 1adc7f1..2cc9b08 100644
--- a/audit/README.md
+++ b/audit/README.md
@@ -2,91 +2,82 @@
**Scope:** [README](../README.md) · [AGENTS](../AGENTS.md)
-A fixed, named set of regression checks for vulnerability classes relevant to the
-mechanisms MoloApp actually has (an in-house HTTP/1 and HTTP/2 server, an in-house
-WebSocket/WebDAV/reverse-tunnel realtime stack, a shell-invoking CLI, in-house
-crypto and an ORM), each in its own directory with where the problem lives, why it
-matters to MoloApp specifically, and a check that reproduces it against real,
-built artifacts. Modeled on the `audit/` convention used by the `doos` project:
-capped to the issues that target code paths MoloApp actually has, not "every CVE",
-consistent with the base rule that every automated process gets a fixed, named
-ceiling instead of an open-ended scope.
+Two fixed, named regression sets, each check in its own directory with the
+public source (or in-house finding), why it matters, and a non-destructive
+check. This is not "every CVE" (that set is unbounded and mostly
+irrelevant); it is capped to the exposures that target code paths this tree
+actually has.
-Most of these are **in-house findings** from reading this codebase, not public CVE
-assignments (MoloApp is not itself a CVE-tracked project); each README still cites
-the real-world vulnerability *class* it is modeled on, with sources, so the check's
-severity and shape can be judged against known precedent.
-
-A check here answers one question: does *this build*, today, reproduce the exposure
-described. It is not a claim that MoloApp is unaffected by anything not listed here.
+- `MOLO-*`: in-house findings against the framework (HTTP parsing, CLI,
+ WebDAV, tunnels, static files, websockets). Each drives the built
+ artifacts (`build/molo`, `build/example/living-server`,
+ `build/bin/runtime_interop_server`) or compiles a tiny harness from `src/`.
+- `CVE-*`: 18 known CVEs relevant to the mechanisms doos uses (user
+ namespaces, overlayfs, tar extraction, abstract sockets, mount handling),
+ each run against `build/doos/doos` inside a scratch `DOOS_HOME`.
+ Inherited from doos 1.6.0 (see `src/doos/PROVENANCE.md`); they answer one
+ question: does *this doos binary*, today, reproduce the exposure the CVE
+ describes.
## Running it
```
-make # build/bin/runtime_interop_server, build/example/living-server, build/molo
-make -C audit test # sequential
-make -C audit -j8 test # concurrent, one job per check
-make -C audit report # runs all, never stops, one line prefix per check
-make -C audit list # names the check directories
+make # build first (artifacts must exist)
+make cve-audit # all checks, concurrent, via the root Makefile
+make -C audit test # sequential, stops at the first FAIL
+make -C audit -j8 test # concurrent, one job per check directory
+make -C audit report # runs all, never stops, one line prefix per check
+make -C audit list # names the check directories
```
-Each check is independent, writes only under its own `mktemp -d` (Python checks) or
-is a pure in-memory harness (C++ checks), and cleans up on exit. A check that needs
-something the host does not have (an unbuilt binary) prints `SKIP` with the reason
-and exits 0; it never reports PASS for a precondition it could not test. Every check
-runs under a hard wall-clock watchdog (`audit/lib/molo_audit.py`'s `arm_watchdog`, or
-an `alarm()` call in the C++ harnesses) so a check that finds a genuine hang reports
-FAIL instead of wedging the suite.
+Each check is independent, writes only under its own `mktemp -d` (under
+`$TMPDIR`, defaulting to `build/audit-tmp`), and cleans up on exit. Checks
+that need something the host does not have (network, `python3`, a specific
+kernel feature, an unbuilt artifact) print `SKIP` with the reason and exit 0;
+they never report PASS for a precondition they could not test. The CVE checks
+additionally need user namespaces for the `build/doos/doos` path (see
+`src/doos/README.md` troubleshooting).
## Verdicts
| Verdict | Meaning |
|---|---|
-| `PASS` | This build does not reproduce the exposure described, under the conditions this check creates. |
+| `PASS` | This binary does not reproduce the exposure, under the conditions this check creates. |
| `FAIL` | It does. Treat as a regression; the check prints what it observed. |
-| `SKIP` | The check's precondition was not met on this host (missing build). Not a verdict on MoloApp. |
-
-## How a check drives the real thing
-
-Three kinds of real artifact, no mocks:
-
-- **Over a real socket**, against `build/bin/runtime_interop_server` (the runtime's
- own interop test server: real HTTP/1.1, real h2c HTTP/2, real compression, real
- static files, nothing stubbed) or `build/example/living-server`. These checks live
- in `audit/lib/molo_audit.py`'s `H2`/`h1` helpers: a minimal HTTP/2 client speaking
- real frames, and raw-socket HTTP/1.1, both stdlib-only Python.
-- **Through the real CLI**, `build/molo`, run as a subprocess against a scratch
- directory.
-- **Against the real class directly**, for the handful of classes (`src/realtime/
- websocket/server/handshake_validator.cpp`, `src/realtime/webdav/server/
- resource_tree.cpp`, `src/realtime/expose/upstream.cpp`) that are pure, I/O-free
- logic not yet wired to any route in the shipped example (`example/fw/` is
- explicitly a skeleton still being re-bound to `src/`, per the main README). Each
- such check's README says so and compiles a tiny harness straight from the real
- `.cpp` file, the same code any real route would call, rather than skipping the
- class entirely.
+| `SKIP` | The check's precondition was not met on this host. Not a verdict on the code. |
## What is deliberately not here
-No kernel-level memory-corruption exploit code, and no check that requires outbound
-network access (DNS resolution, reaching a real external host) to prove its point.
-Everything here drives a MoloApp artifact through its real inputs inside a scratch
-directory or a loopback socket; nothing here targets any host other than the one
-running the check, and nothing here is a weaponized exploit for an unrelated target.
+No kernel memory-corruption exploit code (Dirty Pipe, Dirty COW, the
+`legacy_parse_param` heap overflow). Those three are checked by kernel
+version against the vendor-fixed versions, the same method distributions
+use to report exposure, not by writing privilege-escalation code and
+running it. Everything else here drives the binaries through their real
+interfaces on the machine running the check; nothing here targets any
+other host, and nothing here is a weaponized exploit for an unrelated
+target.
-## The list
+## The CVE list
-| Check | Mechanism | Modeled on |
+| CVE | Component the bug lives in | What doos has in common |
|---|---|---|
-| [MOLO-H1-001](MOLO-H1-001/) | HTTP/1 chunked-body cap bypass via chunk-size addition overflow | CWE-190 / request-smuggling-adjacent resource exhaustion |
-| [MOLO-H2-001](MOLO-H2-001/) | HTTP/2 stream-open/reset churn, no rate limit | CVE-2023-44487 "Rapid Reset" |
-| [MOLO-H2-002](MOLO-H2-002/) | HTTP/2 server-triggered reset churn | CVE-2025-8671 "MadeYouReset" |
-| [MOLO-H2-003](MOLO-H2-003/) | HTTP/2 empty-CONTINUATION flood, byte cap only | CVE-2024-27316 "CONTINUATION flood" |
-| [MOLO-H2-004](MOLO-H2-004/) | HTTP/2 PING flood to an unread peer, no queue cap | CVE-2019-9511/9512/9515/9518 HTTP/2 DoS batch |
-| [MOLO-STATIC-001](MOLO-STATIC-001/) | Static-file jail escape via a symlinked intermediate directory | CWE-61 symlink following |
-| [MOLO-CLI-001](MOLO-CLI-001/) | Shell command injection in `molo new ` | CWE-78 OS command injection |
-| [MOLO-WS-001](MOLO-WS-001/) | WebSocket handshake has no Origin check | CWE-1385 / CVE-2024-23898-class CSWSH |
-| [MOLO-DAV-001](MOLO-DAV-001/) | WebDAV COPY into its own subtree never terminates | CWE-674 uncontrolled recursion |
-| [MOLO-EXPOSE-001](MOLO-EXPOSE-001/) | `expose` upstream allow-list bypassed by hostname prefix | CWE-184 incomplete allow-list / SSRF-adjacent |
+| [CVE-2019-5736](CVE-2019-5736/) | runc (Go) `/proc/self/exe` handling | overlayed host `/usr` must stay read-only from inside |
+| [CVE-2024-21626](CVE-2024-21626/) | runc (Go) `fchdir` / fd close ordering | no leaked host fd reachable from the exec'd process |
+| [CVE-2020-15257](CVE-2020-15257/) | containerd-shim (Go) UID-only access check | `--net host` shares the host's abstract socket namespace by design |
+| [CVE-2022-0185](CVE-2022-0185/) | Linux kernel `fs/fs_context.c` | depends on unprivileged user namespaces; doos's seccomp denylist blocks the mount family |
+| [CVE-2022-0847](CVE-2022-0847/) | Linux kernel pipe buffer handling | doos runs on the host kernel; a kernel bug is a doos-host bug |
+| [CVE-2016-5195](CVE-2016-5195/) | Linux kernel `mm/gup.c` | doos runs on the host kernel; a kernel bug is a doos-host bug |
+| [CVE-2026-17106](CVE-2026-17106/) | moby/go-archive (Go), and tar extractors generally | `doos image add` extracts caller-supplied tarballs the same way |
+| [CVE-2021-30465](CVE-2021-30465/) | runc (Go) mount target resolution | `fsutil::mkdirs` follows symlinks the same way `create_directories` does by default |
+| [CVE-2021-3493](CVE-2021-3493/) | Linux kernel overlayfs (`fs/overlayfs`) | doos mounts overlayfs inside an unprivileged user namespace on every attach |
+| [CVE-2023-2640](CVE-2023-2640/) | Linux kernel overlayfs (Ubuntu patch set) | same mount doos issues on every attach |
+| [CVE-2023-32629](CVE-2023-32629/) | Linux kernel overlayfs (Ubuntu patch set) | same mount doos issues on every attach |
+| [CVE-2015-1328](CVE-2015-1328/) | Linux kernel overlayfs | same precondition doos depends on (overlayfs + unprivileged user namespace) |
+| [CVE-2022-0492](CVE-2022-0492/) | Linux kernel `kernel/cgroup/cgroup-v1.c` | doos uses cgroup v2 only and mounts no /sys/cgroupfs into the container |
+| [CVE-2022-27650](CVE-2022-27650/) | crun / Moby (Go/C) capability handling at container start | doos sets its own capability bounding set in `Hardening::apply()` |
+| [CVE-2019-16884](CVE-2019-16884/) | runc (Go) mount-target validation | doos's own `/proc` must be a real proc mount, independent of any AppArmor profile |
+| [CVE-2023-28642](CVE-2023-28642/) | runc (Go) /proc mount-target validation | doos's own /proc must be a real directory mount, not substitutable by an image |
+| [CVE-2018-12020](CVE-2018-12020/) | GnuPG status-fd / verbose filename echoing | doos trusts gpg's verdict to decide whether to extract a downloaded image |
+| [CVE-2020-7039](CVE-2020-7039/) | libslirp (C) packet parsing | slirp4netns, doos's default --net mode, links this library |
-Back to [README](../README.md), [AGENTS](../AGENTS.md).
+Back to [README](../README.md), [SPEC](../src/doos/SPEC.md), [AGENTS](../AGENTS.md).
diff --git a/docs/embed-taicpp-2026-10-26.md b/docs/embed-taicpp-2026-10-26.md
new file mode 100644
index 0000000..62473f7
--- /dev/null
+++ b/docs/embed-taicpp-2026-10-26.md
@@ -0,0 +1,55 @@
+# Static embeddability of ../tai/taicpp - research report (2026-10-26)
+
+## Verdict
+Yes. `taicpp` builds `build/libdetz.a` (36 MB, verified 2026-10-26) excluding `main.o`, plus a fully-static `build/detz-static` (13.5 MB). Link it into molo and inject context via `Agent::update_system()` / `run_turn()`.
+
+## 1. Verified tree
+- `taicpp/main.cpp` (20 lines): `cli::Parser::parseOpts → glue::GlueApp::run → AppBundle`. Not in archive.
+- `taicpp/src/`: 25 modules; agent core `src/agent/agent.{h,cpp}`, prompt bytes `src/agent/data.{h,cpp}` (generated by `src/agent/gen/gen_data.py` from `tai.py`), config `src/agent/agent_config.h`, DI adapters `src/glue/*_adapter.cpp`, entry `src/glue/glue_app.{h,cpp}` + `app_bundle.{h,cpp}`.
+- `taicpp/third_party/`: `curl/libcurl.a`, `sqlite/libsqlite3.a`, `jitterentropy/libjitterentropy.a` (vendored, statically linked).
+- Correction: earlier subagent-2 claim "libdetz.a does NOT exist" was wrong - it inspected moloapp (`build/molo`, `libai.a`), not taicpp. `ls -la` confirms `build/libdetz.a` exists.
+
+## 2. Makefile targets (taicpp/Makefile)
+- Line 27: `LIB = $(BUILD)/libdetz.a`; `all → build/detz` (dynamic: `-lsqlite3 -lcurl -lz -pthread -lutil`).
+- Lines 48–49 `static:`: `g++ -pthread -static main.o ALL_OBJS third_party/curl/libcurl.a third_party/sqlite/libsqlite3.a -lssl -lcrypto third_party/jitterentropy/libjitterentropy.a -lzstd -lz -lnghttp2 -lpsl -lbrotlidec -lidn2 -lrtmp -o build/detz-static`.
+- Line 52 comment: every test links `tests/.cpp` against `build/libdetz.a`.
+- Needs `MOLOAPP_SRC` include (`../../moloapp/src`) + all `src/*/` as `-I`.
+
+## 3. Link recipe (tested 2026-10-26, LINK_OK)
+```
+INCS=$(ls -d ../tai/taicpp/src/*/ | sed 's/^/-I/')
+g++ -std=c++23 $INCS -I../tai/taicpp -I../tai/taicpp/src \
+ your_molo_obj.o build/libdetz.a \
+ third_party/curl/libcurl.a third_party/sqlite/libsqlite3.a \
+ third_party/jitterentropy/libjitterentropy.a \
+ -lssl -lcrypto -lzstd -lz -lnghttp2 -lpsl -lbrotlidec -lidn2 -lrtmp \
+ -lsqlite3 -lcurl -lz -pthread -lutil -o molo
+```
+Probe `/tmp/embed_probe.cpp` calling `detz::agent::data::DefaultSystem()` linked OK (104 KB binary).
+
+## 4. Context-injection hooks (verified signatures + probe)
+- `src/agent/agent.h:64` `std::string system_message;`
+- `src/agent/agent.h:90` `void update_system(const std::string& text);` - sets `system_message`, persists via `store->save_system/save_bot_system`, calls `apply_system()`, logs event (agent.cpp:353-359).
+- `src/agent/agent.cpp:301` `void Agent::apply_system()` - composes `system_message + skill_catalog + tool_catalog + orientation_block + capability_block + AutonomousNote`.
+- `src/agent/agent.h:124` `std::string run_turn(const std::string& text, bool capture=false, int max_steps=MAX_STEPS, bool routed=false);` - per-turn injection point (prepend molo context to `text`).
+- `src/agent/data.h:13-14` `DefaultSystem()/MergeSystem()` - byte-exact base prompt; permanent edits go via `src/agent/gen/gen_data.py`.
+- `src/agent/agent_config.h` `struct AgentConfig : llm::LlmConfig` - `profile, db_path, history_path, auto_approve`.
+- Probe `/tmp/embed_ctx.cpp`: `DefaultSystem() + "\n\n# Molo extra context\n..."` → `CTX_OK base=2796 total=2869`, asserts substring present. Compiled + ran OK against `libdetz.a`.
+- Minimal embed:
+```cpp
+#include "agent/agent.h"
+detz::agent::AgentConfig cfg; /* db_path, profile, ... */
+detz::agent::Agent agent(cfg, myPorts); // StorePort etc., see src/glue/*_adapter.cpp
+agent.update_system(detz::agent::data::DefaultSystem() + "\n\n# Molo extra context\n" + myCtx);
+agent.run_turn(userInput);
+```
+
+## 5. External sources (static-embedding practice)
+1. AwesomeModernCPP - Static Libraries: Packaging with `ar` and Linking with `-l/-L` - `ar rcs` replace-and-insert semantics. https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/en/compilation/06-static-libraries (retrieved 2026-10-26)
+2. CodeGenes - Best Practices for Wrapping C++ Class APIs for C/FFI (2026-01-19): opaque types, `extern "C"`, no exceptions across boundary, error codes. https://www.codegenes.net/blog/wrapping-c-class-api-for-c-consumption/ (retrieved 2026-10-26)
+3. zackli.ai - How C/C++ Bindings Work: ABI and FFI (2026-07-15): C ABI as interop standard, `extern "C"` linkage, opaque handles, function tables. https://zackli.ai/blog/c-abi-ffi/ (retrieved 2026-10-26)
+4. w3tutorials - How to Develop a C Wrapper API for Object-Oriented C++ Code (2026-01-16): C wrapper with opaque pointer + `extern "C"` + careful error handling. https://www.w3tutorials.net/blog/developing-c-wrapper-api-for-object-oriented-c-code/ (retrieved 2026-10-26)
+
+## 6. Gaps
+- No `extern "C"` wrapper exists yet - needed only for C/Python FFI; C++ molo links directly.
+- Fully-static link requires static variants of system libs (ssl, crypto, zstd, nghttp2, psl, brotli, idn2, rtmp) present.
diff --git a/example/SPEC.md b/example/SPEC.md
index c1819c5..287a8cd 100644
--- a/example/SPEC.md
+++ b/example/SPEC.md
@@ -7,6 +7,15 @@ owning sibling plan and the file that will close it.
## Behaviors
1. `GET /` renders the coverage matrix from a template with inheritance.
+ Rows are grouped into themed sections by route prefix (`IndexCatalog`,
+ `example/app/IndexCatalog.cpp`); a route matching no group lands in
+ "Other" and fails `index_test`. Groups whose demos need credentials carry
+ a "needs API key" badge. Each row is `
`
+ (the crawl marker used by `matrix_test` and `tools/verify_deploy.py`),
+ with the route repeated in a column that hides below 40rem. A filter box
+ (`/static/index.js`) hides non-matching rows; without JavaScript the full
+ list shows. Adding a feature stays `add_feature(name, route)`; adding a
+ route under a new prefix means adding the prefix to a group.
2. Every matrix row resolves to a live route, a test file, and a plan link.
3. Every test drives the real stack: TestClient -> middleware -> router ->
view -> in-memory services, plus one real loopback HTTP round-trip.
@@ -79,6 +88,15 @@ owning sibling plan and the file that will close it.
at `/ai/` (compat, mistral, cohere, perplexity, bedrock, azure,
huggingface, audio, media, retrieval). Same contract as items 17 and 18.
Every `/google` and `/ai` route is excluded from locust.
+20. Sandboxed containers (`src/doos`, the real framework part): `GET /doos`
+ renders the container page, `GET /doos/status` returns containers,
+ images, davmounts and the libdoos version as JSON, `POST /doos/create`
+ idempotently creates (name plus optional size/memory/net),
+ `POST /doos/delete` dry-runs unless `confirm=yes`. Validation failures
+ answer 422 with every failure listed; a missing container answers 404.
+ All four run on a demo store (`DOOS_HOME` when the harness sets it,
+ else `build/doos-demo`), never the user's real store; real container
+ starts stay out of the demo (see `src/doos/SPEC.md`, Framework seams).
## Caps
diff --git a/example/app/App.cpp b/example/app/App.cpp
index 51651eb..e13a621 100644
--- a/example/app/App.cpp
+++ b/example/app/App.cpp
@@ -50,6 +50,10 @@ std::shared_ptr build_application(Services& services) {
register_ops_demo(ops, services);
app->include_router("", ops);
+ fw::Router doos;
+ register_doos_demo(doos, services);
+ app->include_router("", doos);
+
fw::Router stats;
register_stats_demo(stats, services);
app->include_router("", stats);
diff --git a/example/app/App.hpp b/example/app/App.hpp
index fe625e7..e70882d 100644
--- a/example/app/App.hpp
+++ b/example/app/App.hpp
@@ -81,6 +81,7 @@ void register_security_demo(fw::Router& router, Services& services);
void register_formats_demo(fw::Router& router, Services& services);
void register_realtime_demo(fw::Router& router, Services& services);
void register_ops_demo(fw::Router& router, Services& services);
+void register_doos_demo(fw::Router& router, Services& services);
void register_stats_demo(fw::Router& router, Services& services);
void register_security_extra_demo(fw::Router& router, Services& services);
void register_platform_demo(fw::Router& router, Services& services);
diff --git a/example/app/DoosDemo.cpp b/example/app/DoosDemo.cpp
new file mode 100644
index 0000000..b2552ce
--- /dev/null
+++ b/example/app/DoosDemo.cpp
@@ -0,0 +1,158 @@
+#include "App.hpp"
+
+#include
+#include
{% endblock %}
)LIVE";
-std::string env_or(const char* name, const char* fallback) {
- std::string v = google::Credentials::env(name);
- return v.empty() ? std::string(fallback) : v;
-}
-
[[noreturn]] void rethrow(const google::GoogleError& e) {
if (e.http_status() == 503 && e.status() == "NOT_CONFIGURED")
throw fw::HttpError(503, "google_not_configured", e.message());
diff --git a/example/example.mk b/example/example.mk
index 777c805..dfafc41 100644
--- a/example/example.mk
+++ b/example/example.mk
@@ -42,12 +42,14 @@ EXAMPLE_SRCS = \
$(EXAMPLE_DIR)/app/Templates.cpp \
$(EXAMPLE_DIR)/app/Embedded.cpp \
$(EXAMPLE_DIR)/app/Index.cpp \
+ $(EXAMPLE_DIR)/app/IndexCatalog.cpp \
$(EXAMPLE_DIR)/app/RoutingDemo.cpp \
$(EXAMPLE_DIR)/app/DataDemo.cpp \
$(EXAMPLE_DIR)/app/SecurityDemo.cpp \
$(EXAMPLE_DIR)/app/FormatsDemo.cpp \
$(EXAMPLE_DIR)/app/RealtimeDemo.cpp \
$(EXAMPLE_DIR)/app/OpsDemo.cpp \
+ $(EXAMPLE_DIR)/app/DoosDemo.cpp \
$(EXAMPLE_DIR)/app/StatsDemo.cpp \
$(EXAMPLE_DIR)/app/SecurityExtraDemo.cpp \
$(EXAMPLE_DIR)/app/PlatformDemo.cpp \
@@ -74,7 +76,7 @@ EXAMPLE_INC = -I$(EXAMPLE_DIR) -I$(EXAMPLE_BUILD) -Isrc
# Real framework parts the example links: Google Cloud (src/google) over the
# HTTP client (src/clients, wolfSSL TLS) and the operability breaker.
EXAMPLE_REAL_LIBS = build/ai/libai.a build/google/libgoogle.a build/clients/libclients.a \
- build/liboperability.a
+ build/liboperability.a build/doos/libdoos.a
.PHONY: example-deploy example-verify deploy verify example example-real-libs example-assets example-test example-clean example-locust
@@ -113,14 +115,14 @@ example: example-assets example-real-libs
example-test: example
rm -rf $(EXAMPLE_BUILD)/tests
- mkdir -p $(EXAMPLE_BUILD)/tests
+ mkdir -p $(EXAMPLE_BUILD)/tests $(EXAMPLE_BUILD)/tmp
find $(EXAMPLE_TESTDIR) -name '*_test.cpp' | sort > $(EXAMPLE_BUILD)/tests/list.txt
xargs -P $(EXAMPLE_TEST_JOBS) -I{} sh -c ' \
t={}; n=`echo $$t | sed "s|$(EXAMPLE_TESTDIR)/||; s|/|_|g; s|\\.cpp$$||"`; \
b=$(EXAMPLE_BUILD)/tests/$$n; \
if $(CXX) $(EXAMPLE_CXXFLAGS) -I$(EXAMPLE_DIR) -I$(EXAMPLE_TESTDIR) -Isrc \
$$t $(EXAMPLE_BUILD)/libexample.a $(EXAMPLE_REAL_LIBS) -lwolfssl -o $$b > $$b.log 2>&1; \
- then MOLO_ENV_FILES=off $$b >> $$b.log 2>&1; else echo "COMPILE FAILED: $$t" >> $$b.log; false; fi; \
+ then MOLO_ENV_FILES=off TMPDIR=$${TMPDIR:-$(EXAMPLE_BUILD)/tmp} $$b >> $$b.log 2>&1; else echo "COMPILE FAILED: $$t" >> $$b.log; false; fi; \
echo $$? > $$b.rc' < $(EXAMPLE_BUILD)/tests/list.txt
pass=0; fail=0; \
for l in `ls $(EXAMPLE_BUILD)/tests/*.log | sort`; do \
@@ -149,8 +151,12 @@ example-deploy: example
kill `cat $(EXAMPLE_RUN)/server.pid`; \
for i in 1 2 3 4 5 6 7 8 9 10; do kill -0 `cat $(EXAMPLE_RUN)/server.pid` 2>/dev/null || break; sleep 0.5; done; \
fi
- setsid nohup $(EXAMPLE_BUILD)/living-server $(EXAMPLE_PORT) --no-locust \
- > $(EXAMPLE_RUN)/server.log 2>&1 < /dev/null & echo $$! > $(EXAMPLE_RUN)/server.pid
+ rm -f $(EXAMPLE_RUN)/server.pid
+ setsid sh -c 'echo $$$$ > $(EXAMPLE_RUN)/server.pid; exec $(EXAMPLE_BUILD)/living-server $(EXAMPLE_PORT) --no-locust > $(EXAMPLE_RUN)/server.log 2>&1 < /dev/null' &
+ for i in `seq 1 20`; do \
+ [ -f $(EXAMPLE_RUN)/server.pid ] && kill -0 `cat $(EXAMPLE_RUN)/server.pid` 2>/dev/null && break; sleep 0.25; \
+ done; \
+ if [ ! -f $(EXAMPLE_RUN)/server.pid ] || ! kill -0 `cat $(EXAMPLE_RUN)/server.pid` 2>/dev/null; then echo "deploy: server died on start"; cat $(EXAMPLE_RUN)/server.log; exit 1; fi
ok=0; for i in `seq 1 30`; do \
if curl -fsS http://127.0.0.1:$(EXAMPLE_PORT)/health > /dev/null 2>&1; then ok=1; break; fi; sleep 0.5; \
done; \
diff --git a/example/locustfile.py b/example/locustfile.py
index 0263acc..d36c791 100644
--- a/example/locustfile.py
+++ b/example/locustfile.py
@@ -37,7 +37,7 @@ GETS = [
"/auth/me", "/cache/lookup", "/cli/ai", "/cli/commands",
"/crypto/hash", "/crypto/password", "/crypto/random",
"/csp/page", "/csp/report",
- "/di/services", "/di/resolve/locust",
+ "/di/services", "/di/resolve/locust", "/doos", "/doos/status",
"/embedded/chart.umd.min.js", "/embedded/hello.txt", "/embedded/stats.js",
"/events/fire", "/expose/record", "/expose/stats",
"/files/", "/files/welcome.txt",
@@ -100,6 +100,8 @@ POSTS = [
("/crypto/hash", {"data": "hello"}),
("/crypto/password", {"password": "secret"}),
("/csp/report", {"report": "test"}),
+ ("/doos/create", {"name": "locust"}),
+ ("/doos/delete", {"name": "locust"}),
("/events/fire", {"event": "test"}),
("/expose/record", {"data": "x"}),
("/flash/set", {"msg": "hi"}),
diff --git a/example/static/app.css b/example/static/app.css
index bb213ec..9450d57 100644
--- a/example/static/app.css
+++ b/example/static/app.css
@@ -102,3 +102,19 @@ label.inline input { padding: 0; }
.voice-log li.bot { border-left: 4px solid var(--series-1); }
.voice-form { flex-direction: row; flex-wrap: wrap; max-width: none; }
.voice-form input[type="text"] { flex: 1 1 12rem; min-width: 0; }
+
+/* Index page: grouped feature list. */
+.chips { display: flex; flex-wrap: wrap; gap: 0.4rem; margin: 0.5rem 0 1rem; }
+.chips a { border: 1px solid var(--border); border-radius: 1rem; padding: 0.1rem 0.7rem;
+ text-decoration: none; font-size: 0.9rem; }
+.filter input { width: 100%; max-width: 28rem; border: 1px solid var(--border);
+ background: var(--surface-1); color: inherit; border-radius: 4px; }
+section.group { margin: 1.25rem 0; scroll-margin-top: 1rem; }
+section.group h2 { font-size: 1.15rem; margin: 0 0 0.1rem; display: flex; flex-wrap: wrap;
+ align-items: baseline; gap: 0.5rem; }
+section.group p.hint { margin: 0 0 0.4rem; }
+.count { color: var(--text-secondary); font-size: 0.85rem; font-weight: normal; }
+.badge { font-size: 0.75rem; font-weight: normal; border: 1px solid var(--series-4);
+ color: var(--series-4); border-radius: 0.7rem; padding: 0 0.5rem; }
+[hidden] { display: none !important; }
+@media (max-width: 40rem) { th.route, td.route { display: none; } }
diff --git a/example/static/index.js b/example/static/index.js
new file mode 100644
index 0000000..871b385
--- /dev/null
+++ b/example/static/index.js
@@ -0,0 +1,19 @@
+// Index page filter: hides rows and groups that do not match. Without
+// JavaScript the full list stays visible.
+(function () {
+ var box = document.getElementById("filter");
+ if (!box) return;
+ var groups = document.querySelectorAll("section.group");
+ box.addEventListener("input", function () {
+ var q = box.value.trim().toLowerCase();
+ groups.forEach(function (g) {
+ var shown = 0;
+ g.querySelectorAll("tbody tr").forEach(function (tr) {
+ var hit = q === "" || tr.textContent.toLowerCase().indexOf(q) !== -1;
+ tr.hidden = !hit;
+ if (hit) shown++;
+ });
+ g.hidden = shown === 0;
+ });
+ });
+})();
diff --git a/specs/example-site.md b/specs/example-site.md
new file mode 100644
index 0000000..e155e7d
--- /dev/null
+++ b/specs/example-site.md
@@ -0,0 +1,246 @@
+
+
+# Example-Site Specification Draft
+
+Status: draft for review. Source: synthesis of workflow evidence P1-P6 (structure, tests, OpenAPI drift, reference-site reuse, error/UX audit, falsification gaps). No live probes were run; counts and bodies cited below are source/grep-level and need the falsification reruns in Section 11 before this becomes normative.
+
+Conventions: MUST/SHOULD/MAY per RFC 2119. This spec wins over code on conflict until amended in the same change.
+
+## 1. Scope, goals, non-goals
+
+Goals:
+- One example site that demonstrates every framework module through a consistent shell, nav, page, form, error, and JS contract.
+- Commercial and scientific tone: direct, factual, user friendly; no complexity pushed to the visitor.
+- Responsive at 360px viewport minimum; narrow screens get dropdowns/collapse, never hidden nav with no fallback.
+- Fully specified: every shared component, envelope, tag, and automation gate is declared here.
+
+Non-goals:
+- Production auth hardening and threat modeling (out of scope for now).
+- Live vendor calls in default suite (paid/live routes stay dry-run or skipped without keys/network).
+- Rewriting framework modules; the example consumes them via the documented demo mounts.
+
+## 2. Quality standards, coverage targets, caps, floors
+
+### 2.1 Test standard
+- Example suite is integration-only; isolated unit tests are forbidden. Arrange/Act/Assert with Fixture plus TestClient, PASS:/FAIL: protocol (tests/README.md).
+- Target: `example suite: 265 passed, 0 failed` (AGENTS.md). Current inventory: 265 files under tests/example, 285 under tests/src. Any count change MUST update this spec plus AGENTS.md in the same change.
+- Per-route minimum (4 cases): happy path, auth-fail or 404/405, validation/422, limit/edge. Applies to every mounted route including /readyz, /startupz (currently misplaced in probes_test.cpp; MUST move to tests/example/readyz and tests/example/startupz).
+- Matrix test: GET every index href, require 2xx/3xx (401 allowed only for /auth/me), minimum row count declared (today >=37; index catalog carries ~40 features in 16 groups).
+- Loud skips: unverifiable input is rejected with reason plus counter, never silently stored.
+
+### 2.2 Build and lint gates
+- Warning-free build with -std=c++23 -Wall -Wextra everywhere. -Werror MUST be universal; today it is missing in example, app, data, cli, observability, realtime, tenancy, audit, governance, supplychain .mk files. Closing that gap is required.
+- `make lint` = warning-free build plus repo-wide em-dash grep. No tidy/sanitizer/format/coverage gate exists today; until one lands, the lint target is the gate and MUST stay green.
+- Pipeline order: lint -> suite -> bump -> changelog -> commit -> tag -> deploy -> verify. Timeout 30 min, then escalate.
+
+### 2.3 Coverage targets
+- Route coverage: 100 percent of mounted router registrations reachable from index matrix or docs table, or explicitly listed as excluded (paid/live prefixes /voice, /google, /agent, /ai excluded from locust by design).
+- OpenAPI coverage: 100 percent of mounted routes appear in served spec (today 3 manual adds vs ~490 registrations; see Section 9).
+- Component coverage: every named component in Section 5 has at least one route-level test rendering it.
+- JS coverage: every shipped asset JS file has a route test that loads its page plus a simulated POST exercising its err/out path.
+
+### 2.4 Caps (static ceilings, no autotuning)
+- Suite: 10 min total, 30 s single test, zero flakes (tests/README.md).
+- HTTP demo payloads: 64 KB request body, 256 KB response body, 100 items per list page default.
+- Rate: 60 req/min per demo write endpoint when loopback deployed; 429 with Retry-After on breach.
+- Embedded bundle: 5 MB total under example/assets; single asset 512 KB max.
+- Gate output panels: 200 lines max with truncation notice; stats tiles: 12 max.
+- Locust headless run: 60 s, 10 users default.
+
+### 2.5 Floors (never crossed alone; dry-run, stop, page human)
+- Protected: specs/, CHANGELOG.md, VERSION, git tags, retention windows, destructive file deletes, history rewrite, force push, hard reset.
+- Docs/off behavior: doc routes disabled by default in prod (prod 404 test required).
+- Destructive/paid demo calls: dry-run by default, explicit confirm to execute; no auto-spend.
+- Release: max 1 release per green run; failed live verification blocks tag.
+
+## 3. Whole-site structure
+
+### 3.1 Information architecture
+- Single shell (base.html) with sticky masthead, main, footer. One shell template only; merge page.html, ent_page.html, platform_page.html into one.
+- Global topbar MUST cover all 16 index groups (today only 7 links: Index/Templates/Forms/Stats/Voice/Docs/Health). Groups: routing, requests, data, security, static, realtime, observability, operations, doos, tenancy, audit, governance, google(+voice), agent, vendors(/ai), tools, plus Other fallback. Narrow screens use the existing details-dropdown pattern (keep; it beats the reference-site nav-hide).
+- Index page: grouped matrix via IndexCatalog render, filter input (no-JS safe), needs-API-key badges on google/agent/vendors groups.
+- Every detail page: section-head (numeral + lede), breadcrumbs (Index / Group / Page), back-link, section nav where page has 2+ sections.
+- Docs page: filterable register table (see Section 5), not a plain list.
+- Static vs embedded: example/static holds shell CSS/JS (app.css, app.js, index.js); example/assets holds per-demo JS bundled to build/example/gen/assets.cpp and served under /embedded/{name}.
+
+### 3.2 Route map (mount contract)
+- Core: / (index), /health, /readyz, /startupz, /metrics, /telemetry, /routing*, /orm/users, /kv/items, /cache/lookup, /pubsub/publish, /auth/*, /sessions/*, /security/*, /security-extra/*, /formats/data, /templates/page, /forms/contact, /validate/user, /ws, /socketio, /sse, /streaming, /webdav, /expose, /supervisor/*, /restclient, /clients/*, /operability/*, /cli/*, /workflow/release, /supplychain/sbom.json, /openapi.json, /docs, /stats, /stats/data, /voice, /voice/say|hear|turn|reset, /google/status, /doos, /doos/status, /doos/create, /doos/delete, /tenancy/*, /audit/*, /governance/*, /v1|v2/items.
+- Agent (9, /agent/): models, runtime, sessions, sandbox, registry, armor, optimize, adk, live.
+- AI (20, /ai/): xai, xaiplatform, anthropic, anthropicadmin, meta, deepseek, openai, openaiplatform, openaiadmin, openrouter, compat, mistral, cohere, perplexity, bedrock, azure, huggingface, audio, media, retrieval.
+- Google (7, /google/): discovery, cloudai, enterprise, data, maps, workspace, ops.
+- Contract for agent/ai/google: GET page plus status returns 2xx always; POST/DELETE without key returns 503 with machine-readable not_configured/google_not_configured; validation failures return 422; paid/destructive runs dry-run unless confirm:true.
+- Doos: GET page, GET status JSON, POST create, POST delete with confirm=yes (else dry-run). Demo store: DOOS_HOME else build/doos-demo.
+
+### 3.3 Build, deploy, verify-live
+- Standalone: make -f example/example.mk example|example-test|example-clean|example-locust. Whole repo: make, make test, make lint via root Makefile aggregation.
+- Deploy: loopback living-server on EXAMPLE_PORT (default 8000), pid build/example/run/server.pid, health-gated; verify via tools/verify_deploy.py.
+- Verify-live gate (manual today, MUST stay manual until wired): health probe, /metrics scrape, index 360px markup checks (viewport meta, .nav-narrow collapse), crawl first 10 matrix links. Any red step halts the pipeline.
+
+## 4. Per-module look (page contract)
+
+Every demo page MUST follow this skeleton in order:
+1. Breadcrumbs plus section-head (numeral, title, one-line lede, status pill if the module has state).
+2. Config/status strip: molo-config-status element (configured/not-configured/live/dry-run) for key-gated modules.
+3. How-it-works block: steps or tabs plus callout for paid/dry-run notes.
+4. Interactive form(s): shared FormView builder only (Section 7); one primary submit; confirm control per Section 7 for paid/destructive.
+5. Output area: molo-json-out (codeblock in panel-dark) plus molo-alert region; run-button triggers fetch; output capped at 200 lines.
+6. Reference row: link to /docs entry plus OpenAPI operation id.
+
+Look rules:
+- One section class vocabulary from Section 5; no per-vendor invented section classes or id prefixes.
+- No page-local
+
+CPU time used by 4 busy loops in one container (CPU-seconds)
+4.2 s of wall time. Half a CPU allows about 2.1 CPU-seconds; measured 2.3.
+
+no limit
+
+--cpus 0.5
+
+0
+
+4
+
+8
+
+12
+
+16
+
+20
+no limit
+no limit: 16.3 CPU-seconds
+16.3 CPU-s
+--cpus 0.5
+--cpus 0.5: 2.3 CPU-seconds
+2.3 CPU-s
+
+
diff --git a/src/doos/docs/charts/make_charts.py b/src/doos/docs/charts/make_charts.py
new file mode 100644
index 0000000..f8b0cf8
--- /dev/null
+++ b/src/doos/docs/charts/make_charts.py
@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Builds the SVG charts and the generated numbers in COMPARISON.md / RESEARCH.md from bench.json.
+
+ python3 docs/charts/make_charts.py (or: make charts)
+
+Input : docs/charts/bench.json (written by scripts/bench.sh, i.e. make bench)
+Output: docs/charts/startup.svg, size.svg, cpu.svg
+ the blocks between and in the markdown documents
+ and inline values written as text
+
+Design rules (the dataviz method): one form per job, doos in the accent hue and everything else in the neutral
+gray (emphasis), bars at most 24 px with a 4 px rounded data end, direct value labels at the bar tip, a legend,
+hairline solid grid, text in ink tokens (never the series color), light and dark palettes selected separately.
+Colors were checked with the dataviz validator: contrast, CVD separation and the normal-vision floor pass in
+both modes; its "chroma floor" flag on the gray is expected, the gray is the de-emphasis neutral by design.
+Standard library only.
+"""
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent.parent
+DATA = HERE / "bench.json"
+
+# ---- palette (dataviz reference instance) ---------------------------------------------------------------
+LIGHT = dict(surface="#fcfcfb", ink="#0b0b0b", ink2="#52514e", muted="#898781", grid="#e1e0d9", axis="#c3c2b7",
+ accent="#2a78d6", other="#898781")
+DARK = dict(surface="#1a1a19", ink="#f0efec", ink2="#c3c2b7", muted="#898781", grid="#2c2c2a", axis="#383835",
+ accent="#3987e5", other="#898781")
+
+STYLE = f"""
+ .bg {{ fill: var(--surface); }}
+ .t1 {{ fill: var(--ink); font: 600 15px system-ui, -apple-system, "Segoe UI", sans-serif; }}
+ .t2 {{ fill: var(--ink2); font: 400 12px system-ui, -apple-system, "Segoe UI", sans-serif; }}
+ .lab {{ fill: var(--ink); font: 400 13px system-ui, -apple-system, "Segoe UI", sans-serif; }}
+ .val {{ fill: var(--ink2); font: 400 12px system-ui, -apple-system, "Segoe UI", sans-serif; }}
+ .tick {{ fill: var(--muted); font: 400 11px system-ui, -apple-system, "Segoe UI", sans-serif; }}
+ .grid {{ stroke: var(--grid); stroke-width: 1; }}
+ .axis {{ stroke: var(--axis); stroke-width: 1; }}
+ .acc {{ fill: var(--accent); }}
+ .oth {{ fill: var(--other); }}
+ :root {{ --surface:{LIGHT['surface']}; --ink:{LIGHT['ink']}; --ink2:{LIGHT['ink2']}; --muted:{LIGHT['muted']};
+ --grid:{LIGHT['grid']}; --axis:{LIGHT['axis']}; --accent:{LIGHT['accent']}; --other:{LIGHT['other']}; }}
+ @media (prefers-color-scheme: dark) {{
+ :root {{ --surface:{DARK['surface']}; --ink:{DARK['ink']}; --ink2:{DARK['ink2']}; --muted:{DARK['muted']};
+ --grid:{DARK['grid']}; --axis:{DARK['axis']}; --accent:{DARK['accent']}; --other:{DARK['other']}; }}
+ }}
+"""
+
+BAR_H = 18 # <= 24 px
+ROW = 30
+RADIUS = 4 # rounded data end only
+
+
+def bar_path(x, y, w, h, r=RADIUS):
+ """Bar growing from x to the right: square at the baseline, rounded at the data end."""
+ w = max(w, 1.0)
+ r = min(r, w, h / 2)
+ return (f"M{x:.1f},{y:.1f} h{w - r:.1f} a{r},{r} 0 0 1 {r},{r} v{h - 2 * r:.1f} "
+ f"a{r},{r} 0 0 1 {-r},{r} h{-(w - r):.1f} z")
+
+
+def svg_open(w, h, title, desc):
+ return (f'\n"
+ return out
+
+
+# ---- chart 2: binary size (log scale) --------------------------------------------------------------------
+def size_chart(d):
+ names = {"bwrap": "bubblewrap", "crun": "crun (OCI runtime)", "doos": "doos", "docker": "docker CLI",
+ "podman": "podman"}
+ rows = sorted([r for r in d["sizes"] if r["bytes"] is not None], key=lambda r: r["bytes"])
+ left, right, top, width = 170, 100, 96, 760
+ plot_w = width - left - right
+ lo, hi = math.log10(50 * 1024), math.log10(100 * (1 << 20))
+ sx = lambda b: (math.log10(b) - lo) / (hi - lo) * plot_w
+ ticks = [(100 * 1024, "100 KiB"), (1 << 20, "1 MiB"), (10 << 20, "10 MiB"), (100 << 20, "100 MiB")]
+ y0 = top + 8
+ body = []
+ for b, lab in ticks:
+ x = left + sx(b)
+ body.append(f'')
+ body.append(f'{lab}')
+ y = y0
+ for r in rows:
+ cls = "acc" if r["id"] == "doos" else "oth"
+ w = sx(r["bytes"])
+ by = y + (ROW - BAR_H) / 2
+ body.append(f'{names.get(r["id"], r["id"])}')
+ body.append(f'{names.get(r["id"], r["id"])}: {fmt_bytes(r["bytes"])}')
+ body.append(f'{fmt_bytes(r["bytes"])}')
+ y += ROW
+ body.append(f'')
+ height = int(y + 62)
+ out = svg_open(width, height, "Size of the main executable",
+ "Horizontal bars on a logarithmic axis: " +
+ ", ".join(f"{names.get(r['id'], r['id'])} {fmt_bytes(r['bytes'])}" for r in rows) + ".")
+ out += 'Size of the main executable (log scale, smaller is smaller)\n'
+ out += 'The docker CLI excludes dockerd and containerd.\n'
+ out += 'doos excludes the helpers it calls (slirp4netns, pasta, newuidmap, curl, tar).\n'
+ out += legend(20, 82, [("acc", "doos"), ("oth", "other tools")]) + "\n"
+ out += "\n".join(body) + f'\nAxis is logarithmic: each gridline is 10x the previous one.\n\n'
+ return out
+
+
+# ---- chart 3: cpu limit ----------------------------------------------------------------------------------
+def cpu_chart(d):
+ c = d["cpu"]
+ if c["unlimited"] is None or c["half_cpu"] is None:
+ return None
+ rows = [("no limit", c["unlimited"], "oth"), ("--cpus 0.5", c["half_cpu"], "acc")]
+ left, right, top, width = 170, 90, 78, 760
+ plot_w = width - left - right
+ axis_max = math.ceil(c["unlimited"] / 4.0) * 4
+ scale = plot_w / axis_max
+ y0 = top + 8
+ body = []
+ for t in range(0, axis_max + 1, 4):
+ x = left + t * scale
+ body.append(f'')
+ body.append(f'{t}')
+ y = y0
+ for lab, v, cls in rows:
+ w = v * scale
+ by = y + (ROW - BAR_H) / 2
+ body.append(f'{lab}')
+ body.append(f'{lab}: {v:.1f} CPU-seconds')
+ body.append(f'{v:.1f} CPU-s')
+ y += ROW
+ body.append(f'')
+ ideal = 0.5 * c["wall_seconds"]
+ height = int(y + 54)
+ out = svg_open(width, height, "CPU time used by four busy loops",
+ f"Two bars, CPU seconds consumed in {c['wall_seconds']} seconds of wall time. Without a limit {c['unlimited']:.1f}, "
+ f"with --cpus 0.5 {c['half_cpu']:.1f}.")
+ out += 'CPU time used by 4 busy loops in one container (CPU-seconds)\n'
+ out += (f'{c["wall_seconds"]} s of wall time. Half a CPU allows about {ideal:.1f} CPU-seconds; '
+ f'measured {c["half_cpu"]:.1f}.\n')
+ out += legend(20, 64, [("oth", "no limit"), ("acc", "--cpus 0.5")]) + "\n"
+ out += "\n".join(body) + "\n\n"
+ return out
+
+
+# ---- generated markdown ---------------------------------------------------------------------------------
+def startup_table(d):
+ rows = [r for r in d["startup"] if r["ms"] is not None]
+ lines = ["| Setup | Network | Time per run |", "|---|---|---|"]
+ order = {"none": 0, "default": 1}
+ for r in sorted(rows, key=lambda r: (order[r["group"]], r["ms"])):
+ net = "none" if r["group"] == "none" else "default"
+ lines.append(f"| {r['label']} | {net} | {fmt_ms(r['ms'])} |")
+ return "\n".join(lines)
+
+
+def size_table(d):
+ names = {"bwrap": "bubblewrap", "crun": "crun", "doos": "doos", "docker": "docker CLI", "podman": "podman"}
+ lines = ["| Executable | Size |", "|---|---|"]
+ for r in sorted([r for r in d["sizes"] if r["bytes"] is not None], key=lambda r: r["bytes"]):
+ lines.append(f"| {names.get(r['id'], r['id'])} | {fmt_bytes(r['bytes'])} ({r['bytes']:,} bytes) |")
+ return "\n".join(lines)
+
+
+def inline_values(d):
+ ms = lambda ids: [r["ms"] for r in d["startup"] if r["id"].startswith(ids) and r["ms"] is not None]
+ rng = lambda xs: f"{min(xs):.0f} to {max(xs):.0f} ms" if xs else "n/a"
+ size = {r["id"]: r["bytes"] for r in d["sizes"] if r["bytes"] is not None}
+ v = {
+ "doos_range": rng(ms("doos")),
+ "podman_range": rng(ms("podman")),
+ "docker_range": rng(ms("docker")),
+ "bwrap_range": rng(ms("bwrap")),
+ "doos_size": fmt_bytes(size["doos"]) if "doos" in size else "n/a",
+ "docker_size": fmt_bytes(size["docker"]) if "docker" in size else "n/a",
+ "podman_size": fmt_bytes(size["podman"]) if "podman" in size else "n/a",
+ "bench_date": d["meta"]["date"],
+ "src_lines": f'{d["meta"].get("src_lines", 0):,}',
+ "shared_libs": str(d["meta"].get("shared_libs", "n/a")),
+ "runs": str(d["meta"]["runs"]),
+ "versions": f'doos {d["meta"]["doos"]}, {d["meta"]["docker"].replace("Docker version ", "Docker ").split(",")[0]}, '
+ f'{d["meta"]["podman"].replace("podman version ", "Podman ")}, {d["meta"]["bubblewrap"].replace("bubblewrap ", "bubblewrap ")}',
+ "cpu_free": f'{d["cpu"]["unlimited"]:.1f}' if d["cpu"]["unlimited"] is not None else "n/a",
+ "cpu_half": f'{d["cpu"]["half_cpu"]:.1f}' if d["cpu"]["half_cpu"] is not None else "n/a",
+ }
+ return v
+
+
+def patch_markdown(path, blocks, inline):
+ s = path.read_text()
+ orig = s
+ for name, text in blocks.items():
+ pat = re.compile(rf"(\n).*?(\n)", re.S)
+ s = pat.sub(lambda m: m.group(1) + text + m.group(2), s)
+ s = re.sub(r".*?",
+ lambda m: f"{inline.get(m.group(1), 'n/a')}", s)
+ if s != orig:
+ path.write_text(s)
+ return True
+ return False
+
+
+def main():
+ if not DATA.exists():
+ sys.exit("no bench.json: run `make bench` first (it needs the built binary)")
+ d = json.loads(DATA.read_text())
+ (HERE / "startup.svg").write_text(startup_chart(d))
+ (HERE / "size.svg").write_text(size_chart(d))
+ cpu = cpu_chart(d)
+ if cpu:
+ (HERE / "cpu.svg").write_text(cpu)
+ blocks = {"startup": startup_table(d), "sizes": size_table(d)}
+ inline = inline_values(d)
+ changed = [p.name for p in (ROOT / "COMPARISON.md", ROOT / "docs" / "RESEARCH.md") if patch_markdown(p, blocks, inline)]
+ print("charts: startup.svg size.svg" + (" cpu.svg" if cpu else "") + (f"; updated {', '.join(changed)}" if changed else "; docs already current"))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/doos/docs/charts/size.svg b/src/doos/docs/charts/size.svg
new file mode 100644
index 0000000..3c6a37f
--- /dev/null
+++ b/src/doos/docs/charts/size.svg
@@ -0,0 +1,55 @@
+
diff --git a/src/doos/docs/charts/startup.svg b/src/doos/docs/charts/startup.svg
new file mode 100644
index 0000000..c751255
--- /dev/null
+++ b/src/doos/docs/charts/startup.svg
@@ -0,0 +1,90 @@
+
diff --git a/src/doos/docs/history/AGENTS.md b/src/doos/docs/history/AGENTS.md
new file mode 100644
index 0000000..307f4f1
--- /dev/null
+++ b/src/doos/docs/history/AGENTS.md
@@ -0,0 +1,113 @@
+# AGENTS.md
+
+**Docs:** [README](README.md) · [SPEC](SPEC.md) · [ARCHITECTURE](docs/ARCHITECTURE.md) · [RESEARCH](docs/RESEARCH.md) · [COMPARISON](COMPARISON.md) · [AGENTS](AGENTS.md) · [CHANGELOG](CHANGELOG.md) · [CI](docs/CI.md)
+
+Rules for any AI agent (or human) changing this repository. The user's global rules
+also apply; this file adds the project-specific ones. Keep this file current: it is
+part of every release.
+
+## Project in one paragraph
+
+`doos` is a user-level container tool in C++20. `attach` builds a user + mount + pid
++ uts + ipc (+ net) namespace set, overlays either the host's `/usr`, `/opt` (host mode) or an
+extracted image (image mode) with a per-container upper dir, pivots into it and runs a command.
+Networking is slirp4netns or pasta, ids are mapped through newuidmap when possible, cgroup v2 limits
+and a watchdog enforce `--memory --pids --cpus --size`, capabilities and seccomp confine the command.
+No root at runtime. Authoritative behavior: [SPEC](SPEC.md). Design notes: [ARCHITECTURE](docs/ARCHITECTURE.md).
+Measurements and gaps: [RESEARCH](docs/RESEARCH.md). Positioning against other tools: [COMPARISON](COMPARISON.md).
+Usage: [README](README.md). History: [CHANGELOG](CHANGELOG.md).
+
+## Mandatory release workflow (every change, same session)
+
+1. Make the change. Smallest diff that does what was asked.
+2. Update docs in the same change (see the table below).
+3. Pick the bump:
+ - `patch`: bug fix, docs, tests, tooling, no behavior change for users.
+ - `minor`: new or changed user-visible behavior (flag, command, mount, limit).
+ - `major`: breaking change to CLI, state layout, or container compatibility.
+4. Run `make docs` (`charts` plus `check-docs`) (the release script does too: every document must link to every other, every relative link must resolve).
+5. Run `scripts/release.sh "imperative commit subject"`.
+ It bumps `VERSION`, builds, runs `tests/run.sh`, commits all changes, and creates
+ the annotated tag `vX.Y.Z`. It aborts on any build or test failure.
+6. Verify live: run `build/doos` once against the real thing (the e2e suite does this).
+7. Report honestly what passed and what did not. Do not push unless the user asks.
+
+Never hand-edit `VERSION` or create tags manually. Never skip the tests to release.
+
+## Docs that must be updated with the code
+
+| If you change | Update |
+|---|---|
+| CLI commands, flags, output | `README.md`, `SPEC.md` (CLI), `src/cli.cpp` usage text |
+| Limits or constants in `src/spec.hpp` | `SPEC.md` limits/layout tables (both must match) |
+| Mounts, namespaces, isolation | `SPEC.md`, `docs/ARCHITECTURE.md`, `docs/RESEARCH.md` host safety section |
+| Networking | `SPEC.md`, `docs/RESEARCH.md` networking table |
+| Source files added/removed/renamed | `docs/ARCHITECTURE.md` file map, `CMakeLists.txt`, this file |
+| A new measurement | `docs/RESEARCH.md` with machine, kernel, and what was run |
+| A new known gap or a closed gap | `docs/RESEARCH.md` gaps list and `README.md` |
+| These workflow rules | this file |
+| A measurement, or anything the charts show | `make bench` then `make charts` (rewrites `docs/charts/*.svg` and every `` number and table in `COMPARISON.md` and `docs/RESEARCH.md`); never type those numbers by hand |
+| A feature or limit that appears in the comparison tables | `COMPARISON.md` (tables, the gaps list, the conclusion) |
+| A code path one of the `audit/CVE-*` checks targets (overlay writes, tar extraction, mount/directory creation, net namespace sharing, seccomp denylist) | re-run `make audit`; update that CVE's `README.md` if the verdict's reasoning changed |
+| Allocation shape of `containerInit`, `setupRoot`, `doMount` or `Sandbox::start` | re-run `make valgrind`; if a suppressed site's stack trace changed, regenerate it (see [valgrind/README.md](valgrind/README.md)) and update `valgrind/doos.supp`'s comment |
+| A new or renamed markdown file | `scripts/check-docs.sh` DOCS list, the nav line (`**Docs:**`) of every document, `README.md` Project docs |
+| Image catalog, sources, verification, pinned keys | `SPEC.md` Images, `README.md`, `docs/RESEARCH.md` |
+| Seccomp list, capability set, `/etc` allowlist | `SPEC.md` Hardening and filesystem, `README.md`, `docs/RESEARCH.md` |
+| Limits, cgroup layout | `SPEC.md` Resource limits, `docs/ARCHITECTURE.md` |
+| Anything above, in every release | `CHANGELOG.md` entry (`README.md` points at `VERSION`, nothing to edit there) |
+| The CI workflow or what a job needs | `.gitea/workflows/ci.yml`, `docs/CI.md` |
+| The davmount flow, pinned rclone version/key, or what `--mount`/`--davmount` accepts | `SPEC.md` (CLI options, davmount section, limits), `docs/ARCHITECTURE.md` davmount flow, `docs/RESEARCH.md` G13 |
+
+Docs describe what the system does today. No roadmap text. A gap is listed next to
+what would close it. A number in the docs needs a run behind it, else say it is unmeasured.
+
+## Changelog
+
+Every release adds a `CHANGELOG.md` entry (newest first): version, date, bullets of
+what changed for users. The release script does not write it; write it before running
+the script.
+
+## Code rules
+
+- C++20, extremely object oriented: one class per responsibility (see file map).
+- Every limit is a named constant in `src/spec.hpp` and listed in `SPEC.md`.
+- No unbounded loops, sizes or recursion. Add a cap when you add a loop.
+- Destructive operations: dry-run by default, `--yes` to act, scoped to the store.
+- Fail loudly with a clear message. Never swallow an error that leaves state half-built.
+- Match surrounding style. No new dependencies without a stated reason.
+- Never use em dashes (U+2014) anywhere. The release script rejects them.
+- Output must stay readable on a narrow terminal.
+
+## Testing
+
+`tests/run.sh [path/to/doos]` runs the real path: real overlayfs, namespaces,
+slirp4netns, filesystem, real downloads of the Alpine and Ubuntu images, real apt/apk installs, the size
+freeze, a real WebDAV round trip through a disposable local `rclone serve webdav` fixture (about 4-5
+minutes in total, needs network, `pasta`, `gpg`, `unzip` and cgroup v2 delegation). Add a case for every
+behavior change. A green run is required before release. On Ubuntu 24.04+ the AppArmor profile in
+`apparmor/doos` must be installed once for the binary being tested (`doos apparmor`; needs sudo, ask the
+user, do not do it yourself).
+
+## CI
+
+`.gitea/workflows/ci.yml` runs `build`, `valgrind`, `test` and `audit` on every push (Gitea Actions).
+`test` and `audit` need the self-hosted host-mode runner described in [docs/CI.md](docs/CI.md) (real
+namespaces, cgroup v2 delegation, the AppArmor profile); the workflow itself never runs `sudo`, same
+rule as everywhere else. See that file before changing the workflow or what a job needs.
+
+## Make targets
+
+`make help` lists them: `build`, `test`, `audit` (named CVE regression checks against `build/doos`,
+see [audit/README.md](audit/README.md)), `valgrind` (memcheck against a fixed set of invocations,
+see [valgrind/README.md](valgrind/README.md)), `check-docs`, `bench` (re-measure into `docs/charts/bench.json`),
+`charts` (SVGs and generated numbers from that file), `docs`, `release KIND=patch MSG="..."`, `clean`.
+The Makefile is a thin wrapper; the logic lives in `CMakeLists.txt`, `scripts/`, `audit/`, `valgrind/` and `docs/charts/`.
+
+## Environment notes
+
+- State dir: `$DOOS_HOME`, else `$XDG_DATA_HOME/doos`, else `~/.local/share/doos`.
+ Tests use a temp `DOOS_HOME`; never point tests at the user's real store.
+- Build: `cmake -S . -B build && cmake --build build`.
+- Requirements: Linux >= 5.11, `slirp4netns` for the default network mode. `unzip` and `fusermount3`
+ (or `fusermount`) are needed only for `--mount`/`--davmount` against a `dav://`/`davs://`/`http(s)://`
+ source; doos installs its own `rclone` under `$DOOS_HOME/tools/`, never the system's.
diff --git a/src/doos/docs/history/prompt.md b/src/doos/docs/history/prompt.md
new file mode 100644
index 0000000..acca69a
--- /dev/null
+++ b/src/doos/docs/history/prompt.md
@@ -0,0 +1,9 @@
+DIt project moet doos heten. Het is geschreven in C++ en het bied een user-level container die gebruik maakt van een overlayfs.
+Het moet cli commands hebben voor:
+ - list containers
+ - get_or_create container
+ - attach container (this does get_or_Create first)
+ - delete container
+THe containers should have networking going on.
+
+Please deep resarch on how to achieve all this on user level and what mounts we need while keeping our host safe.
diff --git a/src/doos/docs/history/review.md b/src/doos/docs/history/review.md
new file mode 100644
index 0000000..620964e
--- /dev/null
+++ b/src/doos/docs/history/review.md
@@ -0,0 +1,52 @@
+# doos: Security Review
+
+Date: 2026-10-23 | Reviewer: tai | Scope: `src/*.cpp/*.hpp`, `CMakeLists.txt`, `Makefile`, `apparmor/doos`, `tests/run.sh`, `docs/*`, `SPEC.md`
+Build: C++17 CMake project ("doos" container/sandbox tool using user namespaces, cgroup v2, seccomp-bpf, pasta/slirp4netns networking, overlayfs).
+
+## Summary
+Rootless container runtime with generally sound isolation primitives (user ns + idmap, pivot_root, cap-drop, seccomp denylist, no-new-privs, cgroup limits). Main risks: privileged helpers trusted via PATH (`pasta`, `slirp4netns`, `newuidmap/newgidmap`), TOCTOU-prone fs setup, permissive `--hardening relaxed` and `--net host` modes, and missing supply-chain/hardening controls (no SBOM/signing, no CI fuzz/scan, trivial AppArmor profile).
+
+## Findings (severity-ordered)
+1. **[MEDIUM] PATH-based exec of network helpers**: `src/network.cpp` execs `pasta`/`slirp4netns` resolved via PATH; a poisoned PATH in attach path = code exec as the user. Mitigate with absolute paths + allowlist env scrub.
+2. **[MEDIUM] Symlink-following fs staging (TOCTOU)**: `src/sandbox.cpp:133-139` mirrors host `/etc` entries with `symlink_status`/`read_symlink` then recreates; bind source handling without `O_NOFOLLOW`/fd-relative ops invites race/escape. Use `openat2(RESOLVE_NO_SYMLINKS)` or pin fds.
+3. **[MEDIUM] `relaxed` mode silently drops most controls**: per `cli.cpp:121`, relaxed = no cap-drop, no seccomp, full `/etc`. Users likely won't grasp severity. Require explicit `--i-understand` flag + warning.
+4. **[MEDIUM] No integrity for images/layers**: `src/image.cpp` untars with numeric-owner handling but no digest/signature verification. Tampered tar = full container compromise. Add sha256 manifest check.
+5. **[LOW] Temp overlay upperdir via `mkdtemp` in shared TMPDIR**: `src/image.cpp:52` uses `temp_directory_path()` (often `/tmp`, sticky but world-visible); predictable staging + 0700 chmod after the fact. Prefer per-user state dir with `O_EXCL`.
+6. **[LOW] `sscanf` parsing of cgroup stat**: `src/container.cpp:231` unchecked return; malformed file → stale values. Check return value.
+7. **[LOW] AppArmor profile is a stub**: `apparmor/doos` (12 lines) grants far less than runtime needs / isn't enforced by code. Either complete or remove to avoid false assurance.
+8. **[INFO] No seccomp allowlist, denylist only**: `hardening.cpp` blocks keyring/bpf/perf/io_uring/mount/kexec/module-load; reasonable, but bypass surface remains (ptrace? userfaultfd covered). Document residual attack surface.
+9. **[INFO] No network egress policy**: pasta/slirp give full user-mode egress; no DNS/TLS filtering. Expected for dev tool; document.
+
+### What is done well
+- User-namespace-first, no setuid binary; `newuidmap` delegation preferred.
+- `NO_NEW_PRIVS` + capability bounding set to Docker-default keep-list.
+- `/proc`/`/sys` remounts read-only, masked paths (`kcore`, `keys`), minimal `/dev`.
+- Cgroup v2 `main/` vs `shell/` split with freeze + rescue path is thoughtful anti-ransom design.
+- `pivot_root` (not just chroot), `umask`, `0700/0640` perms on state.
+
+## Grades (0–10, 10=excellent)
+| Category | Score | Rationale |
+|---|---|---|
+| Isolation & sandboxing | 7.5 | userns+pivot+cap-drop+seccomp+nonewprivs solid; weakened by relaxed mode, helper PATH trust |
+| Filesystem security | 6.5 | Good perms/skeleton; symlink TOCTOU + /tmp staging + no dm-verity/readonly-root |
+| Privilege & identity mgmt | 7.0 | No setuid, subuid mapping correct; host-uid file visibility nuance documented but subtle |
+| Network security | 6.0 | User-mode net avoids root; no egress/filtering, PATH-exec helpers, `--net host` footgun |
+| Resource controls (DoS) | 8.0 | cgroup v2 mem/pids/cpu + freeze model; best-effort when undelegated (fail-open must warn) |
+| Input validation & parsing | 6.5 | CLI fixed-value flags good; tar/symlink handling + sscanf without strict checks |
+| Secrets & state handling | 7.0 | State under DOOS_HOME with 0700; env (HOME/PATH) trusted too broadly |
+| Supply chain & build | 5.0 | No SBOM, signing, pinning, CI SAST/fuzz; CMake clean but no `-D_FORTIFY`/`-fstack-protector` audit |
+| Observability & audit | 5.5 | `doos list` table ok; no security event log, no seccomp-deny telemetry |
+| Defaults & secure-by-default | 6.0 | Default mode good; relaxed/host modes one flag away with weak friction |
+| **Overall** | **6.5** | Solid rootless dev-sandbox; fix PATH-exec, TOCTOU, image integrity before untrusted workloads |
+
+## Recommendations (prioritized)
+1. Absolute-path helpers + minimal sanitized env for all `execvp`.
+2. `openat2` / fd-pinned fs staging; fail closed on symlink races.
+3. Image digest verification (sha256 manifest) before untar.
+4. Gate `relaxed`/`--net host` behind explicit confirmation + log warning.
+5. Harden build flags (`-Wall -Wextra -Werror -D_FORTIFY_SOURCE=3 -fstack-protector-strong -Wl,-z,RelRO,Now`), add SBOM + CI (CodeQL/Semgrep/Trivy).
+6. Check `sscanf` returns; move temp staging under state dir.
+7. Finish or drop AppArmor profile; add seccomp-deny + OOM audit logging.
+
+## Verdict
+Fit for trusted-dev use. **Not yet recommended** for running untrusted images/payloads until (1), (2), (3) are fixed.
diff --git a/src/doos/docs/history/review2.md b/src/doos/docs/history/review2.md
new file mode 100644
index 0000000..cfb72d5
--- /dev/null
+++ b/src/doos/docs/history/review2.md
@@ -0,0 +1,150 @@
+# doos: full review
+
+Date: 2026-10-24 | Scope: all of `src/` (3,558 lines, read in full), `CMakeLists.txt`, `Makefile`,
+`scripts/*.sh`, `tests/run.sh`, `audit/`, `valgrind/`, and every document (`README.md`, `SPEC.md`,
+`docs/ARCHITECTURE.md`, `docs/RESEARCH.md`, `COMPARISON.md`, `AGENTS.md`, `CHANGELOG.md`).
+Method: read every source file top to bottom (not a diff), ran the real e2e suite, the CVE audit,
+and valgrind against the current binary, and tested two inputs by hand that looked suspicious while
+reading. This is a second, independent pass; [`review.md`](review.md) is an earlier review whose
+findings are checked against the current code, not reused.
+
+**State at review time:** `v1.3.1`, working tree clean, `tests/run.sh` 88/88, `make audit` 18/18,
+`make valgrind` 6/6 (see those tools for what they do and do not cover).
+
+## 1. Summary
+
+doos is a small, coherent, unusually well-specified codebase for what it is: a single C++20 binary
+that builds a user-namespace container by hand (no runc, no libcontainer, no OCI anything) and
+backs it with overlayfs, cgroup v2 and a seccomp denylist. The code reads like it was written by one
+disciplined author following one set of rules consistently: every constant lives in `spec.hpp`, every
+destructive path is capped, every external process is run from a fixed path, every error throws with
+a message that says what to do about it. The project-level discipline (docs that state gaps next to
+the code that closes them, a changelog per release, a `make audit`/`make valgrind` pair that produces
+actual evidence instead of claims) is better than most projects an order of magnitude larger.
+
+The flip side of "one author, one style" is that nothing here has been read by a second pair of eyes
+until review.md and this review. I found one confirmed, reproducible bug (an integer overflow that
+silently accepts a nonsensical `--size`) and a handful of smaller inconsistencies and gaps, listed
+below. Nothing I found is a new security hole in the model doos is actually built on; the shared-kernel,
+denylist-seccomp, unaudited-code risks are already disclosed in `COMPARISON.md` section 6 and
+`docs/RESEARCH.md`, and I did not find reason to soften or harden that disclosure.
+
+**Resolution (1.3.2, same day):** 2.1, 2.2 and 2.4 are fixed (see `CHANGELOG.md`); 2.3 is logged as
+an accepted trade-off (gap G11 in `docs/RESEARCH.md`) rather than fixed; 2.5's CI half is resolved
+by `.gitea/workflows/ci.yml` and `docs/CI.md`, and its LICENSE half by the new `LICENSE` file. The
+findings below are left exactly as first written, for the record of what was found and how.
+
+## 2. Findings
+
+Ordered most to least severe. Each is something I read or reproduced, not a hypothetical.
+
+### 2.1 [MEDIUM] `parseSize` silently overflows on an absurd input, instead of rejecting it
+
+`src/util.cpp:54-71`. The function accepts up to 15 digits, then left-shifts by up to 40 bits with no
+overflow check. `--size 16777217t` (16.7 million exabytes, obvious garbage) wraps around 64-bit
+arithmetic to exactly `2^40`, which is `1.0T`, which is a *valid* size, so it is accepted silently:
+
+```
+$ doos get_or_create --size 16777217t sizetest2
+created sizetest2
+$ doos list
+NAME STATE NET IMAGE SIZE AGE
+sizetest2 stopped slirp host 1.0T 0s
+```
+
+Reproduced against `build/doos` at the time of this review. The same shift pattern exists for `k`/`m`/`g`
+too, just with smaller multipliers that need more digits to wrap; `t` wraps with an 8-digit input. Every
+caller does bound-check the *result*, which is why most overflowing inputs are still rejected (the
+earlier example, `16777217t`+1 lands outside range and throws): it is specifically the inputs that
+wrap into the valid `[64m, 1t]` window that go through unnoticed. Fix: check `v > (kMaxSizeBytes >>
+shift)` before shifting, or reject more than 4-5 digits before a `t`/`g` suffix.
+
+### 2.2 [LOW] Two different "no PATH lookup" strategies for external helpers, not one
+
+`spec.hpp:52-53,75-76` hardcode `/usr/bin/newuidmap`, `/usr/bin/newgidmap`, `/usr/bin/slirp4netns`,
+`/usr/bin/pasta` as single absolute paths. `resolveBinary()` (`src/util.cpp:397-417`) instead checks a
+state-dir override then a list of six system directories, and is used for `curl`, `tar`, `sha256sum`
+and `gpg`. Both avoid a `PATH`-poisoning attack (the actual goal, and both reach it), but the first
+group breaks if a distribution installs those four tools somewhere other than exactly `/usr/bin` (for
+example Fedora's `/usr/sbin` for some setuid helpers, or a non-standard prefix), while the second group
+would still find them. This is not a security gap, it is an inconsistency that will show up as a
+confusing "helper not found" on a distro the project has not been tested on, where the real fix (run
+`resolveBinary()` for all five, or document the four as intentionally pinned) is a few lines either way.
+
+### 2.3 [LOW] Catalog YAML/JSON parsing is hand-rolled string search, not a parser
+
+`src/image.cpp:160-173` (Alpine's `latest-releases.yaml`) and `src/image.cpp:192-204` (Debian's
+`index.json`, including a base64-embedded manifest) are read with `line.find(...)` and fixed byte
+offsets, not a YAML/JSON library. This keeps the dependency count at zero, which fits the project's
+"fewer moving parts" rule, and it is already tested against the real Alpine and Debian endpoints in
+`tests/run.sh`. The risk is narrow but real: if either publisher reformats their file (reorders keys,
+changes indentation, wraps a line), the parser fails closed with a thrown error (good: `docs/RESEARCH.md`
+already calls this an accepted trade-off for Debian specifically) rather than silently extracting the
+wrong artifact. Worth a one-line gap entry next to the code, same as the project's own convention asks.
+
+### 2.4 [LOW] `Sandbox::join`'s ordering is a correctness invariant that is not stated in code
+
+`src/sandbox.cpp:521-581`. Joining a running container does six `setns()` calls in a plain (not yet
+seccomp-filtered) forked process, then forks again and *only there* calls `applyLimitsAndEnv`, which
+installs the seccomp filter that denies `setns` (`src/hardening.cpp:184-186`). This is correct and
+I could not find a bug in it, but the correctness depends entirely on hardening being applied after
+the `setns` loop and in the right (inner) fork, a constraint that lives only in the order of statements,
+not in a comment or an assertion. A future edit that moves `applyLimitsAndEnv` earlier "to simplify"
+would silently break every second `attach`, and the e2e suite's "second attach joins" case would need
+to be the thing that catches it rather than a comment telling the next editor not to do that.
+
+### 2.5 [LOW] No CI, no license file
+
+`find . -iname "*.yml"` turns up nothing; there is no `.github/workflows`, so the 88-check e2e suite,
+`make audit` and `make valgrind` only run when someone remembers to run them by hand. There is also no
+`LICENSE` file, which for a "commercial and scientific" project (the user's own standing rule) means
+the legal default is "all rights reserved" by anyone who is not the author, worth a deliberate choice
+rather than an omission.
+
+### 2.6 [INFO] Everything else I checked was either already documented or held up
+
+I specifically went looking for bugs in the capability-drop/seccomp-install ordering relative to
+`execve`, in the overlayfs mount option construction, in the `--size`/`--memory`/`--pids`/`--cpus`
+range validation (other than 2.1), in the container/image name validators against path traversal, in
+`Store::remove`'s delete-outside-the-store guard, and in the symlink handling added for the PATH and
+TOCTOU fixes (`src/util.cpp:329-354`, `src/sandbox.cpp:130-153`). All of it matched what the comments
+claim, and the specific "mkdirs follows a symlink" class of bug this project itself found via
+`audit/CVE-2021-30465` is closed the right way (per-component `openat(O_NOFOLLOW)`), not patched over.
+
+## 3. Grades
+
+| Category | Grade | Why |
+|---|---|---|
+| Architecture & code organization | 8.5/10 | One class per responsibility, matches `docs/ARCHITECTURE.md` exactly; every constant in one file; consistent error style throughout 3,558 lines. Loses points only for 2.4's unstated invariant. |
+| Correctness & input validation | 7/10 | Careful everywhere except one real bug (2.1). CLI parsing, name validation, bounds checks on memory/pids/cpus are all solid; size parsing is the one spot that was not. |
+| Isolation design (namespaces, overlayfs, mounts) | 9/10 | TOCTOU-safe symlink handling, `O_NOFOLLOW` directory creation, correct remount-flag preservation, correct setns/seccomp ordering. This is the part of the codebase that most clearly got the most attention, and it shows. |
+| Resource controls (cgroup, size cap) | 8.5/10 | Adaptive scan-duty throttling, freeze/thaw hysteresis, whole-container OOM kill, hard caps on scan size and tree depth. Honestly scoped: documented as advisory without cgroup v2 delegation rather than pretending to enforce. |
+| Supply chain (image verification) | 8/10 | Real signature verification against pinned fingerprints for two of three catalog sources, sha256 for all three, URL inputs refused without a hash. Loses points for the hand-rolled parsers (2.3) and for Debian having no publisher signature (disclosed, not doos's fault, but still the weakest link). |
+| Hardening (capabilities, seccomp) | 8/10 | Matches Docker's default capability mask (measured, not assumed), denylist seccomp with the known evasions (x32, clone3, nested userns) explicitly closed. A denylist is inherently weaker than an allowlist by design, which the project says itself in `COMPARISON.md`; grade reflects execution of the chosen design, not the design choice. |
+| Testing & verification tooling | 8.5/10 | 88 end-to-end checks through the real path (real overlayfs, real downloads, real cgroups), plus `audit/` (18 named CVEs with working reproducers) and `valgrind/` (6 checks, suppressions individually justified) are well above what a project this size usually has. One machine, one architecture, no CI (2.5) is the honest ceiling. |
+| Documentation | 9/10 | Seven cross-linked documents that state what exists today, with gaps listed next to the code that closes them; generated numbers and charts instead of hand-typed ones; a changelog that actually matches releases. Among the best-documented small C++ projects I have reviewed. |
+| Build & release automation | 8.5/10 | `scripts/release.sh` bumps, builds, tests, checks docs, commits and tags in one gated command and aborts on any failure; hardened compiler/linker flags. Loses half a point for no CI to run any of it automatically. |
+| CLI/UX | 7.5/10 | Clear, narrow-terminal-friendly usage text; sensible fixed-vs-changeable option model; good error messages that say what to do next. `--i-understand` as a deliberate confirmation gate for reduced sandboxing is a good pattern. |
+| Project hygiene | 6/10 | No LICENSE, no CI (2.5); otherwise clean (`.gitignore` is thorough, no stray build artifacts tracked, commit messages are consistent and attributed). |
+
+**Overall: 8/10.** A small, honest, carefully built tool with one real bug found by testing it rather
+than reading it, and a short, specific list of things worth fixing. Nothing found here changes the
+conclusion already in `COMPARISON.md`: fine for your own tools, not a substitute for an audited,
+multi-tenant-hardened runtime.
+
+## 4. Recommended order of fixes
+
+1. Fix the `parseSize` overflow (2.1): cheapest fix, only confirmed bug, trivial to test.
+2. Add a one-line comment above `applyLimitsAndEnv`'s two call sites in `sandbox.cpp` stating the
+ ordering invariant from 2.4, so the next edit does not have to rediscover it the hard way.
+3. Decide and document the helper-resolution split (2.2): either move the four pinned paths through
+ `resolveBinary()`, or add one line to `SPEC.md` saying why they are intentionally narrower.
+4. Add a LICENSE file (2.5); pick whichever the user already uses elsewhere.
+5. CI is the only item here that is genuinely more than a few lines of work (namespaces, cgroup v2
+ delegation and AppArmor all need to exist on the runner); worth a separate, explicit decision
+ rather than a drive-by addition.
+
+**Docs:** [README](README.md) · [SPEC](SPEC.md) · [ARCHITECTURE](docs/ARCHITECTURE.md) ·
+[RESEARCH](docs/RESEARCH.md) · [COMPARISON](COMPARISON.md) · [AGENTS](AGENTS.md) ·
+[CHANGELOG](CHANGELOG.md) · [audit](audit/README.md) · [valgrind](valgrind/README.md) ·
+[review.md](review.md) (earlier security-only review)
diff --git a/src/doos/doos.mk b/src/doos/doos.mk
new file mode 100644
index 0000000..d08021d
--- /dev/null
+++ b/src/doos/doos.mk
@@ -0,0 +1,105 @@
+# Part doos (rootless user-level containers) build fragment.
+# Included by the root Makefile. Double-colon rules let every part append
+# its own all/test/clean steps without editing shared targets.
+# Standalone from the repo root:
+# make -f src/doos/doos.mk doos # build/doos/doos binary
+# make -f src/doos/doos.mk doos-test # hermetic suites (no network)
+# make -f src/doos/doos.mk doos-live # full e2e (needs network)
+# make -f src/doos/doos.mk doos-valgrind # memcheck fixed invocations
+# make -f src/doos/doos.mk doos-docs # charts plus docs check
+#
+# Layout: static lib build/doos/libdoos.a (linked by molo and the seams)
+# plus the preserved standalone binary build/doos/doos.
+
+DOOS_CXX ?= g++
+DOOS_CXXFLAGS ?= -std=c++23 -O2 -g -Wall -Wextra -Wpedantic -Werror -MMD -MP -D_FORTIFY_SOURCE=3 -fstack-protector-strong
+DOOS_LDFLAGS ?= -Wl,-z,relro -Wl,-z,now
+DOOS_ROOT = src/doos
+DOOS_BUILD = build/doos
+DOOS_LIB = $(DOOS_BUILD)/libdoos.a
+DOOS_BIN = $(DOOS_BUILD)/doos
+DOOS_INCPATH = -Isrc -Isrc/cli
+DOOS_VERSION := $(strip $(shell cat $(DOOS_ROOT)/VERSION))
+DOOS_DEFS = -DDOOS_VERSION='"$(DOOS_VERSION)"'
+
+DOOS_SRCS = \
+ $(DOOS_ROOT)/hardening.cpp \
+ $(DOOS_ROOT)/idmap.cpp \
+ $(DOOS_ROOT)/image.cpp \
+ $(DOOS_ROOT)/cgroup.cpp \
+ $(DOOS_ROOT)/cli.cpp \
+ $(DOOS_ROOT)/container.cpp \
+ $(DOOS_ROOT)/network.cpp \
+ $(DOOS_ROOT)/sandbox.cpp \
+ $(DOOS_ROOT)/util.cpp \
+ $(DOOS_ROOT)/davmount.cpp \
+ $(DOOS_ROOT)/cli/forward.cpp \
+ $(DOOS_ROOT)/cli/doos_cli.cpp \
+ $(DOOS_ROOT)/seam/isolation.cpp \
+ $(DOOS_ROOT)/deploy/doos_strategy.cpp
+
+DOOS_OBJS = $(DOOS_SRCS:$(DOOS_ROOT)/%.cpp=$(DOOS_BUILD)/%.o)
+DOOS_MAIN_OBJ = $(DOOS_BUILD)/main.o
+
+SUP_LIB ?=
+DOOS_TEST_SRCS := $(sort $(wildcard tests/src/doos/test_*.cpp))
+DOOS_TEST_BINS := $(patsubst tests/src/doos/%.cpp,$(DOOS_BUILD)/%,$(filter-out tests/src/doos/test_isolation.cpp,$(DOOS_TEST_SRCS)))
+ifneq ($(SUP_LIB),)
+DOOS_TEST_BINS += $(DOOS_BUILD)/test_isolation
+DOOS_TEST_SKIP_NOTE = true
+else
+DOOS_TEST_SKIP_NOTE = echo "SKIP test_isolation: SUP_LIB unavailable (root build only)"
+endif
+
+all:: $(DOOS_LIB) $(DOOS_BIN)
+
+$(DOOS_LIB): $(DOOS_OBJS)
+ @mkdir -p $(DOOS_BUILD)
+ ar rcs $@ $^
+
+$(DOOS_BUILD)/%.o: $(DOOS_ROOT)/%.cpp
+ @mkdir -p $(dir $@)
+ $(DOOS_CXX) $(DOOS_CXXFLAGS) $(DOOS_INCPATH) $(DOOS_DEFS) -c $< -o $@
+
+$(DOOS_BIN): $(DOOS_MAIN_OBJ) $(DOOS_LIB)
+ @mkdir -p $(DOOS_BUILD)
+ $(DOOS_CXX) $(DOOS_CXXFLAGS) $(DOOS_MAIN_OBJ) $(DOOS_LIB) $(DOOS_LDFLAGS) -o $@
+
+$(DOOS_BUILD)/test_%: tests/src/doos/test_%.cpp $(DOOS_LIB)
+ @mkdir -p $(DOOS_BUILD)
+ $(DOOS_CXX) $(DOOS_CXXFLAGS) $(DOOS_INCPATH) $(DOOS_DEFS) -Itests/src/doos $< $(DOOS_LIB) -o $@
+
+ifneq ($(SUP_LIB),)
+$(DOOS_BUILD)/test_isolation: tests/src/doos/test_isolation.cpp $(DOOS_LIB) $(SUP_LIB)
+ @mkdir -p $(DOOS_BUILD)
+ $(DOOS_CXX) $(DOOS_CXXFLAGS) $(DOOS_INCPATH) $(DOOS_DEFS) -Itests/src/doos $< $(DOOS_LIB) $(SUP_LIB) -o $@
+endif
+
+doos-test: $(DOOS_BIN) $(DOOS_TEST_BINS)
+ @mkdir -p build/doos-tmp
+ @$(DOOS_TEST_SKIP_NOTE)
+ @for t in $(DOOS_TEST_BINS); do echo "== $$t"; TMPDIR=$${TMPDIR:-$(abspath build/doos-tmp)} ./$$t || exit 1; done
+ @echo "doos: hermetic suites green"
+
+test:: doos-test
+
+doos-live: $(DOOS_BIN)
+ @mkdir -p build/doos-tmp
+ TMPDIR=$${TMPDIR:-$(abspath build/doos-tmp)} ./tests/src/doos/run_live.sh $(abspath $(DOOS_BIN))
+
+doos-valgrind: $(DOOS_BIN)
+ @mkdir -p build/doos-tmp
+ TMPDIR=$${TMPDIR:-$(abspath build/doos-tmp)} VALGRIND_REPORTS=$(abspath $(DOOS_BUILD))/valgrind-reports ./$(DOOS_ROOT)/scripts/valgrind.sh $(abspath $(DOOS_BIN))
+
+doos-docs:
+ python3 $(DOOS_ROOT)/docs/charts/make_charts.py
+ ./$(DOOS_ROOT)/scripts/check-docs.sh
+
+clean::
+ rm -rf $(DOOS_BUILD)
+
+.PHONY: doos doos-test doos-live doos-valgrind doos-docs
+
+doos: $(DOOS_BIN)
+
+-include $(DOOS_OBJS:.o=.d)
diff --git a/src/doos/hardening.cpp b/src/doos/hardening.cpp
new file mode 100644
index 0000000..ea0be43
--- /dev/null
+++ b/src/doos/hardening.cpp
@@ -0,0 +1,262 @@
+#include "doos/hardening.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+
+#include "doos/caps.h"
+#include "doos/util.hpp"
+
+#ifndef SECCOMP_RET_KILL_PROCESS
+#define SECCOMP_RET_KILL_PROCESS 0x80000000U
+#endif
+#ifndef CAP_LAST_CAP_FALLBACK
+#define CAP_LAST_CAP_FALLBACK 40
+#endif
+
+namespace molo::doos {
+
+namespace {
+
+#if defined(__x86_64__)
+constexpr unsigned kArch = AUDIT_ARCH_X86_64;
+constexpr bool kHasX32 = true;
+#elif defined(__aarch64__)
+constexpr unsigned kArch = AUDIT_ARCH_AARCH64;
+constexpr bool kHasX32 = false;
+#else
+constexpr unsigned kArch = 0;
+constexpr bool kHasX32 = false;
+#endif
+
+// Syscalls answered with EPERM. Entries the architecture does not have are skipped at compile time.
+std::vector deniedSyscalls() {
+ std::vector v;
+#define DENY(name) v.push_back(static_cast(name))
+#ifdef SYS_acct
+ DENY(SYS_acct);
+#endif
+#ifdef SYS_add_key
+ DENY(SYS_add_key);
+#endif
+#ifdef SYS_bpf
+ DENY(SYS_bpf);
+#endif
+#ifdef SYS_clock_adjtime
+ DENY(SYS_clock_adjtime);
+#endif
+#ifdef SYS_clock_settime
+ DENY(SYS_clock_settime);
+#endif
+#ifdef SYS_create_module
+ DENY(SYS_create_module);
+#endif
+#ifdef SYS_delete_module
+ DENY(SYS_delete_module);
+#endif
+#ifdef SYS_finit_module
+ DENY(SYS_finit_module);
+#endif
+#ifdef SYS_init_module
+ DENY(SYS_init_module);
+#endif
+#ifdef SYS_get_kernel_syms
+ DENY(SYS_get_kernel_syms);
+#endif
+#ifdef SYS_keyctl
+ DENY(SYS_keyctl);
+#endif
+#ifdef SYS_kexec_file_load
+ DENY(SYS_kexec_file_load);
+#endif
+#ifdef SYS_kexec_load
+ DENY(SYS_kexec_load);
+#endif
+#ifdef SYS_lookup_dcookie
+ DENY(SYS_lookup_dcookie);
+#endif
+#ifdef SYS_nfsservctl
+ DENY(SYS_nfsservctl);
+#endif
+#ifdef SYS_open_by_handle_at
+ DENY(SYS_open_by_handle_at);
+#endif
+#ifdef SYS_perf_event_open
+ DENY(SYS_perf_event_open);
+#endif
+#ifdef SYS_pivot_root
+ DENY(SYS_pivot_root);
+#endif
+#ifdef SYS_process_vm_readv
+ DENY(SYS_process_vm_readv);
+#endif
+#ifdef SYS_process_vm_writev
+ DENY(SYS_process_vm_writev);
+#endif
+#ifdef SYS_query_module
+ DENY(SYS_query_module);
+#endif
+#ifdef SYS_quotactl
+ DENY(SYS_quotactl);
+#endif
+#ifdef SYS_reboot
+ DENY(SYS_reboot);
+#endif
+#ifdef SYS_request_key
+ DENY(SYS_request_key);
+#endif
+#ifdef SYS_settimeofday
+ DENY(SYS_settimeofday);
+#endif
+#ifdef SYS_stime
+ DENY(SYS_stime);
+#endif
+#ifdef SYS_swapon
+ DENY(SYS_swapon);
+#endif
+#ifdef SYS_swapoff
+ DENY(SYS_swapoff);
+#endif
+#ifdef SYS_sysfs
+ DENY(SYS_sysfs);
+#endif
+#ifdef SYS__sysctl
+ DENY(SYS__sysctl);
+#endif
+#ifdef SYS_uselib
+ DENY(SYS_uselib);
+#endif
+#ifdef SYS_userfaultfd
+ DENY(SYS_userfaultfd);
+#endif
+#ifdef SYS_ustat
+ DENY(SYS_ustat);
+#endif
+#ifdef SYS_mount
+ DENY(SYS_mount);
+#endif
+#ifdef SYS_umount2
+ DENY(SYS_umount2);
+#endif
+#ifdef SYS_umount
+ DENY(SYS_umount);
+#endif
+#ifdef SYS_mount_setattr
+ DENY(SYS_mount_setattr);
+#endif
+#ifdef SYS_move_mount
+ DENY(SYS_move_mount);
+#endif
+#ifdef SYS_open_tree
+ DENY(SYS_open_tree);
+#endif
+#ifdef SYS_fsopen
+ DENY(SYS_fsopen);
+#endif
+#ifdef SYS_fsconfig
+ DENY(SYS_fsconfig);
+#endif
+#ifdef SYS_fsmount
+ DENY(SYS_fsmount);
+#endif
+#ifdef SYS_fspick
+ DENY(SYS_fspick);
+#endif
+#ifdef SYS_io_uring_setup
+ DENY(SYS_io_uring_setup);
+#endif
+#ifdef SYS_io_uring_enter
+ DENY(SYS_io_uring_enter);
+#endif
+#ifdef SYS_io_uring_register
+ DENY(SYS_io_uring_register);
+#endif
+#ifdef SYS_setns
+ DENY(SYS_setns);
+#endif
+#ifdef SYS_kcmp
+ DENY(SYS_kcmp);
+#endif
+#undef DENY
+ return v;
+}
+
+sock_filter stmt(unsigned short code, unsigned k) { return BPF_STMT(code, k); }
+sock_filter jump(unsigned short code, unsigned k, unsigned char jt, unsigned char jf) { return BPF_JUMP(code, k, jt, jf); }
+
+constexpr unsigned kOffNr = offsetof(seccomp_data, nr);
+constexpr unsigned kOffArch = offsetof(seccomp_data, arch);
+constexpr unsigned kOffArg0 = offsetof(seccomp_data, args); // low 32 bits on little-endian
+
+std::vector buildFilter() {
+ const unsigned eperm = SECCOMP_RET_ERRNO | EPERM;
+ const unsigned enosys = SECCOMP_RET_ERRNO | ENOSYS;
+ std::vector f;
+ // wrong architecture: kill, never guess
+ f.push_back(stmt(BPF_LD | BPF_W | BPF_ABS, kOffArch));
+ f.push_back(jump(BPF_JMP | BPF_JEQ | BPF_K, kArch, 1, 0));
+ f.push_back(stmt(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS));
+ f.push_back(stmt(BPF_LD | BPF_W | BPF_ABS, kOffNr));
+ if (kHasX32) { // x32 syscall numbers must not dodge the numbers below
+ f.push_back(jump(BPF_JMP | BPF_JSET | BPF_K, 0x40000000U, 0, 1));
+ f.push_back(stmt(BPF_RET | BPF_K, enosys));
+ }
+ // clone3 cannot be inspected (flags live in a struct): ENOSYS makes libc fall back to clone()
+#ifdef SYS_clone3
+ f.push_back(jump(BPF_JMP | BPF_JEQ | BPF_K, static_cast(SYS_clone3), 0, 1));
+ f.push_back(stmt(BPF_RET | BPF_K, enosys));
+#endif
+ // clone/unshare with CLONE_NEWUSER: EPERM (nested user namespaces are the usual first step of kernel exploits)
+ for (unsigned nr : {static_cast(SYS_clone), static_cast(SYS_unshare)}) {
+ f.push_back(jump(BPF_JMP | BPF_JEQ | BPF_K, nr, 0, 4));
+ f.push_back(stmt(BPF_LD | BPF_W | BPF_ABS, kOffArg0));
+ f.push_back(jump(BPF_JMP | BPF_JSET | BPF_K, CLONE_NEWUSER, 0, 1));
+ f.push_back(stmt(BPF_RET | BPF_K, eperm));
+ f.push_back(stmt(BPF_LD | BPF_W | BPF_ABS, kOffNr)); // restore the accumulator for the next compare
+ }
+ for (unsigned nr : deniedSyscalls()) {
+ f.push_back(jump(BPF_JMP | BPF_JEQ | BPF_K, nr, 0, 1));
+ f.push_back(stmt(BPF_RET | BPF_K, eperm));
+ }
+ f.push_back(stmt(BPF_RET | BPF_K, SECCOMP_RET_ALLOW));
+ if (f.size() > 4096) throw std::runtime_error("seccomp program too large");
+ return f;
+}
+
+void dropCapabilities() {
+ int last = CAP_LAST_CAP_FALLBACK;
+ std::ifstream in("/proc/sys/kernel/cap_last_cap");
+ if (in) in >> last;
+ for (int cap = 0; cap <= last; ++cap) {
+ if (std::find(Caps::kKeptCaps.begin(), Caps::kKeptCaps.end(), cap) != Caps::kKeptCaps.end()) continue;
+ if (::prctl(PR_CAPBSET_DROP, cap, 0, 0, 0) != 0 && errno != EINVAL) {
+ throw SysError("drop capability " + std::to_string(cap));
+ }
+ }
+ ::prctl(PR_CAP_AMBIENT, PR_CAP_AMBIENT_CLEAR_ALL, 0, 0, 0);
+}
+
+} // namespace
+
+void Hardening::apply() {
+ dropCapabilities();
+ if (kArch == 0) {
+ std::fprintf(stderr, "doos: no seccomp filter for this CPU architecture, capabilities were still reduced\n");
+ return;
+ }
+ std::vector prog = buildFilter();
+ sock_fprog fp{static_cast(prog.size()), prog.data()};
+ if (::prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &fp) != 0) throw SysError("install seccomp filter");
+}
+
+} // namespace molo::doos
diff --git a/src/doos/hardening.hpp b/src/doos/hardening.hpp
new file mode 100644
index 0000000..dbf0aaf
--- /dev/null
+++ b/src/doos/hardening.hpp
@@ -0,0 +1,15 @@
+#pragma once
+
+namespace molo::doos {
+
+// Confinement applied to every process that runs a container command, right before exec:
+// 1. capability bounding set reduced to the Docker default set (Caps::kKeptCaps),
+// 2. a seccomp-bpf denylist (keyring, bpf, perf, userfaultfd, io_uring, mount family, kexec, module loading,
+// nested user namespaces and the like), with an architecture check and x32 guard.
+// Both need no_new_privs, which the caller sets. Throws when the filter cannot be installed.
+class Hardening {
+public:
+ static void apply();
+};
+
+} // namespace molo::doos
diff --git a/src/doos/idmap.cpp b/src/doos/idmap.cpp
new file mode 100644
index 0000000..08747ac
--- /dev/null
+++ b/src/doos/idmap.cpp
@@ -0,0 +1,157 @@
+#include "doos/idmap.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+
+#include "doos/caps.h"
+#include "doos/util.hpp"
+
+namespace molo::doos {
+
+namespace {
+
+// Same trusted-path resolution as every other external helper (resolveBinary in util.cpp): the
+// state dir's bin/ override, then a fixed list of system directories, never the caller's PATH.
+std::string findBinary(const char* name) {
+ try {
+ return resolveBinary(name);
+ } catch (const std::exception&) {
+ return {};
+ }
+}
+
+void writeProcFile(pid_t pid, const char* file, const std::string& content) {
+ std::string path = "/proc/" + std::to_string(pid) + "/" + file;
+ int fd = ::open(path.c_str(), O_WRONLY | O_CLOEXEC);
+ if (fd < 0) throw SysError("open " + path);
+ Fd guard(fd);
+ if (::write(fd, content.data(), content.size()) != static_cast(content.size())) {
+ throw SysError("write " + path + " (user namespaces blocked? see apparmor/doos and docs/RESEARCH.md)");
+ }
+}
+
+} // namespace
+
+IdMode IdMap::parse(const std::string& s) {
+ if (s == "single") return IdMode::Single;
+ if (s == "subuid") return IdMode::Subuid;
+ throw std::runtime_error("unknown id mode '" + s + "' (use single or subuid)");
+}
+
+std::string IdMap::name(IdMode m) { return m == IdMode::Subuid ? "subuid" : "single"; }
+
+std::optional IdMap::range(const char* file) {
+ std::ifstream in(file);
+ if (!in) return std::nullopt;
+ std::string user;
+ if (const passwd* pw = ::getpwuid(::geteuid())) user = pw->pw_name;
+ std::string uid = std::to_string(::geteuid());
+ for (std::string line; std::getline(in, line);) {
+ std::vector f;
+ std::stringstream ss(line);
+ for (std::string t; std::getline(ss, t, ':');) f.push_back(t);
+ if (f.size() != 3 || (f[0] != user && f[0] != uid)) continue;
+ try {
+ SubRange r{std::stoul(f[1]), std::stoul(f[2])};
+ if (r.count > 0) return r;
+ } catch (const std::exception&) {
+ }
+ }
+ return std::nullopt;
+}
+
+bool IdMap::subuidAvailable() {
+ return range("/etc/subuid") && range("/etc/subgid") && !findBinary("newuidmap").empty() &&
+ !findBinary("newgidmap").empty();
+}
+
+IdMode IdMap::best() { return subuidAvailable() ? IdMode::Subuid : IdMode::Single; }
+
+void IdMap::mapSelfSingle() {
+ std::string uid = std::to_string(::geteuid()), gid = std::to_string(::getegid());
+ writeProcFile(::getpid(), "setgroups", "deny");
+ writeProcFile(::getpid(), "uid_map", "0 " + uid + " 1\n");
+ writeProcFile(::getpid(), "gid_map", "0 " + gid + " 1\n");
+}
+
+void IdMap::apply(pid_t pid, IdMode mode) {
+ std::string uid = std::to_string(::geteuid()), gid = std::to_string(::getegid());
+ if (mode == IdMode::Single) {
+ writeProcFile(pid, "setgroups", "deny");
+ writeProcFile(pid, "uid_map", "0 " + uid + " 1\n");
+ writeProcFile(pid, "gid_map", "0 " + gid + " 1\n");
+ return;
+ }
+ auto u = range("/etc/subuid");
+ auto g = range("/etc/subgid");
+ std::string newuidmap = findBinary("newuidmap"), newgidmap = findBinary("newgidmap");
+ if (!u || !g || newuidmap.empty() || newgidmap.empty()) {
+ throw std::runtime_error("subuid mapping unavailable: need /etc/subuid, /etc/subgid, newuidmap and newgidmap "
+ "(install uidmap, or use --ids single)");
+ }
+ auto n = [](const SubRange& r) { return std::to_string(std::min(r.count, Caps::kMaxIdRange - 1)); };
+ std::string p = std::to_string(pid);
+ ProcResult a = runProcess({newuidmap, p, "0", uid, "1", "1", std::to_string(u->start), n(*u)});
+ if (a.code != 0) throw std::runtime_error("newuidmap failed (exit " + std::to_string(a.code) + ")");
+ ProcResult b = runProcess({newgidmap, p, "0", gid, "1", "1", std::to_string(g->start), n(*g)});
+ if (b.code != 0) throw std::runtime_error("newgidmap failed (exit " + std::to_string(b.code) + ")");
+}
+
+namespace {
+struct JobCtx {
+ const std::function* fn;
+ int syncFd;
+};
+
+int jobMain(void* arg) {
+ auto* c = static_cast(arg);
+ ::prctl(PR_SET_PDEATHSIG, SIGKILL);
+ char go = 0;
+ if (::read(c->syncFd, &go, 1) != 1 || go != 'G') ::_exit(125);
+ ::close(c->syncFd);
+ int code = 125;
+ try {
+ code = (*c->fn)();
+ } catch (const std::exception& e) {
+ ::dprintf(2, "doos: %s\n", e.what());
+ }
+ ::_exit(code);
+}
+} // namespace
+
+int UserNsJob::run(IdMode mode, const std::function& fn) {
+ int sync[2];
+ if (::pipe2(sync, O_CLOEXEC) != 0) throw SysError("pipe");
+ Fd rd(sync[0]), wr(sync[1]);
+ std::vector stack(1 << 20);
+ JobCtx ctx{&fn, rd.get()};
+ pid_t child = ::clone(jobMain, stack.data() + stack.size(), CLONE_NEWUSER | SIGCHLD, &ctx);
+ if (child < 0) throw SysError("clone (user namespaces available?)");
+ try {
+ IdMap::apply(child, mode);
+ } catch (...) {
+ ::kill(child, SIGKILL);
+ ::waitpid(child, nullptr, 0);
+ throw;
+ }
+ char go = 'G';
+ if (::write(wr.get(), &go, 1) != 1) throw SysError("sync job");
+ wr.reset();
+ int st = 0;
+ while (::waitpid(child, &st, 0) < 0) {
+ if (errno != EINTR) throw SysError("waitpid");
+ }
+ return WIFEXITED(st) ? WEXITSTATUS(st) : 128 + WTERMSIG(st);
+}
+
+} // namespace molo::doos
diff --git a/src/doos/idmap.hpp b/src/doos/idmap.hpp
new file mode 100644
index 0000000..f53a801
--- /dev/null
+++ b/src/doos/idmap.hpp
@@ -0,0 +1,44 @@
+#pragma once
+#include
+
+#include
+#include
+#include
+
+namespace molo::doos {
+
+// How container ids map to host ids.
+// single: container 0 -> invoking user, nothing else mappable.
+// subuid: container 0 -> invoking user, 1..N -> the user's /etc/subuid and /etc/subgid range (newuidmap).
+enum class IdMode { Single, Subuid };
+
+struct SubRange {
+ unsigned long start = 0;
+ unsigned long count = 0;
+};
+
+class IdMap {
+public:
+ static IdMode parse(const std::string& s); // "single" or "subuid"
+ static std::string name(IdMode m);
+ // Subuid when both ranges and both helper binaries exist, else Single.
+ static IdMode best();
+ static bool subuidAvailable();
+ // Applies the map to the user namespace of `pid`. Throws with the reason when it cannot.
+ static void apply(pid_t pid, IdMode mode);
+ // Maps this process's own ids (single mode) after it entered a user namespace itself:
+ // setgroups deny, 0->euid, 0->egid. Throws SysError. Fork-safe (raw syscalls only).
+ static void mapSelfSingle();
+
+private:
+ static std::optional range(const char* file);
+};
+
+// Runs `fn` as root of a fresh user namespace carrying the same id map as containers of `mode`.
+// Needed to touch files owned by subuids (extract images, delete trees). Returns fn's exit code.
+class UserNsJob {
+public:
+ static int run(IdMode mode, const std::function& fn);
+};
+
+} // namespace molo::doos
diff --git a/src/doos/image.cpp b/src/doos/image.cpp
new file mode 100644
index 0000000..86f9656
--- /dev/null
+++ b/src/doos/image.cpp
@@ -0,0 +1,300 @@
+#include "doos/image.hpp"
+
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+
+#include "doos/caps.h"
+#include "doos/util.hpp"
+
+namespace fs = std::filesystem;
+
+namespace molo::doos {
+
+namespace {
+
+std::string cpuArch(bool debianStyle) {
+ utsname u;
+ if (::uname(&u) != 0) throw SysError("uname");
+ std::string m = u.machine;
+ if (m == "x86_64") return debianStyle ? "amd64" : "x86_64";
+ if (m == "aarch64") return debianStyle ? "arm64" : "aarch64";
+ throw std::runtime_error("no catalog images for architecture " + m + "; use a file or URL with --sha256");
+}
+
+std::vector versionParts(const std::string& v) {
+ std::vector out;
+ std::stringstream ss(v);
+ for (std::string t; std::getline(ss, t, '.');) out.push_back(t.empty() ? 0 : std::stoul(t));
+ return out;
+}
+
+std::string lowerCase(std::string s) {
+ for (auto& c : s) c = static_cast(std::tolower(static_cast(c)));
+ return s;
+}
+
+} // namespace
+
+std::vector Catalog::names() { return {"alpine", "ubuntu", "ubuntu-24.04", "debian"}; }
+
+bool Catalog::knows(const std::string& n) {
+ return n == "alpine" || n == "ubuntu" || (n.rfind("ubuntu-", 0) == 0 && n.size() > 7) || n == "debian" ||
+ (n.rfind("debian-", 0) == 0 && n.size() > 7);
+}
+
+ImageSource Catalog::resolve(const std::string& n) {
+ ImageSource src;
+ src.name = n;
+ if (n == "alpine") {
+ std::string arch = cpuArch(false);
+ std::string base = std::string(Caps::kAlpineBase) + arch + "/";
+ std::string yaml = fetchText(base + "latest-releases.yaml");
+ std::istringstream in(yaml);
+ std::string file, sha;
+ bool inBlock = false;
+ for (std::string line; std::getline(in, line);) {
+ if (line.find("flavor: alpine-minirootfs") != std::string::npos) { inBlock = true; continue; }
+ if (inBlock && line.rfind("-", 0) == 0) break;
+ auto val = [&](const char* key) {
+ auto p = line.find(key);
+ return p == std::string::npos ? std::string() : line.substr(p + std::string(key).size());
+ };
+ if (inBlock && file.empty()) file = val("file: ");
+ if (inBlock && sha.empty()) sha = val("sha256: ");
+ }
+ if (file.empty() || !isHex64(sha) || file.find('/') != std::string::npos) {
+ throw std::runtime_error("cannot find alpine-minirootfs in latest-releases.yaml");
+ }
+ src.location = base + file;
+ src.sha256 = sha;
+ src.sigUrl = src.location + ".asc";
+ src.keyUrl = std::string(Caps::kAlpineKeyUrl);
+ src.keyFpr = std::string(Caps::kAlpineKeyFpr);
+ return src;
+ }
+ if (n == "debian" || n.rfind("debian-", 0) == 0) {
+ std::string rel = n == "debian" ? std::string(Caps::kDebianDefaultRelease) : n.substr(7);
+ if (rel.empty() || !std::all_of(rel.begin(), rel.end(), [](unsigned char c) { return std::islower(c); })) {
+ throw std::runtime_error("invalid debian release '" + rel + "' (example: debian-bookworm)");
+ }
+ std::string arch = cpuArch(true);
+ std::string dist = arch == "amd64" ? "dist-amd64" : "dist-arm64v8";
+ std::string base = std::string(Caps::kDebianBase) + dist + "/" + rel + "/slim/oci/";
+ std::string index = fetchText(base + "index.json");
+ // The manifest is embedded (base64) in the index; its single layer digest is the sha256 of the rootfs tarball.
+ auto d = index.find("\"data\":\"");
+ if (d == std::string::npos) throw std::runtime_error("unexpected debian index.json (no embedded manifest)");
+ d += 8;
+ std::string manifest = base64Decode(index.substr(d, index.find('"', d) - d));
+ auto l = manifest.find("\"layers\"");
+ auto dg = l == std::string::npos ? l : manifest.find("sha256:", l);
+ if (dg == std::string::npos) throw std::runtime_error("unexpected debian manifest (no layer digest)");
+ std::string sha = manifest.substr(dg + 7, 64);
+ if (!isHex64(sha)) throw std::runtime_error("unexpected debian layer digest");
+ src.location = base + "blobs/rootfs.tar.gz";
+ src.sha256 = sha; // content-addressed: the digest is the integrity check; there is no publisher signature
+ return src;
+ }
+ if (n == "ubuntu" || n.rfind("ubuntu-", 0) == 0) {
+ std::string ver = n == "ubuntu" ? std::string(Caps::kUbuntuDefaultVersion) : n.substr(7);
+ if (ver.empty() || !std::all_of(ver.begin(), ver.end(), [](unsigned char c) { return std::isdigit(c) || c == '.'; })) {
+ throw std::runtime_error("invalid ubuntu version '" + ver + "' (example: ubuntu-24.04)");
+ }
+ std::string arch = cpuArch(true);
+ std::string base = std::string(Caps::kUbuntuBase) + ver + "/release/";
+ TempDir tmp;
+ fetchFile(base + "SHA256SUMS", tmp.path() / "SHA256SUMS");
+ fetchFile(base + "SHA256SUMS.gpg", tmp.path() / "SHA256SUMS.gpg");
+ verifyDetachedSignature(tmp.path() / "SHA256SUMS", tmp.path() / "SHA256SUMS.gpg", std::string(Caps::kUbuntuKeyUrl),
+ std::string(Caps::kUbuntuKeyFpr));
+ std::string sums = fsutil::readFile(tmp.path() / "SHA256SUMS");
+ std::string suffix = "-base-" + arch + ".tar.gz";
+ std::string bestFile, bestSha;
+ std::vector bestVer;
+ std::istringstream in(sums);
+ for (std::string line; std::getline(in, line);) {
+ auto sp = line.find(" *");
+ if (sp == std::string::npos) continue;
+ std::string sha = line.substr(0, sp), file = line.substr(sp + 2);
+ if (file.rfind("ubuntu-base-", 0) != 0 || file.size() <= suffix.size() ||
+ file.compare(file.size() - suffix.size(), suffix.size(), suffix) != 0 || !isHex64(sha)) {
+ continue;
+ }
+ auto v = versionParts(file.substr(12, file.size() - 12 - suffix.size()));
+ if (bestFile.empty() || v > bestVer) { bestFile = file; bestSha = sha; bestVer = v; }
+ }
+ if (bestFile.empty()) throw std::runtime_error("no ubuntu-base " + ver + " for " + arch + " found at " + base);
+ src.location = base + bestFile;
+ src.sha256 = bestSha;
+ return src;
+ }
+ throw std::runtime_error("unknown catalog image '" + n + "' (known: alpine, ubuntu, ubuntu-VERSION, debian, debian-RELEASE)");
+}
+
+std::string ImageStore::normalize(const std::string& name) {
+ std::string s = lowerCase(name);
+ std::replace(s.begin(), s.end(), ':', '-');
+ return s;
+}
+
+void ImageStore::validateName(const std::string& name) {
+ bool ok = !name.empty() && name.size() <= Caps::kMaxNameLen && std::isalnum(static_cast(name[0]));
+ for (char c : name) ok = ok && (std::islower(static_cast(c)) || std::isdigit(static_cast(c)) ||
+ c == '-' || c == '_' || c == '.');
+ if (!ok) throw std::runtime_error("invalid image name '" + name + "': use [a-z0-9][a-z0-9._-]{0,31}");
+}
+
+ImageStore::ImageStore(fs::path root) : root_(std::move(root)) { fsutil::mkdirs(root_, 0700); }
+
+bool ImageStore::has(const std::string& name) const { return fs::exists(dir(name) / "meta"); }
+fs::path ImageStore::rootfs(const std::string& name) const { return dir(name) / "rootfs"; }
+
+namespace {
+std::map readMeta(const fs::path& p) {
+ std::map kv;
+ std::istringstream in(fsutil::readFile(p));
+ for (std::string line; std::getline(in, line);) {
+ auto eq = line.find('=');
+ if (eq != std::string::npos) kv[line.substr(0, eq)] = line.substr(eq + 1);
+ }
+ return kv;
+}
+} // namespace
+
+IdMode ImageStore::ids(const std::string& name) const {
+ auto kv = readMeta(dir(name) / "meta");
+ return IdMap::parse(kv.count("ids") ? kv["ids"] : "single");
+}
+
+std::vector ImageStore::list() const {
+ std::vector out;
+ for (const auto& e : fs::directory_iterator(root_)) {
+ std::string name = e.path().filename().string();
+ if (!e.is_directory() || name.rfind(".", 0) == 0 || !has(name)) continue;
+ auto kv = readMeta(e.path() / "meta");
+ ImageInfo i;
+ i.name = name;
+ i.source = kv["source"];
+ i.ids = IdMap::parse(kv.count("ids") ? kv["ids"] : "single");
+ i.created = kv.count("created") ? std::stol(kv["created"]) : 0;
+ i.bytes = kv.count("bytes") ? std::stoull(kv["bytes"]) : 0;
+ out.push_back(i);
+ if (out.size() >= Caps::kMaxImages) break;
+ }
+ std::sort(out.begin(), out.end(), [](const ImageInfo& a, const ImageInfo& b) { return a.name < b.name; });
+ return out;
+}
+
+ImageInfo ImageStore::add(const ImageSource& src, IdMode ids) {
+ validateName(src.name);
+ if (has(src.name)) throw std::runtime_error("image '" + src.name + "' already exists");
+ std::size_t count = 0;
+ for (const auto& e : fs::directory_iterator(root_)) count += (e.is_directory() && has(e.path().filename().string())) ? 1 : 0;
+ if (count >= Caps::kMaxImages) {
+ throw std::runtime_error("image limit reached (" + std::to_string(Caps::kMaxImages) + "); delete one first");
+ }
+ std::string curl, tar, sha256sum;
+ try {
+ curl = resolveBinary("curl");
+ tar = resolveBinary("tar");
+ sha256sum = resolveBinary("sha256sum");
+ } catch (const std::exception& e) {
+ throw std::runtime_error(std::string("required tool missing: ") + e.what());
+ }
+ fs::path tmp = root_ / (".tmp-" + src.name);
+ {
+ std::error_code ec;
+ if (fs::exists(tmp, ec)) {
+ int rc = UserNsJob::run(ids, [&] { fsutil::removeTree(tmp); return 0; });
+ if (rc != 0) throw std::runtime_error("cannot clean stale " + tmp.string());
+ }
+ }
+ fsutil::mkdirs(tmp, 0700);
+ auto cleanup = [&] { UserNsJob::run(ids, [&] { try { fsutil::removeTree(tmp); } catch (...) { return 1; } return 0; }); };
+ try {
+ fs::path archive;
+ if (src.isFile) {
+ archive = src.location;
+ if (!fs::is_regular_file(archive)) throw std::runtime_error("not a file: " + archive.string());
+ } else {
+ archive = tmp / "download";
+ std::fprintf(stderr, "downloading %s\n", src.location.c_str());
+ ProcResult d = runProcess({curl, "--fail", "--location", "--proto", "=https", "--progress-bar",
+ "--max-filesize", std::to_string(Caps::kMaxImageDownloadBytes), "--max-time",
+ std::to_string(Caps::kDownloadTimeoutSec), "--output", archive.string(), src.location});
+ if (d.code != 0) throw std::runtime_error("download failed (curl exit " + std::to_string(d.code) + ")");
+ }
+ if (!src.sha256.empty()) {
+ ProcResult h = runProcess({sha256sum, archive.string()}, true);
+ std::string got = h.out.substr(0, 64);
+ if (h.code != 0 || got != lowerCase(src.sha256)) {
+ throw std::runtime_error("sha256 mismatch for " + src.location + ": expected " + src.sha256 + ", got " + got);
+ }
+ std::fprintf(stderr, "sha256 verified\n");
+ if (!src.sigUrl.empty()) {
+ TempDir sigDir;
+ fetchFile(src.sigUrl, sigDir.path() / "file.asc");
+ verifyDetachedSignature(archive, sigDir.path() / "file.asc", src.keyUrl, src.keyFpr);
+ }
+ } else {
+ std::fprintf(stderr, "note: local file used without --sha256, not verified\n");
+ }
+ fs::path root = tmp / "rootfs";
+ fsutil::mkdirs(root, 0755);
+ std::vector tarArgv = {tar, "-x", "-p", "--numeric-owner", "--exclude=./dev/*", "--exclude=dev/*",
+ "-f", archive.string(), "-C", root.string()};
+ if (ids == IdMode::Single) tarArgv.insert(tarArgv.begin() + 1, "--no-same-owner");
+ std::fprintf(stderr, "extracting (ids: %s)\n", IdMap::name(ids).c_str());
+ int rc = UserNsJob::run(ids, [&] {
+ std::vector a;
+ for (auto& s : tarArgv) a.push_back(s.data());
+ a.push_back(nullptr);
+ ::execv(a[0], a.data());
+ return 127;
+ });
+ if (rc != 0) throw std::runtime_error("tar failed (exit " + std::to_string(rc) + ")");
+ std::size_t skipped = 0;
+ std::uint64_t bytes = fsutil::diskUsage(root, skipped);
+ ImageInfo info;
+ info.name = src.name;
+ info.source = src.location;
+ info.ids = ids;
+ info.created = std::time(nullptr);
+ info.bytes = bytes;
+ fsutil::writeFile(tmp / "meta", "source=" + src.location + "\nsha256=" + src.sha256 + "\nids=" + IdMap::name(ids) +
+ "\ncreated=" + std::to_string(info.created) + "\nbytes=" + std::to_string(bytes) + "\n");
+ if (!src.isFile) std::remove(archive.c_str());
+ if (::rename(tmp.c_str(), dir(src.name).c_str()) != 0) throw SysError("install image " + src.name);
+ return info;
+ } catch (...) {
+ cleanup();
+ throw;
+ }
+}
+
+std::string ImageStore::remove(const std::string& name, bool confirmed, const std::vector& usedBy) {
+ validateName(name);
+ if (!has(name)) throw std::runtime_error("no such image '" + name + "'");
+ if (!usedBy.empty()) {
+ std::string list;
+ for (const auto& u : usedBy) list += (list.empty() ? "" : ", ") + u;
+ throw std::runtime_error("image '" + name + "' is used by: " + list);
+ }
+ if (!confirmed) return "dry run: would delete image " + name + ". Add --yes to confirm.";
+ IdMode ids = this->ids(name);
+ fs::path d = dir(name);
+ int rc = UserNsJob::run(ids, [&] { fsutil::removeTree(d); return 0; });
+ if (rc != 0) throw std::runtime_error("could not remove image " + name);
+ return "deleted image " + name;
+}
+
+} // namespace molo::doos
diff --git a/src/doos/image.hpp b/src/doos/image.hpp
new file mode 100644
index 0000000..078ecc2
--- /dev/null
+++ b/src/doos/image.hpp
@@ -0,0 +1,63 @@
+#pragma once
+#include
+#include
+#include
+#include
+#include
+
+#include "doos/idmap.hpp"
+
+namespace molo::doos {
+
+// Where an image comes from, after resolving a catalog name, URL or file.
+struct ImageSource {
+ std::string name; // store name
+ std::string location; // https URL or local file path
+ std::string sha256; // expected, empty only for local files
+ bool isFile = false;
+ // Optional detached signature over the downloaded file; the key is fetched and must match the pinned fingerprint.
+ std::string sigUrl;
+ std::string keyUrl;
+ std::string keyFpr;
+};
+
+struct ImageInfo {
+ std::string name;
+ std::string source;
+ IdMode ids = IdMode::Single;
+ long created = 0;
+ std::uint64_t bytes = 0;
+};
+
+// Built-in sources: alpine, ubuntu (latest LTS), ubuntu-VERSION, debian, debian-RELEASE. Resolved from the
+// publishers over https; Alpine and Ubuntu are also checked against their pinned release signing keys.
+class Catalog {
+public:
+ static std::vector names();
+ static bool knows(const std::string& imageName);
+ static ImageSource resolve(const std::string& imageName);
+};
+
+class ImageStore {
+public:
+ explicit ImageStore(std::filesystem::path root);
+
+ static std::string normalize(const std::string& name); // "ubuntu:24.04" -> "ubuntu-24.04"
+ static void validateName(const std::string& name);
+
+ bool has(const std::string& name) const;
+ std::filesystem::path rootfs(const std::string& name) const;
+ IdMode ids(const std::string& name) const;
+ std::vector list() const;
+
+ // Downloads (catalog/URL) or reads (file), verifies the sha256, extracts under the id map.
+ ImageInfo add(const ImageSource& src, IdMode ids);
+ // Dry run unless confirmed. `usedBy` lists containers referencing the image; non-empty refuses.
+ std::string remove(const std::string& name, bool confirmed, const std::vector& usedBy);
+
+private:
+ std::filesystem::path dir(const std::string& name) const { return root_ / name; }
+ std::filesystem::path root_;
+};
+
+} // namespace molo::doos
diff --git a/src/doos/main.cpp b/src/doos/main.cpp
new file mode 100644
index 0000000..7a21fc5
--- /dev/null
+++ b/src/doos/main.cpp
@@ -0,0 +1,13 @@
+#include
+#include
+
+#include "doos/cli.hpp"
+
+int main(int argc, char** argv) {
+ try {
+ return molo::doos::Cli(std::vector(argv + 1, argv + argc)).run();
+ } catch (const std::exception& e) {
+ std::fprintf(stderr, "doos: %s\n", e.what());
+ return 1;
+ }
+}
diff --git a/src/doos/network.cpp b/src/doos/network.cpp
new file mode 100644
index 0000000..17dd779
--- /dev/null
+++ b/src/doos/network.cpp
@@ -0,0 +1,150 @@
+#include "doos/network.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+
+#include "doos/caps.h"
+#include "doos/util.hpp"
+
+namespace molo::doos {
+
+NetMode Network::parse(const std::string& s) {
+ if (s == "slirp") return NetMode::Slirp;
+ if (s == "pasta") return NetMode::Pasta;
+ if (s == "host") return NetMode::Host;
+ if (s == "none") return NetMode::None;
+ throw std::runtime_error("unknown network mode '" + s + "' (use slirp, pasta, host or none)");
+}
+
+std::string Network::name(NetMode m) {
+ switch (m) {
+ case NetMode::Slirp: return "slirp";
+ case NetMode::Pasta: return "pasta";
+ case NetMode::Host: return "host";
+ case NetMode::None: return "none";
+ }
+ return "?";
+}
+
+std::string Network::resolvConf(NetMode m) {
+ switch (m) {
+ case NetMode::Slirp: return "nameserver " + std::string(Caps::kSlirpDns) + "\n";
+ case NetMode::None: return "";
+ case NetMode::Pasta:
+ case NetMode::Host: {
+ // pasta forwards the namespace's loopback to the host and host mode shares it, so the host resolver
+ // config is valid as is, including the 127.0.0.53 stub.
+ std::ifstream in("/etc/resolv.conf");
+ return std::string(std::istreambuf_iterator(in), {});
+ }
+ }
+ return "";
+}
+
+void SlirpSession::start(pid_t targetPid) {
+ std::string bin;
+ try {
+ bin = resolveBinary("slirp4netns");
+ } catch (const std::exception&) {
+ throw std::runtime_error("slirp4netns helper not found (install slirp4netns or use --net none)");
+ }
+ int ready[2];
+ if (::pipe2(ready, O_CLOEXEC) != 0) throw SysError("pipe");
+ Fd readEnd(ready[0]), writeEnd(ready[1]);
+
+ pid_ = ::fork();
+ if (pid_ < 0) throw SysError("fork slirp4netns");
+ if (pid_ == 0) {
+ ::prctl(PR_SET_PDEATHSIG, SIGKILL);
+ // Do not trust the caller's PATH: only system directories may be searched by anything the helper runs.
+ ::setenv("PATH", std::string(Caps::kContainerPath).c_str(), 1);
+ int nul = ::open("/dev/null", O_WRONLY);
+ if (nul >= 0) { ::dup2(nul, 1); ::dup2(nul, 2); }
+ int wfd = ::dup(writeEnd.get()); // dup clears CLOEXEC
+ std::string readyArg = "--ready-fd=" + std::to_string(wfd);
+ std::string target = std::to_string(targetPid);
+ std::string tap(Caps::kSlirpTapName);
+ ::execl(bin.c_str(), bin.c_str(), "--configure", "--mtu=65520", "--disable-host-loopback",
+ readyArg.c_str(), target.c_str(), tap.c_str(), static_cast(nullptr));
+ ::dprintf(2, "doos: cannot exec %s: %s\n", bin.c_str(), std::strerror(errno));
+ ::_exit(127);
+ }
+ writeEnd.reset();
+
+ pollfd p{readEnd.get(), POLLIN, 0};
+ int rc = ::poll(&p, 1, Caps::kNetReadyTimeoutMs);
+ char c = 0;
+ if (rc > 0 && ::read(readEnd.get(), &c, 1) == 1) return;
+ stop();
+ throw std::runtime_error(rc == 0 ? "slirp4netns not ready in time"
+ : "slirp4netns failed to start (is it installed and permitted?)");
+}
+
+void SlirpSession::stop() {
+ if (pid_ <= 0) return;
+ ::kill(pid_, SIGTERM);
+ ::waitpid(pid_, nullptr, 0);
+ pid_ = -1;
+}
+
+} // namespace molo::doos
+
+namespace molo::doos {
+
+void PastaSession::start(pid_t targetPid) {
+ std::string bin;
+ try {
+ bin = resolveBinary("pasta");
+ } catch (const std::exception&) {
+ throw std::runtime_error("pasta helper not found (install pasta or use --net none)");
+ }
+ pid_ = ::fork();
+ if (pid_ < 0) throw SysError("fork pasta");
+ if (pid_ == 0) {
+ ::prctl(PR_SET_PDEATHSIG, SIGKILL);
+ ::setenv("PATH", std::string(Caps::kContainerPath).c_str(), 1);
+ int nul = ::open("/dev/null", O_WRONLY);
+ if (nul >= 0) { ::dup2(nul, 1); ::dup2(nul, 2); }
+ std::string target = std::to_string(targetPid);
+ ::execl(bin.c_str(), bin.c_str(), "--foreground", "--quiet", "--config-net", target.c_str(),
+ static_cast(nullptr));
+ ::_exit(127);
+ }
+ // pasta has no ready fd: wait until the target namespace has an interface besides lo.
+ std::string dev = "/proc/" + std::to_string(targetPid) + "/net/dev";
+ for (int waited = 0; waited < Caps::kNetReadyTimeoutMs; waited += 20) {
+ int st = 0;
+ if (::waitpid(pid_, &st, WNOHANG) == pid_) {
+ pid_ = -1;
+ throw std::runtime_error("pasta exited early (is it installed and permitted?)");
+ }
+ std::ifstream in(dev);
+ int lines = 0;
+ for (std::string line; std::getline(in, line);) ++lines;
+ if (lines > 3) return; // two header lines + lo + at least one more interface
+ ::poll(nullptr, 0, 20);
+ }
+ stop();
+ throw std::runtime_error("pasta not ready in time");
+}
+
+void PastaSession::stop() {
+ if (pid_ <= 0) return;
+ // pasta drops to another uid after start, so we cannot signal it, and it leaves by itself shortly after its
+ // namespace is gone. Reap it if it is already done; otherwise let init adopt it instead of blocking the exit.
+ for (int waited = 0; waited < 20; waited += 5) {
+ if (::waitpid(pid_, nullptr, WNOHANG) == pid_) break;
+ ::poll(nullptr, 0, 5);
+ }
+ pid_ = -1;
+}
+
+} // namespace molo::doos
diff --git a/src/doos/network.hpp b/src/doos/network.hpp
new file mode 100644
index 0000000..3f238d9
--- /dev/null
+++ b/src/doos/network.hpp
@@ -0,0 +1,54 @@
+#pragma once
+#include
+
+#include
+
+namespace molo::doos {
+
+// slirp: private netns, outbound only, host loopback blocked (default).
+// pasta: private netns that behaves like the host network (host loopback, bound ports forwarded), but with
+// its own abstract unix sockets.
+// host: the host's network namespace itself (shares abstract sockets), explicit opt-in.
+// none: loopback only.
+enum class NetMode { Slirp, Pasta, Host, None };
+
+class Network {
+public:
+ static NetMode parse(const std::string& s);
+ static std::string name(NetMode m);
+ // Does the mode need its own network namespace?
+ static bool isolated(NetMode m) { return m != NetMode::Host; }
+ // /etc/resolv.conf content matching the mode.
+ static std::string resolvConf(NetMode m);
+};
+
+// Owns a pasta process attached to a container's network namespace.
+class PastaSession {
+public:
+ PastaSession() = default;
+ PastaSession(const PastaSession&) = delete;
+ PastaSession& operator=(const PastaSession&) = delete;
+ ~PastaSession() { stop(); }
+ void start(pid_t targetPid);
+ void stop();
+
+private:
+ pid_t pid_ = -1;
+};
+
+// Owns a slirp4netns process attached to a container's network namespace.
+class SlirpSession {
+public:
+ SlirpSession() = default;
+ SlirpSession(const SlirpSession&) = delete;
+ SlirpSession& operator=(const SlirpSession&) = delete;
+ ~SlirpSession() { stop(); }
+ // Starts slirp4netns for the netns of `targetPid` and blocks until it is ready.
+ void start(pid_t targetPid);
+ void stop();
+
+private:
+ pid_t pid_ = -1;
+};
+
+} // namespace molo::doos
diff --git a/src/doos/sandbox.cpp b/src/doos/sandbox.cpp
new file mode 100644
index 0000000..fb43b80
--- /dev/null
+++ b/src/doos/sandbox.cpp
@@ -0,0 +1,616 @@
+#include "doos/sandbox.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+
+#include
+#include
+
+#include
+
+#include "doos/cgroup.hpp"
+#include "doos/davmount.hpp"
+#include "doos/hardening.hpp"
+#include "doos/caps.h"
+#include "doos/util.hpp"
+
+namespace fs = std::filesystem;
+
+namespace molo::doos {
+
+namespace {
+
+volatile sig_atomic_t g_forwardTo = 0;
+volatile sig_atomic_t g_terminating = 0;
+
+void forwardSignal(int sig) {
+ g_terminating = 1;
+ if (g_forwardTo > 0) ::kill(g_forwardTo, sig);
+}
+
+void installForwarding(pid_t target, std::initializer_list sigs) {
+ g_forwardTo = target;
+ struct sigaction sa;
+ std::memset(&sa, 0, sizeof sa);
+ sa.sa_handler = forwardSignal;
+ sigemptyset(&sa.sa_mask);
+ for (int s : sigs) ::sigaction(s, &sa, nullptr);
+}
+
+void doMount(const char* src, const std::string& target, const char* type, unsigned long flags,
+ const std::string& data = "") {
+ if (::mount(src, target.c_str(), type, flags, data.empty() ? nullptr : data.c_str()) != 0) {
+ throw SysError(std::string("mount ") + (type ? type : "bind") + " " + target);
+ }
+}
+
+// Remount read-only while preserving the locked flags a userns cannot change.
+void remountReadOnly(const std::string& path) {
+ doMount(path.c_str(), path, nullptr, MS_BIND | MS_REC);
+ struct statvfs sv;
+ if (::statvfs(path.c_str(), &sv) != 0) throw SysError("statvfs " + path);
+ unsigned long flags = MS_BIND | MS_REMOUNT | MS_RDONLY;
+ if (sv.f_flag & ST_NOSUID) flags |= MS_NOSUID;
+ if (sv.f_flag & ST_NODEV) flags |= MS_NODEV;
+ if (sv.f_flag & ST_NOEXEC) flags |= MS_NOEXEC;
+ if (sv.f_flag & ST_NOATIME) flags |= MS_NOATIME;
+ if (sv.f_flag & ST_NODIRATIME) flags |= MS_NODIRATIME;
+ if (sv.f_flag & ST_RELATIME) flags |= MS_RELATIME;
+ doMount(nullptr, path, nullptr, flags);
+}
+
+void touch(const std::string& path) {
+ int fd = ::open(path.c_str(), O_CREAT | O_WRONLY | O_CLOEXEC, 0644);
+ if (fd < 0) throw SysError("create " + path);
+ ::close(fd);
+}
+
+void bringLoopbackUp() {
+ int s = ::socket(AF_INET, SOCK_DGRAM | SOCK_CLOEXEC, 0);
+ if (s < 0) throw SysError("socket");
+ Fd guard(s);
+ ifreq ifr;
+ std::memset(&ifr, 0, sizeof ifr);
+ std::strncpy(ifr.ifr_name, "lo", IFNAMSIZ - 1);
+ if (::ioctl(s, SIOCGIFFLAGS, &ifr) != 0) throw SysError("SIOCGIFFLAGS lo");
+ ifr.ifr_flags |= IFF_UP;
+ if (::ioctl(s, SIOCSIFFLAGS, &ifr) != 0) throw SysError("SIOCSIFFLAGS lo");
+}
+
+std::string sub(const fs::path& root, std::string_view hostDir) { return (root / hostDir.substr(1)).string(); }
+
+void mountOverlay(const Container& c, const fs::path& root, std::string_view hostDir) {
+ std::string dir(hostDir);
+ std::string opts = "lowerdir=" + dir + ",upperdir=" + (c.layer(dir) / "upper").string() +
+ ",workdir=" + (c.layer(dir) / "work").string() + ",userxattr";
+ doMount("overlay", sub(root, hostDir), "overlay", MS_NODEV | MS_NOSUID, opts);
+}
+
+void bindHostDevice(const fs::path& root, const std::string& dev) {
+ std::string target = (root / "dev" / dev).string();
+ touch(target);
+ doMount(("/dev/" + dev).c_str(), target, nullptr, MS_BIND);
+}
+
+// apt drops to its _apt user for downloads; with one mappable id that user does not exist.
+void writeAptSandboxOverride(const Container& c, const fs::path& lowerEtc) {
+ std::error_code ec;
+ if (c.ids() != IdMode::Single || !fs::is_directory(lowerEtc / "apt", ec)) return;
+ fs::path dir = c.etcDir() / "apt/apt.conf.d";
+ fsutil::mkdirs(dir);
+ fsutil::writeFile(dir / "99doos-sandbox", "APT::Sandbox::User \"root\";\n");
+}
+
+void writeResolvConf(const Container& c) {
+ fs::path resolv = c.etcDir() / "resolv.conf";
+ fsutil::mkdirs(resolv.parent_path());
+ std::error_code ec;
+ fs::remove(resolv, ec);
+ fsutil::writeFile(resolv, Network::resolvConf(c.net()));
+}
+
+void mountHostLayers(const Container& c, const fs::path& root) {
+ for (auto d : Caps::kOverlayDirs) {
+ std::error_code e;
+ if (fs::is_directory(std::string(d), e)) mountOverlay(c, root, d);
+ }
+ for (auto d : Caps::kCompatDirs) {
+ std::error_code e;
+ std::string host(d);
+ // Read any symlink through an fd opened on its parent so the target cannot be swapped
+ // between the check and the recreation (TOCTOU). Real directories are overlaid; absent
+ // entries are skipped. Symlinks whose target we cannot pin are not recreated: fail closed.
+ fs::path parent = fs::path(host).parent_path();
+ int pfd = ::open(parent.c_str(), O_PATH | O_DIRECTORY | O_CLOEXEC);
+ if (pfd < 0) continue;
+ Fd guard(pfd);
+ std::string base = fs::path(host).filename().string();
+ char target[4096];
+ ssize_t n = ::readlinkat(pfd, base.c_str(), target, sizeof target - 1);
+ if (n < 0) {
+ if (errno == EINVAL || errno == ENOENT) {
+ if (fs::is_directory(host, e) && !e) mountOverlay(c, root, d);
+ }
+ continue;
+ }
+ target[n] = '\0';
+ fs::path link = root / host.substr(1);
+ fs::remove(link, e);
+ fs::create_symlink(target, link);
+ }
+ for (auto d : Caps::kPrivateDirs) doMount(c.privateDir(std::string(d)).c_str(), sub(root, d), nullptr, MS_BIND);
+ // overlays that live inside a private dir must be mounted after it
+ for (auto d : Caps::kVarOverlayDirs) {
+ std::error_code e;
+ if (fs::is_directory(std::string(d), e)) mountOverlay(c, root, d);
+ }
+}
+
+void mountImageRoot(const Container& c, const fs::path& root, const fs::path& imageRoot) {
+ std::string opts = "lowerdir=" + imageRoot.string() + ",upperdir=" + (c.layer("/root") / "upper").string() +
+ ",workdir=" + (c.layer("/root") / "work").string() + ",userxattr";
+ doMount("overlay", root.string(), "overlay", MS_NODEV | MS_NOSUID, opts);
+ for (auto d : Caps::kEmptyDirs) fsutil::mkdirs(sub(root, d));
+}
+
+// --mount: extra bind mounts beyond the overlay/image root, outside the --size cap.
+void mountExtra(const Container& c, const fs::path& root) {
+ for (const auto& m : c.mounts()) {
+ if (!fs::is_directory(m.src)) {
+ throw std::runtime_error("mount source '" + m.src + "' is not a directory (mount it on the host first)");
+ }
+ std::string target = sub(root, m.dst);
+ fsutil::mkdirs(target);
+ doMount(m.src.c_str(), target, nullptr, MS_BIND | MS_REC);
+ if (m.readOnly) remountReadOnly(target);
+ }
+}
+
+void setupRoot(const Container& c, const fs::path& imageRoot) {
+ fs::path root = c.rootfs();
+ doMount(nullptr, "/", nullptr, MS_REC | MS_PRIVATE);
+ writeResolvConf(c);
+ if (c.imageMode()) {
+ writeAptSandboxOverride(c, imageRoot / "etc");
+ mountImageRoot(c, root, imageRoot);
+ } else {
+ writeAptSandboxOverride(c, "/etc");
+ doMount(root.c_str(), root.string(), nullptr, MS_BIND | MS_REC);
+ mountHostLayers(c, root);
+ }
+
+ // tmpfs mounts
+ doMount("tmpfs", sub(root, "/tmp"), "tmpfs", MS_NOSUID | MS_NODEV, "mode=1777,size=" + std::string(Caps::kTmpSize));
+ doMount("tmpfs", sub(root, "/run"), "tmpfs", MS_NOSUID | MS_NODEV, "mode=755,size=" + std::string(Caps::kRunSize));
+
+ // /dev
+ doMount("tmpfs", sub(root, "/dev"), "tmpfs", MS_NOSUID | MS_STRICTATIME, "mode=755,size=64k");
+ for (auto d : Caps::kDevices) bindHostDevice(root, std::string(d));
+ fsutil::mkdirs(root / "dev/pts");
+ fsutil::mkdirs(root / "dev/shm", 01777);
+ doMount("devpts", sub(root, "/dev/pts"), "devpts", MS_NOSUID | MS_NOEXEC, "newinstance,ptmxmode=0666,mode=0620");
+ doMount("tmpfs", sub(root, "/dev/shm"), "tmpfs", MS_NOSUID | MS_NODEV | MS_NOEXEC,
+ "mode=1777,size=" + std::string(Caps::kShmSize));
+ fs::create_symlink("pts/ptmx", root / "dev/ptmx");
+ fs::create_symlink("/proc/self/fd", root / "dev/fd");
+ fs::create_symlink("/proc/self/fd/0", root / "dev/stdin");
+ fs::create_symlink("/proc/self/fd/1", root / "dev/stdout");
+ fs::create_symlink("/proc/self/fd/2", root / "dev/stderr");
+
+ // /proc (our own pid namespace), with the dangerous parts read-only or hidden.
+ doMount("proc", sub(root, "/proc"), "proc", MS_NOSUID | MS_NODEV | MS_NOEXEC);
+ for (auto p : Caps::kProcReadOnly) remountReadOnly(sub(root, p));
+ for (auto p : Caps::kProcMasked) doMount((root / "dev/null").c_str(), sub(root, p), nullptr, MS_BIND);
+
+ mountExtra(c, root);
+
+ // Switch root, then drop the old one.
+ if (::chdir(root.c_str()) != 0) throw SysError("chdir newroot");
+ if (::syscall(SYS_pivot_root, ".", ".") != 0) throw SysError("pivot_root");
+ if (::umount2(".", MNT_DETACH) != 0) throw SysError("umount old root");
+ if (::chdir("/") != 0) throw SysError("chdir /");
+}
+
+void applyLimitsAndEnv(const Container& c) {
+ if (::prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0) throw SysError("no_new_privs");
+ rlimit core{0, 0};
+ ::setrlimit(RLIMIT_CORE, &core);
+ // No single file can outgrow the size cap, which bounds the overshoot between two usage scans.
+ rlimit fsize{c.sizeCap(), c.sizeCap()};
+ ::setrlimit(RLIMIT_FSIZE, &fsize);
+ rlimit nofile;
+ if (::getrlimit(RLIMIT_NOFILE, &nofile) == 0) {
+ if (nofile.rlim_max > Caps::kMaxOpenFiles) nofile.rlim_max = Caps::kMaxOpenFiles;
+ if (nofile.rlim_cur > nofile.rlim_max) nofile.rlim_cur = nofile.rlim_max;
+ ::setrlimit(RLIMIT_NOFILE, &nofile);
+ }
+ if (!c.relaxed()) Hardening::apply();
+ const char* term = std::getenv("TERM");
+ std::string termv = term && *term ? term : "xterm";
+ const char* lang = std::getenv("LANG");
+ std::string langv = lang ? lang : "";
+ ::clearenv();
+ ::setenv("PATH", std::string(Caps::kContainerPath).c_str(), 1);
+ ::setenv("HOME", std::string(Caps::kHome).c_str(), 1);
+ ::setenv("USER", "root", 1);
+ ::setenv("LOGNAME", "root", 1);
+ ::setenv("TERM", termv.c_str(), 1);
+ ::setenv("HOSTNAME", c.name().c_str(), 1);
+ ::setenv("container", "doos", 1);
+ ::setenv("PS1", ("(doos:" + c.name() + ") \\u@\\h:\\w\\$ ").c_str(), 1);
+ // The host's locale usually does not exist inside an image; C.UTF-8 is built into glibc and musl.
+ if (c.imageMode()) ::setenv("LANG", "C.UTF-8", 1);
+ else if (!langv.empty()) ::setenv("LANG", langv.c_str(), 1);
+}
+
+[[noreturn]] void execCommand(std::vector cmd) {
+ if (cmd.empty()) cmd = {::access("/bin/bash", X_OK) == 0 ? "/bin/bash" : "/bin/sh"};
+ std::vector argv;
+ for (auto& a : cmd) argv.push_back(a.data());
+ argv.push_back(nullptr);
+ ::execvp(argv[0], argv.data());
+ ::dprintf(2, "doos: exec %s: %s\n", argv[0], std::strerror(errno));
+ ::_exit(127);
+}
+
+int exitCodeOf(int status) {
+ if (WIFEXITED(status)) return WEXITSTATUS(status);
+ if (WIFSIGNALED(status)) return 128 + WTERMSIG(status);
+ return 1;
+}
+
+struct ChildCtx {
+ const Container* container;
+ const std::vector* command;
+ int syncFd;
+ fs::path imageRoot;
+ int lockFd; // inherited copy must be closed or the flock outlives unlock()
+};
+
+// Runs as pid 1 of the new pid namespace.
+int containerInit(void* arg) {
+ auto* ctx = static_cast(arg);
+ try {
+ ::prctl(PR_SET_PDEATHSIG, SIGKILL);
+ ::close(ctx->lockFd);
+ char go = 0;
+ if (::read(ctx->syncFd, &go, 1) != 1 || go != 'G') ::_exit(125);
+ ::close(ctx->syncFd);
+
+ const Container& c = *ctx->container;
+ setupRoot(c, ctx->imageRoot);
+ if (::sethostname(c.name().c_str(), c.name().size()) != 0) throw SysError("sethostname");
+ if (Network::isolated(c.net())) bringLoopbackUp();
+ // Hardening (inside applyLimitsAndEnv) must be the last thing before the worker is forked
+ // and exec'd: everything this process still needs to do for itself (mounts, hostname,
+ // loopback) has to happen first, since its seccomp filter and dropped capabilities are
+ // inherited by every descendant from here on. See the matching note in Sandbox::join.
+ applyLimitsAndEnv(c);
+
+ pid_t worker = ::fork();
+ if (worker < 0) throw SysError("fork");
+ if (worker == 0) execCommand(*ctx->command);
+
+ // Minimal init: forward termination signals, reap everything, mirror the worker's status.
+ installForwarding(worker, {SIGTERM, SIGINT, SIGHUP, SIGQUIT});
+ int code = 1;
+ for (;;) {
+ int status = 0;
+ pid_t p = ::waitpid(-1, &status, 0);
+ if (p < 0) {
+ if (errno == EINTR) continue;
+ break;
+ }
+ if (p == worker) {
+ code = exitCodeOf(status);
+ break;
+ }
+ }
+ ::kill(-1, SIGKILL);
+ ::_exit(code);
+ } catch (const std::exception& e) {
+ ::dprintf(2, "doos: %s\n", e.what());
+ auto* se = dynamic_cast(&e);
+ std::ifstream restrictUserns("/proc/sys/kernel/apparmor_restrict_unprivileged_userns");
+ int restricted = 0;
+ if (restrictUserns) restrictUserns >> restricted;
+ if (se && (se->code() == EPERM || se->code() == EACCES) && restricted == 1) {
+ ::dprintf(2, "doos: AppArmor restricts user namespaces for this binary. Install a profile once with:\n %s\n",
+ Sandbox::apparmorInstallHint().c_str());
+ }
+ ::_exit(125);
+ }
+}
+
+} // namespace
+
+namespace {
+fs::path selfPath() {
+ std::error_code ec;
+ fs::path self = fs::read_symlink("/proc/self/exe", ec);
+ if (ec) throw std::runtime_error("cannot resolve the path of this binary: " + ec.message());
+ std::string path = self.string();
+ if (path.find_first_of("{}[]*?\"\n,") != std::string::npos) {
+ throw std::runtime_error("binary path contains characters AppArmor treats as globs: " + path);
+ }
+ return self;
+}
+
+// One profile per binary path, so installing doos in a second place does not replace the first profile.
+std::string profileName(const fs::path& self) {
+ std::string n = "doos" + self.string();
+ for (auto& c : n) {
+ if (c == '/') c = '-';
+ }
+ return n;
+}
+} // namespace
+
+std::string Sandbox::apparmorProfile() {
+ fs::path self = selfPath();
+ return "# Lets doos use unprivileged user namespaces where kernel.apparmor_restrict_unprivileged_userns=1.\n"
+ "# Generated by: doos apparmor (profile is for exactly this path)\n"
+ "abi ,\n"
+ "include \n"
+ "\n"
+ "profile " + profileName(self) + " " + self.string() + " flags=(unconfined) {\n"
+ " userns,\n"
+ " @{exec_path} mr,\n"
+ "}\n";
+}
+
+std::string Sandbox::apparmorInstallHint() {
+ fs::path self = selfPath();
+ std::string file = "/etc/apparmor.d/" + profileName(self);
+ // The generator must be invoked through this same binary: its profile is
+ // path-specific, so `doos apparmor` output would be wrong under `molo`.
+ std::string gen = self.filename() == "doos" ? "doos apparmor" : self.string() + " doos apparmor";
+ return gen + " | sudo tee " + file + " >/dev/null && sudo apparmor_parser -r " + file;
+}
+
+int Sandbox::run() {
+ if (command_.size() > Caps::kMaxCommandArgs) throw std::runtime_error("too many command arguments");
+ // Decide start-or-join under the lock so concurrent attaches agree.
+ FileLock lock(container_.lockFile(), Caps::kLockTimeoutMs);
+ if (auto pid = container_.runningPid()) {
+ return join(*pid, lock);
+ }
+ return start(lock);
+}
+
+int Sandbox::start(FileLock& lock) {
+ NetMode net = container_.net();
+ fs::path imageRoot;
+ if (container_.imageMode()) {
+ Store store = Store::fromEnvironment();
+ imageRoot = store.images().rootfs(container_.image());
+ if (!fs::is_directory(imageRoot)) {
+ throw std::runtime_error("image '" + container_.image() + "' is missing; add it again with: doos image add");
+ }
+ }
+ // davmount entries are resolved here, on the host, before any namespace exists: the FUSE mount
+ // this installs (or reuses) lives outside the container entirely and must outlast it.
+ container_.primeRuntimeMounts(DavMount::resolveAll(container_.mounts()));
+ int flags = CLONE_NEWUSER | CLONE_NEWNS | CLONE_NEWPID | CLONE_NEWUTS | CLONE_NEWIPC | SIGCHLD;
+ if (Network::isolated(net)) flags |= CLONE_NEWNET;
+
+ int sync[2];
+ if (::pipe2(sync, O_CLOEXEC) != 0) throw SysError("pipe");
+ Fd syncRead(sync[0]), syncWrite(sync[1]);
+
+ std::vector stack(1 << 20);
+ ChildCtx ctx{&container_, &command_, syncRead.get(), imageRoot, lock.fd()};
+ pid_t child = ::clone(containerInit, stack.data() + stack.size(), flags, &ctx);
+ if (child < 0) throw SysError("clone (user namespaces available?)");
+
+ // From here on the child is ours: make sure it never outlives a failed setup.
+ struct Reaper {
+ pid_t pid;
+ bool armed = true;
+ ~Reaper() {
+ if (armed) {
+ ::kill(pid, SIGKILL);
+ ::waitpid(pid, nullptr, 0);
+ }
+ }
+ } reaper{child};
+
+ IdMap::apply(child, container_.ids());
+
+ SlirpSession slirp;
+ PastaSession pasta;
+ if (net == NetMode::Slirp) slirp.start(child);
+ if (net == NetMode::Pasta) pasta.start(child);
+
+ Limits limits{container_.memoryCap(), container_.pidsCap(), container_.milliCpus()};
+ std::string cgroupWhy, notEnforced;
+ std::unique_ptr cgroup = Cgroup::create(container_.name(), limits, cgroupWhy, notEnforced);
+ if (cgroup) {
+ cgroup->addMain(child);
+ if (!notEnforced.empty()) std::fprintf(stderr, "doos: limits not enforced (controller missing): %s\n", notEnforced.c_str());
+ } else {
+ std::fprintf(stderr, "doos: memory, pids and cpu limits are not enforced and the size cap only warns: %s\n",
+ cgroupWhy.c_str());
+ }
+
+ container_.recordPid(child);
+ struct PidGuard {
+ const Container& c;
+ ~PidGuard() { c.clearPid(); }
+ } pidGuard{container_};
+
+ char go = 'G';
+ if (::write(syncWrite.get(), &go, 1) != 1) throw SysError("sync child");
+ syncWrite.reset();
+ syncRead.reset();
+
+ // The lock only protects the start decision; joiners must not wait for the container's lifetime.
+ lock.unlock();
+ struct sigaction ign;
+ std::memset(&ign, 0, sizeof ign);
+ ign.sa_handler = SIG_IGN;
+ ::sigaction(SIGINT, &ign, nullptr);
+ ::sigaction(SIGQUIT, &ign, nullptr);
+ installForwarding(child, {SIGTERM, SIGHUP});
+
+ int status = watch(child, cgroup.get());
+ reaper.armed = false;
+ if (cgroup && cgroup->oomKills() > 0) {
+ std::fprintf(stderr, "doos: '%s' was killed by its memory limit (%s); raise it with --memory\n",
+ container_.name().c_str(), formatSize(container_.memoryCap()).c_str());
+ }
+ if (cgroup && cgroup->pidFailures() > 0) {
+ std::fprintf(stderr, "doos: '%s' hit its process limit (%u) %llu times; raise it with --pids\n",
+ container_.name().c_str(), container_.pidsCap(),
+ static_cast(cgroup->pidFailures()));
+ }
+ return exitCodeOf(status);
+}
+
+// Waits for the container's init while enforcing the size cap: warn at kSizeWarnPercent, freeze at the cap,
+// thaw again once usage drops below kSizeThawPercent. Nothing is ever deleted by this loop.
+int Sandbox::watch(pid_t child, Cgroup* cgroup) {
+ using Clock = std::chrono::steady_clock;
+ long fd = ::syscall(SYS_pidfd_open, child, 0);
+ Fd pidfd(static_cast(fd));
+ const std::uint64_t cap = container_.sizeCap();
+ bool warned = false;
+ auto nextScan = Clock::now() + std::chrono::milliseconds(Caps::kSizeCheckMinIntervalMs);
+ for (;;) {
+ auto left = std::chrono::duration_cast(nextScan - Clock::now()).count();
+ int timeout = static_cast(std::max(left, 50));
+ if (pidfd.valid()) {
+ pollfd p{pidfd.get(), POLLIN, 0};
+ int r = ::poll(&p, 1, timeout);
+ if (r > 0) break;
+ if (r < 0 && errno != EINTR) break;
+ } else {
+ int st = 0;
+ if (::waitpid(child, &st, WNOHANG) == child) return st;
+ ::poll(nullptr, 0, std::min(timeout, 1000));
+ }
+ if (g_terminating && cgroup && cgroup->frozen()) cgroup->freeze(false); // a frozen init cannot see SIGTERM
+ if (Clock::now() < nextScan) continue;
+
+ auto began = Clock::now();
+ std::size_t skipped = 0;
+ std::uint64_t used = container_.usedBytes(skipped);
+ // The scan may use at most 1/kSizeScanDutyFactor of the time: big trees are scanned less often.
+ auto took = Clock::now() - began;
+ nextScan = Clock::now() + std::max(std::chrono::milliseconds(Caps::kSizeCheckMinIntervalMs),
+ std::chrono::duration_cast(took) * Caps::kSizeScanDutyFactor);
+ const char* name = container_.name().c_str();
+ if (used >= cap) {
+ if (cgroup && !cgroup->frozen()) {
+ cgroup->freeze(true);
+ std::fprintf(stderr, "doos: '%s' reached its size cap (%s of %s): FROZEN. Free space with 'doos attach %s -- ...'; it thaws below %d%%.\n",
+ name, formatSize(used).c_str(), formatSize(cap).c_str(), name, Caps::kSizeThawPercent);
+ } else if (!cgroup && !warned) {
+ std::fprintf(stderr, "doos: '%s' is over its size cap (%s of %s), cannot freeze\n", name,
+ formatSize(used).c_str(), formatSize(cap).c_str());
+ warned = true;
+ }
+ } else if (used * 100 >= cap * Caps::kSizeWarnPercent) {
+ if (!warned) {
+ std::fprintf(stderr, "doos: '%s' uses %s of its %s size cap\n", name, formatSize(used).c_str(),
+ formatSize(cap).c_str());
+ warned = true;
+ }
+ } else {
+ warned = false;
+ }
+ if (cgroup && cgroup->frozen() && used * 100 < cap * Caps::kSizeThawPercent) {
+ cgroup->freeze(false);
+ std::fprintf(stderr, "doos: '%s' thawed (%s used)\n", name, formatSize(used).c_str());
+ }
+ }
+ int status = 0;
+ while (::waitpid(child, &status, 0) < 0) {
+ if (errno != EINTR) throw SysError("waitpid");
+ }
+ return status;
+}
+
+int Sandbox::join(pid_t initPid, FileLock& lock) {
+ std::string base = "/proc/" + std::to_string(initPid);
+ // Order matters: user first (grants the capabilities to join the rest).
+ const char* names[] = {"user", "mnt", "uts", "ipc", "net", "pid"};
+ const int kinds[] = {CLONE_NEWUSER, CLONE_NEWNS, CLONE_NEWUTS, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWPID};
+ Fd fds[6];
+ for (int i = 0; i < 6; ++i) {
+ if (container_.net() == NetMode::Host && kinds[i] == CLONE_NEWNET) continue;
+ fds[i].reset(::open((base + "/ns/" + names[i]).c_str(), O_RDONLY | O_CLOEXEC));
+ if (!fds[i].valid()) throw SysError(std::string("open ns/") + names[i]);
+ }
+ Fd rootFd(::open((base + "/root").c_str(), O_RDONLY | O_DIRECTORY | O_CLOEXEC));
+ if (!rootFd.valid()) throw SysError("open container root");
+
+ lock.unlock();
+ // Later attaches live in the `shell` leaf: same limits as the container, but never frozen.
+ std::unique_ptr cgroup = Cgroup::open(container_.name());
+ pid_t child = ::fork();
+ if (child < 0) throw SysError("fork");
+ if (child == 0) {
+ try {
+ if (cgroup) {
+ try { cgroup->addShell(::getpid()); } catch (const std::exception&) { /* limits only; keep going */ }
+ }
+ // Ordering invariant: this setns loop must run before Hardening::apply() (inside
+ // applyLimitsAndEnv below), never after. The seccomp filter it installs denies
+ // SYS_setns outright (hardening.cpp's deniedSyscalls), and a seccomp filter is
+ // inherited by every descendant for the rest of its life. Moving the hardening call
+ // earlier would make every second `attach` fail to join a running container.
+ for (int i = 0; i < 6; ++i) {
+ if (fds[i].valid() && ::setns(fds[i].get(), kinds[i]) != 0) {
+ throw SysError(std::string("setns ") + names[i]);
+ }
+ }
+ if (::fchdir(rootFd.get()) != 0 || ::chroot(".") != 0) throw SysError("chroot into container");
+ if (::chdir(std::string(Caps::kHome).c_str()) != 0) throw SysError("chdir home");
+ // setns(pid) only affects children, so fork once more. Hardening (which the setns
+ // loop above must predate) is applied only in this inner child, right before exec.
+ pid_t inner = ::fork();
+ if (inner < 0) throw SysError("fork");
+ if (inner == 0) {
+ applyLimitsAndEnv(container_);
+ execCommand(command_);
+ }
+ int status = 0;
+ installForwarding(inner, {SIGTERM, SIGHUP});
+ while (::waitpid(inner, &status, 0) < 0) {
+ if (errno != EINTR) break;
+ }
+ ::_exit(exitCodeOf(status));
+ } catch (const std::exception& e) {
+ ::dprintf(2, "doos: %s\n", e.what());
+ ::_exit(125);
+ }
+ }
+ struct sigaction ign;
+ std::memset(&ign, 0, sizeof ign);
+ ign.sa_handler = SIG_IGN;
+ ::sigaction(SIGINT, &ign, nullptr);
+ ::sigaction(SIGQUIT, &ign, nullptr);
+ installForwarding(child, {SIGTERM, SIGHUP});
+ int status = 0;
+ while (::waitpid(child, &status, 0) < 0) {
+ if (errno != EINTR) throw SysError("waitpid");
+ }
+ return exitCodeOf(status);
+}
+
+} // namespace molo::doos
diff --git a/src/doos/sandbox.hpp b/src/doos/sandbox.hpp
new file mode 100644
index 0000000..31e1f1f
--- /dev/null
+++ b/src/doos/sandbox.hpp
@@ -0,0 +1,35 @@
+#pragma once
+#include
+#include
+
+#include "doos/container.hpp"
+#include "doos/util.hpp"
+
+namespace molo::doos {
+
+class Cgroup;
+
+// Runs a command inside a container: starts the namespaces if the container is
+// stopped, joins them if it is already running. Returns the command's exit code.
+class Sandbox {
+public:
+ Sandbox(Container container, std::vector command)
+ : container_(std::move(container)), command_(std::move(command)) {}
+
+ int run();
+
+ // AppArmor profile (text) that lets this very binary use user namespaces on Ubuntu 24.04+.
+ static std::string apparmorProfile();
+ // Shell command that installs it; shown when a start fails because of AppArmor.
+ static std::string apparmorInstallHint();
+
+private:
+ int start(FileLock& lock);
+ int watch(pid_t child, Cgroup* cgroup);
+ int join(pid_t initPid, FileLock& lock);
+
+ Container container_;
+ std::vector command_;
+};
+
+} // namespace molo::doos
diff --git a/src/doos/scripts/bench.sh b/src/doos/scripts/bench.sh
new file mode 100755
index 0000000..8f3ca32
--- /dev/null
+++ b/src/doos/scripts/bench.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Reproducible measurements behind COMPARISON.md and the charts. Writes JSON (default docs/charts/bench.json).
+# Tools that are not installed or not usable are skipped and recorded as null, never guessed.
+# Usage: scripts/bench.sh [output.json] Environment: BENCH_RUNS (default 10)
+set -u
+cd "$(dirname "$0")/.."
+OUT=${1:-docs/charts/bench.json}
+RUNS=${BENCH_RUNS:-10}
+DOOS=$(readlink -f "${BENCH_DOOS:-build/doos}")
+[ -x "$DOOS" ] || { echo "bench: build first (make build)" >&2; exit 1; }
+export DOOS_HOME=$(mktemp -d)
+trap '"$DOOS" delete --yes ha >/dev/null 2>&1; rm -rf "$DOOS_HOME"' EXIT
+
+have() { command -v "$1" >/dev/null 2>&1; }
+now() { date +%s%N; }
+# avg_ms LABEL CMD... -> prints average ms per run, or "null" when the command fails
+avg_ms() {
+ timeout 180 "$@" >/dev/null 2>&1 || { echo null; return; } # warm-up, may pull an image
+ local s e i; s=$(now)
+ for i in $(seq "$RUNS"); do timeout 60 "$@" >/dev/null 2>&1 || { echo null; return; }; done
+ e=$(now); awk -v s="$s" -v e="$e" -v n="$RUNS" 'BEGIN{printf "%.1f", (e-s)/1e6/n}'
+}
+note() { echo "bench: $*" >&2; }
+
+# ---- setup doos containers (host mode needs nothing, image mode downloads Alpine once)
+"$DOOS" image add alpine >/dev/null 2>&1 || note "alpine image unavailable, image-mode rows will be null"
+"$DOOS" get_or_create --net none hn >/dev/null 2>&1
+"$DOOS" get_or_create hs >/dev/null 2>&1
+"$DOOS" get_or_create --image alpine --net none an >/dev/null 2>&1
+"$DOOS" get_or_create --image alpine as >/dev/null 2>&1
+"$DOOS" get_or_create --image alpine --net pasta ap >/dev/null 2>&1
+
+BW_BASE="--unshare-user --unshare-pid --unshare-ipc --unshare-uts --die-with-parent --ro-bind /usr /usr --symlink usr/bin /bin --symlink usr/lib /lib --symlink usr/lib64 /lib64 --proc /proc --dev /dev"
+rows=()
+add() { rows+=("{\"id\":\"$1\",\"label\":\"$2\",\"group\":\"$3\",\"kind\":\"$4\",\"ms\":$5}"); }
+
+echo "bench: startup, $RUNS runs each" >&2
+if have bwrap; then
+ add bwrap_none "bubblewrap (host /usr)" none other "$(avg_ms bwrap --unshare-all $BW_BASE true)"
+ add bwrap_net "bubblewrap (host /usr)" default other "$(avg_ms bwrap $BW_BASE true)"
+fi
+add doos_host_none "doos host mode" none doos "$(avg_ms "$DOOS" attach hn -- true)"
+add doos_alpine_none "doos Alpine image" none doos "$(avg_ms "$DOOS" attach an -- true)"
+add doos_host_slirp "doos host mode" default doos "$(avg_ms "$DOOS" attach hs -- true)"
+add doos_alpine_slirp "doos Alpine image" default doos "$(avg_ms "$DOOS" attach as -- true)"
+add doos_alpine_pasta "doos Alpine, pasta" default doos "$(avg_ms "$DOOS" attach ap -- true)"
+if have podman; then
+ add podman_none "Podman Alpine" none other "$(avg_ms podman run --rm --network none alpine true)"
+ add podman_net "Podman Alpine" default other "$(avg_ms podman run --rm alpine true)"
+fi
+if have docker; then
+ add docker_none "Docker Alpine (rootful)" none other "$(avg_ms docker run --rm --network none alpine true)"
+ add docker_net "Docker Alpine (rootful)" default other "$(avg_ms docker run --rm alpine true)"
+fi
+
+# ---- binary sizes
+size_of() { local p; p=$(command -v "$1" 2>/dev/null) && stat -L -c %s "$p" || echo null; }
+sizes=()
+for t in bwrap crun doos docker podman; do
+ if [ "$t" = doos ]; then b=$(stat -c %s "$DOOS"); else b=$(size_of "$t"); fi
+ sizes+=("{\"id\":\"$t\",\"bytes\":$b}")
+done
+
+# ---- cpu limit: 4 busy loops for 4 seconds, CPU seconds consumed (user+sys)
+cpu_run() {
+ /usr/bin/time -f "%U %S" "$DOOS" attach "$1" -- sh -c 'for i in 1 2 3 4; do (timeout 4 sh -c "while :; do :; done" &); done; sleep 4.2' 2>&1 >/dev/null | tail -1 | awk '{printf "%.2f", $1+$2}'
+}
+echo "bench: cpu limit" >&2
+"$DOOS" get_or_create hc >/dev/null 2>&1; "$DOOS" get_or_create --cpus 0.5 hc5 >/dev/null 2>&1
+cpu_free=$(cpu_run hc); cpu_half=$(cpu_run hc5)
+"$DOOS" delete --yes hc >/dev/null 2>&1; "$DOOS" delete --yes hc5 >/dev/null 2>&1
+
+ver() { "$@" 2>/dev/null | head -1 | tr -d '"\\' ; }
+json_join() { local IFS=,; echo "$*"; }
+cat > "$OUT" <&2
diff --git a/src/doos/scripts/check-docs.sh b/src/doos/scripts/check-docs.sh
new file mode 100755
index 0000000..dea7fe4
--- /dev/null
+++ b/src/doos/scripts/check-docs.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Checks the documentation set: every markdown file links to every other one, and every relative link resolves.
+# Usage: scripts/check-docs.sh (exit 1 on any problem, lists them all)
+set -u
+cd "$(dirname "$0")/.."
+
+DOCS=(README.md SPEC.md COMPARISON.md PROVENANCE.md CHANGELOG.md docs/ARCHITECTURE.md docs/RESEARCH.md docs/CI.md)
+bad=0
+fail() { echo "docs: $*"; bad=$((bad+1)); }
+
+# no markdown file may exist outside the checked set (so a new doc cannot dodge the rule)
+while IFS= read -r f; do
+ f=${f#./}
+ printf '%s\n' "${DOCS[@]}" | grep -qxF "$f" || fail "$f is not in the DOCS list of scripts/check-docs.sh"
+done < <(find . -name '*.md' -not -path './build/*' -not -path './.git/*' -not -path './docs/history/*' -not -path './valgrind/*')
+# docs/history/*: frozen originals (AGENTS.md, prompt.md, review.md, review2.md), not maintained docs.
+# valgrind/*: a separate, self-contained doc set (one README for the valgrind setup); linked
+# from the main docs but not forced into their full cross-link mesh. The CVE audit set moved
+# to the repo-root audit/ directory with its own README.
+
+for f in "${DOCS[@]}"; do
+ [ -f "$f" ] || { fail "$f is missing"; continue; }
+ dir=$(dirname "$f")
+ # every other document must be linked
+ for g in "${DOCS[@]}"; do
+ [ "$f" = "$g" ] && continue
+ rel=$(realpath --relative-to="$dir" "$g")
+ grep -qE "\]\(${rel//./\\.}(#[^)]*)?\)" "$f" || fail "$f does not link to $g (expected ]($rel))"
+ done
+ # every relative link must point at something that exists
+ while IFS= read -r target; do
+ case "$target" in http://*|https://*|mailto:*|\#*) continue ;; esac
+ path=${target%%#*}
+ [ -z "$path" ] && continue
+ [ -e "$dir/$path" ] || fail "$f links to missing $target"
+ done < <(grep -oE '\]\([^)]+\)' "$f" | sed -E 's/^\]\(//; s/\)$//')
+done
+
+[ "$bad" -eq 0 ] && echo "docs: ${#DOCS[@]} documents, all cross-linked, all links resolve" || { echo "docs: $bad problem(s)"; exit 1; }
diff --git a/src/doos/scripts/valgrind.sh b/src/doos/scripts/valgrind.sh
new file mode 100755
index 0000000..ad4d9f9
--- /dev/null
+++ b/src/doos/scripts/valgrind.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Runs a fixed, named set of doos invocations under valgrind's memcheck, using
+# valgrind/doos.supp to silence the known, explained allocation sites (see that file's
+# comments), and fails only on a real, unsuppressed memory error or leak. Does not rebuild;
+# run `make build` (or just `make valgrind`, which depends on it) first.
+#
+# Usage: scripts/valgrind.sh [path/to/doos]
+set -u
+cd "$(dirname "$0")/.."
+
+DOOS="${1:-build/doos}"
+SUPP="$(pwd)/valgrind/doos.supp"
+REPORTS="${VALGRIND_REPORTS:-build/valgrind-reports}"
+TIMEOUT=60
+
+command -v valgrind >/dev/null || { echo "valgrind: not installed"; exit 1; }
+[ -x "$DOOS" ] || { echo "valgrind: no doos binary at '$DOOS' (run 'make build' first)"; exit 1; }
+[ -f "$SUPP" ] || { echo "valgrind: suppressions file missing: $SUPP"; exit 1; }
+
+rm -rf "$REPORTS"
+mkdir -p "$REPORTS"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+export DOOS_HOME="$TMP/home"
+
+fails=0
+checked=0
+
+run() { # run NAME -- DOOS_ARGS...
+ local name="$1"; shift
+ shift # drop the --
+ checked=$((checked + 1))
+ local log="$REPORTS/$name.log"
+ timeout "$TIMEOUT" valgrind \
+ --leak-check=full --show-leak-kinds=all --track-origins=yes \
+ --suppressions="$SUPP" --error-exitcode=99 \
+ --log-file="$log" \
+ "$DOOS" "$@" >/dev/null 2>&1
+ local rc=$?
+ if [ "$rc" = 99 ]; then
+ echo "FAIL $name: valgrind reported an unsuppressed error or leak, see $log"
+ fails=$((fails + 1))
+ elif [ "$rc" = 124 ]; then
+ echo "FAIL $name: timed out after ${TIMEOUT}s under valgrind, see $log"
+ fails=$((fails + 1))
+ else
+ echo "ok $name (doos exit=$rc; valgrind found nothing to report), see $log"
+ fi
+}
+
+# Fixed, named set: the four CLI commands SPEC.md documents, plus a second attach to exercise
+# the join-a-running-container path. No image download here (network + extraction add their
+# own long-running C library code, better covered once by a dedicated image-mode run; see
+# valgrind/README.md for how to add one).
+run list -- list
+run get_or_create -- get_or_create --net none vgcheck
+run attach_first -- attach --net none vgcheck -- true
+run attach_join -- attach --net none vgcheck -- true
+run image_list -- image list
+run delete -- delete --yes vgcheck
+
+echo "valgrind: $checked checked, $fails failed, reports in $REPORTS/"
+[ "$fails" -eq 0 ]
diff --git a/src/doos/seam/isolation.cpp b/src/doos/seam/isolation.cpp
new file mode 100644
index 0000000..6883ae5
--- /dev/null
+++ b/src/doos/seam/isolation.cpp
@@ -0,0 +1,74 @@
+#include "doos/seam/isolation.hpp"
+
+#include
+#include
+#include
+
+#include
+#include
+#include
+
+#include "doos/cgroup.hpp"
+#include "doos/hardening.hpp"
+#include "doos/idmap.hpp"
+
+namespace molo::doos::seam {
+
+DoosIsolation::DoosIsolation(std::string name) : name_(sanitizeName(name)) {}
+
+DoosIsolation::~DoosIsolation() = default;
+
+bool DoosIsolation::attach(pid_t child, const molo::supervisor::IsolationSpec& spec, std::string& reason) {
+ Limits limits{spec.memory_bytes, spec.pids, spec.milli_cpus};
+ std::string why, not_enforced;
+ std::unique_ptr cg = Cgroup::create(name_, limits, why, not_enforced);
+ if (!cg) {
+ reason = why;
+ return false;
+ }
+ try {
+ cg->addMain(child);
+ } catch (const std::exception& e) {
+ reason = e.what();
+ return false;
+ }
+ if (!not_enforced.empty()) {
+ reason = "limits partly unenforced (" + not_enforced + "); refusing to run degraded";
+ return false;
+ }
+ cgroup_ = std::move(cg);
+ return true;
+}
+
+int DoosIsolation::confine(const molo::supervisor::IsolationSpec& spec) {
+ if (!spec.hardening) return 0;
+ // Dropping capabilities needs capabilities, which an unprivileged child
+ // only holds inside its own user namespace: enter one (doos single-id
+ // mode) first. Same pid/network/mount namespaces otherwise, so the
+ // supervisor still signals and reaps the child unchanged.
+ if (::unshare(CLONE_NEWUSER) != 0) {
+ ::dprintf(2, "supervisor: isolation confine failed: unshare user ns: %s\n", std::strerror(errno));
+ return 126;
+ }
+ try {
+ IdMap::mapSelfSingle();
+ } catch (const std::exception& e) {
+ ::dprintf(2, "supervisor: isolation confine failed: %s\n", e.what());
+ return 126;
+ }
+ if (::prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) != 0) {
+ ::dprintf(2, "supervisor: isolation confine failed: no_new_privs: %s\n", std::strerror(errno));
+ return 126;
+ }
+ rlimit core{0, 0};
+ ::setrlimit(RLIMIT_CORE, &core);
+ try {
+ Hardening::apply();
+ } catch (const std::exception& e) {
+ ::dprintf(2, "supervisor: isolation confine failed: %s\n", e.what());
+ return 126;
+ }
+ return 0;
+}
+
+} // namespace molo::doos::seam
diff --git a/src/doos/seam/isolation.hpp b/src/doos/seam/isolation.hpp
new file mode 100644
index 0000000..e4fdd8c
--- /dev/null
+++ b/src/doos/seam/isolation.hpp
@@ -0,0 +1,37 @@
+#pragma once
+
+// doos-backed IIsolationBackend for supervised OS programs: cgroup v2 limits
+// (memory/pids/cpus) attached to the supervised child, plus optional
+// pre-exec hardening (no_new_privs, no core dumps, capability drop, seccomp
+// denylist). All-or-nothing: when any requested limit cannot attach, attach()
+// refuses loudly instead of running degraded.
+
+#include
+#include
+
+#include "doos/util.hpp"
+#include "supervisor/common/isolation_backend.hpp"
+
+namespace molo::doos {
+
+class Cgroup;
+
+namespace seam {
+
+class DoosIsolation : public molo::supervisor::IIsolationBackend {
+public:
+ // Both out of line in the .cpp: Cgroup is incomplete in this header.
+ explicit DoosIsolation(std::string name);
+ ~DoosIsolation() override;
+
+ bool attach(pid_t child, const molo::supervisor::IsolationSpec& spec, std::string& reason) override;
+ int confine(const molo::supervisor::IsolationSpec& spec) override;
+
+private:
+ std::string name_;
+ std::unique_ptr cgroup_; // removed when the backend dies (worker stop)
+};
+
+} // namespace seam
+
+} // namespace molo::doos
diff --git a/src/doos/util.cpp b/src/doos/util.cpp
new file mode 100644
index 0000000..d34eb64
--- /dev/null
+++ b/src/doos/util.cpp
@@ -0,0 +1,564 @@
+#include "doos/util.hpp"
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include "doos/caps.h"
+
+namespace fs = std::filesystem;
+
+namespace molo::doos {
+
+SysError::SysError(const std::string& what, int err)
+ : std::runtime_error(what + ": " + std::strerror(err)), code_(err) {}
+
+Fd& Fd::operator=(Fd&& o) noexcept {
+ if (this != &o) reset(o.release());
+ return *this;
+}
+
+int Fd::release() {
+ int f = fd_;
+ fd_ = -1;
+ return f;
+}
+
+void Fd::reset(int fd) {
+ if (fd_ >= 0) ::close(fd_);
+ fd_ = fd;
+}
+
+FileLock::FileLock(const fs::path& file, int timeoutMs) {
+ fd_.reset(::open(file.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0600));
+ if (!fd_.valid()) throw SysError("open lock " + file.string());
+ for (int waited = 0;; waited += 50) {
+ if (::flock(fd_.get(), LOCK_EX | LOCK_NB) == 0) return;
+ if (errno != EWOULDBLOCK) throw SysError("flock " + file.string());
+ if (waited >= timeoutMs) throw std::runtime_error("timed out waiting for lock " + file.string());
+ ::poll(nullptr, 0, 50);
+ }
+}
+
+std::uint64_t parseSize(const std::string& text) {
+ std::size_t i = 0;
+ while (i < text.size() && std::isdigit(static_cast(text[i]))) ++i;
+ if (i == 0 || i > 15) throw std::runtime_error("invalid size '" + text + "' (examples: 512m, 4g)");
+ std::uint64_t v = std::stoull(text.substr(0, i));
+ std::string unit = text.substr(i);
+ for (auto& c : unit) c = static_cast(std::tolower(static_cast(c)));
+ if (unit == "b" || unit.empty()) {
+ } else {
+ if (unit.size() == 2 && unit[1] == 'b') unit.pop_back();
+ int shift;
+ if (unit == "k") shift = 10;
+ else if (unit == "m") shift = 20;
+ else if (unit == "g") shift = 30;
+ else if (unit == "t") shift = 40;
+ else throw std::runtime_error("invalid size unit in '" + text + "' (use k, m, g or t)");
+ // A 64-bit shift wraps silently on a large enough value instead of producing a huge
+ // number; reject anything that would not survive the shift intact rather than let it
+ // land, by chance, inside whatever range the caller validates against next.
+ if (v > (std::numeric_limits::max() >> shift)) {
+ throw std::runtime_error("size '" + text + "' is too large");
+ }
+ v <<= shift;
+ }
+ return v;
+}
+
+std::string formatSize(std::uint64_t b) {
+ const char* u[] = {"B", "K", "M", "G", "T"};
+ double v = static_cast(b);
+ int i = 0;
+ while (v >= 1024 && i < 4) { v /= 1024; ++i; }
+ char buf[32];
+ if (i == 0) std::snprintf(buf, sizeof buf, "%lluB", static_cast(b));
+ else std::snprintf(buf, sizeof buf, v < 10 ? "%.1f%s" : "%.0f%s", v, u[i]);
+ return buf;
+}
+
+std::string base64Decode(const std::string& in) {
+ std::string out;
+ unsigned val = 0;
+ int bits = -8;
+ for (unsigned char c : in) {
+ int d;
+ if (c >= 'A' && c <= 'Z') d = c - 'A';
+ else if (c >= 'a' && c <= 'z') d = c - 'a' + 26;
+ else if (c >= '0' && c <= '9') d = c - '0' + 52;
+ else if (c == '+' || c == '-') d = 62;
+ else if (c == '/' || c == '_') d = 63;
+ else if (c == '=' || std::isspace(c)) continue;
+ else throw std::runtime_error("invalid base64 input");
+ val = (val << 6) | static_cast(d);
+ bits += 6;
+ if (bits >= 0) {
+ out.push_back(static_cast((val >> bits) & 0xFF));
+ bits -= 8;
+ }
+ }
+ return out;
+}
+
+ProcResult runProcess(const std::vector& argv, bool capture, bool quiet) {
+ int pipefd[2] = {-1, -1};
+ if (capture && ::pipe2(pipefd, O_CLOEXEC) != 0) throw SysError("pipe");
+ Fd readEnd(pipefd[0]), writeEnd(pipefd[1]);
+ pid_t pid = ::fork();
+ if (pid < 0) throw SysError("fork " + argv.at(0));
+ if (pid == 0) {
+ if (capture) ::dup2(writeEnd.get(), 1);
+ if (quiet) {
+ int nul = ::open("/dev/null", O_WRONLY);
+ if (nul >= 0) { ::dup2(nul, 2); if (!capture) ::dup2(nul, 1); }
+ }
+ // Never trust the caller's PATH: helpers are found only in system directories.
+ ::setenv("PATH", std::string(Caps::kContainerPath).c_str(), 1);
+ std::vector a;
+ for (const auto& x : argv) a.push_back(const_cast(x.c_str()));
+ a.push_back(nullptr);
+ ::execvp(a[0], a.data());
+ ::dprintf(2, "doos: cannot run %s: %s\n", a[0], std::strerror(errno));
+ ::_exit(127);
+ }
+ writeEnd.reset();
+ ProcResult r;
+ if (capture) {
+ char buf[4096];
+ ssize_t n;
+ while ((n = ::read(readEnd.get(), buf, sizeof buf)) != 0) {
+ if (n < 0) { if (errno == EINTR) continue; break; }
+ if (r.out.size() + static_cast(n) > Caps::kMaxCaptureBytes) {
+ ::kill(pid, SIGKILL);
+ ::waitpid(pid, nullptr, 0);
+ throw std::runtime_error("output of " + argv.at(0) + " exceeds the capture cap");
+ }
+ r.out.append(buf, static_cast(n));
+ }
+ }
+ int st = 0;
+ while (::waitpid(pid, &st, 0) < 0) {
+ if (errno != EINTR) throw SysError("waitpid " + argv.at(0));
+ }
+ r.code = WIFEXITED(st) ? WEXITSTATUS(st) : 128 + WTERMSIG(st);
+ return r;
+}
+
+std::string fetchText(const std::string& url) {
+ ProcResult r = runProcess({resolveBinary("curl"), "--fail", "--silent", "--show-error", "--location",
+ "--proto", "=https", "--max-time", "60", url},
+ true);
+ if (r.code != 0) throw std::runtime_error("download failed: " + url + " (curl exit " + std::to_string(r.code) + ")");
+ return r.out;
+}
+
+void fetchFile(const std::string& url, const fs::path& out, std::uint64_t maxBytes) {
+ ProcResult r = runProcess({resolveBinary("curl"), "--fail", "--silent", "--show-error", "--location",
+ "--proto", "=https", "--max-time", "60", "--max-filesize",
+ std::to_string(maxBytes), "--output", out.string(), url});
+ if (r.code != 0) throw std::runtime_error("download failed: " + url + " (curl exit " + std::to_string(r.code) + ")");
+}
+
+TempDir::TempDir() {
+ fs::path base;
+ if (const char* h = std::getenv("DOOS_HOME"); h && *h) base = h;
+ else if (const char* x = std::getenv("XDG_DATA_HOME"); x && *x) base = fs::path(x) / "doos";
+ else if (const char* home = std::getenv("HOME"); home && *home) base = fs::path(home) / ".local/share/doos";
+ else base = fs::temp_directory_path();
+ fs::path scratch = base / "tmp";
+ std::error_code ec;
+ fs::create_directories(scratch, ec);
+ if (ec) scratch = fs::temp_directory_path();
+ std::string tmpl = (scratch / "doos-XXXXXX").string();
+ if (!::mkdtemp(tmpl.data())) throw SysError("mkdtemp");
+ path_ = tmpl;
+ ::chmod(path_.c_str(), 0700);
+}
+
+TempDir::~TempDir() {
+ std::error_code ec;
+ fs::remove_all(path_, ec);
+}
+
+bool isHex64(const std::string& s) {
+ return s.size() == 64 && std::all_of(s.begin(), s.end(), [](unsigned char c) { return std::isxdigit(c); });
+}
+
+namespace {
+std::string upperStr(std::string s) {
+ for (auto& c : s) c = static_cast(std::toupper(static_cast(c)));
+ return s;
+}
+
+// Imports the publisher key from `keyUrl` into a fresh gpg homedir and checks its fingerprint is
+// exactly `fpr`. Returns the gpg binary path, or "" (with a printed note) when gpg is not installed.
+std::string importPinnedKey(const fs::path& homedir, const std::string& keyUrl, const std::string& fpr) {
+ std::string gpg;
+ try {
+ gpg = resolveBinary("gpg");
+ } catch (const std::exception&) {
+ std::fprintf(stderr, "note: signature NOT checked (gpg is not installed); relying on https and the publisher's checksum\n");
+ return "";
+ }
+ ::chmod(homedir.c_str(), 0700);
+ fs::path keyFile = homedir / "key.asc";
+ fetchFile(keyUrl, keyFile);
+ std::string h = homedir.string();
+ if (runProcess({gpg, "--batch", "--quiet", "--homedir", h, "--import", keyFile.string()}, false, true).code != 0) {
+ throw std::runtime_error("cannot import the publisher key from " + keyUrl);
+ }
+ ProcResult fp = runProcess({gpg, "--batch", "--homedir", h, "--with-colons", "--fingerprint"}, true, true);
+ if (fp.out.find(":::::::::" + upperStr(fpr) + ":") == std::string::npos) {
+ throw std::runtime_error("the key at " + keyUrl + " does not have the pinned fingerprint " + fpr);
+ }
+ return gpg;
+}
+
+// Shared GOODSIG/VALIDSIG parsing for both --verify forms (detached and clearsigned produce the
+// same --status-fd protocol lines).
+void requireGoodSignature(const ProcResult& v, const std::string& fpr, const std::string& what) {
+ bool good = false, valid = false;
+ std::istringstream in(v.out);
+ for (std::string line; std::getline(in, line);) {
+ if (line.find("BADSIG") != std::string::npos || line.find("ERRSIG") != std::string::npos ||
+ line.find("EXPKEYSIG") != std::string::npos || line.find("REVKEYSIG") != std::string::npos) {
+ throw std::runtime_error("bad signature on " + what);
+ }
+ if (line.find("[GNUPG:] GOODSIG") == 0) good = true;
+ if (line.find("[GNUPG:] VALIDSIG") == 0) {
+ std::istringstream ls(line);
+ std::vector tok;
+ for (std::string t; ls >> t;) tok.push_back(upperStr(t));
+ if (tok.size() > 2 && (tok[2] == upperStr(fpr) || tok.back() == upperStr(fpr))) valid = true;
+ }
+ }
+ if (v.code != 0 || !good || !valid) {
+ throw std::runtime_error("signature check failed for " + what + " (not signed by " + fpr + ")");
+ }
+ std::fprintf(stderr, "signature verified (key %s)\n", fpr.c_str());
+}
+} // namespace
+
+bool verifyDetachedSignature(const fs::path& data, const fs::path& sig, const std::string& keyUrl, const std::string& fpr) {
+ TempDir home;
+ std::string gpg = importPinnedKey(home.path(), keyUrl, fpr);
+ if (gpg.empty()) return false;
+ ProcResult v = runProcess({gpg, "--batch", "--homedir", home.path().string(), "--status-fd", "1", "--verify",
+ sig.string(), data.string()},
+ true, true);
+ requireGoodSignature(v, fpr, data.filename().string());
+ return true;
+}
+
+bool verifyClearsignedSignature(const fs::path& file, const std::string& keyUrl, const std::string& fpr) {
+ TempDir home;
+ std::string gpg = importPinnedKey(home.path(), keyUrl, fpr);
+ if (gpg.empty()) return false;
+ ProcResult v = runProcess({gpg, "--batch", "--homedir", home.path().string(), "--status-fd", "1", "--verify",
+ file.string()},
+ true, true);
+ requireGoodSignature(v, fpr, file.filename().string());
+ return true;
+}
+
+namespace fsutil {
+
+namespace {
+void mirrorRec(const fs::path& lower, const fs::path& upper, SeedStats& st, std::size_t depth) {
+ if (depth > Caps::kMaxTreeDepth) throw std::runtime_error("tree too deep: " + lower.string());
+ std::error_code ec;
+ fs::directory_iterator it(lower, ec), end;
+ if (ec) { ++st.skipped; return; }
+ for (; it != end; it.increment(ec)) {
+ if (ec) { ++st.skipped; return; }
+ struct stat sb;
+ if (::lstat(it->path().c_str(), &sb) != 0 || !S_ISDIR(sb.st_mode)) continue;
+ if (st.made >= Caps::kMaxSkeletonDirs) throw std::runtime_error("directory skeleton cap reached");
+ fs::path target = upper / it->path().filename();
+ if (::mkdir(target.c_str(), (sb.st_mode & 07777) | 0700) != 0 && errno != EEXIST) {
+ throw SysError("mkdir " + target.string());
+ }
+ ++st.made;
+ mirrorRec(it->path(), target, st, depth + 1);
+ }
+}
+
+void copyRec(const fs::path& from, const fs::path& to, SeedStats& st, std::size_t depth, const SkipFn& skip) {
+ if (depth > Caps::kMaxTreeDepth) throw std::runtime_error("tree too deep: " + from.string());
+ std::error_code ec;
+ int dirfd = ::open(from.c_str(), O_PATH | O_DIRECTORY | O_CLOEXEC);
+ fs::directory_iterator it(from, ec), end;
+ if (ec) { ++st.skipped; if (dirfd >= 0) ::close(dirfd); return; }
+ for (; it != end; it.increment(ec)) {
+ if (ec) { ++st.skipped; continue; }
+ struct stat sb;
+ const fs::path& src = it->path();
+ fs::path dst = to / src.filename();
+ if (::lstat(src.c_str(), &sb) != 0) { ++st.skipped; continue; }
+ if (skip && skip(src)) { ++st.skipped; continue; }
+ if (st.made >= Caps::kMaxEtcCopyFiles) throw std::runtime_error("copy file cap reached: " + from.string());
+ if (S_ISDIR(sb.st_mode)) {
+ if (::mkdir(dst.c_str(), (sb.st_mode & 07777) | 0700) != 0 && errno != EEXIST) {
+ throw SysError("mkdir " + dst.string());
+ }
+ ++st.made;
+ copyRec(src, dst, st, depth + 1, skip);
+ } else if (S_ISLNK(sb.st_mode)) {
+ char buf[4096];
+ ssize_t n = (dirfd >= 0) ? ::readlinkat(dirfd, src.filename().c_str(), buf, sizeof buf - 1) : -1;
+ if (n < 0) { ++st.skipped; continue; }
+ buf[n] = '\0';
+ std::error_code e2;
+ fs::remove(dst, e2);
+ fs::create_symlink(std::string(buf, static_cast(n)), dst);
+ ++st.made;
+ } else if (S_ISREG(sb.st_mode)) {
+ if (::access(src.c_str(), R_OK) != 0) { ++st.skipped; continue; }
+ st.bytes += static_cast(sb.st_size);
+ if (st.bytes > Caps::kMaxEtcCopyBytes) throw std::runtime_error("copy byte cap reached: " + from.string());
+ std::error_code e2;
+ fs::copy_file(src, dst, fs::copy_options::overwrite_existing, e2);
+ if (e2) { ++st.skipped; continue; }
+ ::chmod(dst.c_str(), (sb.st_mode & 07777) | 0600);
+ ++st.made;
+ } else {
+ ++st.skipped;
+ }
+ }
+ if (dirfd >= 0) ::close(dirfd);
+}
+
+struct InodeHash {
+ std::size_t operator()(const std::pair& k) const { return std::hash()(k.first * 1000003UL ^ k.second); }
+};
+using InodeSet = std::unordered_set, InodeHash>;
+
+std::uint64_t usageRec(const fs::path& p, std::size_t& seen, std::size_t& skipped, std::size_t depth, InodeSet& links) {
+ struct stat sb;
+ if (::lstat(p.c_str(), &sb) != 0) { ++skipped; return 0; }
+ std::uint64_t total = static_cast(sb.st_blocks) * 512;
+ if (!S_ISDIR(sb.st_mode)) {
+ // hard links share their blocks: count each inode once
+ if (sb.st_nlink > 1 && !links.insert({sb.st_dev, sb.st_ino}).second) return 0;
+ return total;
+ }
+ if (depth > Caps::kMaxTreeDepth || seen >= Caps::kMaxScanEntries) { ++skipped; return total; }
+ std::error_code ec;
+ fs::directory_iterator it(p, ec), end;
+ if (ec) { ++skipped; return total; }
+ for (; it != end; it.increment(ec)) {
+ if (ec) { ++skipped; break; }
+ ++seen;
+ total += usageRec(it->path(), seen, skipped, depth + 1, links);
+ }
+ return total;
+}
+} // namespace
+
+SeedStats mirrorDirs(const fs::path& lower, const fs::path& upper) {
+ SeedStats st;
+ mkdirs(upper);
+ mirrorRec(lower, upper, st, 0);
+ return st;
+}
+
+SeedStats copyTree(const fs::path& from, const fs::path& to, const SkipFn& skip) {
+ SeedStats st;
+ mkdirs(to);
+ copyRec(from, to, st, 0, skip);
+ return st;
+}
+
+SeedStats copyEntries(const fs::path& from, const fs::path& to, const std::vector& entries,
+ const SkipFn& skip) {
+ SeedStats total;
+ mkdirs(to);
+ for (const auto& e : entries) {
+ fs::path src = from / e, dst = to / e;
+ struct stat sb;
+ if (::lstat(src.c_str(), &sb) != 0) continue; // not present on this host: nothing to copy, nothing skipped
+ if (skip && skip(src)) { ++total.skipped; continue; }
+ mkdirs(dst.parent_path());
+ if (S_ISDIR(sb.st_mode)) {
+ SeedStats s = copyTree(src, dst, skip);
+ total.made += s.made; total.skipped += s.skipped; total.bytes += s.bytes;
+ } else if (S_ISLNK(sb.st_mode)) {
+ fs::path parent = src.parent_path();
+ int pfd = ::open(parent.c_str(), O_PATH | O_DIRECTORY | O_CLOEXEC);
+ char buf[4096];
+ ssize_t n = (pfd >= 0) ? ::readlinkat(pfd, src.filename().c_str(), buf, sizeof buf - 1) : -1;
+ if (pfd >= 0) ::close(pfd);
+ if (n < 0) { ++total.skipped; continue; }
+ buf[n] = '\0';
+ std::error_code ec;
+ fs::remove(dst, ec);
+ fs::create_symlink(std::string(buf, static_cast(n)), dst);
+ ++total.made;
+ } else if (S_ISREG(sb.st_mode) && ::access(src.c_str(), R_OK) == 0) {
+ std::error_code ec;
+ fs::copy_file(src, dst, fs::copy_options::overwrite_existing, ec);
+ if (ec) { ++total.skipped; continue; }
+ ::chmod(dst.c_str(), (sb.st_mode & 07777) | 0600);
+ total.bytes += static_cast(sb.st_size);
+ ++total.made;
+ } else {
+ ++total.skipped;
+ }
+ if (total.bytes > Caps::kMaxEtcCopyBytes) throw std::runtime_error("copy byte cap reached: " + from.string());
+ }
+ return total;
+}
+
+SeedStats copyFiles(const fs::path& from, const fs::path& to) {
+ SeedStats st;
+ std::error_code ec;
+ fs::directory_iterator it(from, ec), end;
+ if (ec) { ++st.skipped; return st; }
+ for (; it != end; it.increment(ec)) {
+ if (ec) { ++st.skipped; break; }
+ struct stat sb;
+ const fs::path& src = it->path();
+ if (::lstat(src.c_str(), &sb) != 0 || !S_ISREG(sb.st_mode)) continue;
+ fs::path dst = to / src.filename();
+ std::error_code e2;
+ if (fs::exists(dst, e2)) continue;
+ if (::access(src.c_str(), R_OK) != 0) { ++st.skipped; continue; }
+ st.bytes += static_cast(sb.st_size);
+ if (st.bytes > Caps::kMaxEtcCopyBytes) throw std::runtime_error("copy byte cap reached: " + from.string());
+ fs::copy_file(src, dst, fs::copy_options::none, e2);
+ if (e2) { ++st.skipped; continue; }
+ ::chmod(dst.c_str(), (sb.st_mode & 07777) | 0600);
+ ++st.made;
+ }
+ return st;
+}
+
+std::uint64_t diskUsage(const fs::path& p, std::size_t& skipped) {
+ std::size_t seen = 0;
+ InodeSet links;
+ return usageRec(p, seen, skipped, 0, links);
+}
+
+void mkdirs(const fs::path& p, mode_t mode) {
+ if (p.empty()) return;
+ std::vector comps;
+ for (const auto& part : p) {
+ std::string s = part.string();
+ if (s.empty() || s == ".") continue;
+ if (s == "..") throw std::runtime_error("mkdir " + p.string() + ": '..' not allowed");
+ comps.push_back(s);
+ }
+ if (comps.empty()) return;
+ bool absolute = p.is_absolute();
+ int base = ::open(absolute ? "/" : ".", O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+ if (base < 0) throw SysError("mkdir " + p.string());
+ Fd guard(base);
+ for (std::size_t i = 0; i < comps.size(); ++i) {
+ bool last = (i + 1 == comps.size());
+ mode_t m = last ? mode : 0755;
+ if (::mkdirat(guard.get(), comps[i].c_str(), m) != 0 && errno != EEXIST) {
+ throw SysError("mkdir " + p.string());
+ }
+ int nfd = ::openat(guard.get(), comps[i].c_str(), O_PATH | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
+ if (nfd < 0) throw SysError("mkdir " + p.string() + " (not a directory or symlink)");
+ guard.reset(nfd);
+ }
+ ::chmod(p.c_str(), mode);
+}
+
+void writeFile(const fs::path& p, const std::string& content) {
+ std::ofstream out(p, std::ios::trunc);
+ if (!out) throw std::runtime_error("cannot write " + p.string());
+ out << content;
+ out.flush();
+ if (!out) throw std::runtime_error("write failed " + p.string());
+}
+
+std::string readFile(const fs::path& p) {
+ std::ifstream in(p);
+ if (!in) throw std::runtime_error("cannot read " + p.string());
+ std::ostringstream ss;
+ ss << in.rdbuf();
+ return ss.str();
+}
+
+void removeTree(const fs::path& p, std::size_t depth) {
+ if (depth > Caps::kMaxTreeDepth) throw std::runtime_error("tree too deep, refusing: " + p.string());
+ std::error_code ec;
+ auto st = fs::symlink_status(p, ec);
+ if (ec) return;
+ if (fs::is_directory(st)) {
+ // overlayfs workdirs are mode 000
+ fs::permissions(p, fs::perms::owner_all, fs::perm_options::add, ec);
+ for (const auto& e : fs::directory_iterator(p)) removeTree(e.path(), depth + 1);
+ }
+ if (::remove(p.c_str()) != 0) throw SysError("remove " + p.string());
+}
+
+std::size_t countEntries(const fs::path& p, std::size_t cap) {
+ std::size_t n = 0;
+ std::error_code ec;
+ for (auto it = fs::recursive_directory_iterator(p, fs::directory_options::skip_permission_denied, ec);
+ !ec && it != fs::recursive_directory_iterator(); it.increment(ec)) {
+ if (++n >= cap) break;
+ }
+ return n;
+}
+
+} // namespace fsutil
+
+std::string resolveBinary(const std::string& name) {
+ if (name.find('/') != std::string::npos) return name;
+ // The state dir's bin/ wins: it is the trusted configuration location (0700, like /etc) and lets tests
+ // or a user override a helper without touching system directories. Never the caller's PATH.
+ std::string base;
+ if (const char* h = ::getenv("DOOS_HOME"); h && *h) base = h;
+ else if (const char* x = ::getenv("XDG_DATA_HOME"); x && *x) base = std::string(x) + "/doos";
+ else if (const char* home = ::getenv("HOME"); home && *home) base = std::string(home) + "/.local/share/doos";
+ if (!base.empty()) {
+ std::string p = base + "/bin/" + name;
+ struct stat st;
+ if (::stat(p.c_str(), &st) == 0 && S_ISREG(st.st_mode) && ::access(p.c_str(), X_OK) == 0) return p;
+ }
+ for (const char* dir : {"/usr/local/bin", "/usr/bin", "/usr/local/sbin", "/usr/sbin", "/bin", "/sbin"}) {
+ std::string p = std::string(dir) + "/" + name;
+ struct stat st;
+ if (::stat(p.c_str(), &st) == 0 && S_ISREG(st.st_mode) && ::access(p.c_str(), X_OK) == 0) return p;
+ }
+ throw std::runtime_error("required helper '" + name +
+ "' not found in the state dir's bin/, /usr/local/bin, /usr/bin, /usr/sbin, /bin or /sbin (install it)");
+}
+
+std::string sanitizeName(const std::string& base, const std::string& suffix) {
+ std::string b;
+ b.reserve(base.size());
+ for (char c : base) {
+ unsigned char u = static_cast(c);
+ if (std::isupper(u)) b += static_cast(std::tolower(u));
+ else if (std::islower(u) || std::isdigit(u) || c == '-' || c == '_') b += c;
+ else b += '-';
+ }
+ if (b.empty() || !(std::islower(static_cast(b[0])) || std::isdigit(static_cast(b[0])))) {
+ b = "c" + b;
+ }
+ std::size_t room = Caps::kMaxNameLen > suffix.size() ? Caps::kMaxNameLen - suffix.size() : 0;
+ if (b.size() > room) b.erase(room);
+ if (b.empty()) b = "c";
+ return b + suffix;
+}
+
+} // namespace molo::doos
diff --git a/src/doos/util.hpp b/src/doos/util.hpp
new file mode 100644
index 0000000..80ac851
--- /dev/null
+++ b/src/doos/util.hpp
@@ -0,0 +1,136 @@
+#pragma once
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+namespace molo::doos {
+
+class SysError : public std::runtime_error {
+public:
+ explicit SysError(const std::string& what, int err = errno);
+ int code() const { return code_; }
+
+private:
+ int code_;
+};
+
+class Fd {
+public:
+ Fd() = default;
+ explicit Fd(int fd) : fd_(fd) {}
+ Fd(Fd&& o) noexcept : fd_(o.release()) {}
+ Fd& operator=(Fd&& o) noexcept;
+ Fd(const Fd&) = delete;
+ Fd& operator=(const Fd&) = delete;
+ ~Fd() { reset(); }
+ int get() const { return fd_; }
+ int release();
+ void reset(int fd = -1);
+ bool valid() const { return fd_ >= 0; }
+
+private:
+ int fd_ = -1;
+};
+
+// flock(2) on a file for the lifetime of the object, bounded wait.
+class FileLock {
+public:
+ FileLock(const std::filesystem::path& file, int timeoutMs);
+ ~FileLock() = default;
+ void unlock() { fd_.reset(); }
+ int fd() const { return fd_.get(); }
+
+private:
+ Fd fd_;
+};
+
+// Parses "512m", "2g", "1t" (k/m/g/t, optional trailing b) into bytes; throws on garbage.
+std::uint64_t parseSize(const std::string& text);
+std::string formatSize(std::uint64_t bytes);
+
+// Lenient on whitespace, throws on bad characters. Deliberately NOT shared
+// with realtime::shared::base64_decode: that one is strict (rejects
+// whitespace, URL-safe alphabet, and unpadded input with nullopt), while this
+// one must stay lenient for publisher payloads. A differential probe over 10
+// input classes agreed on 4 and differed on 6 (see PROVENANCE.md); unifying
+// in either direction would change one side's contract. Keep both.
+std::string base64Decode(const std::string& in);
+
+// Maps an arbitrary base name to a valid container/cgroup name
+// ([a-z0-9][a-z0-9_-]{0,31}): lowercases, invalid chars become '-', first
+// char forced alnum, base truncated so base+suffix fits kMaxNameLen. Never
+// throws, never empty. `suffix` must itself be valid and short ("-3").
+std::string sanitizeName(const std::string& base, const std::string& suffix = "");
+
+struct ProcResult {
+ int code = -1;
+ std::string out; // stdout, only when captured
+};
+// fork+exec without a shell. Captured output is capped; stderr is inherited unless quiet.
+ProcResult runProcess(const std::vector& argv, bool capture = false, bool quiet = false);
+
+// https-only fetch via curl (resolveBinary("curl")); throws on a non-2xx result or a transfer error.
+std::string fetchText(const std::string& url);
+void fetchFile(const std::string& url, const std::filesystem::path& out, std::uint64_t maxBytes = 1 << 20);
+
+// Private scratch directory under the state dir's tmp/ (falls back to the system temp dir),
+// removed on scope exit. Used for anything downloaded and verified before it is trusted.
+class TempDir {
+public:
+ TempDir();
+ ~TempDir();
+ TempDir(const TempDir&) = delete;
+ TempDir& operator=(const TempDir&) = delete;
+ const std::filesystem::path& path() const { return path_; }
+
+private:
+ std::filesystem::path path_;
+};
+
+bool isHex64(const std::string& s);
+
+// Verifies a detached signature (sig is a separate file from data) against a publisher key fetched
+// over https and accepted only when its fingerprint equals the pinned one. Returns false (and prints
+// a note) when gpg is not installed; throws when the signature is bad, missing, or by another key.
+bool verifyDetachedSignature(const std::filesystem::path& data, const std::filesystem::path& sig,
+ const std::string& keyUrl, const std::string& fpr);
+// Same, for a clearsigned single file (hashes and signature combined in one file, e.g. rclone's
+// SHA256SUMS release artifact).
+bool verifyClearsignedSignature(const std::filesystem::path& file, const std::string& keyUrl, const std::string& fpr);
+
+namespace fsutil {
+struct SeedStats {
+ std::size_t made = 0;
+ std::size_t skipped = 0; // unreadable or unsupported entries, never silent
+ std::uint64_t bytes = 0;
+};
+// Creates every directory of `lower` in `upper` (owner rwx added) so a unmapped-owner lower stays writable.
+SeedStats mirrorDirs(const std::filesystem::path& lower, const std::filesystem::path& upper);
+// Copies dirs, regular files and symlinks readable by the caller. Capped by spec.hpp limits.
+// `skip` (optional) is asked for every entry and returns true to leave it out (counted as skipped).
+using SkipFn = std::function;
+SeedStats copyTree(const std::filesystem::path& from, const std::filesystem::path& to, const SkipFn& skip = nullptr);
+// Copies only the named entries (relative paths, files, links or dirs) of `from` into `to`.
+SeedStats copyEntries(const std::filesystem::path& from, const std::filesystem::path& to,
+ const std::vector& entries, const SkipFn& skip);
+// Copies only the regular files directly inside `from` (readable ones) into `to`; existing targets stay.
+SeedStats copyFiles(const std::filesystem::path& from, const std::filesystem::path& to);
+// Sum of allocated bytes (st_blocks) below p, lstat only. `skipped` counts unreadable dirs.
+std::uint64_t diskUsage(const std::filesystem::path& p, std::size_t& skipped);
+void mkdirs(const std::filesystem::path& p, mode_t mode = 0755);
+void writeFile(const std::filesystem::path& p, const std::string& content);
+std::string readFile(const std::filesystem::path& p);
+// Removes a tree without following symlinks; bounded depth.
+void removeTree(const std::filesystem::path& p, std::size_t depth = 0);
+std::size_t countEntries(const std::filesystem::path& p, std::size_t cap);
+} // namespace fsutil
+
+// Resolves an external helper binary against a fixed set of trusted directories
+// (never the caller's PATH), throwing when it is not found.
+std::string resolveBinary(const std::string& name);
+
+} // namespace molo::doos
diff --git a/src/doos/valgrind/README.md b/src/doos/valgrind/README.md
new file mode 100644
index 0000000..87a831a
--- /dev/null
+++ b/src/doos/valgrind/README.md
@@ -0,0 +1,62 @@
+# valgrind
+
+**Scope:** [README](../README.md) · [AGENTS](../AGENTS.md) · [docs/RESEARCH](../docs/RESEARCH.md)
+
+Memcheck run against a fixed, named set of `doos` invocations, to catch real memory bugs
+(invalid reads/writes, use-after-free, definite leaks) in doos's own code: namespace setup,
+mount handling, the CLI, the image store. Separate from `audit/` (named CVEs against other
+software) and from `tests/run.sh` (behavior, not memory safety).
+
+## Running it
+
+```
+make valgrind # builds build/doos first, then runs scripts/valgrind.sh against it
+scripts/valgrind.sh PATH # run directly against a specific binary, e.g. a copy with an
+ # installed AppArmor profile (see README's apparmor section)
+```
+
+Reports land in `build/valgrind-reports/.log`, one per invocation, kept (not deleted)
+after the run so a failure can be inspected. Each step prints `ok` or `FAIL`; the run exits
+non-zero only if valgrind itself flagged something, never because `doos` exited non-zero for
+its own reasons (an expected `delete` dry-run notice, an AppArmor block on a binary with no
+profile installed, and so on, all exit non-zero as designed and are not memory bugs).
+
+## What it checks
+
+A fixed, capped list (`scripts/valgrind.sh`): `list`, `get_or_create`, `attach` (twice, to
+exercise both the create path and joining an already-running container), `image list`,
+`delete --yes`. All run with `--net none` and no image, so the check needs no network and no
+download; it is about doos's own allocation code, not about what happens after it execs the
+contained command.
+
+## Suppressions (`doos.supp`)
+
+Six specific, named, commented allocation sites, each captured with
+`valgrind --gen-suppressions=all` against a real run and explained in the file itself: the
+clone(2) child's 1 MiB stack buffer (lifetime tied to the child process, not a scope), and five
+"an error path constructed an exception or opened a stream, then the namespace child exited
+right after" patterns (`doMount`'s thrown `SysError`'s message string and the exception object
+itself, once for a mount failure inside `setupRoot` and once for the mount that runs directly in
+`containerInit` before it, such as an AppArmor-blocked `mount bind /`; plus an `ifstream` opened
+in `containerInit`'s cold path). None of these are "definitely lost"; valgrind calls all of them
+"possibly lost" because the process ends before the normal C++ unwind would run their
+destructors, which is expected for a namespace child that is about to disappear regardless. A
+genuinely new leak anywhere else is not covered by these exact stacks and still fails the check.
+
+To add a suppression for a new, understood, one-time allocation: reproduce it, add
+`--gen-suppressions=all` to the `valgrind` invocation in `scripts/valgrind.sh` temporarily, copy
+the exact block `doos.supp` already prints into the file with a name and a comment explaining
+why it is not a real leak, then remove the temporary flag. Never add a suppression you cannot
+explain in one sentence.
+
+## What this does not cover
+
+- Anything that happens after doos execs the user's command: valgrind traces doos's own process
+ tree, not an arbitrary program run inside the container.
+- Image download and extraction (`--image`): not in the fixed list, since it needs network and
+ adds `curl`/`tar`/`gpg` subprocess noise that is not doos's own memory. Add a step to
+ `scripts/valgrind.sh` following the same pattern if that code path needs a dedicated run.
+- `slirp4netns`/`pasta`: separate processes, not doos; see `audit/CVE-2020-7039` for how their
+ memory safety is tracked instead (upstream version, not valgrind).
+
+Back to [README](../README.md), [AGENTS](../AGENTS.md), [docs/RESEARCH](../docs/RESEARCH.md).
diff --git a/src/doos/valgrind/doos.supp b/src/doos/valgrind/doos.supp
new file mode 100644
index 0000000..90e0e64
--- /dev/null
+++ b/src/doos/valgrind/doos.supp
@@ -0,0 +1,105 @@
+# Suppressions for `make valgrind` (see scripts/valgrind.sh and valgrind/README.md).
+#
+# Each entry here is a specific, named allocation site, not a blanket "ignore leaks" rule, and
+# each one is explained. They were captured with `valgrind --gen-suppressions=all` against a
+# real `doos attach` run and trimmed to the exact stack valgrind printed; a new, different leak
+# anywhere else still fails the check. Regenerate a candidate block with
+# `valgrind --gen-suppressions=all` if doos's internals change and one of these stops matching.
+
+{
+ doos-clone-child-stack
+ # Sandbox::start allocates the 1 MiB stack clone(2) needs for the namespace child. Its
+ # lifetime is tied to that child process, not to a scope in the parent, so it is never
+ # `delete[]`d: freeing it after clone() returns would be safe only once the child has copied
+ # what it needs, and doing that bookkeeping would add a second code path purely to silence
+ # a tool, not to fix a real leak. Confirmed "possibly lost", never "definitely lost".
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:_Znwm
+ fun:_ZN4doos7Sandbox5startERNS_8FileLockE
+ fun:_ZN4doos7Sandbox3runEv
+ fun:_ZN4doos3Cli9cmdAttachESt6vectorINSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEESaIS7_EE
+ fun:_ZN4doos3Cli3runEv
+ fun:main
+}
+
+{
+ doos-mount-error-exception-object
+ # doMount's cold (error) path throws a SysError built from a std::string; when the namespace
+ # child terminates right after printing that error, the in-flight exception object itself
+ # (allocated by __cxa_allocate_exception) has not yet been destroyed by the unwinder. This is
+ # the standard valgrind artifact for a C++ exception that is still alive when the process
+ # exits, not a missing `delete`.
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:malloc
+ fun:__cxa_allocate_exception
+ fun:_ZN4doos12_GLOBAL__N_1L7doMountEPKcRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEES2_mSA_.isra.0.cold
+ fun:_ZN4doos12_GLOBAL__N_1L9setupRootERKNS_9ContainerERKNSt10filesystem7__cxx114pathE
+ fun:_ZN4doos12_GLOBAL__N_1L13containerInitEPv
+ fun:clone
+}
+
+{
+ doos-mount-error-message-string
+ # Same doMount error path: the message string's internal buffer, built while constructing
+ # the SysError/runtime_error that is about to be thrown. Same explanation as
+ # doos-mount-error-exception-object, one frame earlier in the chain.
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:_Znwm
+ fun:_ZNSs4_Rep9_S_createEmmRKSaIcE
+ fun:_ZNSt12__cow_stringC2EPKcm
+ fun:_ZNSt13runtime_errorC1ERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE
+ fun:_ZN4doos8SysErrorC1ERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEEi
+ fun:_ZN4doos12_GLOBAL__N_1L7doMountEPKcRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEES2_mSA_.isra.0.cold
+ fun:_ZN4doos12_GLOBAL__N_1L9setupRootERKNS_9ContainerERKNSt10filesystem7__cxx114pathE
+ fun:_ZN4doos12_GLOBAL__N_1L13containerInitEPv
+ fun:clone
+}
+
+{
+ doos-mount-error-exception-object-top-level
+ # Same explanation as doos-mount-error-exception-object, for the mount call that runs
+ # directly in containerInit before setupRoot is reached (the very first "mount bind /",
+ # which is what fails when AppArmor blocks user namespaces for this binary's path).
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:malloc
+ fun:__cxa_allocate_exception
+ fun:_ZN4doos12_GLOBAL__N_1L7doMountEPKcRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEES2_mSA_.isra.0.cold
+ fun:_ZN4doos12_GLOBAL__N_1L13containerInitEPv
+ fun:clone
+}
+
+{
+ doos-mount-error-message-string-top-level
+ # Same explanation as doos-mount-error-message-string, one level up: the mount call that
+ # runs directly in containerInit before setupRoot is reached.
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:_Znwm
+ fun:_ZNSs4_Rep9_S_createEmmRKSaIcE
+ fun:_ZNSt12__cow_stringC2EPKcm
+ fun:_ZNSt13runtime_errorC1ERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE
+ fun:_ZN4doos8SysErrorC1ERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEEi
+ fun:_ZN4doos12_GLOBAL__N_1L7doMountEPKcRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEES2_mSA_.isra.0.cold
+ fun:_ZN4doos12_GLOBAL__N_1L13containerInitEPv
+ fun:clone
+}
+
+{
+ doos-containerinit-ifstream-buffer
+ # containerInit's cold (error) path opens an ifstream (a /proc file, for a diagnostic) whose
+ # libstdc++ filebuf buffer is still open when the namespace child exits right after. Same
+ # "process exited before an RAII object on an about-to-unwind error path ran its destructor"
+ # pattern as the two entries above, for a stream instead of an exception.
+ Memcheck:Leak
+ match-leak-kinds: possible
+ fun:_Znam
+ fun:_ZNSt13basic_filebufIcSt11char_traitsIcEE27_M_allocate_internal_bufferEv
+ fun:_ZNSt13basic_filebufIcSt11char_traitsIcEE4openEPKcSt13_Ios_Openmode
+ fun:_ZNSt14basic_ifstreamIcSt11char_traitsIcEEC1EPKcSt13_Ios_Openmode
+ fun:_ZN4doos12_GLOBAL__N_1L13containerInitEPv.cold
+ fun:clone
+}
diff --git a/src/runtime/http/connection.cpp b/src/runtime/http/connection.cpp
index d8cdedc..edc211a 100644
--- a/src/runtime/http/connection.cpp
+++ b/src/runtime/http/connection.cpp
@@ -553,7 +553,9 @@ Task Connection::RunH1() {
req.is_tls = tls_ && tls_->is_tls();
req.peer = transport_->peer();
req.protocol = "HTTP/1.1";
- bool keep = parser.keep_alive() && !draining_;
+ // The last request a connection may serve announces the close.
+ bool keep = parser.keep_alive() && !draining_ &&
+ requests_ + 1 < config_.max_requests;
// Handler soft budget: the timer closes the transport so stuck handlers
// fail fast; the result is discarded when over budget.
budget_exceeded_ = false;
diff --git a/src/runtime/http/listener.cpp b/src/runtime/http/listener.cpp
index a3c6941..9ad3de6 100644
--- a/src/runtime/http/listener.cpp
+++ b/src/runtime/http/listener.cpp
@@ -158,7 +158,8 @@ void Listener::OnReadable() {
std::string peer = std::string(host) + ":" + std::to_string(cport);
std::size_t cap = max_connections_;
if (cap > caps::kMaxConnectionsCeiling) cap = caps::kMaxConnectionsCeiling;
- if (LiveCount() >= cap) {
+ // Prune only once the table could hit the cap: LiveCount is O(tracked).
+ if (tracked_.size() >= cap && LiveCount() >= cap) {
++refused_;
MOLO_RUNTIME_COUNT("runtime.accept_refused");
close(cfd);
diff --git a/src/runtime/http/v1/serializer.cpp b/src/runtime/http/v1/serializer.cpp
index 33220b8..6821343 100644
--- a/src/runtime/http/v1/serializer.cpp
+++ b/src/runtime/http/v1/serializer.cpp
@@ -61,8 +61,13 @@ std::string Serializer::SerializeHead(const ResponseHead& head,
out.append("\r\n");
}
}
- if (!has_connection && (close || version == "HTTP/1.0")) {
- out.append("connection: close\r\n");
+ if (!has_connection) {
+ if (close) {
+ out.append("connection: close\r\n");
+ } else if (version == "HTTP/1.0") {
+ // HTTP/1.0 persists only when the response says so (RFC 9112 9.3).
+ out.append("connection: keep-alive\r\n");
+ }
}
out.append("\r\n");
return out;
diff --git a/src/supervisor/TOPOLOGY.md b/src/supervisor/TOPOLOGY.md
index db484d2..27cee4f 100644
--- a/src/supervisor/TOPOLOGY.md
+++ b/src/supervisor/TOPOLOGY.md
@@ -87,8 +87,10 @@ the queue dedupes them and no duplicate run happens.
the program, SIGTERM then SIGKILL after a grace on stop, and the child
gets a parent-death SIGTERM so it never outlives the supervisor, even
on SIGKILL of the parent. Restarts, backoff, and intensity caps come
- from the owning `WorkerGroup` like any other worker. Gap: no
- per-process resource limits (rlimit/cgroup) yet.
+ from the owning `WorkerGroup` like any other worker. Optional
+ per-process limits ride on `ProcessSpec::isolation` (doos-backed cgroup
+ v2 plus pre-exec hardening, all-or-nothing); null runs unenclosed, as
+ before. Remaining gap: no plain rlimit-only mode without the doos part.
- In-house backends only; no Redis-protocol compatibility (O7-1).
- At-least-once everywhere; no exactly-once primitive (O7-3). Handlers
must be idempotent (R7-2).
diff --git a/src/supervisor/common/isolation_backend.hpp b/src/supervisor/common/isolation_backend.hpp
new file mode 100644
index 0000000..f7064e9
--- /dev/null
+++ b/src/supervisor/common/isolation_backend.hpp
@@ -0,0 +1,42 @@
+#pragma once
+
+// Optional per-process isolation for supervised OS programs. Implemented by
+// the doos part (doos/seam/isolation.hpp); null by default, in which case
+// supervised processes run exactly as before. This header is dependency-free
+// so the supervisor links without doos (dependency inversion, same shape as
+// the ISupervisorControl seam the CLI drives).
+
+#include
+#include
+#include
+
+namespace molo::supervisor {
+
+struct IsolationSpec {
+ std::uint64_t memory_bytes = 0; // 0 = no limit
+ std::uint32_t pids = 0; // 0 = no limit
+ std::uint32_t milli_cpus = 0; // 0 = all cores
+ bool hardening = false; // capability drop + seccomp before exec
+};
+
+class IIsolationBackend {
+ public:
+ IIsolationBackend() = default;
+ virtual ~IIsolationBackend() = default;
+ IIsolationBackend(const IIsolationBackend&) = delete;
+ IIsolationBackend& operator=(const IIsolationBackend&) = delete;
+
+ // Parent side, after fork: attach limits to `child`. False plus a reason
+ // when limits cannot be enforced; the caller stops the child and reports
+ // instead of running degraded. All-or-nothing: partial limits refuse.
+ virtual bool attach(pid_t child, const IsolationSpec& spec, std::string& reason) = 0;
+
+ // Child side, pre-exec: apply in-process confinement. 0 on success, an
+ // exit code (126) when setup failed. Must be fork-safe (no locks, no
+ // iostream); prints its own reason to stderr on failure. The doos backend
+ // enters its own user namespace first when hardening, since dropping
+ // capabilities needs caps the child only holds there.
+ virtual int confine(const IsolationSpec& spec) = 0;
+};
+
+} // namespace molo::supervisor
diff --git a/src/supervisor/supervisor/process_work.cpp b/src/supervisor/supervisor/process_work.cpp
index 7c9a7dc..86eb269 100644
--- a/src/supervisor/supervisor/process_work.cpp
+++ b/src/supervisor/supervisor/process_work.cpp
@@ -6,6 +6,7 @@
#include
#include
+#include
#include
#include "supervisor/common/caps.hpp"
@@ -70,11 +71,30 @@ WorkFunc make_process_work(ProcessSpec spec) {
if (getppid() != parent) {
_exit(1); // parent already gone
}
+ if (spec.isolation) {
+ int irc = spec.isolation->confine(spec.isolation_spec);
+ if (irc != 0) _exit(irc); // 126: isolation setup failed
+ }
execvp(args[0], args.data());
_exit(127);
}
setpgid(pid, pid); // also from the parent side, avoids the exec race
+ if (spec.isolation) {
+ std::string reason;
+ if (!spec.isolation->attach(pid, spec.isolation_spec, reason)) {
+ int status = 0;
+ if (::waitpid(pid, &status, WNOHANG) == pid) {
+ return decode(status); // child already exited: keep its true code
+ }
+ std::fprintf(stderr, "supervisor: isolation attach failed for '%s': %s; child not started\n",
+ spec.argv[0].c_str(), reason.c_str());
+ ::kill(pid, SIGKILL); // the child itself: always correct, no group race
+ terminate(pid, grace);
+ return 1;
+ }
+ }
+
int status = 0;
while (true) {
if (stop.load()) {
diff --git a/src/supervisor/supervisor/process_work.hpp b/src/supervisor/supervisor/process_work.hpp
index b673a56..666893f 100644
--- a/src/supervisor/supervisor/process_work.hpp
+++ b/src/supervisor/supervisor/process_work.hpp
@@ -1,8 +1,10 @@
#pragma once
+#include
#include
#include
+#include "supervisor/common/isolation_backend.hpp"
#include "supervisor/supervisor/worker_process.hpp"
namespace molo::supervisor {
@@ -11,6 +13,11 @@ namespace molo::supervisor {
struct ProcessSpec {
std::vector argv; // 1..Caps::kProcessArgvMax entries
long stop_grace_ms = 0; // 0 means Caps::kProcessStopGraceMs
+ // Optional isolation (doos-backed). Null runs unenclosed, exactly as
+ // before; set runs the child under the spec, failing loudly instead of
+ // running degraded when limits cannot attach.
+ std::shared_ptr isolation = nullptr;
+ IsolationSpec isolation_spec = IsolationSpec{};
};
// Returns a WorkFunc that runs the program as a child process and blocks
@@ -19,7 +26,8 @@ struct ProcessSpec {
// the child is always reaped before the WorkFunc returns.
// - parent death (even SIGKILL): the child receives SIGTERM (Linux).
// - exit code: the child's code, 128+signal when killed by a signal, 127
-// when exec fails, 1 on invalid spec or fork failure, 0 after a
+// when exec fails, 126 when isolation setup failed in the child, 1 on
+// invalid spec, fork failure, or refused isolation attach, 0 after a
// requested stop. WorkerGroup applies restart policy and backoff.
WorkFunc make_process_work(ProcessSpec spec);
diff --git a/tests/example/doos/create_test.cpp b/tests/example/doos/create_test.cpp
new file mode 100644
index 0000000..ede75ea
--- /dev/null
+++ b/tests/example/doos/create_test.cpp
@@ -0,0 +1,33 @@
+// Route: POST /doos/create (idempotent create with options)
+#include "support/Assert.hpp"
+#include "support/DoosHome.hpp"
+
+using namespace molo::example::test;
+
+int main() {
+ ScratchDoosHome home("create");
+ Fixture f;
+ auto first = f.client->post("/doos/create", "name=app1&size=1g",
+ "application/x-www-form-urlencoded");
+ check(first.status == 200, "status 200");
+ check(contains(first.body, "\"created\":true"), "first create reports created");
+ auto again = f.client->post("/doos/create", "name=app1", "application/x-www-form-urlencoded");
+ check(contains(again.body, "\"created\":false"), "second create is idempotent");
+ auto noname = f.client->post("/doos/create", "size=1g", "application/x-www-form-urlencoded");
+ check(noname.status == 422, "missing name rejected");
+ auto badname = f.client->post("/doos/create", "name=Bad+Name",
+ "application/x-www-form-urlencoded");
+ check(badname.status == 422, "bad name rejected");
+ auto badsize = f.client->post("/doos/create", "name=app2&size=1x",
+ "application/x-www-form-urlencoded");
+ check(badsize.status == 422, "bad size rejected");
+ auto badnet = f.client->post("/doos/create", "name=app2&net=bogus",
+ "application/x-www-form-urlencoded");
+ check(badnet.status == 422, "bad net rejected");
+ auto multi = f.client->post("/doos/create", "size=1x&net=bogus",
+ "application/x-www-form-urlencoded");
+ check(multi.status == 422, "multi-failure is 422");
+ check(contains(multi.body, "name is required"), "all failures listed (name)");
+ check(contains(multi.body, "invalid size"), "all failures listed (size)");
+ return finish("doos/create");
+}
diff --git a/tests/example/doos/delete_test.cpp b/tests/example/doos/delete_test.cpp
new file mode 100644
index 0000000..c3839eb
--- /dev/null
+++ b/tests/example/doos/delete_test.cpp
@@ -0,0 +1,29 @@
+// Route: POST /doos/delete (dry run unless confirm=yes)
+#include "support/Assert.hpp"
+#include "support/DoosHome.hpp"
+
+using namespace molo::example::test;
+
+int main() {
+ ScratchDoosHome home("delete");
+ Fixture f;
+ auto made = f.client->post("/doos/create", "name=temp1", "application/x-www-form-urlencoded");
+ check(made.status == 200, "create 200");
+ auto dry = f.client->post("/doos/delete", "name=temp1", "application/x-www-form-urlencoded");
+ check(dry.status == 200, "dry run 200");
+ check(contains(dry.body, "\"dry_run\":true"), "dry run without confirm");
+ check(contains(dry.body, "dry run"), "report text");
+ auto still = f.client->get("/doos/status");
+ check(contains(still.body, "\"name\":\"temp1\""), "dry run deletes nothing");
+ auto gone = f.client->post("/doos/delete", "name=temp1&confirm=yes",
+ "application/x-www-form-urlencoded");
+ check(contains(gone.body, "\"dry_run\":false"), "confirm deletes");
+ auto after = f.client->get("/doos/status");
+ check(!contains(after.body, "\"name\":\"temp1\""), "container gone after confirm");
+ auto missing = f.client->post("/doos/delete", "name=temp1&confirm=yes",
+ "application/x-www-form-urlencoded");
+ check(missing.status == 404, "missing container is 404");
+ auto noname = f.client->post("/doos/delete", "confirm=yes", "application/x-www-form-urlencoded");
+ check(noname.status == 422, "missing name rejected");
+ return finish("doos/delete");
+}
diff --git a/tests/example/doos/page_test.cpp b/tests/example/doos/page_test.cpp
new file mode 100644
index 0000000..09b31f2
--- /dev/null
+++ b/tests/example/doos/page_test.cpp
@@ -0,0 +1,20 @@
+// Route: GET /doos (sandboxed containers page)
+#include "support/Assert.hpp"
+#include "support/DoosHome.hpp"
+
+using namespace molo::example::test;
+
+int main() {
+ ScratchDoosHome home("page");
+ Fixture f;
+ auto res = f.client->get("/doos");
+ check(res.status == 200, "status 200");
+ check(contains(res.body, "Sandboxed containers"), "heading");
+ check(contains(res.body, "0 containers"), "empty demo store");
+ auto made = f.client->post("/doos/create", "name=web1", "application/x-www-form-urlencoded");
+ check(made.status == 200, "create 200");
+ auto again = f.client->get("/doos");
+ check(contains(again.body, "1 containers"), "count follows creates");
+ check(contains(again.body, "web1"), "row names the container");
+ return finish("doos/page");
+}
diff --git a/tests/example/doos/status_test.cpp b/tests/example/doos/status_test.cpp
new file mode 100644
index 0000000..82eea55
--- /dev/null
+++ b/tests/example/doos/status_test.cpp
@@ -0,0 +1,21 @@
+// Route: GET /doos/status (containers, images, davmounts, version)
+#include "support/Assert.hpp"
+#include "support/DoosHome.hpp"
+
+using namespace molo::example::test;
+
+int main() {
+ ScratchDoosHome home("status");
+ Fixture f;
+ auto res = f.client->get("/doos/status");
+ check(res.status == 200, "status 200");
+ check(contains(res.body, "\"containers\":[]"), "no containers yet");
+ check(contains(res.body, "\"davmounts\":[]"), "no davmounts yet");
+ check(contains(res.body, "\"version\":\"1.6.0\""), "libdoos version");
+ check(contains(res.body, "\"name\":\"alpine\""), "catalog lists alpine");
+ auto made = f.client->post("/doos/create", "name=db1", "application/x-www-form-urlencoded");
+ check(made.status == 200, "create 200");
+ auto after = f.client->get("/doos/status");
+ check(contains(after.body, "\"name\":\"db1\""), "status shows the container");
+ return finish("doos/status");
+}
diff --git a/tests/example/index_test.cpp b/tests/example/index_test.cpp
index 937aa8e..1da53db 100644
--- a/tests/example/index_test.cpp
+++ b/tests/example/index_test.cpp
@@ -13,6 +13,14 @@ int main() {
check(contains(res.body, "/routing/hello/world"), "matrix links a route");
check(contains(res.body, "viewport"), "responsive viewport meta");
check(contains(res.body, "nav-narrow"), "narrow nav dropdown present");
+ check(contains(res.body, "id=\"g-routing\""), "routing group section");
+ check(contains(res.body, "id=\"g-vendors\""), "vendor group section");
+ check(contains(res.body, "needs API key"), "key badge on credentialed groups");
+ check(contains(res.body, "id=\"filter\""), "filter box");
+ check(contains(res.body, "Routing"),
+ "row shows a readable name linking the route");
+ check(contains(res.body, "AI OpenAI"), "acronyms prettified");
+ check(!contains(res.body, "g-other"), "every registered route is grouped");
check(res.headers.has("X-Request-ID"), "request id middleware ran");
return finish("index");
}
diff --git a/tests/example/support/DoosHome.hpp b/tests/example/support/DoosHome.hpp
new file mode 100644
index 0000000..b79531e
--- /dev/null
+++ b/tests/example/support/DoosHome.hpp
@@ -0,0 +1,30 @@
+#pragma once
+// Scratch DOOS_HOME for the /doos route tests: a unique dir under the system
+// temp root (the example suite points TMPDIR at build/example/tmp), exported
+// before the Fixture builds the app, removed on teardown.
+#include
+
+#include
+#include
+
+namespace molo::example::test {
+
+struct ScratchDoosHome {
+ std::filesystem::path dir;
+ explicit ScratchDoosHome(const std::string& tag) {
+ static int seq = 0;
+ dir = std::filesystem::temp_directory_path() /
+ ("molo-doos-route-" + tag + "-" + std::to_string(::getpid()) + "-" +
+ std::to_string(seq++));
+ std::error_code ec;
+ std::filesystem::remove_all(dir, ec);
+ std::filesystem::create_directories(dir, ec);
+ ::setenv("DOOS_HOME", dir.c_str(), 1);
+ }
+ ~ScratchDoosHome() {
+ std::error_code ec;
+ std::filesystem::remove_all(dir, ec);
+ }
+};
+
+} // namespace molo::example::test
diff --git a/tests/src/cli/test_cli_binary.sh b/tests/src/cli/test_cli_binary.sh
index 275c1f2..638a23a 100755
--- a/tests/src/cli/test_cli_binary.sh
+++ b/tests/src/cli/test_cli_binary.sh
@@ -83,4 +83,36 @@ grep -q "Hi!" "$TMP/ai.txt" || fail "ai transcript assembled"
kill $SRV 2>/dev/null
pass "ai stub streaming"
+# `molo doos`: thin front end over libdoos on a scratch store (hermetic: no
+# namespaces, no network; attach needs them and stays in doos-live).
+export DOOS_HOME="$TMP/doos-home"
+"$MOLO" doos --help >/dev/null 2>&1 || fail "molo doos --help exits 0"
+"$MOLO" help doos | grep -q "rootless" || fail "molo help doos page"
+"$MOLO" doos list | grep -q "no containers" || fail "molo doos list empty"
+"$MOLO" doos list --format json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert d["ok"] and d["containers"]==[]' || fail "molo doos list json parses"
+"$MOLO" doos version --format json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert d["ok"] and d["version"]=="1.6.0"' || fail "molo doos version json"
+"$MOLO" doos image list --format json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert any(i["name"]=="alpine" for i in d["images"])' || fail "molo doos image list json"
+"$MOLO" doos get_or_create cli1 | grep -q "created cli1" || fail "molo doos get_or_create"
+"$MOLO" doos get_or_create cli1 | grep -q "exists cli1" || fail "molo doos get_or_create idempotent"
+"$MOLO" doos delete cli1 | grep -q "dry run" || fail "molo doos delete dry-runs"
+"$MOLO" doos delete --yes cli1 | grep -q "deleted cli1" || fail "molo doos delete --yes"
+"$MOLO" doos get_or_create 'Bad Name' >/dev/null 2>&1 && fail "bad name must fail"
+[ "$("$MOLO" doos get_or_create 'Bad Name' >/dev/null 2>&1; echo $?)" = "1" ] || fail "bad name exits 1"
+[ "$("$MOLO" doos nosuch >/dev/null 2>&1; echo $?)" = "2" ] || fail "unknown doos command exits 2"
+"$MOLO" doos attach cli1 --format json >"$TMP/aj.json" 2>/dev/null; [ "$?" = "2" ] || fail "attach json refused with 2"
+python3 -c 'import json; d=json.load(open("'"$TMP"'/aj.json")); assert d["ok"] is False' || fail "attach json error parses"
+pass "molo doos front end"
+
+# Help suffix contract (help_renderer prepends "prog path"): usage() and
+# example() take suffixes, never full "molo ..." paths, or the page doubles.
+"$MOLO" doos --help | grep -q "molo molo" && fail "doos --help doubled"
+"$MOLO" help doos | grep -q "molo molo" && fail "help doos doubled"
+"$MOLO" help doos | grep -q "apparmor|version|image" || fail "doos usage lists version"
+"$MOLO" doos list --help | grep -q "^ molo doos list$" || fail "list usage exact"
+"$MOLO" doos attach --help | grep -q "^ molo doos attach \[OPTIONS\] NAME" || fail "attach usage exact"
+"$MOLO" verify --help | grep -q "molo molo\|molo verify molo" && fail "verify help doubled"
+"$MOLO" supply-check --help | grep -q "molo molo\|supply-check molo" && fail "supply-check help doubled"
+"$MOLO" release --help | grep -q "molo molo\|molo release molo" && fail "release help doubled"
+pass "help suffix contract"
+
echo "ALL_BINARY_OK"
diff --git a/tests/src/cli/test_serve.cpp b/tests/src/cli/test_serve.cpp
new file mode 100644
index 0000000..9a3a26c
--- /dev/null
+++ b/tests/src/cli/test_serve.cpp
@@ -0,0 +1,99 @@
+// molo serve: the port really accepts HTTP, ops paths answer, assets are
+// served, a second server on the same port is refused, shutdown is clean.
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include "cli/exit_code.hpp"
+#include "cli/output.hpp"
+#include "dev/dev_server.hpp"
+
+#define CHECK(cond, label) \
+ do { \
+ if (!(cond)) { \
+ std::cerr << "FAIL: " << label << "\n"; \
+ return 1; \
+ } \
+ std::cout << "PASS: " << label << "\n"; \
+ } while (0)
+
+namespace {
+int free_port() {
+ int fd = ::socket(AF_INET, SOCK_STREAM, 0);
+ sockaddr_in a{};
+ a.sin_family = AF_INET;
+ a.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+ ::bind(fd, reinterpret_cast(&a), sizeof(a));
+ socklen_t len = sizeof(a);
+ getsockname(fd, reinterpret_cast(&a), &len);
+ int port = ntohs(a.sin_port);
+ ::close(fd);
+ return port;
+}
+
+std::string get(int port, const std::string& path) {
+ for (int i = 0; i < 100; ++i) {
+ int fd = ::socket(AF_INET, SOCK_STREAM, 0);
+ sockaddr_in a{};
+ a.sin_family = AF_INET;
+ a.sin_port = htons(static_cast(port));
+ a.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+ if (::connect(fd, reinterpret_cast(&a), sizeof(a)) == 0) {
+ std::string req = "GET " + path + " HTTP/1.1\r\nHost: x\r\nConnection: close\r\n\r\n";
+ (void)!::write(fd, req.data(), req.size());
+ std::string resp;
+ char buf[4096];
+ ssize_t n;
+ while ((n = ::read(fd, buf, sizeof(buf))) > 0) resp.append(buf, static_cast(n));
+ ::close(fd);
+ return resp;
+ }
+ ::close(fd);
+ std::this_thread::sleep_for(std::chrono::milliseconds(50));
+ }
+ return "";
+}
+} // namespace
+
+int main() {
+ namespace fs = std::filesystem;
+ fs::path dir = fs::temp_directory_path() / "molo-serve-test";
+ fs::remove_all(dir);
+ fs::create_directories(dir / "assets");
+ { std::ofstream(dir / "assets" / "index.html") << "