diff --git a/AGENTS.md b/AGENTS.md index 1e89c84..e03f03c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,8 @@ Für Geräte und Kunden gilt Kapitel 0.7. Änderungen an Kundengrenzen mit besch Für Skriptaufträge gelten Kapitel 0.8 und 0.10. Alle neuen Geräteaktionen einschließlich Neustarts verwenden ein Skript. Beim Prüfen eines Neustarts den alten und neuen Bootbezug, die Kopplung und das Ergebnis eines Folgeauftrags festhalten. Die Bibliothek veröffentlicht Skriptversionen. Gerätezuweisung und Ergebniskontrolle gehören zu „Aufträge“, die interaktive Entscheidung zu „Genehmigungen“. Änderungen an einem dieser Wege am Übergang zum nächsten prüfen. +Für MCP-Administratoranträge gemäß Kapitel 0.12 zuerst die wirksamen Tokenrechte im Kunden und die zentrale Regel der konkreten Installation prüfen. Bei `SCRIPT_HELPER_SCOPE_DENIED` zeigt der [Operator für die Geräteregel](docs/public-access.md#administrator-skripte-anfordern), ob sie für solche Anträge geöffnet ist. + ## Betrieb und Freigabe - Der dedizierte Server ist `discovery.ease-technologies.de`. Testclients sind die Cloud-Linux-VM und der Windows-11-Gast. Das Notebook dient ausschließlich der Entwicklung. Plattformspezifische Arbeit auf beiden Gästen darf parallel laufen. Plattformfunktionen jeweils nativ nachweisen. diff --git a/Rust_RMM_Implementierungsspezifikation.md b/Rust_RMM_Implementierungsspezifikation.md index b9d2c15..ad7ab3b 100644 --- a/Rust_RMM_Implementierungsspezifikation.md +++ b/Rust_RMM_Implementierungsspezifikation.md @@ -1,6 +1,6 @@ # Rust RMM: Architektur und Implementierungsspezifikation -Version 1.40 · 2026-11-18 · Sprache: Deutsch +Version 1.41 · 2026-11-18 · Sprache: Deutsch **Zweck:** Vollständige, eigenständig nutzbare Grundlage für die Implementierung einer mandantenfähigen Plattform zur Inventarisierung, Überwachung und Fernadministration von Kundengeräten durch eine Coding-KI und ein Entwicklungsteam. @@ -114,6 +114,12 @@ Minuten nach Empfang nutzbar (bisher 100 ms). Details Kapitel 0.3. ## 0 Auftrag und verbindliche Produktanforderungen +### 0.12 MCP-Anträge für Administrator-Skripte (Version 1.41) + +Ein MCP-Token kann einmalige Skripte und feste Bibliotheksversionen für seine Kunden planen und einreichen. Die Rechte werden pro Token auf dem Server vergeben. Zusätzlich zu Planung, Einreichung, Lesen und Skriptausführung erfordert der administrative Kontext auf Linux `root:execute`, auf Windows `system:execute`. + +Der Betreiber kann eine bestehende zentrale Geräteregel für diese Tokenrechte öffnen. Dabei gelten die Bindungen an Installation, Helper und Skriptprofil sowie etwaige Beschränkungen auf konkrete Skriptinhalte. Eine Tokenrotation erfordert auf dem Client keine Konfigurationsänderung. Der Server stellt den signierten Startauftrag nach der persönlichen Entscheidung aus Kapitel 0.8 aus. Der Client prüft dessen Bindung an Gerät, Skript und Versuch und führt ihn ohne lokale Rückfrage aus. + ### 0.11 Gültigkeit von Releases bei bereits installierten Skripthelfern (Version 1.40) Für Neuinstallationen und Updates muss das Release-Manifest zum Zeitpunkt der Prüfung gültig sein. Für Administrator-Skripte auf bereits installierten Clients prüft der Server die Manifest-Gültigkeit zum gespeicherten Zeitpunkt der Katalogregistrierung. Die Signatur wird mit dem aktuellen Schlüsselring geprüft. Gerätebindung, Helper-Hash, Berechtigungen und Auftragsgenehmigung sind weiterhin erforderlich. diff --git a/crates/server/src/managed_scripts.rs b/crates/server/src/managed_scripts.rs index 5188feb..e2bab12 100644 --- a/crates/server/src/managed_scripts.rs +++ b/crates/server/src/managed_scripts.rs @@ -93,9 +93,26 @@ fn invalid() -> Error { Error(StatusCode::CONFLICT, "MANAGED_SCRIPT_POLICY_INVALID") } +// Only a managed device scope can opt in. The authenticated principal remains +// the token ID for authorization, the plan record and audit. +const SCOPED_MCP: &str = "mcp:scoped"; + +#[derive(Clone, Copy)] +enum HelperBinding { + LocalPins, + VerifiedInstalledRelease, +} + impl Policy { - fn permits(&self, principal: &str, job: &JobPayload, caps: &[String]) -> bool { - if !matches!(job.action, Action::RunScript { .. }) + fn permits( + &self, + principal: &str, + job: &JobPayload, + caps: &[String], + binding: HelperBinding, + ) -> bool { + if principal == SCOPED_MCP + || !matches!(job.action, Action::RunScript { .. }) || !job.action.full_maintenance() || !job.action.validate() || !job.action.available_for(&job.execution_identity, caps) @@ -105,17 +122,23 @@ impl Policy { { return false; } - match job.execution_identity.as_str() { + let permits_subject = |subject: &str| match job.execution_identity.as_str() { "root" => self .linux .iter() - .any(|scope| scope.permits(principal, job, caps, None)), + .any(|scope| scope.permits(subject, job, caps, None)), "system" => self .windows .iter() - .any(|scope| scope.permits(principal, job, caps, false, true, false)), + .any(|scope| scope.permits(subject, job, caps, false, true, false)), _ => false, - } + }; + 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)) } } @@ -190,12 +213,11 @@ pub(crate) async fn permits( { return Err(invalid()); } - let direct = policy.permits(principal, job, caps); if !caps .iter() .any(|cap| cap.starts_with("script.helper.release:")) { - return Ok(direct); + return Ok(policy.permits(principal, job, caps, HelperBinding::LocalPins)); } { let release = Uuid::parse_str(single_value(caps, "script.helper.release:")?) @@ -222,7 +244,12 @@ pub(crate) async fn permits( } })?; check_pair(&manifest, version.as_deref(), &job.execution_identity, caps)?; - if direct { + if policy.permits( + principal, + job, + caps, + HelperBinding::VerifiedInstalledRelease, + ) { return Ok(true); } let current_policy = single_value(caps, "helper.policy.sha256:")?; @@ -241,7 +268,12 @@ pub(crate) async fn permits( }); pinned.push(format!("helper.binary.sha256:{}", anchor.helper_sha256)); pinned.push(format!("helper.policy.sha256:{original}")); - if policy.permits(principal, job, &pinned) { + if policy.permits( + principal, + job, + &pinned, + HelperBinding::VerifiedInstalledRelease, + ) { return Ok(true); } } @@ -253,6 +285,117 @@ pub(crate) async fn permits( mod tests { use super::*; use rmm_domain::agent_update::ArtifactDescriptor; + use serde_json::json; + + #[test] + fn scoped_mcp_requires_a_device_opt_in_and_the_same_pinned_script_scope() { + let token = "mcp:12345678-abcd-4321-b123-123456789abc"; + let verified = HelperBinding::VerifiedInstalledRelease; + let local = HelperBinding::LocalPins; + for (platform, identity, interpreter, script) in [ + ("linux", "root", "posix_sh", "true\n"), + ("windows", "system", "powershell", "Write-Output 'ok'\r\n"), + ] { + let mut 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: 1, + 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 binary = "ab".repeat(32); + let local_policy = "cd".repeat(32); + 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:{local_policy}"), + format!("helper.binary.sha256:{binary}"), + ]; + let mut scope = json!({ + "tenant_id": job.tenant_id, "asset_id": job.asset_id, "agent_id": job.agent_id, + "enrollment_generation": 1, "assignment_version": 1, "principals": ["local:reviewer"], + "helper_policy_sha256": local_policy, "helper_binary_sha256": binary, + "acceptance_evidence_id": Uuid::new_v4(), "allowed_services": [], + "allowed_script_profiles": ["full_maintenance_v1"] + }); + if platform == "linux" { + scope["allow_root_scripts"] = json!(true); + scope["allow_reboot"] = json!(false); + } else { + scope["max_runtime_seconds"] = json!(30); + scope["allowed_script_sha256"] = json!([rmm_domain::jobs::hash(script.as_bytes())]); + caps.push("script.powershell/1".into()); + } + let mut config = json!({"schema_version": 1, "linux": [], "windows": []}); + config[platform] = json!([scope]); + let policy: Policy = serde_json::from_value(config.clone()).unwrap(); + assert!(policy.permits("local:reviewer", &job, &caps, verified)); + assert!(!policy.permits(token, &job, &caps, verified)); + + config[platform][0]["principals"] = json!(["local:reviewer", SCOPED_MCP]); + let policy: Policy = serde_json::from_value(config).unwrap(); + assert!(policy.permits(token, &job, &caps, verified), "{platform}"); + assert!(!policy.permits(token, &job, &caps, local)); + assert!(policy.permits("local:reviewer", &job, &caps, local)); + assert!(policy.permits("local:reviewer", &job, &caps, verified)); + for other in [ + SCOPED_MCP, + "local:other", + "mcp:not-a-uuid", + "mcp:00000000-0000-0000-0000-000000000000", + "mcp:12345678ABCD4321B123123456789ABC", + ] { + assert!( + !policy.permits(other, &job, &caps, verified), + "{platform}: {other}" + ); + } + let mut without_binary = caps.clone(); + without_binary.retain(|cap| !cap.starts_with("helper.binary.sha256:")); + assert!(!policy.permits(token, &job, &without_binary, verified)); + job.assignment_version += 1; + assert!(!policy.permits(token, &job, &caps, verified)); + if platform == "windows" { + job.assignment_version -= 1; + if let Action::RunScript { arguments, .. } = &mut job.action { + arguments.push("other".into()); + } + assert!(!policy.permits(token, &job, &caps, verified)); + if let Action::RunScript { + script_utf8, + arguments, + .. + } = &mut job.action + { + arguments.clear(); + *script_utf8 = "Write-Output 'changed'\r\n".into(); + } + assert!(!policy.permits(token, &job, &caps, verified)); + } + } + } #[test] fn signed_helper_is_bound_to_platform_reported_version_and_unambiguous_local_pins() { diff --git a/docs/mvp-completion-plan.md b/docs/mvp-completion-plan.md index af0e5ec..919e500 100644 --- a/docs/mvp-completion-plan.md +++ b/docs/mvp-completion-plan.md @@ -15,6 +15,8 @@ Auf Windows lieferte der erste Vorversuch Exitcode 0 und keine Ausgabe. Revision **Manifest-Gültigkeit für installierte Administrator-Helper.** Im Quellstand behoben. Der Server prüft die Gültigkeit zum gespeicherten Katalogzeitpunkt und verwendet den aktuellen Schlüsselring. Der Regressionstest prüft ein abgelaufenes Manifest in beiden Pfaden sowie den Widerruf des Signierschlüssels. Die HTTPS-Aufnahme und der Release-Katalog wurden zusätzlich mit isoliertem PostgreSQL geprüft. +**MCP-Abnahme mit individuellen Tokenrechten.** Beim neuen Versuch auf `dev-znuny-db` lehnte der Server den Root-Dateitest bei der Planung mit `SCRIPT_HELPER_SCOPE_DENIED` ab. Der Token hatte die Aktionsrechte, die zentrale Regel für den installierten Helper kannte den Antragsteller nicht. Die feste Bibliotheksrevision „Linux-Kernelversion“ wurde über MCP eingereicht. Die aktuelle Abnahme umfasst je Gerät die Datei mit `HelloWelt`, das Katalogergebnis, den Bootwechsel und einen Ping-Auftrag nach Wiederanmeldung. Zuerst Linux auswerten, dann die Windows-Test-VM prüfen. [Betriebsweg](public-access.md#administrator-skripte-anfordern) + ## Ergänzte Lieferungen am 17. November 2026 - Umlautdarstellung für native PowerShell-Ausgabe korrigiert und am gespeicherten Updateergebnis in der WebUI geprüft. [Darstellung](evidence/powershell-output-encoding-20261117.json) diff --git a/docs/project-decisions.md b/docs/project-decisions.md index b833670..e086091 100644 --- a/docs/project-decisions.md +++ b/docs/project-decisions.md @@ -1,6 +1,10 @@ # Verbindliche Projektentscheidungen -Stand: **2026-11-18**, Spezifikation **1.40** (`Rust_RMM_Implementierungsspezifikation.md`). Die ausdrücklichen normativen Entscheidungen in Kapitel 0 haben Vorrang vor früheren Architekturannahmen. Version 1.6 ersetzt die lokale Servertopologie durch den dedizierten Internetserver; Version 1.7 präzisiert das Notebook als reinen Entwicklungsrechner; Version 1.8 erlaubt vorgezogene parallele Windows-Entwicklung. +Stand: **2026-11-18**, Spezifikation **1.41** (`Rust_RMM_Implementierungsspezifikation.md`). Die ausdrücklichen normativen Entscheidungen in Kapitel 0 haben Vorrang vor früheren Architekturannahmen. Version 1.6 ersetzt die lokale Servertopologie durch den dedizierten Internetserver; Version 1.7 präzisiert das Notebook als reinen Entwicklungsrechner; Version 1.8 erlaubt vorgezogene parallele Windows-Entwicklung. + +## Zentrale Rechte für MCP-Skriptanträge (Version 1.41) + +Die Rechte für Administrator-Skripte werden pro Token und Kunde auf dem Server vergeben. Ein vorbereiteter Client kann solche Aufträge ohne Benutzereingriff am Gerät abarbeiten. Für Betreiber gehört die Auswahl zulässiger Skripte zur Geräteregel und die Freigabe des konkreten Auftrags zu „Genehmigungen“. [Produktvertrag](../Rust_RMM_Implementierungsspezifikation.md#012-mcp-anträge-für-administrator-skripte-version-141) ## Release-Gültigkeit für installierte Skripthelfer (Version 1.40) diff --git a/docs/public-access.md b/docs/public-access.md index 5d0f75d..3a9a13b 100644 --- a/docs/public-access.md +++ b/docs/public-access.md @@ -18,6 +18,21 @@ Die Kontokonfiguration liegt auf dem Server unter `/opt/rust-discovery/devstate/ ## MCP-Tokens +### Administrator-Skripte anfordern + +Für einen vollständigen Skriptauftrag braucht ein Token im Zielkunden `operations:plan`, `operations:submit`, `operations:read` und `scripts:execute`. Hinzu kommt für Administratoraufträge je Plattform `root:execute` oder `system:execute`. Zum Veröffentlichen einer Skriptversion benötigt das Token `operations:plan` und `scripts:execute`. + +Auf einem Gerät mit installiertem, signiertem Administrator-Helper kann der Betreiber die vorhandene Geräteregel einmal für diese Tokenrechte öffnen. Der folgende Befehl zeigt den Zustand für genau die gewählte Regel. Die Werte in Großbuchstaben sind durch die Kennungen der Installation und der bestehenden Regel zu ersetzen. + +```sh +python3 tools/dev_mcp_script_scope.py check --platform linux \ + --tenant TENANT_ID --asset ASSET_ID --agent AGENT_ID --evidence ACCEPTANCE_EVIDENCE_ID +``` + +Mit `enable` wird der Eintrag `mcp:scoped` dieser Regel hinzugefügt, mit `disable` wieder entfernt. Für Windows lautet die Plattform `windows`. Der Server wertet die Regel bei der nächsten Rechteprüfung aus. Bereits separat an einzelne Tokens vergebene Rechte lassen sich durch Widerruf des Tokens entziehen. Ein freies Skript über `operations.plan` oder eine Bibliotheksversion über `scripts.plan` planen und über `operations.submit` einreichen. Die persönliche Entscheidung erfolgt in der WebUI. `jobs.get` liefert über die Auftragskennung den Stand und über die Jobkennung das Ausführungsergebnis. + +### Token ausstellen + Nach der WebUI-Anmeldung unter **Verwaltung → MCP-Tokens** einen Namen, den Kundenkreis, die benötigten Rechte und ein Ablaufdatum wählen. Ein einzelner Kunde ist vorausgewählt. Weitere Kunden lassen sich einzeln ergänzen. „Alle aktuellen und zukünftigen Kunden“ ist eine eigene Option für Kundenadministratoren. Standard sind gespeichertes Inventar, Protokolle und Aufträge/Ergebnisse lesen. Der Tokenwert wird einmal angezeigt. Er kann anschließend im MCP-Client als HTTP-Header hinterlegt werden. ```http diff --git a/tools/dev_mcp_script_scope.py b/tools/dev_mcp_script_scope.py new file mode 100644 index 0000000..b06f424 --- /dev/null +++ b/tools/dev_mcp_script_scope.py @@ -0,0 +1,84 @@ +#!/usr/bin/env python3 +"""Manage scoped MCP planning on one existing Linux or Windows script-helper rule.""" +import argparse +import fcntl +import inspect +import json +from pathlib import Path +import re +import stat +import subprocess +import uuid + +from dev_linux_helper_rollover import POLICY, encoded, protected, replace, require +from dev_stage import ssh_prefix + + +def configure(path, platform, binding, action): + signer = (path.parent.parent / 'jobs/ed25519.pem').lstat() + require(stat.S_ISREG(signer.st_mode), 'Expected a regular job signer file') + owner = signer.st_uid + lock = path.with_name('operator.lock') + protected(path, owner) + lock_info = lock.lstat() + require(stat.S_ISREG(lock_info.st_mode) and lock_info.st_uid in (0, owner) + and not lock_info.st_mode & 0o022, + 'Invalid operator.lock') + with lock.open('rb') as guard: + fcntl.flock(guard, fcntl.LOCK_EX) + info = protected(path, owner) + require(stat.S_IMODE(info.st_mode) == 0o600 and info.st_size <= 65536, + 'Invalid managed policy file') + policy = json.loads(path.read_bytes()) + require(policy['schema_version'] == 1, 'Unknown policy format') + matches = [scope for scope in policy[platform] + if all(scope.get(key) == value for key, value in binding.items())] + require(len(matches) == 1, 'Expected exactly one matching existing device rule') + scope = matches[0] + require(scope.get('allowed_script_profiles') == ['full_maintenance_v1'] + and (platform != 'linux' or scope.get('allow_root_scripts') is True) + and all(re.fullmatch(r'[0-9a-f]{64}', scope.get(key) or '') + for key in ('helper_binary_sha256', 'helper_policy_sha256')), + 'Rule does not describe a pinned administrator script helper') + principals = scope['principals'] + require(isinstance(principals, list) and 1 <= len(principals) <= 64 + and len(principals) == len(set(principals)), + 'Invalid rule principals') + marker = 'mcp:scoped' + enabled = marker in principals + changed = action != 'check' and enabled != (action == 'enable') + if changed: + if action == 'enable': + require(len(principals) < 64, 'Rule principal list is full') + principals.append(marker) + else: + require(len(principals) > 1, 'Removing the last principal would invalidate this rule') + principals.remove(marker) + data = encoded(policy) + require(len(data) <= 65536, 'Managed policy exceeds the server size limit') + replace(path, data) + return {**binding, 'platform': platform, 'scoped_mcp_planning': marker in principals, + 'changed': changed} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('action', choices=('check', 'enable', 'disable')) + parser.add_argument('--platform', required=True, choices=('linux', 'windows')) + for field in ('tenant', 'asset', 'agent'): + parser.add_argument('--' + field, required=True, type=uuid.UUID) + parser.add_argument('--evidence', required=True, help='acceptance_evidence_id of the existing device rule') + args = parser.parse_args() + binding = dict(tenant_id=str(args.tenant), asset_id=str(args.asset), agent_id=str(args.agent), + acceptance_evidence_id=args.evidence) + # Send the same locked atomic file operations as helper rollover through the pinned SSH profile. + program = 'import fcntl,json,os,re,stat,tempfile\nfrom pathlib import Path\n' + for helper in (require, protected, encoded, replace, configure): + program += inspect.getsource(helper) + '\n' + params = (args.platform, binding, args.action) + program += f'print(json.dumps(configure(Path({str(POLICY)!r}), *{params!r})))\n' + subprocess.run([*ssh_prefix('server'), 'python3 -I -'], input=program, text=True, check=True) + + +if __name__ == '__main__': + main()