Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Trust Boundaries

This page gives reviewers one place to find the hostile-input boundaries, trusted inputs, and current isolation assumptions that matter for capOS security review.

Current Boundaries

Ring 0 to Ring 3

  • Trust rule: the kernel trusts no userspace register, pointer, SQE, CapSet, or result-buffer field.
  • Implemented: syscall arguments, user-buffer ranges, page permissions, opcodes, and capability-table lookups are validated before privileged use in kernel/src/arch/x86_64/syscall.rs, kernel/src/mem/paging.rs, kernel/src/mem/validate.rs, and kernel/src/cap/ring.rs.
  • Validation: Panic Surface Inventory and REVIEW.md at the repository root.

Capability Table to Kernel Object

  • Trust rule: a process acts only through a live table-local CapId with matching generation and interface.
  • Implemented: capos-lib/src/cap_table.rs owns generation-tagged slots; kernel capability dispatch goes through CapObject::call.
  • Validation: cargo test-lib plus QEMU ring and IPC smokes recorded in done task records.

Capability Ring Shared Memory

  • Trust rule: userspace owns SQ writes, but the kernel owns validation, dispatch, completion, and failure semantics.
  • Implemented: SQ/CQ headers and entries live in capos-config/src/ring.rs; kernel dispatch bounds indexes, opcodes, transfer descriptors, and CQ posting, and copies CALL/RECV/RETURN buffers while holding the owning process AddressSpace lock.
  • Validation: cargo test-ring-loom plus QEMU ring corruption, reserved opcode, fairness, IPC, and transfer smokes.

Endpoint IPC and Transfer

  • Trust rule: IPC cannot create or destroy authority except through explicit copy, move, release, or spawn transactions. Delegating an imported client facet must preserve service-visible identity, and shared-service handlers should derive caller identity from live caller-session metadata.
  • Implemented: kernel/src/cap/endpoint.rs, kernel/src/cap/transfer.rs, and capos-lib/src/cap_table.rs implement queued calls, RECV/RETURN, copy/move transfer, legacy receiver metadata propagation, and rollback. Legacy badge metadata is a debug/test surface only. Normal chat, stdio bridge, and shared demo handlers use live caller-session metadata instead of caller-selected badge identity.
  • Validation: Authority Accounting and any open transfer review-finding task records.

Manifest and Boot Package

  • Trust rule: boot manifest bytes and embedded binaries are untrusted until parsed and validated. Only BootPackage holders can request chunked manifest bytes; ordinary services receive no default boot-package authority.
  • Implemented: tools/mkmanifest validates the embedded initConfig graph before serialization. Kernel bootstrap validates the kernel-owned manifest boundary before loading one init process; init BootPackage validation resolves service graph references before spawning children. kernel/src/cap/boot_package.rs, capos-lib/src/elf.rs, and load paths still enforce manifest-read, ELF, load-range, CapSet, and interface bounds.
  • Validation: cargo test-config, cargo test-mkmanifest, cargo test-lib, manifest and ELF fuzz targets, and make run.

Process Spawn Inputs

  • Trust rule: parent-supplied spawn params, ELF bytes, grants, legacy badges, and result-cap insertion must fail closed. Endpoint kernel grants must not share owner caps with the parent. Delegated client facets must not be relabeled into another service identity.
  • Implemented: ProcessSpawner validates ELF load, grants, frame exhaustion, parent cap-slot exhaustion, child-local endpoint creation, and parent-only client result facets. Delegated ClientEndpoint grants preserve source identity; explicit relabel encodings fail closed except for owner or trusted parent endpoint-result caps.
  • Validation: spawn QEMU smoke evidence and review-finding task records.

Console Authentication and Setup

  • Trust rule: console input, account selectors, password verifiers, setup tokens, and passkey challenge state are hostile or sensitive until a login/session component validates them.
  • Implemented: Console remains output-only. The first interactive boundary is session-scoped TerminalSession with bounded readLine, visible/hidden echo, structured cancellation, one move-only foreground holder, caller-session-checked output, and stale-input scrubbing on cancel or owner teardown. CredentialStore verifies one manifest-supplied Argon2id operator credential and one bounded volatile RAM-overlay password created by first-boot setup. capos-shell drives login and setup; there is no separate ConsoleLogin service.
  • Validation: Boot to Shell, boot-to-shell gates in ../../docs/tasks/README.md, make run-terminal, make run-login, and make run-login-setup.
  • Open/future: durable multi-account credential storage, multiple verifier records, rotate/disable state, broader anti-enumeration audit policy, and bounded single-use setup-token/challenge state.

Session Authority and Audit

  • Trust rule: authenticated sessions receive only broker-issued narrow caps. Audit output, service logs, terminal output, and failed-auth diagnostics must not disclose secrets or verifier material.
  • Implemented: SessionManager mints entropy-backed UserSession metadata for operator, explicitly seeded guest, and anonymous profiles. Endpoint caller-session references are HMAC-SHA256 values scoped by an entropy-backed boot key and non-reused endpoint service-scope id. AuthorityBroker validates session/profile matches before minting bundles. RestrictedLauncher returns shell-scoped launch paths instead of BootPackage or broad ProcessSpawner authority.
  • Validation: User Identity and Policy, Boot to Shell, make run-login, make run-login-setup, and future auth/session hostile input tests.
  • Open/future: audit records, stable service-audit identity across endpoint replacement, opaque record IDs, mutable session liveness cells, UserSession.logout, owner-shell/gateway close propagation, narrow renewal paths, broader policy evaluation, and web-terminal origin/RP-ID validation.

SSH Remote Shell Ingress

  • Trust rule: SSH network input, keys, usernames, channel requests, PTY state, environment requests, and disconnects are hostile until the gateway validates protocol state, authenticates the user, and receives a broker-issued shell bundle.
  • Implemented: current proofs cover schema stubs, one development-only host-key fixture, manifest-seeded AuthorizedKeyStore, public-key session minting, unsupported-feature policy, restricted shell launch, and bounded terminal-host wiring over host-local plain TCP. The proposal keeps SSH transport authority in SshGateway; the spawned shell receives only an SshTerminalFactory-produced TerminalSession plus the normal scoped session bundle through RestrictedShellLauncher. Fixture host-key signing, authorized-key mapping, public-key session minting, SSH policy rejection, and restricted launcher inputs fail closed for malformed or unsupported cases.
  • Validation: SSH Shell Gateway, Runtime, Networking, and Shell, make run-ssh-host-key, make run-ssh-authorized-key, make run-ssh-public-key-session, make run-ssh-public-key-auth, make run-ssh-feature-policy, and make run-restricted-shell-launcher (the plain-TCP run-ssh-gateway-terminal-host terminal-host proof is retired with the kernel socket owner).
  • Open/future: full SSH transport transcript and channel binding, password-auth verifier/backoff wiring, production host-key storage, broader account storage, and production remote-shell hardening.

Identity Metadata and Account Records

  • Trust rule: users, principals, accounts, sessions, roles, and profile names are policy metadata, not kernel subjects, ambient authority, or substitutes for held capabilities.
  • Implemented: sessions receive capabilities only after authentication and broker policy evaluation; a principal or account record does not run or call the kernel.
  • Validation: Local Users, Storage, and Policy and User Identity and Policy.
  • Open/future: durable local account-store behavior, profile persistence, rollback checks, and quota enforcement.

Host Tools and Filesystem

  • Trust rule: manifest/config input must not escape intended source directories or invoke unconstrained host commands.
  • Implemented: tools/mkmanifest validates references and path containment, rejects unpinned CUE compilers, and Makefile targets route CUE and Cap’n Proto through pinned tool paths.
  • Validation: Trusted Build Inputs, make generated-code-check, and make dependency-policy-check.

Generated Code and Schema

  • Trust rule: schema, generated bindings, and no_std patches are trusted build inputs.
  • Implemented: schema/capos.capnp, build scripts, tools/generated/capos_capnp.rs, and tools/check-generated-capnp.sh make generated-code drift review-visible.
  • Validation: Trusted Build Inputs and make generated-code-check.

Device DMA and MMIO

  • Trust rule: current userspace receives no raw DMA buffer, device physical address, virtqueue pointer, BAR mapping, or device interrupt handle.
  • Implemented: the QEMU virtio-net path is allowed only through kernel-owned bounce buffers and kernel-owned MSI-X source records routed through the kernel device interrupt dispatch table, bounded device MSI vector pool, and kernel-owned route lifecycle checks.
  • Validation: DMA Isolation and make run-net.
  • Open/future: typed DMAPool, DeviceMmio, and Interrupt capabilities for userspace-driver transition.

Panic and Emergency Paths

  • Trust rule: hostile input should produce controlled errors, not panic, allocate unexpectedly, or expose stale state.
  • Implemented: ring dispatch is mostly controlled-error; remaining panic surfaces are classified by reachability and tracked as hardening work.
  • Validation: Panic Surface Inventory and REVIEW.md.

Security Invariants

  • All authority is represented by capability-table hold edges; no syscall or host tool path should bypass the capability graph.
  • Identity metadata is not authority. Principals identify audit and policy subjects, accounts store durable policy inputs, profiles select bundle and quota templates, and sessions receive caps only through explicit broker minting.
  • The interface is the permission: method authority is expressed by the typed Cap’n Proto interface or by a narrower wrapper capability, not by ambient process identity.
  • Kernel operations at hostile boundaries validate structure, bounds, ownership, generation, interface ID, and resource availability before mutating privileged state.
  • Failed transfer, spawn, manifest, and DMA setup paths must leave ledgers, cap tables, frame ownership, and in-flight call state unchanged or explicitly rolled back.
  • Trusted build inputs must be pinned or drift-review-visible before their output becomes part of the boot image or generated source baseline.
  • Authentication/session code must treat credential records, setup tokens, passkey challenges, session IDs, and audit logs as security boundaries, not ordinary console text.

Open Work

  • Unify fragmented resource ledgers into the authority-accounting model so reviewers can audit quotas without following parallel counters.
  • Harden open panic-surface entries that become more exposed as spawn, lifecycle, SMP, or userspace drivers expand hostile input reachability.
  • Keep DMA in kernel-owned bounce-buffer mode until the DMAPool, DeviceMmio, and Interrupt transition gates have code and QEMU proof.
  • Do not expand production authentication or remote-shell surfaces without hostile-input tests for bounded terminal input, credential failure paths, challenge expiry/replay, audit redaction, and narrow shell cap bundles.