//! SYSTEM service with an independent signed-sync gate and durable ledger. //! Only fixed, policy-pinned SCM state changes exist; no arbitrary SYSTEM CLI. //! //! Bootstrap contract (not performed by this module): install exactly //! `RmmDiscoverySystemHelper` as an OWN_PROCESS LocalSystem service with its //! unrestricted service SID, image `"...\\rmm-helper-windows.exe" --service`. //! Both peers keep their fixed names and binary hashes in `helper.json`. //! The public root/settings are owned by SYSTEM or Administrators, grant only //! those principals write access, and permit agent/helper service SIDs read. //! `state` MUST have a separately protected SYSTEM/Administrators/helper-SID-only //! ACL: no inherited agent reader. Files inherit that private ACL. This service //! never installs itself, repairs ACLs, changes its account, resets a ledger, or //! starts a fixture at bootstrap. `enable_effects=false`, `allow_reboot=false` //! is the intended initial profile; clock qualification remains a separate gate. //! A fixture is exactly OWN_PROCESS/LocalService with an unrestricted service //! SID and a quoted argument-free pinned EXE. Dependencies/load-order groups //! must be empty; recovery is empty/SC_ACTION_NONE with no command/reboot text. //! These are read-only admission checks, never implicit configuration repairs. use crate::{ clock::NativeClock, helper_ipc::{self as ipc, Call, Operation, PeerPin, Pin, PinnedFile, Reply, ReplyBody}, }; use anyhow::{Context, Result, ensure}; use fs2::FileExt; use rmm_agent_core::{ auth::{Binding, HelperIdentity, Outcome, Request}, crypto::DalekVerifier, helper_reconcile::{BootSource, ExecutorLedgerGuard, HelperSync}, ledger, }; use rmm_domain::jobs::{Action, ExecutionPermitPayload, JobPayload, hash}; use rusqlite::{Connection, OptionalExtension}; use serde::{Deserialize, Serialize}; use std::{ fs::OpenOptions, mem::{size_of, zeroed}, path::{Path, PathBuf}, ptr, sync::{ OnceLock, atomic::{AtomicBool, AtomicUsize, Ordering}, }, time::{Duration, Instant}, }; use uuid::Uuid; use windows_sys::Win32::{Foundation::*, System::Services::*}; pub const CONFIG_PATH: &str = r"C:\ProgramData\RustDiscoverySystem\helper.json"; pub const STATE_ROOT: &str = r"C:\ProgramData\RustDiscoverySystem\state"; const PUBLIC_ROOT: &str = r"C:\ProgramData\RustDiscoverySystem"; #[derive(Clone, Debug, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ServiceRule { pub name: String, pub binary: PathBuf, pub binary_sha256: String, } #[derive(Clone, Debug, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Settings { pub schema_version: u32, pub binding: Binding, pub agent: PeerPin, pub helper: PeerPin, pub allowed_services: Vec, pub max_runtime_seconds: u32, pub enable_effects: bool, pub allow_reboot: bool, } impl Settings { pub fn validate(&self) -> Result<()> { ensure!( self.schema_version == 1 && !self.allow_reboot && (1..=120).contains(&self.max_runtime_seconds) && self.allowed_services.len() <= 16, "SYSTEM_POLICY_PROFILE" ); self.agent.validate(false)?; self.helper.validate(true)?; ensure!( !self.binding.tenant_id.is_nil() && !self.binding.agent_id.is_nil() && !self.binding.asset_id.is_nil() && self.binding.enrollment_generation > 0 && self.binding.assignment_version > 0, "SYSTEM_POLICY_BINDING" ); use rmm_agent_core::crypto::Ed25519Verifier; let raw = decode_key(&self.binding.public_key_hex)?; ensure!(DalekVerifier.validate_key(&raw)?, "SYSTEM_SIGNING_KEY"); let mut names = std::collections::BTreeSet::new(); for rule in &self.allowed_services { ensure!( rule.name.starts_with("RmmDiscoveryFixture") && rule.name.len() <= 128 && rule .name .bytes() .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-') && names.insert(rule.name.to_ascii_lowercase()), "SYSTEM_SERVICE_ALLOWLIST" ); ensure!( !rule.name.eq_ignore_ascii_case(crate::SERVICE_NAME) && !rule.name.eq_ignore_ascii_case(ipc::HELPER_SERVICE), "SYSTEM_SELF_CONTROL_DENIED" ); ensure!( rule.binary.parent() == Some(Path::new(r"C:\Program Files\RustDiscoveryFixtures")) && rule .binary .extension() .is_some_and(|x| x.eq_ignore_ascii_case("exe")) && rule.binary.file_name().is_some_and(|n| n .to_str() .is_some_and(|n| n.len() <= 200 && n.bytes() .all(|b| b.is_ascii_alphanumeric() || b"_.-".contains(&b)))) && ipc::digest(&rule.binary_sha256), "SYSTEM_FIXTURE_IMAGE" ); } Ok(()) } pub fn policy_sha256(&self) -> Result { Ok(hash(&serde_json::to_vec(self)?)) } pub fn pin(&self) -> Result { self.validate()?; Ok(Pin { schema_version: 1, binding: self.binding.clone(), policy_sha256: self.policy_sha256()?, agent: self.agent.clone(), helper: self.helper.clone(), }) } } fn decode_key(s: &str) -> Result> { ensure!( s.len() == 64 && s.bytes().all(|b| b.is_ascii_hexdigit()), "SYSTEM_KEY_SIZE" ); (0..32) .map(|i| Ok(u8::from_str_radix(&s[i * 2..i * 2 + 2], 16)?)) .collect() } pub fn read_settings() -> Result<(Settings, Vec)> { let agent = ipc::service_sid(crate::SERVICE_NAME)?; let helper = ipc::service_sid(ipc::HELPER_SERVICE)?; let readers = vec![agent, helper]; let root = PinnedFile::open(Path::new(PUBLIC_ROOT), true, &readers, &[], false)?; let mut file = PinnedFile::open(Path::new(CONFIG_PATH), false, &readers, &[], false)?; ensure!(file.file.metadata()?.len() <= 32768, "SYSTEM_CONFIG_SIZE"); use std::io::Read; let mut bytes = Vec::new(); file.file.read_to_end(&mut bytes)?; let settings: Settings = serde_json::from_slice(&bytes)?; settings.validate()?; Ok((settings, vec![root, file])) } struct WindowsBoot(Uuid); impl BootSource for WindowsBoot { fn current_boot(&self) -> Result { Ok(self.0) } } impl WindowsBoot { fn capture() -> Result { // The exact existing fixed read-only CIM getter, independently called here. // No caller values, execution-policy flag, or supplied command are accepted. let rt = tokio::runtime::Builder::new_current_thread() .enable_all() .build()?; let id = rt.block_on(crate::native::boot_id())?; let id = Uuid::parse_str(&id)?; ensure!(!id.is_nil(), "SYSTEM_BOOT_ID"); Ok(Self(id)) } } pub struct LedgerGuard { root: PinnedFile, lock: PinnedFile, ledger: PinnedFile, } impl LedgerGuard { fn acquire(helper_sid: &str, binding: &Binding) -> Result<(Self, Connection)> { let root = PinnedFile::open(Path::new(STATE_ROOT), true, &[], &[helper_sid.into()], true)?; for name in ["executor.lock", "ledger.sqlite"] { let path = Path::new(STATE_ROOT).join(name); if !path.exists() { let _ = OpenOptions::new() .write(true) .create_new(true) .open(&path)?; } } let lock = PinnedFile::open( &Path::new(STATE_ROOT).join("executor.lock"), false, &[], &[helper_sid.into()], true, )?; lock.file .try_lock_exclusive() .context("SYSTEM_EXECUTOR_BUSY")?; let ledger = PinnedFile::open( &Path::new(STATE_ROOT).join("ledger.sqlite"), false, &[], &[helper_sid.into()], true, )?; let db = Connection::open_with_flags(&ledger.path, rusqlite::OpenFlags::SQLITE_OPEN_READ_WRITE)?; db.busy_timeout(Duration::from_millis(250))?; ledger::initialize_ledger(&db)?; db.execute_batch("CREATE TABLE IF NOT EXISTS windows_helper_files(id INTEGER PRIMARY KEY CHECK(id=1),ledger BLOB NOT NULL,executor_lock BLOB NOT NULL,binding_sha256 TEXT NOT NULL)")?; let a = serde_json::to_vec(&ledger.identity)?; let b = serde_json::to_vec(&lock.identity)?; let binding_hash = ipc::binding_hash(binding)?; db.execute( "INSERT OR IGNORE INTO windows_helper_files(id,ledger,executor_lock,binding_sha256) VALUES(1,?1,?2,?3)", rusqlite::params![a, b, binding_hash], )?; let retained: (Vec, Vec, String) = db.query_row( "SELECT ledger,executor_lock,binding_sha256 FROM windows_helper_files WHERE id=1", [], |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)), )?; ensure!( retained == (a, b, binding_hash), "SYSTEM_LEDGER_OR_LOCK_REPLACED" ); let guard = Self { root, lock, ledger }; guard.check(&db)?; Ok((guard, db)) } fn check_files(&self) -> Result<()> { for file in [&self.root, &self.lock, &self.ledger] { ensure!( ipc::file_identity(&file.file)? == file.identity, "SYSTEM_HELD_FILE_CHANGED" ); let opened = PinnedFile::open( &file.path, file.path == Path::new(STATE_ROOT), &[], &[ipc::service_sid(ipc::HELPER_SERVICE)?], true, )?; ensure!( opened.identity == file.identity, "SYSTEM_LEDGER_PATH_CHANGED" ); } Ok(()) } } impl ExecutorLedgerGuard for LedgerGuard { fn check(&self, db: &Connection) -> Result<()> { self.check_files()?; let path = db.path().context("SYSTEM_DB_PATH_MISSING")?; let actual = PinnedFile::open( Path::new(path), false, &[], &[ipc::service_sid(ipc::HELPER_SERVICE)?], true, )?; ensure!(actual.identity == self.ledger.identity, "SYSTEM_DB_FILE_ID"); Ok(()) } } struct ServiceHandle(SC_HANDLE); impl Drop for ServiceHandle { fn drop(&mut self) { unsafe { CloseServiceHandle(self.0); } } } #[derive(Clone, Copy, Debug, Serialize)] struct ServiceState { state: u32, pid: u32, checkpoint: u32, wait_hint_ms: u32, win32_exit: u32, service_exit: u32, } fn state(handle: SC_HANDLE) -> Result { let mut value: SERVICE_STATUS_PROCESS = unsafe { zeroed() }; let mut needed = 0; ensure!( unsafe { QueryServiceStatusEx( handle, SC_STATUS_PROCESS_INFO, (&mut value as *mut SERVICE_STATUS_PROCESS).cast(), size_of::() as u32, &mut needed, ) } != 0, "SYSTEM_SERVICE_STATUS" ); Ok(ServiceState { state: value.dwCurrentState, pid: value.dwProcessId, checkpoint: value.dwCheckPoint, wait_hint_ms: value.dwWaitHint, win32_exit: value.dwWin32ExitCode, service_exit: value.dwServiceSpecificExitCode, }) } fn desired_state(value: &str) -> Result { match value { "running" => Ok(SERVICE_RUNNING), "stopped" => Ok(SERVICE_STOPPED), _ => anyhow::bail!("SYSTEM_SERVICE_STATE_UNAVAILABLE"), } } fn check_runtime(deadline: Instant) -> Result<()> { ensure!(Instant::now() < deadline, "SYSTEM_SCM_RUNTIME_EXCEEDED"); Ok(()) } #[derive(Clone, Debug)] struct ServiceConfig { service_type: u32, binary: String, account: String, dependencies_empty: bool, load_group_empty: bool, recovery: RecoveryConfig, sid_type: u32, } #[derive(Clone, Debug)] struct RecoveryConfig { actions: Vec, command_empty: bool, reboot_text_empty: bool, } impl RecoveryConfig { fn validate(&self) -> Result<()> { ensure!( self.command_empty && self.reboot_text_empty && self.actions.iter().all(|kind| *kind == SC_ACTION_NONE), "SYSTEM_UNAPPROVED_SERVICE_RECOVERY" ); Ok(()) } } impl ServiceConfig { fn validate(&self, rule: &ServiceRule) -> Result<()> { ensure!( self.service_type == SERVICE_WIN32_OWN_PROCESS && self.binary == format!("\"{}\"", rule.binary.display()) && matches!( self.account.as_str(), "NT AUTHORITY\\LocalService" | "NT AUTHORITY\\Local Service" ), "SYSTEM_FIXTURE_SCM_BINDING" ); // StartService may implicitly start dependencies/groups. A fixed-fixture // grant authorizes exactly this service, so neither is admitted. ensure!( self.dependencies_empty && self.load_group_empty, "SYSTEM_UNAPPROVED_SERVICE_DEPENDENCY" ); self.recovery.validate()?; ensure!( self.sid_type == SERVICE_SID_TYPE_UNRESTRICTED, "SYSTEM_FIXTURE_SERVICE_SID_DISABLED" ); Ok(()) } } fn query_service_config2(handle: SC_HANDLE, level: u32) -> Result> { let mut needed = 0; unsafe { QueryServiceConfig2W(handle, level, ptr::null_mut(), 0, &mut needed); } ensure!((1..=32768).contains(&needed), "SYSTEM_SERVICE_CONFIG2_SIZE"); let mut bytes = vec![0usize; (needed as usize).div_ceil(size_of::())]; ensure!( unsafe { QueryServiceConfig2W( handle, level, bytes.as_mut_ptr().cast(), needed, &mut needed, ) } != 0, "SYSTEM_SERVICE_CONFIG2" ); Ok(bytes) } fn buffer_empty_string(bytes: &[usize], text: *const u16) -> Result { if text.is_null() { return Ok(true); } let base = bytes.as_ptr() as usize; let address = text as usize; let size = std::mem::size_of_val(bytes); ensure!( address >= base && address - base <= size.saturating_sub(2) && address.is_multiple_of(2), "SYSTEM_CONFIG2_STRING_POINTER" ); Ok(unsafe { *text } == 0) } fn recovery_config(handle: SC_HANDLE) -> Result { let bytes = query_service_config2(handle, SERVICE_CONFIG_FAILURE_ACTIONS)?; ensure!( std::mem::size_of_val(bytes.as_slice()) >= size_of::(), "SYSTEM_RECOVERY_STRUCT_SIZE" ); let value = unsafe { &*bytes.as_ptr().cast::() }; ensure!(value.cActions <= 128, "SYSTEM_RECOVERY_ACTION_COUNT"); let mut actions = Vec::new(); if value.cActions > 0 { let base = bytes.as_ptr() as usize; let address = value.lpsaActions as usize; let length = value.cActions as usize * size_of::(); let size = std::mem::size_of_val(bytes.as_slice()); ensure!( !value.lpsaActions.is_null() && address >= base && length <= size && address - base <= size - length && address.is_multiple_of(std::mem::align_of::()), "SYSTEM_RECOVERY_ACTION_POINTER" ); actions.extend( unsafe { std::slice::from_raw_parts(value.lpsaActions, value.cActions as usize) } .iter() .map(|a| a.Type), ); } Ok(RecoveryConfig { actions, command_empty: buffer_empty_string(&bytes, value.lpCommand)?, reboot_text_empty: buffer_empty_string(&bytes, value.lpRebootMsg)?, }) } fn query_service_config(handle: SC_HANDLE) -> Result { let mut needed = 0; unsafe { QueryServiceConfigW(handle, ptr::null_mut(), 0, &mut needed); } ensure!((1..=32768).contains(&needed), "SYSTEM_SERVICE_CONFIG_SIZE"); let mut bytes = vec![0usize; (needed as usize).div_ceil(size_of::())]; ensure!( unsafe { QueryServiceConfigW(handle, bytes.as_mut_ptr().cast(), needed, &mut needed) } != 0, "SYSTEM_SERVICE_CONFIG" ); let value = unsafe { &*bytes.as_ptr().cast::() }; // Microsoft defines NULL or first UTF16 NUL as empty for both fields. // Do not enumerate or adopt any dependency supplied by configuration. let sid_info = query_service_config2(handle, SERVICE_CONFIG_SERVICE_SID_INFO)?; ensure!( std::mem::size_of_val(sid_info.as_slice()) >= size_of::(), "SYSTEM_SID_CONFIG_SIZE" ); Ok(ServiceConfig { service_type: value.dwServiceType, binary: unsafe { ipc::utf16_pointer(value.lpBinaryPathName) }?, account: unsafe { ipc::utf16_pointer(value.lpServiceStartName) }?, dependencies_empty: value.lpDependencies.is_null() || unsafe { *value.lpDependencies } == 0, load_group_empty: value.lpLoadOrderGroup.is_null() || unsafe { *value.lpLoadOrderGroup } == 0, recovery: recovery_config(handle)?, sid_type: unsafe { (*sid_info.as_ptr().cast::()).dwServiceSidType }, }) } struct PreparedService { handle: ServiceHandle, _manager: ServiceHandle, image: PinnedFile, root: PinnedFile, rule: ServiceRule, pin: PeerPin, running: Option, wanted: u32, initial: ServiceState, } impl PreparedService { fn prepare(settings: &Settings, job: &JobPayload) -> Result { ensure!( job.execution_identity == "system" && job.max_runtime_seconds <= settings.max_runtime_seconds, "SYSTEM_IDENTITY_OR_RUNTIME" ); let Action::SetServiceState { unit, state: desired, } = &job.action else { anyhow::bail!("SYSTEM_TYPED_SERVICE_ONLY"); }; let wanted = desired_state(desired)?; let rule = settings .allowed_services .iter() .find(|r| r.name == *unit) .context("SYSTEM_SERVICE_DENIED")? .clone(); let sid = ipc::service_sid(&rule.name)?; let readers = [ settings.agent.service_sid.clone(), settings.helper.service_sid.clone(), sid.clone(), ]; let root = PinnedFile::open( Path::new(r"C:\Program Files\RustDiscoveryFixtures"), true, &readers, &[], false, )?; let mut image = PinnedFile::open(&rule.binary, false, &readers, &[], false)?; ensure!( image.sha256()? == rule.binary_sha256, "SYSTEM_SERVICE_IMAGE_HASH" ); let manager = ServiceHandle(unsafe { OpenSCManagerW(ptr::null(), ptr::null(), SC_MANAGER_CONNECT) }); ensure!(!manager.0.is_null(), "SYSTEM_SERVICE_MANAGER"); let handle = ServiceHandle(unsafe { OpenServiceW( manager.0, ipc::wide(unit).as_ptr(), SERVICE_QUERY_CONFIG | SERVICE_QUERY_STATUS | if wanted == SERVICE_RUNNING { SERVICE_START } else { SERVICE_STOP }, ) }); ensure!(!handle.0.is_null(), "SYSTEM_SERVICE_OPEN"); query_service_config(handle.0)?.validate(&rule)?; let initial = state(handle.0)?; ensure!( matches!(initial.state, SERVICE_RUNNING | SERVICE_STOPPED), "SYSTEM_SERVICE_BUSY" ); let pin = PeerPin { service_name: rule.name.clone(), service_sid: sid, user_sid: "S-1-5-19".into(), binary: rule.binary.clone(), binary_sha256: rule.binary_sha256.clone(), }; let running = if initial.state == SERVICE_RUNNING { Some(ipc::PeerProof::for_service(&pin, initial.pid)?) } else { None }; Ok(Self { handle, _manager: manager, image, root, rule, pin, running, wanted, initial, }) } fn recheck(&mut self) -> Result { self.image.check()?; self.root.check()?; query_service_config(self.handle.0)?.validate(&self.rule)?; let before = state(self.handle.0)?; ensure!( before.state == self.initial.state && before.pid == self.initial.pid, "SYSTEM_SERVICE_CHANGED_BEFORE_EFFECT" ); if let Some(process) = &mut self.running { process.check()?; } Ok(before) } fn execute(&mut self, timeout: Duration, mut authorize: impl FnMut() -> Result<()>) -> Outcome { let result = (|| -> Result { let deadline = Instant::now() + timeout; let before = match self.recheck() { Ok(value) => value, Err(error) => { return Ok(Outcome { state: "failed".into(), evidence: serde_json::json!({"postconditions_passed":false,"not_started":true}), ..Outcome::unknown(&safe_error(&error)) }); } }; let noop = before.state == self.wanted; // This callback performs the final BOTH-edge clock/permit check, // after all potentially slow configuration/process preflights. if let Err(error) = authorize() { return Ok(Outcome { state: "failed".into(), evidence: serde_json::json!({"postconditions_passed":false,"not_started":true}), ..Outcome::unknown(&safe_error(&error)) }); } if let Err(error) = check_runtime(deadline) { return Ok(Outcome { state: "failed".into(), evidence: serde_json::json!({"postconditions_passed":false,"not_started":true}), ..Outcome::unknown(&safe_error(&error)) }); } if !noop { // SCM's synchronous RPC can block (documented up to30s), and // cannot be safely cancelled here. Exceedance remains Unknown, // never success or a claim that effects stopped at the limit. let ok = unsafe { if self.wanted == SERVICE_RUNNING { StartServiceW(self.handle.0, 0, ptr::null()) } else { let mut ignored: SERVICE_STATUS = zeroed(); ControlService(self.handle.0, SERVICE_CONTROL_STOP, &mut ignored) } }; let native_error = if ok == 0 { Some(unsafe { GetLastError() }) } else { None }; check_runtime(deadline)?; if ok == 0 { return Ok(Outcome { evidence: serde_json::json!({"postconditions_passed":false,"native_error":native_error,"initial":before}), ..Outcome::unknown("SYSTEM_SCM_EFFECT_UNCONFIRMED") }); } } let mut final_state = state(self.handle.0)?; while final_state.state != self.wanted && Instant::now() < deadline { std::thread::sleep(Duration::from_millis(50)); final_state = state(self.handle.0)?; } if final_state.state != self.wanted { return Ok(Outcome { evidence: serde_json::json!({"postconditions_passed":false,"initial":before,"last_status":final_state}), ..Outcome::unknown("SYSTEM_SERVICE_POSTCONDITION_TIMEOUT") }); } self.image.check()?; query_service_config(self.handle.0)?.validate(&self.rule)?; let process_identity = if self.wanted == SERVICE_RUNNING { if self.running.is_none() { self.running = Some(ipc::PeerProof::for_service(&self.pin, final_state.pid)?); } let process = self.running.as_mut().unwrap(); process.check()?; Some(process.identity().clone()) } else { if let Some(process) = &self.running { while !process.exited()? && Instant::now() < deadline { std::thread::sleep(Duration::from_millis(50)); } ensure!(process.exited()?, "SYSTEM_STOPPED_PROCESS_STILL_ALIVE"); } None }; // Re-read after live process proof; a stale SCM config/state is // never turned into success for an old SYSTEM/other image process. query_service_config(self.handle.0)?.validate(&self.rule)?; let confirmed = state(self.handle.0)?; ensure!( confirmed.state == self.wanted && (self.wanted != SERVICE_RUNNING || confirmed.pid == final_state.pid), "SYSTEM_SERVICE_CHANGED_DURING_POSTCONDITION" ); check_runtime(deadline)?; Ok(Outcome { state: "succeeded".into(), stdout: vec![], stderr: vec![], exit_code: Some(0), output_truncated: false, reboot_required: false, error_code: String::new(), evidence: serde_json::json!({"postconditions_passed":true,"provider":"windows.scm/1","service":self.rule.name,"requested_state":self.wanted,"initial":before,"final_status":confirmed,"noop":noop,"fixture_sha256":self.rule.binary_sha256,"fixture_file_id":self.image.identity,"running_process":process_identity,"captured_process_exited":self.wanted==SERVICE_STOPPED&&self.running.is_some()}), }) })(); result.unwrap_or_else(|error| Outcome::unknown(&safe_error(&error))) } } fn verified_window( binding: &Binding, request: &Request, clock: &impl rmm_agent_core::reconcile::SyncClock, ) -> Result<( JobPayload, ExecutionPermitPayload, chrono::DateTime, )> { let now = clock.now()?; let lower = now .checked_sub_signed(chrono::Duration::seconds(2)) .context("SYSTEM_CLOCK_RANGE")?; let upper = now .checked_add_signed(chrono::Duration::seconds(2)) .context("SYSTEM_CLOCK_RANGE")?; let (job, permit) = binding.verify_with(request, lower, &DalekVerifier)?; binding.verify_with(request, upper, &DalekVerifier)?; Ok((job, permit, now)) } pub struct SystemHelper { settings: Settings, pin: Pin, files: Vec, guard: LedgerGuard, db: Connection, clock: NativeClock, boot: WindowsBoot, sync: Option>, } impl SystemHelper { pub fn open() -> Result { let (settings, files) = read_settings()?; ipc::require_self(&settings.helper)?; let pin = settings.pin()?; ipc::publish_self_query_rights(&settings.agent.service_sid, &settings.helper.service_sid)?; let (guard, db) = LedgerGuard::acquire(&settings.helper.service_sid, &settings.binding)?; let clock = NativeClock::new(); let boot = WindowsBoot::capture()?; let sync = HelperSync::with_verifier(settings.binding.clone(), DalekVerifier, &clock) .ok() .map(|s| s.with_helper_identity(HelperIdentity::System)); Ok(Self { settings, pin, files, guard, db, clock, boot, sync, }) } pub fn pin(&self) -> &Pin { &self.pin } fn recheck(&mut self) -> Result<()> { ipc::require_self(&self.settings.helper)?; for file in &mut self.files { file.check()?; } self.guard.check(&self.db) } fn sync(&mut self) -> Result<&mut HelperSync> { if self.sync.is_none() { self.sync = Some( HelperSync::with_verifier( self.settings.binding.clone(), DalekVerifier, &self.clock, )? .with_helper_identity(HelperIdentity::System), ); } self.sync.as_mut().context("SYSTEM_SYNC_CLOSED") } pub fn handle(&mut self, call: &Call, peer: &mut ipc::PeerProof) -> Reply { let result = (|| -> Result { self.recheck()?; peer.check()?; ensure!( call.schema_version == 1 && !call.challenge.is_nil() && ipc::binding_hash(&call.binding)? == ipc::binding_hash(&self.settings.binding)? && call.policy_sha256 == self.pin.policy_sha256, "SYSTEM_CALL_BINDING" ); let response: Result = match &call.operation { Operation::Probe {} => { let ready = self.settings.enable_effects && self .sync .as_ref() .and_then(|s| { s.active_generation().map(|g| { s.can_start(&self.db, &self.guard, g, &self.clock, &self.boot) }) }) .unwrap_or(false); Ok(ReplyBody::Probe { clock_qualified: self.clock.now().is_ok(), ready, ledger: self.guard.ledger.identity, lock: self.guard.lock.identity, }) } Operation::Snapshot { generation } => { self.sync()?; let snapshot = self.sync.as_mut().unwrap().snapshot( &mut self.db, &self.guard, *generation, &self.clock, &self.boot, )?; Ok(ReplyBody::Snapshot { snapshot }) } Operation::Apply { response, request_bytes, } => { self.sync()?; let value = self.sync.as_mut().unwrap().apply( &mut self.db, &self.guard, response, request_bytes, &self.clock, &self.boot, )?; Ok(ReplyBody::Applied { snapshot: value.snapshot, unlocked_grants: value.unlocked_grants, ready: value.ready && self.settings.enable_effects, }) } Operation::Execute { generation, request, } => Ok(ReplyBody::Executed { outcome: self.execute(*generation, request, peer)?, }), }; let response = response?; peer.check()?; Ok(response) })(); let body = match result { Ok(body) => body, Err(e) => { if let Some(sync) = &mut self.sync { sync.close(); } ReplyBody::Denied { code: safe_error(&e), } } }; Reply { schema_version: 1, challenge: call.challenge, binding_sha256: ipc::binding_hash(&self.settings.binding).expect("validated binding"), policy_sha256: self.pin.policy_sha256.clone(), helper_binary_sha256: self.settings.helper.binary_sha256.clone(), body, } } fn execute( &mut self, generation: u64, request: &Request, peer: &mut ipc::PeerProof, ) -> Result { // Historical signature validation can only return retained evidence. It // never reopens a start window or authorizes an effect after expiry. let parsed: ExecutionPermitPayload = serde_json::from_slice(&request.permit_bytes)?; let (job, permit) = self.settings .binding .verify_with(request, parsed.not_before, &DalekVerifier)?; ensure!( job.execution_identity == "system", "SYSTEM_IDENTITY_REQUIRED" ); type Completion = (Option>, Option>); let old:Option=self.db.query_row("SELECT e.start,COALESCE(c.result,e.outcome) FROM consumed c LEFT JOIN execution_evidence e ON e.grant_id=c.grant_id WHERE c.grant_id=?1",[permit.grant_id.to_string()],|r|Ok((r.get(0)?,r.get(1)?))).optional()?; if let Some((start, outcome)) = old { let Some(start) = start else { return Ok(Outcome::unknown("SYSTEM_PREVIOUS_START_UNRESOLVED")); }; let value: serde_json::Value = serde_json::from_slice(&start)?; let original: Request = serde_json::from_value(value["request"].clone())?; ensure!( serde_json::to_vec(&original)? == serde_json::to_vec(request)?, "SYSTEM_REDELIVERY_REQUEST_CHANGED" ); return outcome .map(|bytes| Ok(serde_json::from_slice(&bytes)?)) .unwrap_or_else(|| Ok(Outcome::unknown("SYSTEM_PREVIOUS_EFFECT_UNRESOLVED"))); } ensure!(self.settings.enable_effects, "SYSTEM_EFFECTS_DISABLED"); verified_window(&self.settings.binding, request, &self.clock)?; self.sync()?; ensure!( self.sync.as_ref().unwrap().can_start( &self.db, &self.guard, generation, &self.clock, &self.boot ), "SYSTEM_SIGNED_SYNC_REQUIRED" ); let mut provider = PreparedService::prepare(&self.settings, &job)?; self.recheck()?; peer.check()?; ensure!( self.sync.as_ref().unwrap().can_start( &self.db, &self.guard, generation, &self.clock, &self.boot ), "SYSTEM_SIGNED_SYNC_REQUIRED" ); provider.recheck()?; let (_, fresh, recorded_at) = verified_window(&self.settings.binding, request, &self.clock)?; ensure!(fresh == permit, "SYSTEM_START_REQUEST_CHANGED"); // Parent core provides atomic request/consumption persistence; never // dispatch SCM until both exact request and tombstone are durable. ledger::begin_execution( &mut self.db, &permit, request, self.boot.current_boot()?, recorded_at, )?; self.sync.as_mut().unwrap().close(); let outcome = provider.execute(Duration::from_secs(job.max_runtime_seconds.into()), || { self.recheck()?; peer.check()?; verified_window(&self.settings.binding, request, &self.clock)?; Ok(()) }); ledger::persist_outcome(&self.db, &permit, &outcome)?; self.guard.check(&self.db)?; ledger::finish(&self.db, &permit, &outcome)?; Ok(outcome) } } pub fn safe_error(error: &anyhow::Error) -> String { if error.chain().any(|cause| { matches!(cause.downcast_ref::(), Some(rusqlite::Error::SqliteFailure(code,_)) if code.code==rusqlite::ErrorCode::DiskFull) }) { return "JOURNAL_STORAGE_CAPACITY_BLOCKED".into(); } let text = error.to_string(); if text.len() <= 96 && text .bytes() .all(|b| b.is_ascii_uppercase() || b.is_ascii_digit() || b == b'_') { text } else { "SYSTEM_VALIDATION_OR_STORAGE_FAILURE".into() } } static STOP: AtomicBool = AtomicBool::new(false); static SCM_HANDLE: AtomicUsize = AtomicUsize::new(0); static START: OnceLock<()> = OnceLock::new(); fn scm_status(state: u32, error: u32) { let h = SCM_HANDLE.load(Ordering::SeqCst) as SERVICE_STATUS_HANDLE; if h.is_null() { return; } let status = SERVICE_STATUS { dwServiceType: SERVICE_WIN32_OWN_PROCESS, dwCurrentState: state, dwControlsAccepted: if state == SERVICE_RUNNING { SERVICE_ACCEPT_STOP | SERVICE_ACCEPT_SHUTDOWN } else { 0 }, dwWin32ExitCode: error, dwServiceSpecificExitCode: 0, dwCheckPoint: u32::from(state == SERVICE_START_PENDING || state == SERVICE_STOP_PENDING), dwWaitHint: if state == SERVICE_STOP_PENDING { 125000 } else { 30000 }, }; unsafe { SetServiceStatus(h, &status); } } unsafe extern "system" fn control( code: u32, _: u32, _: *mut std::ffi::c_void, _: *mut std::ffi::c_void, ) -> u32 { if matches!(code, SERVICE_CONTROL_STOP | SERVICE_CONTROL_SHUTDOWN) { STOP.store(true, Ordering::SeqCst); scm_status(SERVICE_STOP_PENDING, 0); } 0 } unsafe extern "system" fn service_main(_: u32, _: *mut *mut u16) { let name = ipc::wide(ipc::HELPER_SERVICE); let handle = unsafe { RegisterServiceCtrlHandlerExW(name.as_ptr(), Some(control), ptr::null_mut()) }; if handle.is_null() { return; } SCM_HANDLE.store(handle as usize, Ordering::SeqCst); scm_status(SERVICE_START_PENDING, 0); let result = (|| -> Result<()> { let mut helper = SystemHelper::open()?; let server = ipc::Server::bind(helper.pin().clone())?; scm_status(SERVICE_RUNNING, 0); while !STOP.load(Ordering::SeqCst) { match server.receive() { Ok(Some(mut incoming)) => { let reply = helper.handle(&incoming.call, &mut incoming.peer); if server.reply(&reply).is_err() && let Some(sync) = &mut helper.sync { sync.close(); } server.disconnect(); } Ok(None) => {} Err(_) => { if let Some(sync) = &mut helper.sync { sync.close(); } server.disconnect(); } } } Ok(()) })(); scm_status(SERVICE_STOPPED, if result.is_ok() { 0 } else { 1066 }); } pub fn dispatch() -> Result<()> { ensure!( std::env::args().skip(1).collect::>() == ["--service"], "SYSTEM_SCM_MODE_ONLY" ); ensure!(START.set(()).is_ok(), "SYSTEM_SCM_ALREADY_STARTED"); let mut name = ipc::wide(ipc::HELPER_SERVICE); let table = [ SERVICE_TABLE_ENTRYW { lpServiceName: name.as_mut_ptr(), lpServiceProc: Some(service_main), }, SERVICE_TABLE_ENTRYW { lpServiceName: ptr::null_mut(), lpServiceProc: None, }, ]; ensure!( unsafe { StartServiceCtrlDispatcherW(table.as_ptr()) } != 0, "SYSTEM_SCM_DISPATCH" ); Ok(()) } #[cfg(test)] mod tests { use super::*; #[test] fn service_adapter_exposes_only_implemented_states() { assert_eq!(desired_state("running").unwrap(), SERVICE_RUNNING); assert_eq!(desired_state("stopped").unwrap(), SERVICE_STOPPED); for state in ["restarted", "reload", "start;whoami", ""] { assert!(desired_state(state).is_err()); } } #[test] fn single_fixture_cannot_start_services_or_groups_as_dependencies() { let rule = ServiceRule { name: "RmmDiscoveryFixtureTest".into(), binary: PathBuf::from(r"C:\Program Files\RustDiscoveryFixtures\fixture.exe"), binary_sha256: "a".repeat(64), }; let view = ServiceConfig { service_type: SERVICE_WIN32_OWN_PROCESS, binary: format!("\"{}\"", rule.binary.display()), account: "NT AUTHORITY\\LocalService".into(), dependencies_empty: true, load_group_empty: true, recovery: RecoveryConfig { actions: vec![], command_empty: true, reboot_text_empty: true, }, sid_type: SERVICE_SID_TYPE_UNRESTRICTED, }; assert!(view.validate(&rule).is_ok()); for changed in [ ServiceConfig { dependencies_empty: false, ..view.clone() }, ServiceConfig { load_group_empty: false, ..view.clone() }, ServiceConfig { account: "LocalSystem".into(), ..view.clone() }, ServiceConfig { binary: r"C:\Windows\System32\other.exe".into(), ..view.clone() }, ServiceConfig { sid_type: SERVICE_SID_TYPE_NONE, ..view.clone() }, ] { assert!(changed.validate(&rule).is_err()); } } #[test] fn fixture_recovery_cannot_add_commands_reboots_or_restart_attempts() { let none = RecoveryConfig { actions: vec![SC_ACTION_NONE], command_empty: true, reboot_text_empty: true, }; assert!(none.validate().is_ok()); for kind in [SC_ACTION_RESTART, SC_ACTION_RUN_COMMAND, SC_ACTION_REBOOT] { assert!( RecoveryConfig { actions: vec![kind], ..none.clone() } .validate() .is_err() ); } assert!( RecoveryConfig { command_empty: false, ..none.clone() } .validate() .is_err() ); assert!( RecoveryConfig { reboot_text_empty: false, ..none } .validate() .is_err() ); } #[test] fn completed_scm_state_cannot_override_elapsed_runtime() { let expired = Instant::now().checked_sub(Duration::from_secs(1)).unwrap(); assert!(check_runtime(expired).is_err()); assert!(check_runtime(Instant::now() + Duration::from_secs(10)).is_ok()); } }