Controlled Execution Layer

Stand: 2026-05-26

Ziel

Der Controlled Execution Layer ist die einzige vorgesehene Schicht fuer echte Infrastruktur-Writes. Er ersetzt keine menschliche Freigabe und stellt keine freie Root-Shell bereit.

Zielkette:

Prompt -> Plan -> Risk Classification -> Backup Requirement -> Approval ID
-> Controlled Execute MCP/API -> Verification -> Audit -> Rollback Reference -> Dokumentation

Status

Aktiv in LXC 259:

• Python-Engine: /opt/agent-runtime/tools/controlled_execution.py
• OpenAPI-Endpoint: http://10.222.70.20:3010/controlled-execution/*
• Remote-MCP-Tools: https://mcphub.lanstyle.de/lanstyle-mcp
• Approval Store: /opt/agent-runtime/controlled-execution/approvals.jsonl
• Backups/Exports: /opt/agent-runtime/controlled-execution/backups/
• Audit Log: /opt/agent-runtime/logs/controlled-execution.jsonl

Dateirechte:

• Approval Store: 0600
• Audit Log: 0600
• Backup-Exports: 0600

Execution Policy

Pflichtfelder fuer jede freigegebene Aktion:

Feld	Zweck
approval_id	Eindeutige Einmalfreigabe
requested_by	Anforderer
approved_by	Menschlicher Freigeber
change_ticket	Ticket, Issue oder Changeplan
risk_level	low, medium, high, forbidden
target_system	Zielsystem
action_type	Exakt erlaubte Aktion
requested_action	Menschlich lesbare Kurzbeschreibung
backup_required	Muss fuer Writes true sein
backup_reference	Pfad/Referenz auf Backup oder auto
rollback_plan	Rueckweg
expires_at	Ablaufzeitpunkt
execution_status	Muss approved sein

Approval-IDs sind Single-Use. Eine bereits erfolgreich verwendete approval_id wird bei erneuter Nutzung abgelehnt.

Risk Levels

Level	Bedeutung
low	Mock, Export, nicht-destruktive, gut rueckverfolgbare Operation
medium	Begrenzter produktiver Write mit eindeutigem Zielobjekt
high	Moegliche Service-Auswirkung oder Netzwerk-/Routing-Relevanz
forbidden	Durch Policy blockiert

Forbidden Actions

Automatisch blockiert:

• VM/LXC delete/destroy
• Firewall default policy changes
• mass AD changes
• mass Exchange changes
• Intune wipe/delete
• secret export
• NPM Access List lockout
• VLAN/routing destructive changes
• Proxmox storage deletion

Aktuell Ausfuehrbare Aktionen

Produktive Infrastruktur-Writes sind noch nicht aktiviert. Ausfuehrbar sind nur ungefaehrliche Aktionen:

Zielsystem	Action	Wirkung
mock	mock_noop_change	schreibt nur Backup-/Audit-Testdaten
proxmox	config_export	liest Proxmox-Konfiguration/Ressourcen und schreibt Export
proxmox	set_lxc_description	setzt ausschliesslich die Beschreibung des Test-LXC 121 auf einen freigegebenen Testwert
npm	export_proxy_host	liest NPM Proxy Hosts und schreibt Export
netbox	export_object	liest NetBox-Objekt/API-Liste und schreibt Export
netbox	test_write	erstellt/aktualisiert ausschliesslich das NetBox-Test-Tag AI-Controlled-Execution-Test mit Slug ai-execution-test

Weitere produktionsnahe Actions sind als Policy vorgesehen, aber nicht live aktiviert:

• Proxmox: create_lxc, start_lxc, stop_lxc, snapshot_lxc, set_lxc_description, attach_vlan_interface
• NetBox: create_prefix, reserve_ip, create_vlan, tag_object, update_description
• NPM: update_backend, rollback_backend
• Open Terminal: restricted_execute

Fuer die erste Multi-System-Orchestrierung lanstyle-ce-test-01 sind folgende Actions nur als Plan-/Preflight-Schritte vorbereitet:

• proxmox:plan_create_lxc
• proxmox:plan_set_resources
• proxmox:plan_attach_vlan
• netbox:plan_create_vm_object
• mkdocs:plan_create_doc_stub
• proxmox:stop_lxc
• proxmox:archive_lxc_config
• proxmox:plan_remove_lxc
• netbox:plan_remove_vm_object
• mkdocs:plan_remove_doc_stub

Diese Plan-Actions fuehren keine produktiven Writes aus.

proxmox:remove_lxc, netbox:remove_vm_object und mkdocs:remove_doc_stub sind weiterhin nicht aktiv. Destroy-Aktionen brauchen den separaten Cleanup-Governance-Pfad mit Cooldown, Double Confirmation, Dependency Check und Archivnachweis.

Backup Enforcement

Vor erfolgreicher Ausfuehrung erzeugt die Engine einen Backup-/Export-Nachweis. Ohne gueltiges Backup wird die Verification fehlschlagen und die Aktion endet ohne Folge-Write.

Derzeit erzeugte Referenzen:

• Mock: Mock-Backup JSON
• Proxmox: API-Export JSON
• Proxmox LXC Description Test: Vorab-Export der LXC-Konfiguration
• NPM: Proxy-Host-Export JSON
• NetBox: Objekt-/Listen-Export JSON
• NetBox Test Write: Vorab-Export des Tags ai-execution-test

Approval Engine

Der Server prueft:

• approval_id existiert
• Status ist approved
• Freigabe ist nicht abgelaufen
• target_system und action_type passen exakt
• requested_action passt exakt
• Risiko der Anfrage ueberschreitet nicht das genehmigte Risiko
• backup_required ist true
• Approval-ID wurde noch nicht erfolgreich verbraucht
• Action ist nicht forbidden

Das LLM entscheidet nicht, ob eine Freigabe gueltig ist.

Audit Logging

Jeder Versuch schreibt ein JSONL-Event mit:

• run_id
• approval_id
• user
• target_system
• action_type
• input_hash
• backup_reference
• verification_result
• rollback_reference
• timestamp
• duration_ms
• status

Secrets werden vor dem Schreiben redacted. Der Secret-Scan auf Audit und Backups war am 2026-05-26 ohne Treffer.

Changeplan-Artefakte

Zusätzlich zu Audit und Backup erzeugt die Operator-UX fuer Preflights, Approval Requests, Recovery-Flows und Beispielplaene standardisierte Changeplan-Artefakte.

Speicherort:

• /var/lib/lanstyle-agent/controlled-execution/artifacts/

Formate:

• Markdown fuer menschliche Review
• JSON fuer OpenCode, API-Clients und spaetere Automationen

Jedes Artefakt enthaelt:

• approval_request
• execution_chain_plan
• risk_summary
• lock_summary
• backup_summary
• rollback_summary
• recovery_summary
• verification_summary
• audit_references
• operator_summary
• timeline

Details: Changeplan-Artefakte.

Verification und Rollback

Verification prueft mindestens:

• Backup-Datei existiert
• Backup-Datei ist nicht leer
• Backup-Datei hat private Rechte 0600

Rollback wird nicht automatisch ausgefuehrt. Jede erfolgreiche Aktion bekommt eine Rollback-Referenz und einen textlichen Rueckweg.

OpenCode-Nutzung

OpenCode nutzt die Remote-MCP-Tools:

• controlled_execution_get_policy
• controlled_execution_mock_noop
• controlled_execution_proxmox_config_export
• controlled_execution_proxmox_set_lxc_description
• controlled_execution_npm_proxy_export
• controlled_execution_netbox_object_export
• controlled_execution_netbox_test_write

Flow fuer echte Changes:

1. Plan mit Ist-Zustand, Risiko, Backup-Anforderung, Tests und Rollback erzeugen.
2. Menschliche Approval-ID einholen.
3. Scoped Execute Tool mit exakt passendem target_system und action_type aufrufen.
4. Verification und Audit pruefen.
5. Dokumentation aktualisieren.

Open WebUI-Nutzung

Open WebUI nutzt denselben Layer ueber die Lanstyle Tools API:

• GET /controlled-execution/policy
• POST /controlled-execution/execute

Es gibt keinen separaten Open-WebUI-Write-Pfad.

State und Drift

Der Controlled Execution Layer wird durch einen read-only State Layer ergaenzt:

• GET /state/policy
• GET /state/lxc-124-desired
• POST /state/drift-check

Diese Endpunkte fuehren keine Writes aus. Sie vergleichen desired_state und observed_state, erzeugen stabile Hashes und markieren Drift. Reconciliation bleibt plan-only und braucht spaeter eine eigene Approval-ID.

Fuer Chain-verwaltete Objekte muessen State Records mindestens enthalten:

• object_id
• source_system
• created_by_chain
• approval_reference
• backup_reference
• current_state_hash
• desired_state_hash
• last_verified_at
• drift_detected
• rollback_possible
• cleanup_state

Policy und Risk

Vor spaeteren produktiven Writes kann die Tools-API eine read-only Risk-/Policy-Bewertung liefern:

• GET /policy-risk/policy
• GET /policy-risk/lxc-124
• POST /policy-risk/evaluate

Diese Endpunkte fuehren keine Writes aus. Sie bewerten Risk Score, Risk Level, Blast Radius, Maintenance Window, Policy-Verstoesse, Approval Escalation und Dependency Locks.

Die Risk Engine ersetzt keine Approval-ID. Sie begrenzt und erlaeutert nur, welche Approval-Stufe und welche Constraints fuer eine Chain erforderlich sind.

Dependency Locks im Lifecycle

Execution Chains muessen vor dem Execute einen Dependency Lock erwerben. Der Lock ist an chain_id, approval_id und Zielobjekt gebunden.

Blockiert wird bei:

• fremdem aktivem Write-/Destructive-/Global-Lock
• orphaned Lock auf demselben Zielobjekt
• failed-release Lock auf demselben Zielobjekt
• abgelaufenem aktiven Lock ohne Manual Review

Nach erfolgreicher Verification und Audit wird der Lock released. Bei Chain-Failure bleibt er nicht stillschweigend weg, sondern wird als orphaned markiert.

Ein Timeout macht einen Lock nicht automatisch sicher. Stale/expired aktive Locks blockieren Folge-Chains auf demselben Objekt. Der korrekte Weg ist inspect_lock, inspect_chain_status, state_drift_check, recovery_preflight, Recovery Approval und erst danach release_after_verification.

Fuer Proxmox-Lifecycle-Actions gilt:

• start_lxc: backup_required=true, backup_type=proxmox_config_export
• stop_lxc: backup_required=true, backup_type=proxmox_config_export
• Snapshot ist fuer reine Start-/Stop-Aktionen nicht zwingend, der Config-/State-Export aber schon.

Der Lock-Store ist fuer v2 SQLite-basiert. Wenn SQLite nicht verfuegbar ist, muss Execute fail-closed abbrechen. JSONL bleibt Audit Trail und darf nicht als unsicherer automatischer Fallback fuer neue Writes genutzt werden.

Tests 2026-05-26

Erfolgreich:

• Policy Endpoint: 200
• Unauthorized Execute: 401
• Mock mit gueltiger Approval-ID: 200
• Proxmox Config Export: 200, keine Infrastruktur-Aenderung
• Proxmox set_lxc_description fuer Test-LXC 121: Write ausgefuehrt, Vorab-Export geschrieben, Verification erfolgreich, Audit ok
• Proxmox rollback_set_lxc_description fuer Test-LXC 121: Rollback ausgefuehrt, Vorab-Export geschrieben, Verification erfolgreich, Audit ok
• NetBox test_write: Vorab-Export geschrieben, Write durch NetBox mit 403 Forbidden abgelehnt, kein Testobjekt erstellt
• Execution Chain proxmox_test_chain_v1: zwei scoped Proxmox-Steps erfolgreich, Chain-Audit geschrieben, Rollback nur geplant
• Execution Chain lanstyle_ce_test_01_create: LXC 124 erfolgreich erstellt, Ressourcen/Netz/Beschreibung gesetzt, keine Folge-Writes, Rollback nur geplant
• NPM Proxy Export: 200, keine Infrastruktur-Aenderung
• fehlende Approval-ID: 400
• abgelaufene Approval-ID: 400
• falsches Zielsystem zur Approval-ID: 400
• forbidden Action proxmox:destroy_guest: 400
• Single-Use-Replay derselben Approval-ID: 400
• fehlendes backup_required=true: 400
• Remote-MCP Policy Tool: 200
• Remote-MCP Mock Tool: 200
• Healthcheck: OK: 25 checks

Proxmox set_lxc_description Test

Approval-ID: appr-proxmox-set-lxc-description-20260526-024135

Ziel: ausschliesslich LXC 121 auf Node pve, Beschreibung Controlled Execution Layer Test.

Ergebnis:

• Backup/Export: /opt/agent-runtime/controlled-execution/backups/proxmox/20260526-004819-run-proxmox-set-lxc-description-20260526-024135-set_lxc_description.json
• Backup-Rechte: 0600, Owner root:root
• Verification: backup_file_exists, backup_file_nonempty, backup_file_private, proxmox_lxc_description_matches
• Audit: erfolgreicher ok-Eintrag fuer run-proxmox-set-lxc-description-20260526-024135
• Rollback-Referenz: rollback:run-proxmox-set-lxc-description-20260526-024135:proxmox:set_lxc_description
• Replay-Schutz: erneute Nutzung derselben Approval-ID liefert 400
• Fehlende Approval-ID: 400
• Falsche Approval-ID: 400

Beobachtung: Proxmox gibt die gesetzte Beschreibung ueber die API mit einem abschliessenden Newline zurueck. Die Verification normalisiert deshalb Whitespace am Rand, ohne den erlaubten Zielwert zu erweitern. Es wurde kein zweiter Proxmox-Write fuer die Reconciliation ausgefuehrt.

Proxmox rollback_set_lxc_description Test

Approval-ID: appr-proxmox-rollback-set-lxc-description-20260526-030305

Ziel: ausschliesslich LXC 121 auf Node pve, Beschreibung zurueck auf den vorherigen leeren Zustand.

Ergebnis:

• Backup/Export direkt vor Rollback: /opt/agent-runtime/controlled-execution/backups/proxmox/20260526-011753-run-proxmox-rollback-set-lxc-description-20260526-030305-rollback_set_lxc_description.json
• Backup-Rechte: 0600, Owner root:root
• Verification: backup_file_exists, backup_file_nonempty, backup_file_private, proxmox_lxc_description_restored_empty
• Audit: erfolgreicher ok-Eintrag fuer run-proxmox-rollback-set-lxc-description-20260526-030305
• Rollback-/Roll-forward-Referenz: rollback:run-proxmox-rollback-set-lxc-description-20260526-030305:proxmox:rollback_set_lxc_description
• Replay-Schutz: erneute Nutzung derselben Approval-ID liefert 400
• Ergebnis am Ziel: LXC 121 enthaelt keine description-Zeile mehr

Beobachtung: Die Execute-API klassifiziert scoped Write-Actions jetzt fuer Folgeausfuehrungen als execution_mode=scoped_write und live_infrastructure_changed=true. Der Rollback selbst wurde bereits vor dieser reinen Rueckgabe-Korrektur erfolgreich ausgefuehrt und auditierbar verifiziert.

NetBox test_write Versuch

Approval-ID: appr-netbox-test-write-20260526-032955

Ziel: ausschliesslich NetBox-Test-Tag AI-Controlled-Execution-Test mit Slug ai-execution-test.

Ergebnis:

• Backup/Export direkt vor Write: /opt/agent-runtime/controlled-execution/backups/netbox/20260526-090028-run-netbox-test-write-20260526-032955-test_write.json
• Backup-Rechte: 0600, Owner root:root
• NetBox-Write: durch NetBox mit 403 Forbidden abgelehnt
• Testobjekt: nicht erstellt, ai-execution-test existiert weiterhin nicht
• Audit: failed-Eintrag fuer run-netbox-test-write-20260526-032955
• Verification/Rollback: nicht erzeugt, weil der Write nicht ausgefuehrt wurde

Beobachtung: Das Verhalten ist fail-closed und zeigt, dass der aktuell genutzte NetBox-Token keine Tag-Write-Rechte hat. Fuer einen erfolgreichen NetBox-Write-Test braucht es entweder ein explizit freigegebenes Test-Write-Token mit minimalen Rechten fuer extras.tags oder eine andere eindeutig nicht-produktive NetBox-Action, die vom vorhandenen Token erlaubt wird.

Audit-Nacharbeit: Der Failure-Audit-Pfad wurde korrigiert. Wenn ein Backup/Export erfolgreich geschrieben wurde und der anschliessende Write oder die Verification fehlschlaegt, enthaelt der failed-/rejected-Audit-Eintrag jetzt trotzdem backup_reference und backup_status. Eine isolierte Mock-Failure-Simulation bestaetigt: Backup vorhanden, Status failed, keine Rollback-Referenz ohne erfolgreichen Write.

NetBox-Testwrite-Vorbereitung: Der dedizierte Benutzer lanstyle-agent-netbox-test-write und ein separater Runtime-Token NETBOX_TEST_WRITE_TOKEN sind vorbereitet. Der Token hat API-Zugriff auf Status und Tags, aber keine Prefix-Write-Rechte. Der eigentliche netbox:test_write nutzt eine neue Approval-ID: appr-netbox-test-write-20260526-114210.

NetBox test_write Erfolg

Approval-ID: appr-netbox-test-write-20260526-114210

Ziel: ausschliesslich NetBox-Test-Tag AI-Controlled-Execution-Test mit Slug ai-execution-test.

Ergebnis:

• Backup/Export direkt vor Write: /opt/agent-runtime/controlled-execution/backups/netbox/20260526-094122-run-netbox-test-write-20260526-114210-test_write.json
• Backup-Rechte: 0600, Owner root:root
• Execution: scoped_write, live_infrastructure_changed=true
• Operation: created
• Objekt-ID: 8
• Verification: backup_file_exists, backup_file_nonempty, backup_file_private, netbox_tag_exists, netbox_tag_name_matches, netbox_tag_description_matches
• Audit: erfolgreicher ok-Eintrag fuer run-netbox-test-write-20260526-114210
• Rollback-Referenz: rollback:run-netbox-test-write-20260526-114210:netbox:test_write
• Replay-Schutz: erneute Nutzung derselben Approval-ID liefert 400
• Negativtest: Prefix-Write mit Testtoken liefert 403

Kein Cleanup wurde ausgefuehrt. Wenn der Test-Tag entfernt werden soll, braucht das eine separate Approval-ID und eine eigene scoped Cleanup-Action.

Execution Chains

Mehrstufige Workflows werden separat in Execution Chains beschrieben. Aktiv sind Mock-/Dry-Run-Chains und die eng begrenzte Proxmox-Test-Chain proxmox_test_chain_v1 fuer LXC 121. Produktive Chains fuer NetBox, NPM, DNS, AD, Exchange, Intune oder Firewall sind nicht aktiviert.

Der Multi-System-Preflight lanstyle_ce_test_01_preflight ist als Governance-Validierung aktiv und prueft Dependency Graph, Rollback-Reihenfolge, Risk Summary und Approval Scope ohne Live-Write.

Die erste echte Proxmox-Create-Chain lanstyle_ce_test_01_create wurde mit Approval appr-chain-lanstyle-ce-test-01-create-20260526-134137 ausgefuehrt. Sie beschraenkt sich auf Proxmox und LXC 124; NetBox-, MkDocs-, DNS-, NPM- und Firewall-Writes sind nicht Teil dieser Approval.

Absichtlich Nicht Erlaubt

• freie Shell
• freie SSH-/PowerShell-Kommandos
• direkte NPM-SQLite-Manipulation
• produktive Firewall-/DNS-/AD-/Exchange-/Intune-Aenderungen
• Proxmox Guest Delete/Destroy
• Secret Export
• automatische Rollbacks ohne neue Freigabe

Naechster Produktivschritt

Der naechste echte Write sollte eine separate Rollback-Freigabe fuer die Chain-Testbeschreibung oder eine zweite kleine Proxmox-Test-Chain mit vorab definierter Ruecksetzung sein. Der Proxmox-Beschreibungs-Write inklusive Rollback-Pfad ist als Einzelaktion und Chain-Step end-to-end validiert; NetBox ist als Zielsystem mit minimalem Test-Write validiert.