feat: snapshot Linux-first RMM MVP and pause handover
Rust development slice / linux (push) Failing after 1m10s

This commit is contained in:
BuTzZ
2026-11-12 22:06:25 +01:00
commit 6c3203d725
194 changed files with 49234 additions and 0 deletions
+277
View File
@@ -0,0 +1,277 @@
# Linux agent/helper bootstrap contract (not a VM acceptance)
**Current integrated runtime contract:** [runtime-README.md](runtime-README.md).
The module-only blockers and integration steps below record the earlier increments;
they are historical and superseded by that runtime document. In particular Sync,
HTTPS, rotation and authenticated helper apply are now wired in source, not VM-
accepted. Use the current document and installed units for new bootstrap work.
Dedicated APT runner, exact config/unit/CLI/readiness/agent-routing preflight:
[`apt-helper-README.md`](apt-helper-README.md). This newer profile does not weaken
the existing general/readiness helper unit. Native VM measurements remain open.
No install/start/reboot command in this document has been executed on the VM.
No RustDesk component is installed. Deploy only the artifacts/configuration for
the explicitly agreed test; do not copy central signing/TLS private keys.
## Built artifacts and process configuration
Planned build command (the debug test/build commands actually executed are listed
in `tests/agent_jobs/README.md`):
```sh
cargo build --release -p rmm-agent -p rmm-privileged-helper
```
Both binaries are environment-configured, **not** positional-argument CLIs.
Agent: `RMM_AGENT_STATE` (default `devstate/agent`), `RMM_CA_FILE` (default
`devstate/pki/ca.pem`), `RMM_CONNECT_ADDR` (default `127.0.0.1:18443`),
`RMM_ENROLLMENT_TOKEN_FILE` (first registration only), and optional
`RMM_JOB_BINDING_FILE`, plus optional `RMM_HELPER_SOCKET` for explicit-root grants.
The TCP override never changes the TLS DNS/SNI name
`rmm-dev.internal`. No proxy or invalid-certificate bypass. Without a binding,
the agent remains passive. It refuses to advertise/execute actions as UID 0.
Provision a dedicated unprivileged `rmm-agent` system account/group. Install the
agent binary root-owned and non-writable by that account at
`/usr/local/libexec/rmm-agent`. State must be owned by that account, mode 0700;
its files are 0600. The sample service uses systemd `StateDirectory` and no
ambient capabilities. Install only the public CA at `/etc/rmm/ca.pem`. An
optional root-owned 0600 `/etc/rmm/agent.env` supplies the first-enrollment token
**path**, never an inline token. Remove that bootstrap token after registration.
Retain the enrolled VM-generated private device key on the VM.
The operator must provision the job signing key over the authenticated bootstrap
channel: authenticated `GET https://rmm-dev.internal:18443/api/v1/job-signing-key`
using the verified CA, checking `algorithm == "Ed25519"`, `schema_version == 1`,
32-byte `public_key_hex` and `key_id == SHA256(raw_public_key)`. Do not trust a key
sent alongside a job, use an unauthenticated GET, put bearer credentials in
command arguments, or substitute TLS/update keys. This increment does not
rotate this trust anchor. Optional automatic agent fetching is described below;
the helper remains independently provisioned. The authenticated operator/bootstrap
must also resolve the enrolled agent's tenant, asset, generation and assignment
from server records, not accept an offer as identity provisioning.
Agent binding JSON, owned by `rmm-agent`, 0600, in a root-owned configuration
directory (replace every placeholder; invalid placeholders intentionally fail):
```json
{
"tenant_id": "PROVISIONED-TENANT-UUID",
"asset_id": "ENROLLED-ASSET-UUID",
"agent_id": "ENROLLED-AGENT-UUID",
"enrollment_generation": 1,
"assignment_version": 1,
"public_key_hex": "AUTHENTICATED-32-BYTE-KEY-IN-HEX"
}
```
The agent additionally compares asset/agent IDs to its enrollment response.
Generation/assignment changes require an authenticated re-provisioning procedure,
not an in-band config assertion. State lock, integrity check and journal capacity
errors fail closed; never delete journal/consumption files to force a retry.
## Independent helper boundary
Helper: `RMM_HELPER_CONFIG`, default `/etc/rmm/helper.json`. It requires UID 0,
a root-owned 0600 config, root-owned private 0700 state directory, and a
root-owned socket parent not writable by group/others. `/run/rmm-helper` may be
0750 with group `rmm-agent`. The root-owned socket is 0660 with the configured
group; `SO_PEERCRED` additionally requires **exactly** the configured non-root
agent UID. Group membership alone grants no execution authority.
Example `/etc/rmm/helper.json` (root:root, 0600):
```json
{
"binding": {
"tenant_id": "PROVISIONED-TENANT-UUID",
"asset_id": "ENROLLED-ASSET-UUID",
"agent_id": "ENROLLED-AGENT-UUID",
"enrollment_generation": 1,
"assignment_version": 1,
"public_key_hex": "AUTHENTICATED-32-BYTE-KEY-IN-HEX"
},
"agent_uid": 12345,
"socket_gid": 12345,
"socket": "/run/rmm-helper/control.sock",
"state": "/var/lib/rmm-helper",
"allowed_services": ["rmm-acceptance.service"],
"allow_reboot": false,
"allow_root_scripts": false
}
```
Use the actual dedicated account's numeric UID/GID, not the example numbers.
The helper re-verifies exact Ed25519 bytes, all identity/hash/action/parameter
bindings, a <=60-second grant interval, synchronized bounded host clock, explicit
`execution_identity:"root"`, local action policy and its **own** SQLite consumption
ledger before invoking the typed OS provider. A request-provided bearer, key or
identity assertion is never an authority. The config has a separate, default-off
root-script permission; enabling it is consciously broad administration, still
subject to the sample service sandbox. Only exact allowed service units with
running/stopped state and >=180s runtime are accepted; restart is not silently
rewritten as start. Reboot is default-off and never yields exit-code success.
IPC framing: one big-endian u32 length plus JSON `Request` (<=512 KiB) per Unix
connection. Fields are `job_bytes`, `permit_bytes`, `signature` (JSON byte arrays),
`plan_hash`, `authorization_id`. Response has the same framing and an `Outcome`.
Read/write deadlines are 5s. No request errors/secrets are echoed. The server
process is serial; unknown effects retain its global device resource lock, even
after restart. Duplicate consumed grants return stored evidence/unknown, never
execute again. A new grant for an already consumed attempt is also refused.
The helper refuses a preexisting socket; systemd removes its RuntimeDirectory
on stop. Manual stale-socket recovery requires checking that no helper is alive,
not blindly unlinking a path at startup.
## Explicit integration/acceptance blockers
* Backend currently permits only `agent_service`. Network agent intentionally
advertises only `run_script` and `refresh_inventory`, not privileged actions.
Network-agent → Unix-helper invocation is wired for explicit-root signed jobs
when `RMM_HELPER_SOCKET` is configured, with root socket/peer authentication.
A backend-authorized explicit root identity plus helper capability negotiation
must land before service/reboot/root-script E2E tests. Helper policy denies
unconfigured actions independently; the agent never relabels a service-identity
grant into root authority.
* Real APT mutation remains unsupported. A simulation followed by `apt-get`
cannot guarantee exact approved resolution under dpkg fcntl locks or suppress
arbitrary maintainer-script reboots. Neither `ensure_package` nor
`apply_updates` is advertised. No false flock-on-dpkg-lock implementation.
* No backend SyncRequest/Response exists. Only the **first** authenticated session
of a journal may start effects. On reconnect/restart new effects are blocked;
in-flight reservations become unknown, durable evidence still replays and
heartbeats remain fresh. No DB deletion/new-grant shortcut. Existing previously
connected state also needs real synchronization before jobs can be enabled.
* Running-script cancellation is recorded but not claimed as confirmed abort;
bounded execution finishes and reports its real result. A reboot does not
complete without authenticated new-boot evidence; automatic reboot recovery
synchronization is not implemented.
* Extended collectors now map to bounded per-source observations inside the
existing `linux.base` JSON, not new protobuf scopes/tags. Enable only after
backend JSON-extension acceptance is confirmed, as described below.
* No VM deployment, systemd install, root action, package/update/reboot host
effects or real UI approval were performed by this increment.
## Additional environment variables and bootstrap (second increment)
* `RMM_JOB_SIGNING_KEY_BOOTSTRAP=1`: after enrollment, use **device mTLS** to GET
`/api/v1/job-signing-key` over verified TLS. DNS/SNI remains `rmm-dev.internal`;
`RMM_CONNECT_ADDR` changes TCP only. Built-in roots, proxies and redirects are
disabled. The response is bounded to 4096 bytes and Ed25519/schema/key-hash
checked. No bearer is copied into the agent. A preconfigured binding key must
match; an empty key allows initial authenticated provisioning. The resulting
`RMM_AGENT_STATE/job-signing-key.json` is private and create-only. A changed
existing pin **fails**, never silently rotates. Keep the bootstrap flag enabled
on subsequent starts when the binding's key is empty, so the endpoint is
reauthenticated and checked against the cached pin. If the current backend
endpoint accepts bearer identity only, bootstrap fails closed; backend must
explicitly authorize the authenticated enrolled device at that endpoint.
* Helper config optional `"signing_key_file":"/etc/rmm/helper-signing-key.json"`:
root-owned 0600 JSON with `key_id`, `algorithm`, `schema_version`,
`public_key_hex` in the GET response shape. Provision via the trusted operator
bootstrap, **not** from an agent-provided file/path/request. If an inline helper
binding key is present it must match. The helper has no network key-fetch or
auto-replacement operation; agent cache changes cannot change helper trust.
* `RMM_LOG_UNITS_FILE`: private, agent-owned 0600 JSON array of 1–128 exact
`.service` names. `query_logs` is advertised only when this allowlist and a
native journald executable/runtime exist. The signed action must bind an
allowlisted unit, nonnegative UTC window <=24h, <=1000 lines, >=20s runtime and
bounded output. No arbitrary paths or caller-defined journal arguments.
Access/JSON/output failures retain quality/error metadata. The current action
has **no cursor input field**; no cursor is fabricated or advanced. Results
explicitly report `cursor_status:not_advanced_no_ack_contract` and partial
coverage until a concrete durable cursor-ACK contract exists.
* `RMM_EXTENDED_INVENTORY=1`: opt-in additive snapshot JSON fields `observations`,
`collection_started_at`, `collection_completed_at`. Every observation has
`scope`, source, real RFC3339 observation time, quality, completeness,
truncation, error and data. CPU, memory, OS, interfaces, routes, DNS, volumes,
installed packages, local update metadata and DMI are mapped; SMART remains
explicitly unsupported. Per-scope output is <=32 KiB and entire data <=512 KiB.
**Do not enable against a gateway deserializing the old deny-unknown-fields
Inventory struct.** Confirm backend storage accepts these additive JSON fields
first. Default remains compatible base JSON; no wire/protocol file changed.
Passive collection now runs in one bounded-inflight blocking worker with a
bounded completion channel, not inside the network/heartbeat loop. A reconnect
does not spawn a second collector while one is already running. A refresh job
still collects a **new** base observation for its signed `linux.base` scope;
it never returns an old stored passive snapshot as a live measurement.
Awaiting-reboot evidence now persists before effect: original native boot ID,
exact signed request, reservation time and reconnect deadline in each process's
own `execution_evidence` ledger. Awaiting/unknown outcomes persist without
unlocking the consumed attempt. Neither exit code nor a process restart supplies
authenticated new-boot completion. Cancellation arriving while a permit is
outstanding is checked before effect; running cancellation remains conservative.
An earlier future-scheduled job no longer starves later ready jobs.
## Offline package installer (not executed on VM)
`deploy/linux/install.py` is create-only. Planned invocation:
```sh
python3 deploy/linux/install.py --root /PATH/TO/STAGING \
--agent-binary target/release/rmm-agent \
--helper-binary target/release/rmm-privileged-helper --ca-file /PATH/TO/PUBLIC-CA.pem
```
Staging writes only the x86-64 ELF artifacts, public CA and unit files. A live
installation additionally requires root, `--root / --install-live` and an already
provisioned unprivileged `rmm-agent` account. It refuses overwrites, writable or
symlinked install directories, non-x86-64 artifacts and private-key CA inputs.
It does **not** create accounts/config/identities/state, call systemctl, enable or
start anything, install packages, change the network or reboot. Configure trust
and enrollment first; systemd StateDirectory/RuntimeDirectory creates the correct
runtime state when a later explicitly authorized bootstrap starts the units.
The units retain empty agent capabilities, NoNewPrivileges, private temp,
read-only system/home protection and no privileged-shell bypass. Privileged
scripts are separately default-off and remain subject to the helper sandbox.
## Concrete backend contracts needed next
### APT bridge increment (not installed or VM-tested)
The helper's typed APT bridge is implemented at
`crates/privileged-helper/src/apt.rs`, through its existing SO_PEERCRED/signature/
parent-consumption boundary. Root config has optional `apt_provider`; default is
disabled. The exact schema-2 signed manifest, additive domain action fields,
compile-time-known create-only provider installation, pre-grant sealed archive/
baseline layout, context/ledger mapping and conservative outcome contract are
documented in [`../../tools/apt-transaction/HELPER-CONTRACT.md`](../../tools/apt-transaction/HELPER-CONTRACT.md).
This does not remove the package-capability blocker: the domain must preserve
the complete typed `action.apt_manifest`, validate the narrow fixture closure,
and support dedicated `apt_native_acceptance`; the agent remains unchanged.
Legacy package/update actions without this field fail closed. No RunScript
conversion, arbitrary archive URL or unsigned IPC manifest is accepted.
Planned root-only `rmm-privileged-helper --install-apt-provider` installs only
embedded reviewed provider/hook bytes and fixed metadata, create-only. It does
not start services, create grants, install .deb packages or create acceptance.
`provision-fixture-store` prepares only the pinned fixture artifacts before any
final grant. Neither command was executed in this increment.
The existing helper unit's ProtectSystem=strict/other protections are **not**
an APT write/setup profile. A reviewed native fixture runner/unit configuration
and actual VM tests are still required; no unit restriction was relaxed here.
Do not advertise APT merely because the Rust bridge and local tests compile.
Before removing `begin_session`'s fail-closed reconnect gate, agree a versioned
authenticated SyncRequest/Response carrying device identity/assignment and
connection generation, journal identity/checkpoint, fixed job/attempt, payload
hash, grant ID/bytes or reservation ambiguity, local revision/state, original
boot ID, persisted outcomes and concrete durable event receipts. Server must
return an explicit reconciled/fenced decision, not a blanket `ok`. Unknown or
missing old reservations must retain resource locks; no response may authorize a
new attempt or silently manufacture a replacement grant. Restored/mismatched
generations must stay blocked. Reboot success requires authenticated current
envelope boot ID different from persisted original boot and bound postconditions.
Long-poll must deliver the same typed envelopes and concrete ACKs with one active
generation, including late evidence ingestion; no new endpoint/wire assumption
is implemented here. Root planning must bind explicit root identity and local
helper capabilities/policy, never reinterpret `agent_service`. The public key
GET must authorize enrolled device mTLS. Additive inventory JSON acceptance must
be confirmed before enabling extended collection in a real agent.
+60
View File
@@ -0,0 +1,60 @@
# Dev/test root-helper readiness, not package acceptance
`python3 deploy/vm_root_bootstrap.py inspect` is read-only. `build` creates a
private minimal Docker context containing only Rust sources, pinned Cargo files,
migrations and the reviewed APT-tool sources; it never includes credentials.
`install` is the separately authorized create-only systemd bootstrap. It refuses
existing root-helper paths, unresolved VM jobs, an active agent/tunnel, changed
agent identity/signing authority or incompatible artifacts. It never resets an
identity/journal or authorizes a job. Do not retry a partial install blindly.
Fixed resources: `/usr/local/libexec/rmm-privileged-helper`, root-owned 0600
`/etc/rmm/helper-dev-test-v1.json` and `helper-signing-key-v1.json`, private root
state `/var/lib/rmm-helper`, `rmm-helper-dev-test.service`, and root-owned agent
drop-in `10-dev-helper-v1.conf`. The drop-in adds only
`RMM_HELPER_SOCKET=/run/rmm-helper/control.sock`; it does not restart the agent.
The helper's root-owned socket is 0660/group `rmm-agent` in a 0750 root-owned
runtime directory. `SO_PEERCRED` separately checks exactly the provisioned
non-root agent UID; a connect-only readiness probe is not a signed IPC test.
Public signing authority comes from the authenticated, CA/name-verified server
GET and must match the preserved agent binding. No server private key is copied.
Helper trust/ledger remain inaccessible to the network service. The helper is
enabled for its expressly named dev/test service but stopped after readiness
only when its own consumption ledger is confirmed empty. No agent/tunnel is
started. Creation lists, native measurements and sanitized failure class/line
numbers are stored privately; raw stderr, payloads and exceptions are withheld.
## Intentionally disabled execution gates
The dev/test config allows only the future exact `rmm-mvp-test.service` unit;
this bootstrap **does not create or start that test service**. Root scripts and
reboot are disabled. `apt_provider` is null. Installing the compiled-in provider
via `--install-apt-provider` creates trusted code/hook and empty sealed-store
directories/metadata only. No package, fixture archive, baseline, active context,
grant or native-acceptance record is generated. `inspect-runtime` and
`print-config` are measurements, not authority. Their hashes belong to a future
explicitly UI-approved immutable plan.
`inspect-sandbox` is invoked read-only as root in the parent environment. A veto
there is expected and reported as **not passed**, never bypassed with fabricated
`host-namespaces.json`/sandbox-ready files. The actual provider requires its
signed worker context before building the final sandbox.
The new readiness unit preserves restrictive protections; it is deliberately
**not APT-execution-capable**. Package setup requires CAP_SYS_ADMIN for private
mount/PID/network namespaces and mount setup, CAP_MKNOD for the four basic device
nodes, and write access to the actual fixture package payload/dpkg/APT stores.
The final package child must then retain exactly CHOWN, DAC_OVERRIDE, FOWNER,
FSETID, SETGID, SETUID, SETPCAP and SETFCAP, NNP and seccomp; no SYS_ADMIN,
SYS_BOOT, KILL or MKNOD may remain. Host control sockets must be hidden and the
private PID1/mount/network checks must pass. The readiness unit's deny-mount
syscall policy and ProtectSystem=strict prevent this setup. Do not loosen them
blindly: a separately reviewed native APT runner/profile is still required.
Future backend root planning, manifest preservation, helper policy changes and
agent capability negotiation do not follow from installation. Reconnect/sync
must be ready before starting new jobs. Every service/package/update/reboot or
new attempt still needs its own fixed plan and actual dev/test WebUI approval.
Actual commands/results are recorded in `docs/implementation-status.md`; this
document alone claims no VM execution or Linux-MVP acceptance.
+227
View File
@@ -0,0 +1,227 @@
# 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.
+27
View File
@@ -0,0 +1,27 @@
{
"profile": "apt_only",
"binding": {
"tenant_id": "REPLACE-TENANT-UUID",
"asset_id": "REPLACE-ASSET-UUID",
"agent_id": "REPLACE-AGENT-UUID",
"enrollment_generation": 1,
"assignment_version": 1,
"public_key_hex": ""
},
"signing_key_file": "/etc/rmm/helper-signing-key.json",
"agent_uid": 993,
"socket_gid": 993,
"socket": "/run/rmm-apt-helper/helper.sock",
"state": "/var/lib/rmm-helper",
"allowed_services": [],
"allow_reboot": false,
"allow_root_scripts": false,
"apt_provider": {
"schema_version": 1,
"execution_profile": "dev-test",
"allow_fixture_bootstrap": true,
"allowed_recipes": ["rmm-apt-fixture-install-1.0", "rmm-apt-fixture-update-1.1"],
"runtime_sha256": "REPLACE-WITH-REVIEWED-RUNTIME-OBJECT-SHA256",
"apt_config_sha256": "REPLACE-WITH-REVIEWED-CONFIG-BYTES-SHA256"
}
}
+96
View File
@@ -0,0 +1,96 @@
#!/usr/bin/env python3
"""Offline, create-only package installation. Never starts/enables services.
Default staging is testable without root. A live filesystem install requires
both --root / and --install-live plus a preexisting dedicated system account.
No device/private signing keys or bearer credentials are accepted as inputs.
"""
from __future__ import annotations
import argparse
import os
from pathlib import Path
import pwd
import stat
def directory(path: Path, mode: int) -> None:
if not path.exists():
path.mkdir(mode=mode)
metadata = path.lstat()
if not stat.S_ISDIR(metadata.st_mode) or metadata.st_mode & 0o022:
raise ValueError("unsafe installation directory")
if metadata.st_uid != os.geteuid():
raise ValueError("installation directory has unexpected owner")
def create(path: Path, data: bytes, mode: int) -> None:
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, mode)
with os.fdopen(fd, "wb") as stream:
stream.write(data)
stream.flush()
os.fsync(stream.fileno())
fd = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
try:
os.fsync(fd)
finally:
os.close(fd)
def elf(path: Path) -> bytes:
if path.stat().st_size > 100 * 1024 * 1024:
raise ValueError("binary size limit")
data = path.read_bytes()
if len(data) < 64 or data[:6] != b"\x7fELF\x02\x01" or data[18:20] != b"\x3e\x00":
raise ValueError("expected Linux x86-64 ELF artifact")
return data
def install(root: Path, agent: Path, ca: Path, helper: Path | None, live: bool) -> None:
if not root.is_absolute() or ".." in root.parts:
raise ValueError("absolute installation root required")
if root == Path("/") and not live:
raise ValueError("live installation requires --install-live")
if live and (root != Path("/") or os.geteuid() != 0):
raise ValueError("live installation requires root and --root /")
account = pwd.getpwnam("rmm-agent") if live else None
if account is not None and (account.pw_uid == 0 or account.pw_gid == 0):
raise ValueError("rmm-agent must be a dedicated unprivileged account")
# Validate all inputs before creating anything. CA is public, never private.
agent_data = elf(agent)
helper_data = elf(helper) if helper else None
ca_data = ca.read_bytes()
if len(ca_data) > 65536 or b"-----BEGIN CERTIFICATE-----" not in ca_data or b"PRIVATE KEY" in ca_data:
raise ValueError("expected public CA certificates only")
directory(root, 0o755)
for relative in ["usr", "usr/local", "usr/local/libexec", "etc", "etc/rmm",
"etc/systemd", "etc/systemd/system", "var", "var/lib"]:
directory(root / relative, 0o755)
units = Path(__file__).parent
files = [("usr/local/libexec/rmm-agent", agent_data, 0o755),
("etc/rmm/ca.pem", ca_data, 0o644),
("etc/systemd/system/rmm-agent.service", (units / "rmm-agent.service").read_bytes(), 0o644)]
if helper_data is not None:
files += [("usr/local/libexec/rmm-privileged-helper", helper_data, 0o755),
("etc/systemd/system/rmm-privileged-helper.service", (units / "rmm-privileged-helper.service").read_bytes(), 0o644)]
# Never overwrite binaries, CA, service units, config or enrollment state.
if any((root / relative).exists() or (root / relative).is_symlink() for relative, _, _ in files):
raise ValueError("existing installation requires a separate controlled upgrade")
for relative, data, mode in files:
create(root / relative, data, mode)
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, required=True)
parser.add_argument("--agent-binary", type=Path, required=True)
parser.add_argument("--helper-binary", type=Path)
parser.add_argument("--ca-file", type=Path, required=True)
parser.add_argument("--install-live", action="store_true")
args = parser.parse_args()
install(args.root, args.agent_binary, args.ca_file, args.helper_binary, args.install_live)
print("Package files installed. No account, device identity or authorization config created; services not started/enabled.")
if __name__ == "__main__":
main()
+35
View File
@@ -0,0 +1,35 @@
[Unit]
Description=RMM unprivileged outbound Linux agent
After=network-online.target time-sync.target
Wants=network-online.target
[Service]
Type=simple
User=rmm-agent
Group=rmm-agent
StateDirectory=rmm-agent
StateDirectoryMode=0700
UMask=0077
Environment=RMM_AGENT_STATE=/var/lib/rmm-agent
Environment=RMM_CA_FILE=/etc/rmm/ca.pem
Environment=RMM_TRANSPORT=auto
Environment=RMM_EXTENDED_INVENTORY=1
Environment=RMM_CONNECT_ADDR=127.0.0.1:18443
EnvironmentFile=-/etc/rmm/agent.env
ExecStart=/usr/local/libexec/rmm-agent
Restart=on-failure
RestartSec=10
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
CapabilityBoundingSet=
AmbientCapabilities=
[Install]
WantedBy=multi-user.target
+52
View File
@@ -0,0 +1,52 @@
[Unit]
Description=RMM dedicated fixture APT helper (no generic root commands)
After=local-fs.target
[Service]
Type=simple
User=root
Group=rmm-agent
Environment=RMM_HELPER_CONFIG=/etc/rmm/apt-helper.json
ExecStartPre=/usr/local/libexec/rmm-privileged-helper --probe-native
ExecStart=/usr/local/libexec/rmm-privileged-helper
WorkingDirectory=/
RuntimeDirectory=rmm-apt-helper
RuntimeDirectoryMode=0750
StateDirectory=rmm-helper rmm-apt-transaction
StateDirectoryMode=0700
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
PrivateNetwork=true
PrivateDevices=no
DevicePolicy=strict
DeviceAllow=/dev/null rwm
DeviceAllow=/dev/zero rwm
DeviceAllow=/dev/random rwm
DeviceAllow=/dev/urandom rwm
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX
SystemCallArchitectures=native
RestrictNamespaces=mnt pid net
AmbientCapabilities=
CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_FOWNER CAP_FSETID CAP_SETGID CAP_SETUID CAP_SETPCAP CAP_SETFCAP CAP_SYS_ADMIN CAP_MKNOD
# Trusted setup needs mount/unshare/fork/capset/prctl/seccomp. There is deliberately
# no outer @mount deny; the irreversible worker filter denies it after setup.
SystemCallFilter=~@reboot @module @raw-io @swap @clock @debug
# Existing helper clock trust reads adjtimex(modes=0). Mutating adjtimex still
# requires CAP_SYS_TIME, absent from the bounding set; other @clock calls denied.
SystemCallFilter=adjtimex
SystemCallErrorNumber=EPERM
ReadWritePaths=/var/lib/dpkg /var/lib/rmm-helper /var/lib/rmm-apt-transaction /usr/share/rmm-mvp-test
Restart=on-failure
RestartSec=5s
TimeoutStopSec=infinity
KillMode=process
[Install]
WantedBy=multi-user.target
+35
View File
@@ -0,0 +1,35 @@
[Unit]
Description=RMM dev-test root helper readiness (APT execution disabled)
After=time-sync.target
[Service]
Type=simple
User=root
Group=rmm-agent
StateDirectory=rmm-helper
StateDirectoryMode=0700
RuntimeDirectory=rmm-helper
RuntimeDirectoryMode=0750
UMask=0077
Environment=RMM_HELPER_CONFIG=/etc/rmm/helper-dev-test-v1.json
ExecStart=/usr/local/libexec/rmm-privileged-helper
Restart=no
NoNewPrivileges=true
PrivateTmp=true
PrivateNetwork=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX
CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_FOWNER CAP_FSETID CAP_SETGID CAP_SETUID CAP_SETPCAP CAP_SETFCAP
AmbientCapabilities=
SystemCallFilter=~@mount @reboot @swap @raw-io @module @clock @debug
# This readiness unit intentionally CANNOT set up the APT worker's namespaces
# or device nodes. Do not remove these restrictions to make a demo pass.
# apt_provider remains null until a separately reviewed native runner exists.
[Install]
WantedBy=multi-user.target
@@ -0,0 +1,29 @@
[Unit]
Description=RMM independently authorizing local privileged executor
After=time-sync.target
[Service]
Type=simple
User=root
Group=rmm-agent
StateDirectory=rmm-helper
StateDirectoryMode=0700
RuntimeDirectory=rmm-helper
RuntimeDirectoryMode=0750
UMask=0077
Environment=RMM_HELPER_CONFIG=/etc/rmm/helper.json
ExecStart=/usr/local/libexec/rmm-privileged-helper
Restart=on-failure
RestartSec=10
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
RestrictAddressFamilies=AF_UNIX
[Install]
WantedBy=multi-user.target
+311
View File
@@ -0,0 +1,311 @@
# Agent/helper runtime — integrated source, VM acceptance pending
This is the current runtime contract. It supersedes the earlier module-only
handoffs in `README.md` and `tests/agent_sync/README.md`. No installation, target
job, service/reboot/package mutation, SSH tunnel or server restart was performed
by this integration. Actual VM execution/acceptance belongs to the next worker.
Nothing here approves an RMM job or substitutes for the WebUI approval boundary.
## Binaries and complete CLI/environment
Both binaries support `--help`; unknown arguments fail closed. Normal agent
operation has no positional arguments. Planned bootstrap invocation:
```text
RMM_AGENT_STATE=/var/lib/rmm-agent
RMM_CA_FILE=/etc/rmm/ca.pem
RMM_CONNECT_ADDR=127.0.0.1:18443
RMM_TRANSPORT=https
/usr/local/libexec/rmm-agent
```
These are environment assignments, not an instruction to source a credential
file. The trusted CA and TLS name **rmm-dev.internal** are always checked. TCP
override changes neither DNS/SNI nor certificate verification. No proxy trust,
invalid-certificate bypass or public Docker port is introduced.
| Variable | Meaning/default |
|---|---|
| `RMM_AGENT_STATE` | Private 0700 owned agent state; default `devstate/agent` |
| `RMM_CA_FILE` | Public trusted CA; default `devstate/pki/ca.pem` |
| `RMM_CONNECT_ADDR` | Parsed TCP SocketAddr; default `127.0.0.1:18443` |
| `RMM_TRANSPORT` | `auto` (default), `wss`, or `https`; HTTPS can be explicitly selected for VM acceptance |
| `RMM_ENROLLMENT_TOKEN_FILE` | First registration only; remove the bootstrap token after enrollment |
| `RMM_JOB_BINDING_FILE` | Optional private agent-owned JSON Binding; absent means passive, no job capabilities |
| `RMM_JOB_SIGNING_KEY_BOOTSTRAP=1` | Authenticated device-mTLS GET, using the current rotation-store identity; pins without replacing existing trust |
| `RMM_HELPER_SOCKET` | Configured general helper socket, e.g. `/run/rmm-helper/control.sock` |
| `RMM_HELPER_POLICY_FILE` | Root-owned, agent-readable public general policy pin; required with general socket |
| `RMM_APT_HELPER_SOCKET` | Dedicated fixed `/run/rmm-apt-helper/helper.sock`, never generic fallback |
| `RMM_APT_HELPER_PROOF_FILE` | Root-owned public APT stack/profile/identity pin; see `apt-helper-README.md` |
| `RMM_LOG_UNITS_FILE` | Private agent-owned JSON array of exact allowed service units for unprivileged live logs |
| `RMM_EXTENDED_INVENTORY` | `1` by default with the now-compatible backend, `0` for legacy base-only JSON |
| `RMM_AGENT_PROFILE` | `development` required only for the rotation-test interval override |
| `RMM_ROTATION_TEST_AFTER_SECONDS` | Positive development-only certificate-age trigger; never bypasses chain/expiry/EKU/key/identity verification |
Binding fields: tenant_id, asset_id, agent_id, enrollment_generation,
assignment_version, public_key_hex. Device/asset must match enrollment. Empty key
is allowed only with authenticated signing-key bootstrap; later startup must
reauthenticate that bootstrap or use a fully provisioned binding. Key response is
Ed25519/schema 1/raw 32-byte key with SHA-256 key ID, bounded and no redirects.
The immutable agent cache is `job-signing-key.json`. Signing-pin replacement and
identity/assignment recovery are controlled provisioning operations, not automatic
trust in a key from a job. Helper trust stays independently root-provisioned.
The unit leaves the job-binding optional in `/etc/rmm/agent.env`, allowing a first
passive enrollment. Set binding/key-bootstrap/helper variables only after the
authenticated operator resolves the enrolled IDs and provisions their pins.
Do not delete an old identity/journal to get a new first-session shortcut.
## Integrated transport and sync
One bounded actor and one dispatcher serve WSS and HTTPS with identical envelopes,
journal, result receipts, cancellation and signature checks. `auto` tries WSS
first and falls back only after two typed HTTP upgrade-block classifications;
401/403, TLS/identity failures and ambiguous errors never select a bypass.
WSS Ping/Pong are handled. HTTPS uses the existing MessageBatch/25-second poll
contract. Poll cancellation cannot create a new attempt; fresh heartbeat IDs/
sequences are never reused or queued as offline telemetry. Actor queues are bounded.
Every authenticated Hello advertises `rmm.sync.v1` and closes all local effect
gates. Agent obtains actual root snapshots, durably reserves the fresh SyncRequest,
checks exact signed SyncResponse bytes and all device/channel/boot/checkpoint/
request-hash/time bindings, commits targeted journal/receipt changes, applies its
own consumption decisions, forwards the **original** signed response plus original
request protobuf to every configured helper, then confirms actual applied root
checkpoints. No generic ready boolean opens either process.
Both root profiles share actual DB/lock inodes. They join an unchanged pending
root capture created after both process births, so ONE signed response/checkpoint
can be independently applied by both. A new process never inherits readiness
from the shared DB. Stale process captures are fenced; known outcomes may unlock
specifically while an unknown retains the resource and global gates stay closed.
Consumed grant/attempt tombstones are never removed.
Scheduler AND immediate worker effect admission check the current signed lease;
the worker also rechecks fresh grant/time and the disconnect/rotation atomic fence.
Helper checks its own process gate under the same executor guard before consumption.
Unknown, missing authoritative history, clock failure and rollback remain closed.
Clock/helper sync failure does not stop independent passive heartbeat/inventory
traffic. Sync retries are bounded, happen on fresh inventory/result ACK and on a
lease timer, and never retry a lost permit request as a new grant.
After reboot, old/new boot ID alone is not success. Fresh current-boot inventory
is durably ACKed, a new signed decision must bind the persisted original boot and
current authenticated boot plus inventory evidence, then each helper independently
applies that specific canonical terminal outcome/unlock. Thus an initial negative
sync does not deadlock waiting forever without the post-inventory resync.
Result envelopes are archived before concrete ACK deletion in one SQLite
transaction. Historical message identity/output is retained for reconciliation.
Inventory mapping preserves source/time/quality/completeness and unsupported states.
Live journal permission warnings become permission_denied, not a fake empty success.
## Helper bootstrap/policy inspection
Helper normal daemon: `RMM_HELPER_CONFIG=/etc/rmm/helper.json` (root-owned 0600).
Both profiles use `/var/lib/rmm-helper/consumption.sqlite` and `executor.lock`.
Helper config uses the existing binding, optional independent signing_key_file,
agent_uid, socket_gid, socket, shared state, allowed_services, allow_reboot,
allow_root_scripts; APT adds its existing sealed apt_provider configuration.
Public general pin, **planned command, not executed on VM here**:
```text
RMM_HELPER_CONFIG=/etc/rmm/helper.json /usr/local/libexec/rmm-privileged-helper --inspect-general-profile
```
Install the exact JSON as root:rmm-agent 0640 in non-writable root-owned parents,
then set RMM_HELPER_POLICY_FILE. It binds profile, device identity/key and exact
policy hash. General policy probe uses root socket/peer credentials and a fresh
challenge; capabilities reflect actual policy/interpreter availability. Root
scripts remain default-off broad administration. Services are exact allowed
running/stopped units with >=180s runtime, reboot separately enabled with >=60s.
Root jobs are NEVER relabelled into agent_service.
APT install/probe/inspection modes and profile sandbox remain exactly documented
in `apt-helper-README.md`. Both daemons need this same installed build and reviewed
new proof hashes (binary bytes are part of the APT proof). Prefetched sealed
archives, receipts predating the grant and exact baselines are still prerequisites;
this integration introduces no unsafe generic APT download/install/simulation path.
Root native-acceptance and accepted-recipe/manifest capabilities come only from
authenticated real readiness. Successful native acceptance triggers a controlled
reconnect to advertise newly accepted recipes; periodic safe capability refresh
also reconnects rather than silently changing the Hello contract.
## Passive APT planning and declarative no-change
The normal extended inventory worker now runs at startup and every 60 seconds
(one inflight collector; not in the heartbeat handler). Unacknowledged durable
traffic backpressures new collection without deleting old data; job results and
control receipts retain priority. It includes the fixed
`linux.apt.planning` scope from `root-helper:apt_planning_v1`. This currently
refreshes the existing extended inventory scopes too; their actual individual
source timestamps/quality remain intact. There is no arbitrary package query,
requested live diagnosis or software effect hidden in this collector.
`apt_planning_v1` uses the existing UID-authenticated dedicated Unix socket,
fresh challenge, device/generation/signing-key identity, root peer and separately
root-provisioned stack pin. Its response is the readiness envelope with a typed
`planning` result and **empty capability/acceptance fields**. It does not depend
on a prior native-acceptance record and cannot create one. Root validates the
installed code, exact runtime/config policy pins and actual archive bytes, sizes,
ownership/modes/link count and private prefetch receipts. No artifact is fetched
or installed by this RPC. Administratively stage the known fixture archives via
`provision-fixture-store` before planning/the final 60-second grant.
The fixed metadata child has a 4-second whole-process/output budget (32 KiB),
the socket has 5-second IO limits, and root measurement timestamps are preserved.
Dirty dpkg updates/triggers, foreign locks, unsafe/missing receipts, permission
failure, timeout or missing helper yield an unknown observation with null data,
not fake hashes or accepted capability. Runtime policy drift fails closed.
Complete observations contain the suite's `fixture_package`, `baseline_sha256`,
`sealed_baseline_sha256`, `status_fingerprint`, `dpkg_updates_empty`,
`pending_triggers_empty`, `runtime`, `runtime_sha256`, `provider_sha256`,
`hook_sha256`, `apt_config_sha256` and `prefetch`. The full package baseline stays
root-private at `baselines/<sha256>.json`; only hashes, fixture projection and
minimal public runtime/artifact pins cross the wire. Stable sampling is checked
before and after content-addressed exclusive write/file+directory fsync; existing
identical seals are verified, never overwritten. This is passive metadata, not
job authority. The ordinary durable inventory outbox/ACK path persists it.
Normal accepted fixture `ensure_package`/`apply_updates` may return
`POSTCONDITION_ALREADY_MET`, `changed=false`, `already_desired=true`,
`postcondition_already_met=true`, `transaction_executed=false` only when the
**entire selected set** is independently installed at its exact target version
and architecture, clean, matches the current approved baseline/fingerprint and
has the expected fixture payload. Root signature, all original bindings,
expiry/sync/local-policy/resource gates, all manifest/code/runtime/artifact pins,
native accepted-recipe record and durable grant/attempt consumption remain
mandatory. Only the historical `old_version` condition is skipped in this
no-mutation branch. No APT/hook/native launch/effect marker is created. A foreign
lock, dirty/unknown state or changed baseline cannot become success; native
acceptance itself never uses this branch. Other versions still follow the
unchanged no-reinstall/no-downgrade/no-remove mutation guards.
VM suite owner must update its absent/1.0-only adapter: after native update to
1.1, a normal exact desired-1.1 job must use the accepted update recipe with a
fresh planning seal. A desired-1.0 job on 1.1 is still correctly denied; this
implementation does not authorize removal/downgrade to make a stale test pass.
No backend/domain/protobuf signatures or plan bytes have been changed.
Provider source changes change the embedded provider/helper/stack/runtime pins.
Deploy both helpers from this build and provision reviewed new proof/policy
pins **before** native acceptance; old native records cannot silently certify
new runtime bytes. Manifest schema 2 / transaction schema 1 / fixture archives
1.0 and 1.1 (20,672 bytes, unchanged hashes) remain unchanged.
These are implemented source/local-fixture semantics, not VM or MVP acceptance.
## Certificate rotation and recovery
`RMM_AGENT_STATE/certificates/current.json` is the authoritative atomic selector
over private versioned device key/cert files. Existing enrolled files initialize
the store exactly once; later connections/bootstrap use the selected identity.
Rotation checks chain, current validity, exact agent CN, clientAuth purpose and
public/private key match. It persists one pending key/CSR and retries those SAME
CSR bytes after response loss. A verified swap closes the old actor/effect fence
and requires a new Hello/Sync. Agent/enrollment IDs and independent job/helper
signing pins do not change. Expired/revoked/invalid certs remain blocked and need
authorized identity recovery; no auto-reenrollment or TLS downgrade.
## Verification boundaries / concrete remaining policy issue
Local Rust source/unit/integration tests cover actual loopback mTLS dispatcher
WSS/HTTPS clean reconnect, Ping, forged sync rejection, passive traffic with an
untrusted effect clock, journal reopen/replay and independent helper checkpoint/
outcome/boot checks. Unsafe OS providers are mocked or denied; no local service,
APT install or reboot was executed. This is not a real WebUI-approved VM result,
native package acceptance, production auth acceptance or full Linux-MVP sign-off.
Concrete backend policy limitation, not bypassed here: `RootScope::permits` in
`crates/server/src/root_policy.rs` does not match `Action::QueryLogs` and falls
through to false. The typed, bounded root helper log handler exists, and the
unprivileged allowlisted path is live, but a root live-log plan will be denied by
that backend policy until its owner adds an explicit permitted scope. Do NOT
work around it by relabelling identity, direct approval or a generic root shell.
## Executed local verification
Using `/home/Kevin/.cargo/bin/cargo`, actually passed during integration:
```sh
cargo test -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux --all-targets --locked
cargo clippy -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux --all-targets --locked -- -D warnings
cargo build -p rmm-agent -p rmm-privileged-helper --locked
cargo fmt -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux -- --check
python3 tests/agent_jobs/test_install.py
target/debug/rmm-agent --help
target/debug/rmm-privileged-helper --help
```
111 executed Rust test cases passed (including reused transport tests), two
create-only installer guard tests passed, both debug binaries built and both
help commands returned successfully without loading secret configuration. No
warnings/type errors were suppressed. A boxed tungstenite HTTP-response test
constructor was corrected, not bypassed. No coverage percentage was measured.
Coverage boundaries: real loopback TLS/dispatcher WSS and HTTPS reconnect and
forged sync rejection are exercised; helper cryptography/checkpoints/two-process
shared signature and replay/unknown/reboot decisions use real SQLite/signatures
with local fixtures. Native service/APT/reboot effects and positive root UID-0
daemon/VM RPC acceptance are NOT substituted by these tests. The built artifacts
are `target/debug/rmm-agent` and `target/debug/rmm-privileged-helper`; a reviewed
VM-compatible release artifact still needs the target worker's ELF/glibc/library
preflight and actual authorized VM run.
## Executed local verification — planning/no-change increment
After **all** source changes, the following complete targeted block passed with
`/home/Kevin/.cargo/bin` on PATH (2026-11-12):
```sh
cargo test -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux --all-targets --locked
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests/apt_transaction -p 'test_*.py' -v
cargo clippy -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux --all-targets --locked -- -D warnings
cargo fmt -p rmm-agent -p rmm-privileged-helper -p rmm-agent-linux -- --check
cargo build -p rmm-agent -p rmm-privileged-helper --locked
cargo build -p rmm-agent -p rmm-privileged-helper --release --locked
python3 tests/agent_jobs/test_install.py
target/debug/rmm-agent --help
target/debug/rmm-privileged-helper --help
```
Results: **115 Rust tests**, **56 Python APT tests**, **2 installer guard tests**
passed; warning-denying all-target Clippy and formatting passed; both Debug and
Release binaries built; both help commands succeeded. Separate final AST parsing
passed for **8 Python files**. No full workspace/backend/web test suite was run.
New regressions cover shared Python/Rust canonical golden bytes/hash, receipt
and timestamp freshness, private content-addressed seal reuse/change without
full-baseline disclosure, sampling drift/dirty/foreign-lock/bad-artifact failure,
normal exact already-desired install/update postconditions, no launch/effect
markers, old-version mutation rejection, wrong architecture/newer version,
audit/payload/expiry rejection, no-change outcome binding and durable duplicate
grant/attempt rejection, honest missing-helper data and collection backpressure.
Root ownership/kernel state and unsafe native package processes are mocked;
existing harmless unprivileged seccomp tests really execute. No native host
package mutation, root systemd/probe/VM action, approval or reboot was performed.
Earlier intermediate failures were corrected, not suppressed: the inherited two
unformatted source edits, a mock reader missing the `limit` keyword argument,
and a newly inserted function accidentally inheriting a test-only cfg attribute.
The final complete block above passed after these corrections.
Final artifact SHA-256 (native developer-PC builds; **not** Bookworm/VM proof):
| Artifact | SHA-256 |
|---|---|
| `target/debug/rmm-agent` | `90a4eab064301740cd938a41a76a510ad3b4abc3e48a188ba12bfe22f123266c` |
| `target/debug/rmm-privileged-helper` | `54db2fe17841fef9af48bbeb446f45bda52f62e442a4900e0543e358095900b7` |
| `target/release/rmm-agent` | `eac5434fd7a1e509c0971e4e05d4e1aedbde1bb90f7d7a8f9ec4d48ab4d34597` |
| `target/release/rmm-privileged-helper` | `581a033478b41365066df2dc9ac0d11e314160909b5fab612be0be97be1bbbdc` |
| `tools/apt-transaction/apt_transaction.py` | `57b695bf57ea2703393e39f92a1b6ef2314b4838f3dfb29e4e70da79687c9987` |
Remaining: suite-owner adapter update for exact desired 1.1 after native upgrade,
reviewed deployment/new pins, actual dedicated-profile metadata RPC and native
UI-approved fixture/no-change VM proof, target ELF/library compatibility, and
VM resource/retention measurements for the new 60-second extended collection.
No real current baseline change was induced on the host/VM: freshness tests use
changed temporary/mock package state, not a disguised package installation.
Linux-MVP and production acceptance remain open. Backend Root QueryLogs policy
is owned by its separate worker and was neither changed nor reverified here.