278 lines
16 KiB
Markdown
278 lines
16 KiB
Markdown
# 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.
|