Document the accepted MVP and retire superseded development plans
Rust development slice / linux (push) Failing after 14s

This commit is contained in:
2026-11-18 17:21:12 +01:00
parent f37b6dc4f7
commit 6963ad332c
188 changed files with 370 additions and 34933 deletions
+18 -269
View File
@@ -1,277 +1,26 @@
# Linux agent/helper bootstrap contract (not a VM acceptance)
# Linux-Agent betreiben
**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.
Der Linux-Client für `x86_64-unknown-linux-gnu` meldet sich ausgehend per mTLS am Gerätegateway. Als Systembenutzer `rmm-discovery` liefert er Heartbeats und Inventar, holt genehmigte Shell-Skripte ab und meldet Ausgabe und Exitcode zurück. Der optionale Root-Helper gehört zur gleichen signierten Releaseversion wie der Agent.
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.
## Installation
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.
1. In der WebUI den Zielkunden wählen, **Gerät aufnehmen** öffnen und einen Einmalcode erzeugen.
2. Auf dem x86-64-Linux-Gerät mit systemd und Python 3 den dort angezeigten Linux-Befehl ausführen. Er lädt `/install/linux.sh` über HTTPS und ruft es mit `sudo sh` und dem Bootstrap-Ursprung des Servers auf. Den Einmalcode am verdeckten Prompt eingeben.
3. Für Root-Skripte die Administratoroption der WebUI wählen. Sie ergänzt `--enable-admin-scripts`. Auf einem bereits eingeschriebenen Gerät lässt sich der Installer mit demselben Ursprung und dieser Option erneut ausführen. Die Geräteidentität bleibt erhalten.
4. Im Gerätedetail Hostname, Kunde, Agentversion und letzten authentisierten Kontakt kontrollieren. Für einen Root-Auftrag braucht das Gerät den gemeldeten Root-Kontext und eine passende zentrale Geräteregel. Ein MCP-Token benötigt zusätzlich die passenden Rechte für diesen Kunden. [MCP-Zugang](../../docs/public-access.md)
## Built artifacts and process configuration
## Selbstupdate und Diagnose
Planned build command (the debug test/build commands actually executed are listed
in `tests/agent_jobs/README.md`):
`rmm-discovery-update.timer` ruft den Releasebestand nach dem Booten und anschließend alle fünf Minuten mit einer zufälligen Verzögerung von bis zu 20 Sekunden ab. Vor dem Wechsel prüft der Updater das signierte Paket und die Auftragsjournale. Eine neue Generation wird durch den frischen Kontakt des Agenten bestätigt. Scheitert die Aktivierung, wählt der Updater den Vorgänger. Ein über den Installer aktivierter Helper wechselt zusammen mit dem Agenten. [Installer und Aktualisierungslogik](../../crates/server/src/bootstrap/lifecycle.py)
```sh
cargo build --release -p rmm-agent -p rmm-privileged-helper
```
| Am Gerät prüfen | Befehl oder Pfad |
| --- | --- |
| Agent und letzter Update-Lauf | `systemctl status rmm-discovery-agent.service rmm-discovery-update.timer` und `journalctl -u rmm-discovery-update.service -n 50` |
| Installierter Root-Helper | `systemctl status rmm-discovery-managed-script-helper.service` |
| Aktive Generation | `readlink -f /opt/rust-discovery-client/current` |
| Zustand und Identität | `/var/lib/rmm-discovery` gehört dem Dienstkonto. Bei einem Binärwechsel bleiben Gerätedaten, Schlüssel und Journal erhalten. |
| Tatsächlicher Neustart | `cat /proc/sys/kernel/random/boot_id` vor und nach dem Neustart vergleichen. Anschließend denselben Agenten am Gateway und das Ergebnis eines nachfolgenden Skripts prüfen. |
Both binaries are environment-configured, **not** positional-argument CLIs.
Die Bibliotheksrevision „Linux neu starten“ kündigt den Neustart mit einer Minute Vorlauf an. Eine Datei unter `/tmp` kann beim Booten gemäß lokaler Systemkonfiguration verschwinden. Für die Beurteilung eines Auftrags zählt die Ausgabe seines konkreten Versuchs. [Native MCP-Abnahme](../../docs/evidence/mcp-scoped-script-requests-20261118.json)
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.
Für einen neuen Release oder eine direkte Entwicklungsbereitstellung den gemeinsamen [Entwicklungsweg](../../docs/development.md) verwenden.
-60
View File
@@ -1,60 +0,0 @@
# 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
@@ -1,227 +0,0 @@
# 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.
-241
View File
@@ -1,241 +0,0 @@
# Explizite Hostwartung mit full_maintenance_v1
Stand 2026-11-14, Spezifikation1.20. Die Batch-Skriptkonsole und der unabhängig
geprüfte Fullhelper-Binärpinfix sind implementiert, neu quellqualifiziert und nach
tatsächlichem Linux-Unitlauf erhaltend auf der Cloud-Linux-VM bereitgestellt.
Agent, General und Full laufen mit den geprüften Images; signierter Folgeabgleich
und WebUI-genehmigter Fulljob bleiben separat offen. Tatsächliche Teilfehler,
Fortsetzungen und unveränderte Originalbelege:
[Bootstrap-Ergebnisse](../../docs/script-console-bootstrap-results.md).
Cloud-Linux-VM zuerst, Windowsgast separat; Notebook ausschließlich Entwicklung.
## Aktueller korrigierter lokaler Nachweis
Der neue eigenständige Pack liegt privat unter
`devstate/script-console-qualification/run-29461892-343f-42f4-b469-88703535425e/`.
Manifest-SHA256:
`ddd1a78d1cd289b02b1f98572f9652171ec00be84e01ce099fd722d689bcaacd`.
158 vollständige Compiler-/Include-/Fixture-/Deploymentinputs vor/nach identisch.
Sourcearchiv-SHA256:
`fcb57f69ad81ea4acde15af6022d5c2da32f5699ebd39886c530c77882b369cc`.
Tatsächlich ausgeführt: Formatprüfung, Linux-Workspace-Alltargets-Clippy mit
`-D warnings`,285 lokale Tests bestanden (5DB-Fälle zunächst ausgelassen), danach
sämtliche45 Serververträge inklusive dieser5 gegen frisches isoliertes PostgreSQL
bestanden (0ignored). Windows-GNU-Alltargets-Clippy mit -Dwarnings im Default-
und SYSTEM-Helperprofil bestanden. Kein geänderter Test unterdrückt; die neue
Imageprüfung führt auch bei nicht vertrauenswürdigem Dateibesitz echte
Verweigerungsassertions aus, keinen stillen Early-return-Skip.
Neue tatsächliche Linux-Unitlisten: Domain22, Linuxruntime16, Helperpolicy6,
Serververträge45. Auf Cloud-Linux ohne isolierte DB erwartet:84PASS und5explizite
DBignored; diese5 sind separat im lokalen45er-DB-Lauf tatsächlich bestanden.
Alle vier vollständigen Listen müssen vor irgendeinem Unitstart geprüft sein.
Linux-Release-Helper SHA256
`79442727c3ba31cda02a8bc0e67481f14db9f39fc07520a880a90b64f10f1eaf`;
Agent `0a7ad6eefaefda79ee80b6a41b2df904e9e7f50ae6ebeed01b98c25b6ce5c06f`;
Server `610017637a9f9e55a6cb3cd8264937b953996af84e86dd49f2ea00c8e59739cd`.
Keine dieser neuen Binaries ist durch den Builder auf einem Ziel installiert.
Native Cloud-Linux-Units bestanden anschließend tatsächlich; siehe den separaten
Beleg unten. Auch die späteren 36+7 Windows-Units bestanden separat nativ:
[Windows-Nachweis und Grenzen](../../docs/script-console-windows-link.md).
Laufende Windows-SYSTEM-Runtime und WebUI-genehmigter FullMaintenancejob sind
eigenständige, dadurch nicht ersetzte Nachweise.
## Frühere lokale Nachweise und der danach behobene Binärpinbefund
Das eingefrorene Paket liegt ausschließlich privat unter
`devstate/script-console-qualification/run-de34d47c-985e-460c-b18c-3f0d1b3fd315/`.
Manifest-SHA256:
`60a50262f9f8d85c11eb58e1a9e0f6e03be6cd5db7a59bc1745fb7d9dc8a6f65`.
157 Compiler-, Include-, Fixture- und Deploymentinputs wurden vor/nach dem
vollständigen Lauf identisch geprüft. `reviewed-sources.tar.gz`:
`ef822b2e2ec6f8ad3d828f0923b2aa886d462fba328affb61bd80e98acf2c357`.
Tatsächlich lokal ausgeführt: Formatprüfung; Linux-Workspace-Clippy mit allen
Targets und `-D warnings`; Workspace284PASS bei fünf zunächst ausgelassenen
DB-Fällen; anschließend sämtliche45 Servertests mit `--include-ignored` in
frischem isoliertem PostgreSQL17.6:45PASS,0ignored. DB ohne veröffentlichten Port,
Netzwerknamespace ausschließlich intern, frische Rollen/Migrationen, danach
entfernt. Keine Produktionsdatenbank. Windows-GNU-Alltargets-Clippy separat im
Default- und SYSTEM-Helperprofil jeweils bestanden; keine native Windowsausführung.
Linux-Releasebinaries und vier native Linux-Testprogramme dieses früheren
Quellenstands sind gebaut/gehasht, noch nicht auf der Cloud-VM ausgeführt oder
installiert. **Nachträglicher unabhängiger Reviewblocker:** Dieser Pack bindet
noch nicht den tatsächlichen laufenden Linux-Fullhelpercodehash. Er berechtigt
keine Fullprofilaktivierung. Der danach separat geprüfte und im neuen Pack qualifizierte enge Corefix ergänzt ausschließlich
im Fullprofil tatsächliches gehaltenes `/proc/self/exe`, geschützten Binärpin,
authentisierte Probe, zusätzliche Binärcapability und zentrale Hashprüfung.
General/APT lassen neue Metadaten vollständig aus. Der neue lokale Stand steht
oben; dieser alte Pack bleibt ausdrücklich der ursprüngliche Beleg.
Die ersten Packvorbereitungen erzeugten kein qualifiziertes Manifest: Der erste
before/after-Schutz bemerkte die währenddessen vervollständigte Builderinputliste;
der zweite hielt bei PostgreSQLs temporärer Initialisierungsphase an. Der finale
oben genannte Lauf wartet auf den endgültigen TCP-Endpunkt und besteht vollständig.
Diese Vorbereitungsläufe werden nicht zu bestandenen Abnahmen umgedeutet.
## Separater Linux-first-Unitrunner
Der Runner `deploy/script_console_acceptance.py` ist separat reviewbar und kein
Teil der158 eingefrorenen Compilerinputs; er baut und verändert diese nicht.
Er ist ausdrücklich auf den neuen Pack29461892 und dessen Manifestddd1a78d…
gebunden; bei veränderten Compilerinputs wird ein neuer Start verweigert. Die
ursprüngliche Vorbereitung für Packde34 bleibt ein früherer, nie ausgeführter
Runnerstand. Die jetzigen Counts beruhen auf den tatsächlich erzeugten Listen.
Runnerquellhash:
`2b3ba8d548d18627643a9f73c9a4f7bacce4ac2cd5495745c6760d088e078145`.
Supportquellen werden vor Import und jedem Zielaufruf inklusive Readback exakt
geprüft und in Intent/Payload/Result gebunden: Runtime-Bootstraphelper
`833ad8806c90a19342aa6fbc71c33e81975caffb1746550e9b0fbdca7fa0c7ab`,
Zugangsparser
`5c8107ea9151a9f498b2530cdc61c1a7a6d745aff853a9b05710f3395838c0dd`.
Der finale Readback verlangt product_state_writes, rmm_jobs,
capabilities_activated und approvals ausdrücklich jeweils false.
Er verwendet ausschließlich den vorhandenen strikten Bootstraptransport und
`credentials/linux-vm.conf` im ursprünglichen Hauptcheckout, ausschließlich als root auf der festgelegten Linux-Test-VM, mit vorhandenem
SSH-Key und strenger Hostprüfung. Keine
Zugangsdatenkopie ins Scriptworktree, keine alternative IP oder Passwortfallback.
**Tatsächlich ausgeführt:** Alle vier Listen wurden vor jedem Unitstart geprüft;
84 Tests bestanden, fünf ausdrücklich ausgelassene DB-Verträge waren zuvor im
isolierten lokalen PostgreSQL-Lauf bestanden. Fall
`7b61ce46-7913-492b-9c6b-414a0c2b6ffc`, Beleg-SHA256
`a831a70a3cf76a3e8a9bf5820dcca7100d2ef9860dd9388539fe9c13f949f470`.
Der verwendete Aufruf war:
```bash
python3 deploy/script_console_acceptance.py execute-linux
```
Es entstehen nur neue private Scratchdateien unter
`/var/lib/rmm-script-console-contracts/<case-id>/`. Erst werden alle vier exakten
ELF-Hashes und vollständigen Listen geprüft; kein Unitstart vor dem gesamten
Listenbeleg. Danach feste Testargumente, geleerte Umgebung, eigenes TMPDIR,
eigener Netzwerknamespace und CPU-/Speicher-/Dateilimits. Erwartet werden84PASS
und fünf ausdrücklich ausgelassene DB-Fälle auf der VM ohne DB; dieselben fünf
DB-Verträge sind bereits im isolierten lokalen45er-Lauf belegt. Keine Installation,
Enrollment-, Dienst-, Policy-, Paket-, Schlüssel-, Journal- oder Capabilityänderung.
Bei verlorenem Ergebnis ausschließlich denselben ursprünglichen Fall lesen:
```bash
python3 deploy/script_console_acceptance.py read-linux --case <urspruengliche-case-id>
```
Readback erzeugt keinen zweiten Remote-Start. Ein vorhandener Create-once-
Startmarker erlaubt kein erneutes `run`; Teilergebnisse bleiben erhalten. Ein
unvollständiger/fehlender Beleg ist keine bestandene Abnahme und wird nicht blind
wiederholt. Native Units sind keine RMM-Dienst-/WebUI-/FullMaintenanceabnahme.
## Bootstrapvorbereitung nach gesondertem Erhaltungsreview
Der ursprüngliche Erhaltungsplan und die weiterhin geltenden Schutzgrenzen
folgen unten; tatsächliche Ausführung samt fehlgeschlagenen Teilphasen und
separaten Erststartfortsetzungen steht in den
[Bootstrap-Ergebnissen](../../docs/script-console-bootstrap-results.md).
Aktuelle Cloudbelege, Geräte-/Boot-/
Journalidentitäten, Inodes, Verbrauchszeilen und Dienstzustände werden vor einer
Änderung durch den verantwortlichen Rootprozess unabhängig gegengeprüft. Die
bisherigen General-/APT-Units und Pins sowie deren Historie bleiben erhalten;
keine Ledgerkopie, kein Reset und kein stilles Öffnen alter Scopes.
Die neue Unit ist `deploy/linux/rmm-full-maintenance-helper.service` mit eigenem
Runtimeverzeichnis `/run/rmm-helper-maintenance`. Sie verweist auf
`/etc/rmm-remote/helper-full-maintenance.json`. Diese Konfiguration erhält exakt
die bestehende provisionierte öffentliche Bindingidentität und dieselben
Root-Sharedledger-/Lockdateien; neue Auswahl:
```json
{
"profile": "full_maintenance_v1",
"allowed_services": [],
"allow_reboot": false,
"allow_root_scripts": true,
"allowed_script_profiles": ["full_maintenance_v1"],
"helper_binary_sha256": "<tatsaechlicher SHA256 der qualifizierten laufenden Helperbinary>"
}
```
Das ist ein Ausschnitt, keine vollständige einsatzfähige Konfiguration. Socket,
Agent-UID/GID, Zustandspfad und bestehendes Binding müssen aus dem tatsächlich
geprüften Bestand kommen. Kein `apt_provider`. `allow_reboot=false` verweigert
nur die typisierte Rebootaction; genehmigter Rootcode besitzt volle Hostautorität.
Der separat geschützte Policy-Pin bindet Profil `full_maintenance_v1`, bestehende
Identität, tatsächlichen lokalen Policyhash und unabhängig beobachteten
laufenden Binärhash. Das neue Fullprofil benötigt Schema2 im Pin; der Helper
kann diesen nach selbst geprüftem Rootimage mit dem ausdrücklich getrennten
Bootstrapmodus `--inspect-full-maintenance-profile` ausgeben. Generalpin
Schema1 bleibt unverändert. Agentumgebung ausschließlich
additiv um `RMM_FULL_MAINTENANCE_HELPER_SOCKET` und
`RMM_FULL_MAINTENANCE_POLICY_FILE` ergänzen. Kein Fallback auf General/APT und
keine Änderung deren bestehender Umgebung. Die zentrale Rootpolicy braucht
Schema2 und einen ausdrücklich begrenzten Scope mit neuen exakten Helperpins
sowie `allowed_script_profiles=["full_maintenance_v1"]`. Aktuelle Rechte beider
Planakteure, Helper-Sync, TrustedClock, ursprünglicher Grant und Einmalverbrauch
bleiben zusätzlich erforderlich. Eine Policy ist keine Jobgenehmigung.
Vor Installation werden zusammengesetzte systemd-Unit und etwaige Drop-ins
geprüft: Vollwartung darf keine General-Sandbox erben, die Hostdateisystem oder
Netzwerk unerwartet sperrt. Dienst- und Binärwechsel nur mit qualifizierten
Artefakten und explizitem Erhaltungsplan. Insbesondere darf eine neue allgemeine
Helperbinary nicht still die alten APT-Codepins überschreiben/öffnen. Gegebenenfalls
eigenen qualifizierten Binärpfad für die neue FullMaintenanceunit wählen und die
bestehenden Providerpfade unverändert erhalten. Native Erhaltung und Sync nachweisen,
bevor neue Capabilities/Scopes geöffnet werden.
Erster tatsächlicher FullMaintenancejob nur nach bereitgestellter WebUI und
expliziter Genehmigung der unveränderlichen Skript-/Profil-/Ziel-/Rechtebytes.
Abgestimmter Scope: harmlose Identität/stdout/stderr und kontrollierte lesende
Dateisystem-/Netzwerkbeobachtung; kein Betriebssystemupdate oder Neustart. Volle
Hostautorität wird sichtbar erklärt; kein Sandbox-, No-Reboot- oder Rollbackversprechen.
Windows-SYSTEM folgt nach eigenem Clock-/Pipe-/Profilnachweis. Die vorhandene
PipeV2-Datei ist unverändert SHA256
`ce525dab23f2e4faa2c9816280c1a5a8b40e56d0e63a350256e83b2df1d9229d`;
ursprüngliche native Pipebelege werden nicht als Belege der neuen Runtime ausgegeben.
## Anschließend auf der tatsächlichen Cloud-Linux-VM bestanden
Root führte ausschließlich den korrigierten Pack29461892 nativ aus: Fall
`7b61ce46-7913-492b-9c6b-414a0c2b6ffc`, **84PASS,5explizite DBignored**.
Die vier vollständigen tatsächlichen Listen wurden vor irgendeinem Unitstart
exakt geprüft; anschließend liefen alle vier festen ELFs im eigenen Scratch,
mit geleerter Umgebung, Netzwerknamespace und Ressourcenlimits. Die5DB-Verträge
bleiben diesem VM-Lauf ausdrücklich nicht zugerechnet; sie sind im separaten
isolierten45er-PostgreSQL-Lauf belegt. Kein stiller Testskip oder Produktjob.
Beleg `passed-e214cd9b-21ac-48ce-82dc-d10364329d04.json`, SHA256
`a831a70a3cf76a3e8a9bf5820dcca7100d2ef9860dd9388539fe9c13f949f470`.
Keine Agent-/Helperinstallation, Änderung bestehender Dienste/Policies/PKI/
Datenbanken, veröffentlichte Capability oder WebUI-Genehmigung durch diesen
Unitlauf. Der oben ursprünglich geplante Unitaufruf ist damit abgeschlossen.
Der inzwischen erhaltend ausgeführte Bootstrap steht in den separaten
[Bootstrap-Ergebnissen](../../docs/script-console-bootstrap-results.md);
signierter Folgeabgleich und tatsächlicher FullMaintenancejob sind dadurch
noch nicht abgenommen.
## Verbindlicher Generationsentscheid vor dem Bootstrap
Ein eigener neuer Fullhelper bei weiterlaufendem altem Generalhelper reicht
nicht: Alle aktiven Leser des gemeinsamen Root-Ledgers müssen neue
`privileged_script_profile`-Jobbytes unabhängig dekodieren und prüfen können.
Alte Decoder verweigern selbst geschlossene neue Zeilen und können beim
Snapshot/Sync einen sticky Fault schreiben. Deshalb neuer Agent und aktive
General-/Fullhelper gemeinsam auf die neue qualifizierte Generation; bestehende
Generalunit/Sandbox/Config/Policy-/Pinbytes unverändert. APT bleibt disabled/
inactive, ohne Endpoint und mit geschlossenen Scopes. Seine aktuelle Generation
war bereits laut vorherigem Runtimeindex nicht qualifiziert; historische
Abnahmen bleiben erhalten. Vor späterer Wiedereröffnung eigener APT-Stackpin-
/Generationnachweis, kein alter Helper gegen neue Ledgerzeilen.
Der Rootprozess hat die84 native Cloud-Linux-Units tatsächlich ausgeführt:
Fall `7b61ce46-7913-492b-9c6b-414a0c2b6ffc`, Proof-SHA256
`a831a70a3cf76a3e8a9bf5820dcca7100d2ef9860dd9388539fe9c13f949f470`,
84PASS und5 ausdrücklich ausgelassene DB-Fälle. Diese5 sind im isolierten lokalen
45er-Lauf bestanden. Keine RMM-Jobs oder neue Capabilities aus diesem Unitlauf;
der inzwischen ausgeführte Runtimeaustausch ist separat belegt. Tatsächlicher
signierter Folgeabgleich und genehmigter Fulljob bleiben eigene offene Schritte.
Details und Nach-MVP-Entdeckung:
[script-console-helper-generations.md](../../docs/script-console-helper-generations.md).
-311
View File
@@ -1,311 +0,0 @@
# 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.