# Dedicated APT runner / VM preflight contract **Implemented, built and locally tested, not deployed or measured on a VM.** Every command below is **planned, not executed here**. No host package, service, reboot, root installation or acceptance operation was executed in this dispatch. Readiness is not package acceptance or authorization. Existing readiness/general helper unit is unchanged: no broadening its write paths/capabilities/filters. ## Architecture and fixed paths Same helper binary, two separate daemon profiles: | Profile | Socket | Allowed operations | |---|---|---| | general (existing/default) | existing configured general socket | existing explicitly permitted root operations, never APT | | `apt_only` | `/run/rmm-apt-helper/helper.sock` | read-only readiness and typed fixture APT jobs only | APT profile requires agent UID **993**, root-owned agent-group socket ACL, empty allowed_services, allow_reboot=false, allow_root_scripts=false and a valid apt_provider policy. Unknown profiles/actions/CLI programs fail closed. No shell, service, reboot or generic-program dispatch exists in apt_only. Root administrative CLI modes are fixed install/probe/inspect operations, not network-callable argv. **Both daemons must run the same new helper build** and use the exact same `/var/lib/rmm-helper/consumption.sqlite` and `executor.lock` inodes. All SQLite sidecars stay in that shared directory (current ledger uses synchronous FULL / DELETE journal mode; no database/WAL/SHM copy or private bind). Flank lock is now per actual request/effect, not daemon lifetime, allowing coexistence. Startup DDL is locked; consume/execute/finish are locked. An unresolved consumed row blocks all new effects across both profiles, including reboot/package conflicts. No tombstone deletion, marker reset, database copy or grant replacement shortcut. APT-owned store: `/var/lib/rmm-apt-transaction` (0700), including archives, baselines, history, probes, state, log and active handoff. The child sees neither the shared ledger nor `/etc/rmm` keys/config, `/var/lib/rmm-agent`, home directories, host manager sockets or inherited private fds. Only the trusted outside root controller sees the signing-key pin/ledger. Central private signing keys must never be deployed to the VM. ## Installation order (planned) 1. Authenticated operator installs the reviewed newly built helper at fixed `/usr/local/libexec/rmm-privileged-helper` using the existing controlled artifact deployment process. Both helper daemons need this same build; do not blindly overwrite an active old helper or restart away unknown effects. 2. Before starting the new unit, run the root-only known-payload installer: ```text /usr/local/libexec/rmm-privileged-helper --install-apt-provider ``` It exclusively creates known embedded provider/hook files, schema-2 install metadata, the exact `rmm-apt-helper.service` at `/etc/systemd/system/`, private store directories and empty `/usr/share/rmm-mvp-test`. It does NOT install a .deb, start systemd, create grants or create an acceptance record. Existing/ partial paths are refused, not overwritten, chmod-repaired or deleted. 3. Root-provision `/etc/rmm/apt-helper.json` (0600) from `apt-helper.example.json`; replace all invalid placeholders and verify actual rmm-agent UID is 993 and socket_gid is the actual rmm-agent group GID. Keep the existing separately authenticated Ed25519 key pin/binding procedure. 4. Inspect the installed provider/config/runtime, including installed helper binary and exact unit profile: ```text /usr/bin/python3 -I /usr/lib/rmm-apt-transaction/apt_transaction.py print-config /usr/bin/python3 -I /usr/lib/rmm-apt-transaction/apt_transaction.py inspect-runtime ``` Set approved apt_config_sha256 from exact config bytes. Set runtime_sha256 from the canonical runtime object **without its trailing newline**. Review the contents/code/configuration; blindly hashing unreviewed configuration is not a security review. No timestamp/hash placeholder can enable execution. 5. After valid private config/key provisioning, inspect the helper identity pin: ```text RMM_HELPER_CONFIG=/etc/rmm/apt-helper.json /usr/local/libexec/rmm-privileged-helper --inspect-apt-profile ``` Operator installs its exact JSON output at e.g. `/etc/rmm/apt-helper-proof.json`, root:rmm-agent 0640, in root-owned, non-group/world-writable configuration parents. This pin contains public identity/hash metadata, no grant or secret. Agent must be able to read it but not alter it. The inspected executable must match the installed daemon bytes. 6. Validate the unit on the VM before start (`systemd-analyze verify`), then perform the separately authorized unit bootstrap. `ExecStartPre` executes: ```text RMM_HELPER_CONFIG=/etc/rmm/apt-helper.json /usr/local/libexec/rmm-privileged-helper --probe-native ``` **The probe runs under the actual dedicated service profile**, not a generic root shell: controller verification requires NoNewPrivileges, exact ten-bit setup capability set, zero inherited/ambient caps, the actual rmm-apt-helper.service cgroup and readonly /usr, /etc and /var. Direct daemon/ probe invocation outside that profile is rejected. `--inspect-apt-profile` remains a read-only administrative metadata operation and is not readiness. Controller verification also requires an outer seccomp filter, actual writable declared targets, and rejects unexpected writable submounts below /usr,/etc, /var. Inspect effective systemd configuration (`systemctl cat/show`) on the VM; do not introduce unreviewed drop-ins or substitute a root-shell launch. ## Unit and irreversible worker sandbox `rmm-apt-helper.service` provides NNP, PrivateTmp/PrivateNetwork, strict readonly system/home/kernel/control-group protection, AF_UNIX only, native syscall ABI, mount/PID/net namespaces only, no ambient caps. Bounding set is filesystem/UID bits 0,1,3,4,6,7,8,31 plus SYS_ADMIN/MKNOD for trusted setup; no SYS_BOOT, SYS_CHROOT or SYS_TIME. DevicePolicy=strict permits only null/zero/random/urandom rwm; PrivateDevices=no permits trusted construction of a minimal private /dev. Outer filter allows mount/unshare/fork/capset/prctl/seccomp trusted setup instead of an outer @mount prohibition. Reboot/module/raw-io/swap/debug and clock setters remain denied. The narrow adjtimex exception is necessary for the existing read-only modes=0 trusted-clock query; mutating adjtimex still needs CAP_SYS_TIME, which is absent. This is not a clock-verification bypass. Write paths are **only** `/var/lib/dpkg`, shared helper ledger, private provider store and precreated `/usr/share/rmm-mvp-test`. No whole /usr, /etc or /var writes. APT terminal/history logs and dpkg log are explicitly under provider `log/`; APT cache/state and extended_states are private, no default /var/log/apt write. These are configured paths, **not natively proven log/write requirements** yet. Unexpected native write failures must be reported, not fixed with blanket writes. One common Python setup function serves mutation and readiness. It makes mount propagation private, hides keys/ledger/sockets/fds, mounts minimal devices and kernel controls, then irreversibly drops E/P/B to the original eight caps, clears I/A, retains NNP and installs seccomp. Both clone namespace flags (including NEWUSER/NEWTIME) and clone3 pointer flags are closed: clone3 returns ENOSYS for libc's ordinary fork fallback; clone namespace flags return EPERM. Ordinary fork/exec remains allowed. No reconfiguration/reboot/kexec escape is allowed after setup. Trusted setup with SYS_ADMIN is explicitly in the TCB. ## Readiness probe: no package transaction `--probe-native` does NOT create jobs, grants, receipts, launch/effect markers or native-acceptance records. It exclusively creates a generated private probe dir, copies host dpkg status (host opened read-only), binds the copy over /var/lib/dpkg inside the worker namespace, uses source/hook-isolated private APT config, tests private-db frontend lock conflict and runs positive `apt-get check` on that copy. The host frontend lock is only observed with O_RDONLY/F_GETLK: never F_SETLK, flock/lockf, deletion or killing an owner. Invalid-magic/flags reboot/kexec probes must return EPERM; no valid calls or PID1 signals are attempted. The worker checks namespaces/PID1, capabilities/NNP/seccomp, readonly control mounts, hidden sockets and masked sysrq. Parent verifies complete result and private namespace identities, unchanged host status/runtime and publishes only root-private `native-readiness.json` (readiness_only=true, native_acceptance=false). It is boot-/code-/OS-/binary-/unit-bound and invalidated by changes. Partial, failed or malformed results do not publish new readiness. Acceptance/bootstrap attempt tombstones are neither created nor reset by this operation. ## Agent environment / read-only IPC API ``` RMM_APT_HELPER_SOCKET=/run/rmm-apt-helper/helper.sock RMM_APT_HELPER_PROOF_FILE=/etc/rmm/apt-helper-proof.json ``` `RMM_HELPER_SOCKET` remains the general route. Typed ensure_package, apply_updates and apt_native_acceptance exclusively use the dedicated socket. Missing/wrong APT socket/pin/readiness never falls back to general helper, SSH, shell or local execution. The unprivileged agent obtains a fresh read-only probe before capability advertisement and before use; it authenticates root SO_PEERCRED, root-owned safe socket/parents and independent root-provisioned pin. Same u32-big-endian framed JSON socket, a distinct read-only request shape: ``` operation: "apt_readiness_v1" challenge: fresh nonnil UUID identity: {tenant_id,asset_id,agent_id,enrollment_generation,assignment_version,signing_key_id} expected_stack_sha256: independently pinned helper/identity/policy/unit stack hash ``` Response strictly binds nonce, identity, apt_only profile and provider stack; includes shared ledger/lock dev/inodes and separate fixture_acceptance_ready, bootstrap_recipes and accepted_recipes. Wrong nonce/identity/generation/profile/ stack/root peer is rejected. An unresolved shared ledger suppresses all APT readiness/capabilities. This API never consumes a grant or authorizes a job. Readiness alone advertises **only apt_native_acceptance** for fixed allowed fixtures. Valid native acceptance records enable only matching fixture recipes: ensure_package, and apply_updates only for the accepted update recipe. Agent also checks each actual typed job's manifest recipe, not just aggregate action capability names. No production/arbitrary catalog capability is manufactured. ## Actual jobs remain UI-authorized Domain's additive typed schema-2 apt_manifest and dedicated AptNativeAcceptance are now present; local tests roundtrip the actual domain variant through exact signed bytes into the helper validator. See `tools/apt-transaction/HELPER-CONTRACT.md` for the full immutable payload/context schema. Readiness does not replace independent Ed25519 verification, all target/ tenant/generation/plan/job/attempt/authorization/action/hash/time bindings, current trusted clock, parent consumption and immutable WebUI approval. Use provision-fixture-store / prepare-baseline **before** final grant to stage the two known archives and snapshot. One UI-approved dedicated fixture job may install 1.0, another may update 1.0 -> 1.1. Same guard/native lock/deadline/hash/ postcondition pipeline, no weak path. Failed/stale/partial/unknown never acceptance. Armed/unknown outcomes retain both parent resource fencing and effect markers. One-time failures are not blindly reset: technical no-start recovery needs a separate durable signed reconciliation procedure, not implemented as a shortcut. No actual native namespace/APT/service/root execution has been measured here. The subsequent VM worker must execute this profile/probe and UI-authorized fixture jobs, retain actual evidence and report all native failures separately. ## Executed local verification (this increment) * Source-tree rustfmt check passed for helper lib/main and agent main/modules. * Targeted Clippy `-p rmm-privileged-helper -p rmm-agent --lib --bins -- -D warnings` passed. * `cargo test -p rmm-privileged-helper -p rmm-agent --lib --bins`: **37 passed** (20 helper library, 3 helper binary, 14 agent). * `PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests/apt_transaction -p 'test_*.py' -v`: **48 passed**; AST syntax checks **7 Python files**; example JSON syntax passed. * Local unprivileged seccomp invalid-input/clone-flag denial and ordinary fork/exec really ran. Root setup/installer/APT/probe unit execution was mocked where unsafe. Temporary mock readiness files are not deployed native evidence. Package-wide verification has a concurrent-work limitation: the last full `cargo fmt --check` encountered formatting in the other worker's `crates/privileged-helper/tests/reconcile.rs`; the last all-target Clippy attempt failed on missing `validate_history` in its included `src/reconcile.rs`. Those Sync files were not edited here. The focused source checks/tests above passed afterwards; this is not a claim that the parallel Sync integration suite passed.