Open administrator scripts fleet-wide for helpers verified against a signed release

policy.json gains an optional fleet rule per platform. It covers every device
whose helper the server has matched to a signed installed release, so new
devices no longer need a hand-written device entry. Callers already require
root:execute or system:execute plus scripts:execute in the target customer;
the rule can admit scoped tokens, limit customers and exclude devices.
OPNsense and locally pinned helpers keep their device rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-21 15:38:18 +01:00
co-authored by Claude Opus 5.5
parent a1ef33ff21
commit 2f05d0a019
3 changed files with 195 additions and 6 deletions
+1 -1
View File
@@ -52,7 +52,7 @@ Die WebUI verwendet HTTPS mit lokalem Passwort und TOTP. MCP verwendet HTTPS mit
MCP unterstützt Kunden-, Geräte- und Hypervisorabfragen, Skriptbibliothek, Planung, Planvorschau, Einreichung, Auftragsliste mit den Filtern der WebUI, Auftrags- und Ergebnisabfrage, Abbruchanforderung, das Lesen von Paket- und MSI-Rezepten sowie Katalogartefakten und gespeicherte Status-, Log- und Releaseabfragen. Kundenpflege, Geräteverwaltung und Kundenwechsel, Geräteaufnahme, Notstopp, Katalogimporte, Tokenverwaltung und persönliche Entscheidungen erfolgen in einer persönlichen WebUI-Sitzung. Die vom Server angebotenen MCP-Werkzeuge und deren Parameter sind im Toolkatalog definiert. [MCP-Werkzeuge](crates/server/src/mcp.rs) · [Bedienung und Rechte](docs/public-access.md)
Für administrative Skripte gilt zusätzlich das Plattformrecht `root:execute` oder `system:execute`. Bei einem installierten signierten Helper kann der Betreiber die vorhandene zentrale Geräteregel mit `mcp:scoped` für berechtigte Token öffnen. Der Server prüft Kunde, aktuelle Tokenrechte, Installation, Helper und gegebenenfalls die in der Regel festgelegten Skriptbeschränkungen. Eine Tokenrotation erfordert keine Anpassung auf dem Gerät. [Geräteregel](crates/server/src/managed_scripts.rs)
Für administrative Skripte gilt zusätzlich das Plattformrecht `root:execute` oder `system:execute`. Bei einem installierten signierten Helper kann der Betreiber die vorhandene zentrale Geräteregel mit `mcp:scoped` für berechtigte Token öffnen. Der Server prüft Kunde, aktuelle Tokenrechte, Installation, Helper und gegebenenfalls die in der Regel festgelegten Skriptbeschränkungen. Eine Tokenrotation erfordert keine Anpassung auf dem Gerät. Für Geräte, deren Helper der Server gegen ein signiertes, installiertes Release verifiziert, kann der Betreiber stattdessen eine Flottenregel je Plattform öffnen. Sie gilt ohne Eintrag pro Gerät für alle Kunden oder für ausgewählte Kunden, nimmt bei Bedarf einzelne Geräte aus und lässt optional berechtigte Tokens zu. Persönliche Genehmigung, signierte Startfreigabe und die lokale Prüfung durch den Helper bleiben unverändert. [Geräteregel](crates/server/src/managed_scripts.rs)
## Geräteaufnahme und Agentupdates
+185 -5
View File
@@ -21,6 +21,85 @@ struct Policy {
windows: Vec<SystemScope>,
#[serde(default)]
release_anchors: Vec<ReleaseAnchor>,
#[serde(default)]
fleet: Fleet,
}
/// Fleet-wide ceiling for helpers the server has verified against a signed,
/// installed release. It replaces one operator entry per device; the caller has
/// already required root:execute or system:execute plus scripts:execute in the
/// target customer, and planning, approval and start each re-run this check.
#[derive(Default, Deserialize)]
#[serde(deny_unknown_fields)]
struct Fleet {
#[serde(default)]
linux: Option<FleetRule>,
#[serde(default)]
windows: Option<FleetRule>,
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct FleetRule {
/// Operator decision that opened this rule, recorded like a device rule.
acceptance_evidence_id: String,
/// Lets customer tokens with the platform right request plans (mcp:scoped).
#[serde(default)]
allow_scoped_mcp: bool,
/// Restricts the rule to these customers; omitted means every customer.
#[serde(default)]
tenants: Option<Vec<Uuid>>,
/// Devices that keep needing an explicit device rule.
#[serde(default)]
exclude_assets: Vec<Uuid>,
}
impl FleetRule {
fn valid(&self) -> bool {
let evidence = self.acceptance_evidence_id.trim();
!evidence.is_empty()
&& evidence.len() <= 128
&& self
.tenants
.as_ref()
.is_none_or(|t| !t.is_empty() && t.len() <= 1024 && !t.contains(&Uuid::nil()))
&& self.exclude_assets.len() <= 1024
}
fn permits(&self, principal: &str, job: &JobPayload, caps: &[String]) -> bool {
let identity = job.execution_identity.as_str();
let has = |cap: &str| caps.iter().any(|c| c == cap);
let platform = match identity {
"root" => "linux.base/1",
"system" => "windows.base/1",
_ => return false,
};
let token = principal.starts_with("mcp:");
self.valid()
&& (!token || (self.allow_scoped_mcp && scoped_token(principal)))
&& self.tenants.as_ref().is_none_or(|t| t.contains(&job.tenant_id))
&& !self.exclude_assets.contains(&job.asset_id)
&& job.max_output_bytes <= 65536
&& has(platform)
&& !has("opnsense.base/1")
&& [
"rmm.sync.v1",
"run_script",
FULL_MAINTENANCE_CAPABILITY,
&format!("helper.{identity}.v1"),
&format!("{identity}:run_script"),
]
.iter()
.all(|cap| has(cap))
&& single_value(caps, "helper.binary.sha256:").is_ok()
&& single_value(caps, "helper.policy.sha256:").is_ok_and(digest)
}
}
fn scoped_token(principal: &str) -> bool {
principal.strip_prefix("mcp:").is_some_and(|id| {
Uuid::parse_str(id).is_ok_and(|uuid| !uuid.is_nil() && uuid.to_string() == id)
})
}
/// Operator-pinned canonical bytes of an already authorized local policy.
@@ -137,12 +216,15 @@ impl Policy {
.any(|scope| scope.permits(subject, job, caps, false, true, false)),
_ => false,
};
let verified = matches!(binding, HelperBinding::VerifiedInstalledRelease);
let fleet = match job.execution_identity.as_str() {
"root" => self.fleet.linux.as_ref(),
"system" => self.fleet.windows.as_ref(),
_ => None,
};
permits_subject(principal)
|| (matches!(binding, HelperBinding::VerifiedInstalledRelease)
&& principal.strip_prefix("mcp:").is_some_and(|id| {
Uuid::parse_str(id).is_ok_and(|uuid| !uuid.is_nil() && uuid.to_string() == id)
})
&& permits_subject(SCOPED_MCP))
|| (verified && scoped_token(principal) && permits_subject(SCOPED_MCP))
|| (verified && fleet.is_some_and(|rule| rule.permits(principal, job, caps)))
}
}
@@ -217,6 +299,10 @@ pub(crate) async fn permits(
.iter()
.any(|a| a.policy_json.len() > 8192)
|| !policy.windows.iter().all(SystemScope::valid)
|| [&policy.fleet.linux, &policy.fleet.windows]
.into_iter()
.flatten()
.any(|rule| !rule.valid())
{
return Err(invalid());
}
@@ -404,6 +490,100 @@ mod tests {
}
}
#[test]
fn fleet_rule_covers_every_verified_release_helper_without_device_entries() {
let token = "mcp:12345678-abcd-4321-b123-123456789abc";
let verified = HelperBinding::VerifiedInstalledRelease;
for (platform, identity, interpreter, script) in [
("linux", "root", "posix_sh", "true\n"),
("windows", "system", "powershell", "Write-Output 'ok'\r\n"),
] {
let job = JobPayload {
schema_version: 1,
tenant_id: Uuid::new_v4(),
asset_id: Uuid::new_v4(),
agent_id: Uuid::new_v4(),
enrollment_generation: 1,
assignment_version: 3,
job_id: Uuid::new_v4(),
attempt_id: Uuid::new_v4(),
action: Action::RunScript {
interpreter: interpreter.into(),
script_utf8: script.into(),
arguments: vec![],
expected_stdout: None,
windows_execution_profile: None,
privileged_script_profile: Some(
rmm_domain::jobs::PrivilegedScriptProfile::FullMaintenanceV1,
),
},
execution_identity: identity.into(),
not_before: chrono::Utc::now(),
start_before: chrono::Utc::now() + chrono::Duration::minutes(5),
max_runtime_seconds: 30,
max_output_bytes: 4096,
};
let mut caps = vec![
format!("{platform}.base/1"),
format!("helper.{identity}.v1"),
format!("{identity}:run_script"),
"run_script".into(),
"rmm.sync.v1".into(),
FULL_MAINTENANCE_CAPABILITY.into(),
format!("helper.policy.sha256:{}", "cd".repeat(32)),
format!("helper.binary.sha256:{}", "ab".repeat(32)),
];
if platform == "windows" {
caps.push("script.powershell/1".into());
}
let policy = |rule: serde_json::Value| -> Policy {
let mut config = json!({"schema_version": 1, "linux": [], "windows": []});
config["fleet"][platform] = rule;
serde_json::from_value(config).unwrap()
};
let open = policy(json!({"acceptance_evidence_id": "fleet-20261121"}));
assert!(open.permits("local:reviewer", &job, &caps, verified), "{platform}");
assert!(!open.permits(token, &job, &caps, verified), "{platform}: no MCP opt-in");
assert!(!open.permits("local:reviewer", &job, &caps, HelperBinding::LocalPins));
let other = if platform == "linux" { "windows" } else { "linux" };
let mut config = json!({"schema_version": 1, "linux": [], "windows": []});
config["fleet"][other] = json!({"acceptance_evidence_id": "x"});
let wrong: Policy = serde_json::from_value(config).unwrap();
assert!(!wrong.permits("local:reviewer", &job, &caps, verified));
let mcp = policy(json!({"acceptance_evidence_id": "fleet", "allow_scoped_mcp": true}));
assert!(mcp.permits(token, &job, &caps, verified), "{platform}");
for principal in [SCOPED_MCP, "mcp:not-a-uuid", "mcp:00000000-0000-0000-0000-000000000000"] {
assert!(!mcp.permits(principal, &job, &caps, verified), "{principal}");
}
let scoped = policy(json!({"acceptance_evidence_id": "fleet", "allow_scoped_mcp": true,
"tenants": [Uuid::new_v4()]}));
assert!(!scoped.permits(token, &job, &caps, verified));
let included = policy(json!({"acceptance_evidence_id": "fleet", "tenants": [job.tenant_id]}));
assert!(included.permits("local:reviewer", &job, &caps, verified));
let excluded = policy(json!({"acceptance_evidence_id": "fleet", "exclude_assets": [job.asset_id]}));
assert!(!excluded.permits("local:reviewer", &job, &caps, verified));
let blank = policy(json!({"acceptance_evidence_id": " "}));
assert!(!blank.permits("local:reviewer", &job, &caps, verified));
for missing in [format!("helper.{identity}.v1"), FULL_MAINTENANCE_CAPABILITY.into(),
format!("{identity}:run_script")] {
let mut fewer = caps.clone();
fewer.retain(|c| *c != missing);
assert!(!open.permits("local:reviewer", &job, &fewer, verified), "{missing}");
}
let mut ambiguous = caps.clone();
ambiguous.push(format!("helper.policy.sha256:{}", "ef".repeat(32)));
assert!(!open.permits("local:reviewer", &job, &ambiguous, verified));
let mut firewall = caps.clone();
firewall.push("opnsense.base/1".into());
assert!(!open.permits("local:reviewer", &job, &firewall, verified));
let mut service = job.clone();
service.execution_identity = "agent_service".into();
assert!(!open.permits("local:reviewer", &service, &caps, verified));
}
}
#[test]
fn signed_helper_is_bound_to_platform_reported_version_and_unambiguous_local_pins() {
let binary = "ab".repeat(32);
+9
View File
@@ -81,6 +81,15 @@ Ein Administratorauftrag braucht auf Linux `root:execute`, auf Windows `system:e
Der installierte signierte Helper muss auf die Geräteidentität gebunden sein. Die zentrale Richtlinie liegt auf dem Server in `/opt/rust-discovery/devstate/managed-scripts/policy.json`. API und Gateway lesen sie über `RMM_MANAGED_SCRIPT_POLICY_FILE`. Für verifizierte Agent-/Helper-Paarwechsel kann `release_anchors` die ursprüngliche Release-ID, Geräteinstallation, Binärhashes und die kanonischen lokalen Richtlinienbytes binden. Der Server vergleicht die daraus für das signierte Folgepaket berechneten Prüfdaten mit den Geräteangaben. [Mounts](../deploy/server.managed-scripts.compose.yaml) · [Serverprüfung](../crates/server/src/managed_scripts.rs)
Für alle Geräte mit release-verwaltetem Helper gilt zusätzlich die Flottenregel unter `fleet` in derselben Datei. Ein Gerät fällt darunter, wenn es mit `--enable-admin-scripts` eingerichtet wurde und der Server Helper-Binärdatei, Version und Plattform gegen ein signiertes, installiertes Release geprüft hat. Ein eigener Eintrag pro Gerät ist dann nicht nötig. Berechtigt ist, wer im Zielkunden `root:execute` (Linux) bzw. `system:execute` (Windows) und `scripts:execute` hat. `allow_scoped_mcp` lässt entsprechend berechtigte Tokens zu, `tenants` beschränkt die Regel auf bestimmte Kunden und `exclude_assets` nimmt einzelne Geräte aus. OPNsense-Firewalls und Geräte mit lokal gepinntem Helper brauchen weiterhin eine Geräteregel.
```json
"fleet": {
"linux": {"acceptance_evidence_id": "fleet-root-20261121", "allow_scoped_mcp": true},
"windows": {"acceptance_evidence_id": "fleet-system-20261121", "allow_scoped_mcp": true}
}
```
Der folgende Operator prüft eine vorhandene Geräteregel. Platzhalter durch die tatsächlichen Kennungen der Installation und ihrer bestehenden Regel ersetzen.
```sh