Zum Inhalt

Approval-Policy

Stand: 2026-05-26

Ziel

Agenten dürfen produktiv helfen, aber keine gefährlichen Infrastruktur-Änderungen unkontrolliert ausführen. Die Policy trennt Discovery, lokale Dokuarbeit und produktive Writes.

Toolklassen

Klasse Beispiele Standard
Discovery git status, curl -I, NetBox read, Proxmox list, DNS lookup erlaubt
Lokale Dokuarbeit Markdown, Runbooks, Prompts, Skripte im Repo erlaubt mit Backup/Diff
Lokaler Git-Write Commit, Push, PR erlaubt nach Diff-Pruefung
Kontrollierter API-Write NetBox write, Gitea Issue/PR, n8n Workflow Approval oder dokumentierter Auftrag
Produktiver System-Write SSH sudo, Proxmox config, UniFi Firewall, NPM Proxy expliziter Changeplan
Blockiert Secret-Dump, Private-Key-Kopie, destruktives Löschen, Firewall-Lockout nicht automatisch

Pflichtfelder für produktive Changes

Jeder produktive Change braucht:

  • Ziel
  • betroffene Systeme
  • Ist-Zustand
  • Backup
  • Änderungsplan
  • Rollback
  • Testplan
  • Run-ID
  • Git-Referenz oder Change-Referenz

Technisches Approval-Schema

Write-Tools müssen serverseitig ablehnen, wenn eine produktive Write-Anfrage keine gültige Approval-ID enthält. Das Frontend darf diese Prüfung nicht nur selbst übernehmen.

Pflichtfelder für Live-Writes:

Feld Zweck
approval_id Eindeutige Freigabe-ID aus Ticket, Changeplan oder genehmigtem Runbook
approved_by Menschliche freigebende Person
change_ticket Ticket-, Issue- oder Changeplan-Referenz
risk_level low, medium, high oder forbidden
expires_at Ablaufzeit der Freigabe; abgelaufene Freigaben müssen abgelehnt werden
requested_action Kurzbeschreibung der beantragten Aktion
target_system Zielsystem wie netbox, proxmox, npm, gitea, ad, exchange, intune

Die Lanstyle Tools API und der Remote-MCP nutzen dieses Schema jetzt im Controlled Execution Layer. Produktive Live-Writes sind weiterhin stark eingeschraenkt; erlaubt sind Mock, Export-only Aktionen und explizit gescopte Low-Risk-Testwrites.

Zusätzliche Pflichtfelder im Controlled Execution Layer:

  • requested_by
  • action_type
  • backup_required
  • backup_reference
  • rollback_plan
  • execution_status

Approval-IDs sind Single-Use. Eine erfolgreiche Aktion verbraucht die Freigabe.

Failure-Audits muessen die Backup-Referenz enthalten, wenn der Backup-/Export-Schritt bereits erfolgreich war. Eine Rollback-Referenz darf nur entstehen, wenn der Write erfolgreich war und die Verification den Zielzustand bestaetigt hat.

Bei Execution Chains kann eine Approval-ID spaeter entweder pro Step oder fuer die gesamte Chain gelten. Bis produktive Chains freigegeben sind, ist nur Mock-/Dry-Run-Ausfuehrung erlaubt. Jede produktive Chain muss Step-Audit, Step-Verification und Rollback-Reihenfolge nachweisen.

Approval UX

Jeder Approval Request soll automatisch einen Operator-Changeplan erzeugen. Pflichtinhalte:

  • kurze Zusammenfassung
  • voller Changeplan als Markdown-/JSON-Artefakt
  • exakter Freigabetext
  • Ablaufzeit
  • Approver-Anforderungen
  • Risk Level
  • Blast Radius
  • Maintenance-Window-Warnung
  • Policy-Entscheidung
  • Blockgruende, falls vorhanden

OpenCode darf bei policy_decision=blocked oder vorhandenen blocked_reasons keinen Execute anbieten, sondern muss den Changeplan und die Blockgruende anzeigen.

Die Unified Operator Response enthaelt zusaetzlich:

  • requires_human_review
  • requires_approval
  • requires_second_approval
  • requires_maintenance_window
  • requires_manual_verification
  • requires_post_execution_validation

Diese Flags sind fuer OpenCode verbindliche Bedienhinweise. Execute darf nicht angeboten werden, wenn ein erforderlicher Review-/Approval-Schritt offen ist.

Golden Path Approval

Golden Paths duerfen ohne Approval nur katalogisiert, validiert und simuliert werden. Ein spaeterer produktiver Execute braucht weiterhin eine konkrete Approval-ID fuer den Ziel-Workflow und die Zielobjekte.

Die Approval muss den konkreten Golden Path, die Version und die Inputs referenzieren. Eine allgemeine Freigabe wie "LXC anlegen" reicht nicht.

Backup-Regel

Vor jeder Datei- oder Konfigurationsaenderung:

  • lokale Datei: *.bak-YYYYMMDD-HHMMSS
  • Remote-Konfiguration: Backup im Zielsystem mit Zeitstempel
  • Datenbank: Dump oder dateibasiertes Backup vor manuellen Aenderungen

Secret-Regel

  • Keine Secrets in Git.
  • Keine privaten SSH-Keys kopieren oder exportieren.
  • Keine Secret-Werte in Markdown-Dokumentation.
  • Lokale temporäre Secret-Arbeitsdateien müssen ignoriert, zugriffsbeschränkt und nach Rotation entfernt werden.
  • In Doku nur Vaultwarden-Eintragsnamen referenzieren.

Agentenverhalten

Agenten sollen bei riskanten Aktionen nicht raten, sondern einen Changeplan erzeugen. Wenn der Benutzer einen laufenden Change explizit freigibt, wird trotzdem Backup, Test und Dokumentation ausgeführt.

Maschinenlesbare Policy

Die maschinenlesbare Approval-Policy liegt unter:

  • agent-runtime/configs/approval-flow.yaml

Ein separates plan-only MCP erzeugt strukturierte Changeplaene:

  • agent-runtime/mcp/lanstyle-infra-write-plan-mcp

Dieses MCP führt keine Live-Writes aus.

Die kontrollierte Ausfuehrung laeuft separat ueber:

  • agent-runtime/tools/controlled_execution.py
  • docs/agent-runtime/controlled-execution.md