feat: snapshot Linux-first RMM MVP and pause handover
Rust development slice / linux (push) Failing after 1m10s
Rust development slice / linux (push) Failing after 1m10s
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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()
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user