Files
rust-discovery/crates/agent-windows/src/helper_system.rs
T
2026-11-14 02:39:39 +01:00

1174 lines
43 KiB
Rust

//! 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<ServiceRule>,
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<String> {
Ok(hash(&serde_json::to_vec(self)?))
}
pub fn pin(&self) -> Result<Pin> {
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<Vec<u8>> {
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<PinnedFile>)> {
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<Uuid> {
Ok(self.0)
}
}
impl WindowsBoot {
fn capture() -> Result<Self> {
// 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<u8>, Vec<u8>, 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<ServiceState> {
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::<SERVICE_STATUS_PROCESS>() 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<u32> {
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<SC_ACTION_TYPE>,
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<Vec<usize>> {
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::<usize>())];
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<bool> {
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<RecoveryConfig> {
let bytes = query_service_config2(handle, SERVICE_CONFIG_FAILURE_ACTIONS)?;
ensure!(
std::mem::size_of_val(bytes.as_slice()) >= size_of::<SERVICE_FAILURE_ACTIONSW>(),
"SYSTEM_RECOVERY_STRUCT_SIZE"
);
let value = unsafe { &*bytes.as_ptr().cast::<SERVICE_FAILURE_ACTIONSW>() };
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::<SC_ACTION>();
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::<SC_ACTION>()),
"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<ServiceConfig> {
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::<usize>())];
ensure!(
unsafe { QueryServiceConfigW(handle, bytes.as_mut_ptr().cast(), needed, &mut needed) } != 0,
"SYSTEM_SERVICE_CONFIG"
);
let value = unsafe { &*bytes.as_ptr().cast::<QUERY_SERVICE_CONFIGW>() };
// 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::<SERVICE_SID_INFO>(),
"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::<SERVICE_SID_INFO>()).dwServiceSidType },
})
}
struct PreparedService {
handle: ServiceHandle,
_manager: ServiceHandle,
image: PinnedFile,
root: PinnedFile,
rule: ServiceRule,
pin: PeerPin,
running: Option<ipc::PeerProof>,
wanted: u32,
initial: ServiceState,
}
impl PreparedService {
fn prepare(settings: &Settings, job: &JobPayload) -> Result<Self> {
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<ServiceState> {
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<Outcome> {
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<chrono::Utc>,
)> {
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<PinnedFile>,
guard: LedgerGuard,
db: Connection,
clock: NativeClock,
boot: WindowsBoot,
sync: Option<HelperSync<DalekVerifier>>,
}
impl SystemHelper {
pub fn open() -> Result<Self> {
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<DalekVerifier>> {
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<ReplyBody> {
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<ReplyBody> = 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<Outcome> {
// 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<Vec<u8>>, Option<Vec<u8>>);
let old:Option<Completion>=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::<rusqlite::Error>(),
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::<Vec<_>>() == ["--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());
}
}