phoebus_os/docs/AGENTIC-HARDENING.md
2026-10-12 04:27:15 -07:00

104 lines
7.9 KiB
Markdown

# Agentic boundary hardening — 2026-10-12
The implementation review identified seven concrete gaps. All seven have code
changes and regression coverage. Native package and sandbox acceptance passed on an installed-system overlay;
a fresh installer run remains pending. This is not a new ISO release.
| Gap | Implemented change | Evidence |
| --- | --- | --- |
| Raw OpenCode provider credentials entered logs before catalog parsing | Sensitive output suppresses both streaming sinks, logged bodies and attached command failure bodies; curl ignores user configuration | Unknown synthetic provider credential tested on success and failure; real HTTP fixture suite |
| Investigation evidence could carry registered secrets and service journals/argv | Shared evidence boundary redacts, removes private-path lines and bounds UTF-8 output; service evidence uses only enumerated state properties | Registered service token absent from the second scripted model request |
| Approval digest omitted execution context | Versioned envelope binds id, kind, creation/expiry, root, uid, privilege, source, application, full candidate and material effects; lifetime limited to 900 seconds | Context substitutions and expiry extensions refused after resealing, including recomputed digests against retained approvals |
| Developer jail exposed home and could unmask credentials | Synthetic home, clean environment, private PID/IPC/UTS namespaces, no capabilities, only a selected writable workspace; mask overlaps refused; workspace bound by an open descriptor | Real Bubblewrap denied synthetic private files, environment, host processes and offline network; a post-review workspace symlink swap still bound the original workspace |
| Target writes checked paths and later reopened them | Root and parent descriptors, no-follow component traversal, atomic temporary-file replacement and descriptor chmod; root symlinks refused, hardlinks cannot receive writes | Root replacement, hardlink and concurrent atomic directory/symlink exchange tests |
| Installation verification only proved presence | Portage exact atom/version with explicit source/binary mode; Flatpak ref/commit, Snap revision/version/channel, Nix active-profile store path, AppImage bytes/version checks | Wrong Portage identity/version and wrong Flatpak commit refused; mocked install success/failure transactions remain truthful |
| PID-based per-action locking raced and allowed plan interleaving | Persistent inode plus kernel flock; transaction-wide reentrant ownership through revalidation, execution, verification and outcome recording | Competing acquisition, nested guard lifetime, other-thread exclusion, killed-process recovery, and a worker lease that survives broker death |
## Additional enforced limits
The process runner drains stdout/stderr concurrently with nonblocking stdin,
limits capture per stream (16 MiB by default), bounds log emission, and applies
wall-clock deadlines. Streaming builds retain a bounded tail. Oversized query
responses fail. Provider limits/deadlines also apply to sandboxed calls, and the
systemd manager receives RuntimeMaxSec so the actual service worker is bounded.
Model units have MemoryMax=256M and TasksMax=64. Commands issued under a mutation
hold inherit a duplicate lock descriptor; broker death cannot release exclusion
while an inheriting worker still runs. A real-process crash regression proves
that ownership passes to the worker and ends when it exits. Long build commands
retain a 24-hour default; common catalogue, candidate and verification reads use 120
seconds. Service evidence uses 30 seconds and 64 KiB.
Actual negative testing exposed a further gap: the original systemd user unit
could read a synthetic file beneath home. The unprivileged model path now uses
explicit Bubblewrap filesystem/PID isolation inside the transient user unit.
Systemd retains process/syscall/address-family restrictions. Its user-manager
filesystem properties were removed because they implied a namespace that
prevented Bubblewrap creating its jail. Root model calls retain the hardened
DynamicUser system-unit path. Missing tools or namespace failures stop the
request; there is no unconfined fallback. Effective uid is read from the kernel,
and developer home comes from the account database, rather than PATH or HOME.
## Artifact semantics
Flatpak does not support an install --commit option. The reviewed flow downloads
without deployment, uses OSTree's native REF@COMMIT pull with the configured
remote's signature policy, then deploys with Flatpak --no-pull and checks the
active commit. Phoebus now installs dev-util/ostree with its Flatpak lane.
Snap installs with --revision. Nix evaluates from an immutable path flake and
verifies its active store path. These pins bind the selected application;
backend-managed runtime/dependency closures are not claimed to be completely
content-pinned. Portage exact-version selection is not an immutable repository
snapshot. Portage, Flatpak and Nix were exercised in a disposable installed-system VM;
native Snap revision acceptance remains pending.
Primary command references:
[Flatpak](https://docs.flatpak.org/en/latest/flatpak-command-reference.html),
[OSTree pull](https://ostreedev.github.io/ostree/man/ostree-pull.html),
[Snap revisions](https://snapcraft.io/docs/revisions),
[Nix profile install](https://nix.dev/manual/nix/2.18/command-ref/new-cli/nix3-profile-install.html),
[Portage emerge](https://dev.gentoo.org/~zmedico/portage/doc/man/emerge.1.html).
## Verification and remaining acceptance
Real host denial tests are intentionally ignored by the portable suite and run
explicitly with:
```sh
cd installer-rs
cargo test -p phoebus-executor --test isolation_acceptance -- --ignored --skip model_system_unit
# The system-manager probe is run separately as root only in the disposable VM.
```
Both user probes passed on the development host. The system-manager probe
also passed as root in the disposable Gentoo VM. They use only synthetic fixture files,
never account credentials. Their fixtures are deleted at test completion.
Portable gates pass: 981 Rust tests, 22 VM-harness safety tests, strict Clippy,
fmt, repository checks and staged secret scan. Dynamic and static release
builds passed. No physical disk was touched.
The native run `serial-boot-20261012T105530Z-9c09094e` passed all 14 driver cases:
detached generic boot/login, running systemd, developer/user/root isolation,
deterministic history, descriptor-backed Btrfs snapshot, exact Portage install
and removal, persistent lock permissions, Flatpak commit install and removal,
Nix active store-path install, and clean poweroff. It used a separate qcow2
backing overlay; the source-build base image and local ISO are unchanged.
Two preceding attempts exposed fixture errors (password mapping and the KVM
virtualization identifier); neither is claimed as a product acceptance pass.
Initially doctor found 6 GiB free. Compiler-cache cleanup restored sufficient
space and host doctor passed with a tight-space warning. A fresh installation
was not repeated. Native pins/isolation/snapshot behavior were exercised on the
installed Gentoo overlay. The subsequent lock-lease addition has its own real
crash-process regression. Final static binary smoke
`serial-boot-20261012T112454Z-47d3cfae` passed 8/8 with clean poweroff,
repeating sandbox denials and executing history and a Btrfs snapshot in an
explicitly network-free namespace. Its SHA-256 was
`1ea91f6f0ac82d88e9a8c400f510819aefaf73251778b248ef2443fdf18e2b62`.
Remaining acceptance: a fresh encrypted installation with descriptor I/O; native
Snap revision installation and adversarial metadata drift across the lanes;
interrupted native package-worker recovery and broader network-free repair/undo
acceptance beyond the verified history/snapshot commands. Older staged approvals
must be reviewed again because the envelope digest has changed. Developer
tools/auth state outside the selected workspace are intentionally hidden; narrowly scoped explicit grants are future
work, rather than silently exposing the whole home directory.