//! Independently usable authorization boundary. No bearer credentials or keys //! received with a job are trusted. Both processes keep their own consumption DB. extern crate self as rmm_privileged_helper; pub mod apt; pub mod apt_reconcile; pub mod checkpoint_repair; pub mod control; pub mod readiness; pub mod reconcile; #[cfg(test)] mod tests; use anyhow::{Context, Result, ensure}; use chrono::{DateTime, Utc}; use openssl::{ pkey::{Id, PKey}, sign::Verifier, }; use rmm_domain::jobs::{ExecutionPermitPayload, JobPayload, hash}; use serde::{Deserialize, Serialize}; use std::{fs, os::unix::fs::MetadataExt, path::Path}; use uuid::Uuid; #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] #[serde(deny_unknown_fields)] pub struct SigningKey { pub key_id: String, pub algorithm: String, pub schema_version: u32, pub public_key_hex: String, } impl SigningKey { pub fn validate(&self) -> Result<()> { let raw = hex::decode(&self.public_key_hex)?; ensure!( self.algorithm == "Ed25519" && self.schema_version == 1 && raw.len() == 32 && self.key_id == hash(&raw), "SIGNING_KEY_PROFILE" ); PKey::public_key_from_raw_bytes(&raw, Id::ED25519)?; Ok(()) } pub fn read(path: &Path, uid: u32) -> Result { private_path(path, uid, false)?; ensure!(fs::metadata(path)?.len() <= 4096, "SIGNING_KEY_SIZE"); let key: Self = serde_json::from_slice(&fs::read(path)?)?; key.validate()?; Ok(key) } } #[derive(Debug, Clone, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Binding { pub tenant_id: Uuid, pub asset_id: Uuid, pub agent_id: Uuid, pub enrollment_generation: u64, pub assignment_version: u64, pub public_key_hex: String, } impl Binding { pub fn job(&self, bytes: &[u8]) -> Result { ensure!(bytes.len() <= 65536, "JOB_SIZE"); let j: JobPayload = serde_json::from_slice(bytes)?; ensure!( j.schema_version == 1 && j.tenant_id == self.tenant_id && j.asset_id == self.asset_id && j.agent_id == self.agent_id && j.enrollment_generation == self.enrollment_generation && j.assignment_version == self.assignment_version, "IDENTITY_BINDING" ); ensure!( j.action.validate() && (1..=3600).contains(&j.max_runtime_seconds) && (1..=262144).contains(&j.max_output_bytes) && j.not_before < j.start_before, "INVALID_JOB" ); Ok(j) } pub fn verify( &self, request: &Request, now: DateTime, ) -> Result<(JobPayload, ExecutionPermitPayload)> { let job = self.job(&request.job_bytes)?; ensure!( request.permit_bytes.len() <= 8192 && request.signature.len() == 64, "PERMIT_SIZE" ); let raw = hex::decode(&self.public_key_hex)?; ensure!(raw.len() == 32, "TRUST_KEY_SIZE"); let key = PKey::public_key_from_raw_bytes(&raw, Id::ED25519)?; ensure!( Verifier::new_without_digest(&key)? .verify_oneshot(&request.signature, &request.permit_bytes)?, "INVALID_SIGNATURE" ); let p: ExecutionPermitPayload = serde_json::from_slice(&request.permit_bytes)?; ensure!( p.domain == "rmm.execution-permit" && p.schema_version == 1 && p.key_id == hash(&raw) && !p.grant_id.is_nil() && !p.authorization_id.is_nil(), "PERMIT_DOMAIN" ); ensure!( p.authorization_id == request.authorization_id && p.plan_hash == request.plan_hash && p.plan_hash.len() == 64 && hex::decode(&p.plan_hash)?.len() == 32 && p.job_payload_hash == hash(&request.job_bytes) && p.tenant_id == job.tenant_id && p.asset_id == job.asset_id && p.agent_id == job.agent_id && p.enrollment_generation == job.enrollment_generation && p.assignment_version == job.assignment_version && p.job_id == job.job_id && p.attempt_id == job.attempt_id && p.action == job.action.name() && p.execution_identity == job.execution_identity && p.max_runtime_seconds == job.max_runtime_seconds, "PERMIT_BINDING" ); ensure!( p.not_before >= job.not_before && p.start_before <= job.start_before && p.not_before < p.start_before && (p.start_before - p.not_before).num_seconds() <= 60 && now >= p.not_before && now < p.start_before, "PERMIT_TIME" ); Ok((job, p)) } } #[derive(Clone, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Request { pub job_bytes: Vec, pub permit_bytes: Vec, pub signature: Vec, pub plan_hash: String, pub authorization_id: Uuid, } #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Outcome { pub state: String, pub stdout: Vec, pub stderr: Vec, pub exit_code: Option, pub output_truncated: bool, pub reboot_required: bool, pub evidence: serde_json::Value, pub error_code: String, } impl Outcome { pub fn unknown(code: &str) -> Self { Self { state: "unknown".into(), stdout: vec![], stderr: vec![], exit_code: None, output_truncated: false, reboot_required: false, evidence: serde_json::json!({"postconditions_passed":false}), error_code: code.into(), } } } /// Config and journal directories must already be bootstrapped by the intended /// owner; do not silently chmod a hostile existing path or follow symlinks. pub fn private_path(path: &Path, uid: u32, directory: bool) -> Result<()> { let m = fs::symlink_metadata(path)?; ensure!( !m.file_type().is_symlink() && m.uid() == uid && m.mode() & 0o077 == 0 && if directory { m.is_dir() } else { m.is_file() }, "UNSAFE_LOCAL_PATH" ); Ok(()) } pub fn lock_state(dir: &Path, uid: u32) -> Result { use fs2::FileExt; use std::os::unix::fs::OpenOptionsExt; private_path(dir, uid, true)?; let f = fs::OpenOptions::new() .read(true) .write(true) .create(true) .truncate(false) .mode(0o600) .custom_flags(libc::O_NOFOLLOW) .open(dir.join("executor.lock"))?; private_path(&dir.join("executor.lock"), uid, false)?; f.try_lock_exclusive()?; Ok(f) } /// Finite 256 MiB bound for durable agent/helper history. Unexpected page sizes /// are refused rather than silently multiplying the byte limit. No compaction /// or tombstone deletion occurs here; SQLITE_FULL must still fail closed. pub fn bounded_journal_capacity(db: &rusqlite::Connection) -> Result<()> { let page_size: u32 = db.query_row("PRAGMA page_size", [], |r| r.get(0))?; ensure!(page_size == 4096, "JOURNAL_PAGE_SIZE_UNSUPPORTED"); let maximum: u32 = db.query_row("PRAGMA max_page_count=65536", [], |r| r.get(0))?; ensure!(maximum == 65536, "JOURNAL_STORAGE_CAPACITY_BLOCKED"); Ok(()) } pub fn open_ledger(dir: &Path, uid: u32) -> Result { use std::os::unix::fs::OpenOptionsExt; let path = dir.join("consumption.sqlite"); let f = fs::OpenOptions::new() .read(true) .write(true) .create(true) .truncate(false) .mode(0o600) .custom_flags(libc::O_NOFOLLOW) .open(&path)?; f.sync_all()?; private_path(&path, uid, false)?; let db = rusqlite::Connection::open(path)?; bounded_journal_capacity(&db)?; db.execute_batch("PRAGMA synchronous=FULL; PRAGMA journal_mode=DELETE; CREATE TABLE IF NOT EXISTS consumed(grant_id TEXT PRIMARY KEY, agent TEXT NOT NULL, generation INTEGER NOT NULL, job TEXT NOT NULL, attempt TEXT NOT NULL, result BLOB, UNIQUE(agent,generation,job,attempt)); CREATE TABLE IF NOT EXISTS execution_evidence(grant_id TEXT PRIMARY KEY, start BLOB NOT NULL, outcome BLOB);")?; let check: String = db.query_row("PRAGMA integrity_check", [], |r| r.get(0))?; ensure!(check == "ok", "JOURNAL_INTEGRITY"); fs::File::open(dir)?.sync_all()?; Ok(db) } pub fn consume(db: &mut rusqlite::Connection, p: &ExecutionPermitPayload) -> Result<()> { let tx = db.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?; // Unknown effects retain the global device lock, including across restart. let unresolved: i64 = tx.query_row( "SELECT count(*) FROM consumed WHERE result IS NULL", [], |r| r.get(0), )?; ensure!(unresolved == 0, "UNRESOLVED_EFFECT_RESOURCE_LOCKED"); tx.execute( "INSERT INTO consumed(grant_id,agent,generation,job,attempt) VALUES(?1,?2,?3,?4,?5)", rusqlite::params![ p.grant_id.to_string(), p.agent_id.to_string(), p.enrollment_generation, p.job_id.to_string(), p.attempt_id.to_string() ], )?; tx.commit()?; Ok(()) } pub fn finish( db: &rusqlite::Connection, p: &ExecutionPermitPayload, outcome: &Outcome, ) -> Result<()> { db.execute( "UPDATE execution_evidence SET outcome=?2 WHERE grant_id=?1", rusqlite::params![p.grant_id.to_string(), serde_json::to_vec(outcome)?], )?; // Unknown / awaiting reboot keep the resource reserved until a real sync // protocol exists. Never unlock on a process exit or a network reconnect. if outcome.state != "unknown" && outcome.state != "awaiting_reboot" { ensure!( db.execute( "UPDATE consumed SET result=?2 WHERE grant_id=?1 AND result IS NULL", rusqlite::params![p.grant_id.to_string(), serde_json::to_vec(outcome)?] )? == 1, "CONSUMPTION_NOT_FOUND" ); } Ok(()) } /// Persist the original boot and exact signed request BEFORE any reboot/effect. /// Awaiting/unknown outcomes never release consumed.result's resource lock. pub fn save_start( db: &rusqlite::Connection, permit: &ExecutionPermitPayload, request: &Request, ) -> Result<()> { let job: JobPayload = serde_json::from_slice(&request.job_bytes)?; let recorded_at = Utc::now(); let deadline = match job.action { rmm_domain::jobs::Action::Reboot { reconnect_timeout_seconds, .. } => Some(recorded_at + chrono::Duration::seconds(reconnect_timeout_seconds.into())), _ => None, }; let evidence = serde_json::json!({"previous_boot_id":rmm_agent_linux::boot_id()?, "reserved_at":recorded_at,"reconnect_deadline":deadline,"request":request, "reauthentication_required":true,"postconditions_passed":false}); db.execute( "INSERT INTO execution_evidence(grant_id,start) VALUES(?1,?2)", rusqlite::params![permit.grant_id.to_string(), serde_json::to_vec(&evidence)?], )?; Ok(()) } pub fn script(job: &JobPayload) -> Result { use rmm_agent_linux::actions::{Interpreter, ScriptRequest, run_script}; let rmm_domain::jobs::Action::RunScript { interpreter, script_utf8, arguments, expected_stdout, } = &job.action else { anyhow::bail!("NOT_SCRIPT") }; let interpreter = match interpreter.as_str() { "posix_sh" => Interpreter::PosixSh, "bash" => Interpreter::Bash, _ => anyhow::bail!("UNSUPPORTED_INTERPRETER"), }; let request = ScriptRequest::new( script_utf8.as_bytes().to_vec(), interpreter, arguments.clone(), std::time::Duration::from_secs(job.max_runtime_seconds.into()), job.max_output_bytes as usize, )?; let output = run_script(&request)?; let passed = output.code == Some(0) && !output.timed_out && expected_stdout .as_ref() .is_none_or(|s| !output.truncated && output.stdout == s.as_bytes()); Ok(Outcome { state: if output.timed_out || output.code.is_none() { "unknown" } else if passed { "succeeded" } else { "failed" } .into(), stdout: output.stdout, stderr: output.stderr, exit_code: output.code, output_truncated: output.truncated, reboot_required: false, evidence: serde_json::json!({"postconditions_passed":passed}), error_code: if passed { "" } else if output.timed_out { "TIMEOUT_EFFECT_UNKNOWN" } else { "SCRIPT_POSTCONDITION_FAILED" } .into(), }) } pub fn read_binding(path: &Path, uid: u32) -> Result { private_path(path, uid, false)?; let bytes = fs::read(path)?; ensure!(bytes.len() <= 8192, "CONFIG_SIZE"); serde_json::from_slice(&bytes).context("invalid provisioned binding") } /// A fresh online permit is necessary but does not prove the host clock. Use /// Linux's synchronization/error status, never a gateway-supplied time override. pub fn clock_trusted() -> bool { let mut state = std::mem::MaybeUninit::::zeroed(); // SAFETY: zero modes request a read-only query into initialized storage. let status = unsafe { libc::adjtimex(state.as_mut_ptr()) }; // SAFETY: storage was zero initialized, including on an error return. let state = unsafe { state.assume_init() }; status >= 0 && status != libc::TIME_ERROR && state.status & libc::STA_UNSYNC == 0 && state.maxerror >= 0 && state.maxerror <= 5_000_000 } #[derive(Clone)] pub struct TrustedClock { wall: DateTime, monotonic: std::time::Instant, } /// Local client authenticates the root process as well as the root-owned socket. /// A malicious same-user Unix server must not be able to forge helper success. pub fn invoke(socket: &Path, request: &Request, max_runtime_seconds: u32) -> Result { use std::{ io::{Read, Write}, os::{ fd::AsRawFd, unix::{fs::FileTypeExt, net::UnixStream}, }, time::Duration, }; let parent = fs::symlink_metadata(socket.parent().context("socket parent")?)?; let meta = fs::symlink_metadata(socket)?; ensure!( parent.is_dir() && !parent.file_type().is_symlink() && parent.uid() == 0 && parent.mode() & 0o022 == 0 && meta.file_type().is_socket() && meta.uid() == 0 && meta.mode() & 0o007 == 0, "UNTRUSTED_HELPER_SOCKET" ); let mut stream = UnixStream::connect(socket)?; let mut credentials = std::mem::MaybeUninit::::uninit(); let mut size = std::mem::size_of::() as libc::socklen_t; // SAFETY: correct writable ucred storage and length for a live Unix socket. ensure!( unsafe { libc::getsockopt( stream.as_raw_fd(), libc::SOL_SOCKET, libc::SO_PEERCRED, credentials.as_mut_ptr().cast(), &mut size, ) } == 0 && size as usize == std::mem::size_of::(), "HELPER_PEER_CREDENTIALS" ); // SAFETY: getsockopt initialized the full ucred on success. ensure!( unsafe { credentials.assume_init() }.uid == 0, "HELPER_PEER_NOT_ROOT" ); stream.set_write_timeout(Some(Duration::from_secs(5)))?; stream.set_read_timeout(Some(Duration::from_secs( u64::from(max_runtime_seconds) + 10, )))?; let bytes = serde_json::to_vec(request)?; ensure!(bytes.len() <= 512 * 1024, "HELPER_REQUEST_SIZE"); stream.write_all(&(u32::try_from(bytes.len())?).to_be_bytes())?; stream.write_all(&bytes)?; let mut length = [0; 4]; stream.read_exact(&mut length)?; let length = u32::from_be_bytes(length) as usize; ensure!(length <= 2 * 1024 * 1024, "HELPER_RESPONSE_SIZE"); let mut bytes = vec![0; length]; stream.read_exact(&mut bytes)?; let outcome: Outcome = serde_json::from_slice(&bytes)?; ensure!( outcome.stdout.len() + outcome.stderr.len() <= 262144, "HELPER_OUTPUT_LIMIT" ); Ok(outcome) } impl Default for TrustedClock { fn default() -> Self { Self::new() } } impl TrustedClock { pub fn new() -> Self { Self { wall: Utc::now(), monotonic: std::time::Instant::now(), } } pub fn trusted(&self) -> bool { let elapsed = Utc::now() - self.wall; let skew = elapsed.num_milliseconds() - i64::try_from(self.monotonic.elapsed().as_millis()).unwrap_or(i64::MAX); clock_trusted() && skew.unsigned_abs() <= 5000 } }