228 lines
13 KiB
Markdown
228 lines
13 KiB
Markdown
# 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.
|