Integrate signed agent catalog, tenant enrollment and HTTPS installers

This commit is contained in:
2026-11-17 15:56:18 +01:00
parent 689f326460
commit 7fd17272d5
70 changed files with 12982 additions and 327 deletions
+400
View File
@@ -0,0 +1,400 @@
"""Bootstrap a Linux systemd client and maintain its signed release pair."""
import argparse
import datetime
import fcntl
import getpass
import hashlib
import json
import os
from pathlib import Path
import platform
import pwd
import re
import shutil
import socket
import sqlite3
import ssl
import subprocess
import sys
import tempfile
import time
from urllib.parse import urlsplit
import urllib.request
import uuid
ROOT = Path('/opt/rust-discovery-client')
STATE = Path('/var/lib/rmm-discovery')
SERVICE = 'rmm-discovery-agent.service'
TIMER = 'rmm-discovery-update.timer'
PLATFORM = 'x86_64-unknown-linux-gnu'
MAX_BINARY = 256 * 1024 * 1024
UNIT_DIR = Path('/etc/systemd/system')
def require(condition, message):
if not condition:
raise ValueError(message)
def origin(value):
parsed = urlsplit(value)
require(parsed.scheme == 'https' and parsed.hostname and parsed.username is None
and parsed.password is None and not parsed.query and not parsed.fragment
and parsed.path in ('', '/'), 'HTTPS origin required')
return 'https://' + parsed.netloc
def canonical_id(value):
require(str(uuid.UUID(value)) == value, 'invalid object identifier')
return value
def save(path, value, mode=0o644):
data = json.dumps(value, separators=(',', ':')).encode() if not isinstance(value, bytes) else value
with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as tmp:
tmp.write(data)
os.fchmod(tmp.fileno(), mode)
tmp.flush()
os.fsync(tmp.fileno())
os.replace(tmp.name, path)
fd = os.open(path.parent, os.O_DIRECTORY)
try:
os.fsync(fd)
finally:
os.close(fd)
def read(path):
return json.loads(path.read_bytes())
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, *_):
raise ValueError('unexpected HTTP redirect')
def retrieve(base, route, target, *, context, token=None, size=None, expected=None):
request = urllib.request.Request(origin(base) + route)
if token:
request.add_header('Authorization', 'Enrollment ' + token)
client = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect(),
urllib.request.HTTPSHandler(context=context))
limit = 65536 if size is None else size
require(type(limit) is int and 0 < limit <= MAX_BINARY, 'download size outside profile')
digest = hashlib.sha256()
count = 0
with client.open(request, timeout=30) as response:
require(response.status == 200, 'download rejected')
while True:
chunk = response.read(min(65536, limit + 1 - count))
if not chunk:
break
count += len(chunk)
require(count <= limit, 'download larger than descriptor')
digest.update(chunk)
target.write(chunk)
if size is not None:
require(count == size and digest.hexdigest() == expected, 'download hash or size mismatch')
def as_device(action, *args, stdout=None):
return subprocess.run(['/usr/sbin/runuser', '-u', 'rmm-discovery', '--', sys.executable, '-I',
str(ROOT / 'lifecycle.py'), action, *map(str, args)],
stdout=stdout, check=True, timeout=240)
def device_get(route, size=None, digest=None):
config = read(ROOT / 'config.json')
version = canonical_id(read(STATE / 'certificates/current.json')['version'])
pair = STATE / 'certificates/versions' / version
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
ctx.load_verify_locations(cafile=str(ROOT / 'gateway-ca.pem'))
ctx.load_cert_chain(str(pair / 'device.pem'), str(pair / 'device.key'))
retrieve(config['gateway'], route, sys.stdout.buffer, context=ctx,
size=int(size) if size is not None else None, expected=digest)
def device_idle():
# The root worker holds the admission lock before consulting this journal.
with sqlite3.connect(f'file:{STATE}/journal.sqlite?mode=ro', uri=True) as conn:
busy, = conn.execute("SELECT EXISTS(SELECT 1 FROM job_attempts WHERE state IN ('requesting','running','verifying'))").fetchone()
print('busy' if busy else 'idle')
def remote(source, route, target, descriptor=None):
size = digest = None
if descriptor:
size, digest = descriptor['bytes'], descriptor['sha256']
require(type(size) is int and 0 < size <= MAX_BINARY and re.fullmatch('[0-9a-f]{64}', digest),
'invalid binary descriptor')
with target.open('xb') as output:
if source:
base, token = source
retrieve(base, route, output, context=ssl.create_default_context(), token=token, size=size, expected=digest)
else:
args = [size, digest] if descriptor else []
as_device('fetch', route, *args, stdout=output)
output.flush()
os.fsync(output.fileno())
def pair(folder, doc, source, updater):
manifest = doc['manifest']
release_id = canonical_id(manifest['release_id'])
prefix = '/agent/v1/bootstrap/releases' if source else '/agent/v1/releases'
suffix = '?platform=' + PLATFORM if source else ''
save(folder / 'envelope.json', doc['release_envelope'])
for artifact, role in zip(manifest['artifacts'], ('agent', 'helper'), strict=True):
require(artifact['role'] == role, 'incorrect artifact role')
aid = canonical_id(artifact['artifact_id'])
remote(source, f'{prefix}/{release_id}/artifacts/{aid}{suffix}', folder / role, artifact)
(folder / role).chmod(0o755)
ring = updater.parent / 'keyring.json'
verified = subprocess.check_output([updater, '--verify-bootstrap', ring, folder / 'envelope.json',
folder / 'agent', folder / 'helper'], timeout=120)
require(json.loads(verified) == manifest, 'metadata differs from signed release')
save(folder / 'manifest.json', verified)
folder.chmod(0o755)
return manifest
def link(base, name):
target = base / 'current.next'
target.unlink(missing_ok=True)
target.symlink_to('releases/' + canonical_id(name))
os.replace(target, base / 'current')
fd = os.open(base, os.O_DIRECTORY)
try:
os.fsync(fd)
finally:
os.close(fd)
def installed():
return json.loads(as_device('fetch', '/agent/v1/releases/installed', stdout=subprocess.PIPE).stdout)
def healthy(version, baseline, duration=90):
until = time.monotonic() + duration
while time.monotonic() < until:
try:
record = installed()
contact = record.get('last_contact_at')
if contact:
recent = datetime.datetime.fromisoformat(contact.replace('Z', '+00:00')).timestamp()
if (time.time() - 65 < recent <= time.time() + 10 and record['agent_version'] == version
and record['connection_generation'] > baseline):
return True
except (subprocess.SubprocessError, ValueError, OSError):
pass
time.sleep(2)
return False
def service(*args):
subprocess.run(['systemctl', *args], check=True, timeout=60)
def units():
program = '/usr/bin/python3 -I ' + str(ROOT / 'lifecycle.py')
return {
SERVICE: f"""[Unit]
Description=Rust Discovery Linux agent
Wants=network-online.target
After=network-online.target time-sync.target
[Service]
User=rmm-discovery
Group=rmm-discovery
StateDirectory=rmm-discovery
StateDirectoryMode=0700
UMask=0077
ExecStart={program} run-agent
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
[Install]
WantedBy=multi-user.target
""",
'rmm-discovery-update.service': f"""[Unit]
Description=Check and activate a signed Rust Discovery agent release
After=network-online.target
[Service]
Type=oneshot
ExecStart={program} update
UMask=0077
""",
TIMER: """[Unit]
Description=Periodic Rust Discovery agent release check
[Timer]
OnBootSec=1min
OnUnitActiveSec=5min
RandomizedDelaySec=20
[Install]
WantedBy=timers.target
""",
}
def enable():
for name, data in units().items():
path = UNIT_DIR / name
if path.exists():
require(path.read_bytes() == data.encode(), 'service file conflict: ' + name)
else:
save(path, data.encode())
service('daemon-reload')
service('enable', '--now', SERVICE, TIMER)
def install(base, token_file):
require(platform.machine() == 'x86_64', 'Linux x86-64 required')
base = origin(base)
if ROOT.exists():
config = read(ROOT / 'config.json')
require(config['bootstrap'] == base and (ROOT / 'current/manifest.json').is_file(),
'existing installation differs')
enable()
return
require(not STATE.exists() and not any((UNIT_DIR/name).exists() for name in units()),
'existing device installation requires migration')
token = Path(token_file).read_text().strip() if token_file else getpass.getpass('Einmalcode: ').strip()
require(re.fullmatch('[0-9a-f]{64}', token), 'invalid enrollment token')
try:
account = pwd.getpwnam('rmm-discovery')
except KeyError:
subprocess.run(['useradd', '--system', '--user-group', '--no-create-home', '--shell', '/usr/sbin/nologin',
'rmm-discovery'], check=True)
account = pwd.getpwnam('rmm-discovery')
require(account.pw_uid != 0 and account.pw_gid != 0, 'dedicated unprivileged service account required')
with tempfile.TemporaryDirectory(prefix='.rmm-', dir=ROOT.parent) as work:
staging = Path(work) / 'installation'
staging.mkdir()
remote((base, token), '/agent/v1/bootstrap/current?platform=' + PLATFORM, staging / 'bootstrap.json')
doc = read(staging / 'bootstrap.json')
require(doc['schema_version'] == 1, 'unknown bootstrap profile')
save(staging / 'keyring.json', doc['keyring'])
save(staging / 'gateway-ca.pem', doc['ca_pem'].encode())
save(staging / 'config.json', {'bootstrap': base, 'gateway': origin(doc['gateway_origin']),
'tenant': canonical_id(doc['tenant_id'])})
updater = staging / 'updater'
remote((base, token), '/agent/v1/bootstrap/updater?platform=' + PLATFORM, updater, doc['updater'])
updater.chmod(0o755)
releases = staging / 'releases'
releases.mkdir()
folder = releases / canonical_id(doc['manifest']['release_id'])
folder.mkdir()
manifest = pair(folder, doc, (base, token), updater)
link(staging, manifest['release_id'])
save(staging / 'lifecycle.py', Path(__file__).read_bytes())
save(staging / 'release.lock', b'')
save(staging / 'first.token', token.encode(), 0o440)
os.chown(staging / 'first.token', 0, account.pw_gid)
staging.chmod(0o755)
releases.chmod(0o755)
os.rename(staging, ROOT)
enable()
require(healthy(manifest['version'], 0), 'installed, awaiting authenticated device heartbeat')
(ROOT / 'first.token').unlink(missing_ok=True)
def run_agent():
conf = read(ROOT / 'config.json')
url = urlsplit(conf['gateway'])
# Resolve again on each service start. TLS identity always uses the configured DNS name.
address = socket.getaddrinfo(url.hostname, url.port or 443, type=socket.SOCK_STREAM)[0][4][0]
if ':' in address:
address = '[' + address + ']'
os.environ.update(RMM_AGENT_STATE=str(STATE), RMM_CA_FILE=str(ROOT / 'gateway-ca.pem'),
RMM_CONNECT_ADDR=f'{address}:{url.port or 443}', RMM_SERVER_NAME=url.hostname,
RMM_TRANSPORT='https', RMM_ENROLLMENT_TOKEN_FILE=str(ROOT / 'first.token'),
RMM_ENROLLMENT_TENANT=conf['tenant'], RMM_JOB_SIGNING_KEY_BOOTSTRAP='1',
RMM_RELEASE_LOCK=str(ROOT / 'release.lock'),
RMM_INSTALLED_RELEASE_VERSION=read(ROOT / 'current/manifest.json')['version'])
exe = str(ROOT / 'current/agent')
os.execv(exe, [exe])
def revert(intent):
# Persist failed sequence before restoring. An interruption re-enters recovery.
save(ROOT / 'failed.json', {'release_sequence': intent['sequence'], 'reason': 'activation_unconfirmed'})
link(ROOT, intent['previous'])
service('restart', SERVICE)
(ROOT / 'pending.json').unlink()
raise RuntimeError('release activation unconfirmed; predecessor selected')
def update():
with (ROOT / 'release.lock').open('rb') as lock:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
pending = ROOT / 'pending.json'
if pending.exists():
revert(read(pending))
active = read(ROOT / 'current/manifest.json')
with tempfile.TemporaryDirectory(prefix='.incoming-', dir=ROOT / 'releases') as work:
staging = Path(work) / 'generation'
staging.mkdir()
remote(None, '/agent/v1/releases/current?platform=' + PLATFORM, staging / 'current.json')
response = read(staging / 'current.json')
if response['status'] == 'not_configured':
return
require(response['status'] == 'available', 'unexpected release status')
doc = response['release']
if doc['release_envelope'] == read(ROOT / 'current/envelope.json'):
return
floor = active['release_sequence']
if (ROOT / 'failed.json').exists():
floor = max(floor, read(ROOT / 'failed.json')['release_sequence'])
manifest = pair(staging, doc, None, ROOT / 'updater')
require(manifest['release_sequence'] > floor, 'release sequence previously activated or rejected')
# Guard only this device while it is being changed. A fresh offer may
# remain queued while the worker temporarily owns the admission lock.
if as_device('idle', stdout=subprocess.PIPE).stdout.strip() != b'idle':
return
previous_health = installed()
release = canonical_id(manifest['release_id'])
dest = ROOT / 'releases' / release
if dest.exists():
# A previous check may have staged this version before a crash.
require(read(dest / 'envelope.json') == doc['release_envelope'], 'release id conflict')
subprocess.run([ROOT / 'updater', '--verify-bootstrap', ROOT / 'keyring.json', dest / 'envelope.json',
dest / 'agent', dest / 'helper'], stdout=subprocess.DEVNULL, check=True)
else:
(staging / 'current.json').unlink()
os.rename(staging, dest)
intent = {'previous': active['release_id'], 'sequence': manifest['release_sequence']}
save(pending, intent)
link(ROOT, release)
service('restart', SERVICE)
if not healthy(manifest['version'], previous_health['connection_generation']):
revert(intent)
pending.unlink()
(ROOT / 'first.token').unlink(missing_ok=True)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('action', choices=('install', 'update', 'run-agent', 'fetch', 'idle'))
parser.add_argument('values', nargs='*')
parser.add_argument('--token-file')
args = parser.parse_args()
if args.action in ('install', 'update'):
require(os.geteuid() == 0, 'administrative installation required')
os.umask(0o022)
if args.action == 'install':
require(len(args.values) == 1, 'one HTTPS bootstrap origin required')
install(args.values[0], args.token_file)
elif args.action == 'update':
update()
elif args.action == 'run-agent':
run_agent()
elif args.action == 'fetch':
device_get(*args.values)
else:
device_idle()
if __name__ == '__main__':
main()