Governance¶

Stand: 2026-05-26

Ziel¶

Die Lanstyle AI Suite darf Infrastruktur nur ueber kontrollierte, nachvollziehbare und rollbackbare Pfade veraendern. Freie Shell-Writes, generische Root-Runner und ungescopte Tool-Ausfuehrung sind nicht Teil des produktiven Governance-Modells.

Kontrollmodell¶

Jeder produktive Write braucht:

scoped Action
Approval-ID
Backup oder Export direkt vor Execute
Verification
Audit
Rollback-Referenz
dokumentierten Stop-Punkt bei Fehlern

Operatoren bekommen dazu einen standardisierten Changeplan:

Markdown fuer Review und Wiki
JSON fuer OpenCode und Automationen
eindeutige Artefakt-ID
keine Secret-Werte
direkte Referenzen auf Approval, Backup, Verification, Audit und Rollback

Details: Changeplan-Artefakte.

Human-in-the-loop Operator Workflow¶

OpenCode nutzt die Operator Workflows, um Changes als gefuehrte Entscheidung anzuzeigen:

Action Classification
Workflow State
Human Decision Points
Suggested Actions
Timeline Cards
Rendering-Hinweise fuer Risiko, Approval, Recovery und Blocker

Die Workflow-Schicht ist nur Fuehrung und Nachvollziehbarkeit. Sie ersetzt keine serverseitige Approval-, Lock-, Backup- oder Policy-Pruefung.

Golden Path Governance¶

Golden Paths sind freigegebene Betriebsablauf-Templates. Sie duerfen nur als Preflight, Dry-Run, Mock Execution oder Operator Workflow Preview laufen, bis die darunterliegenden scoped Actions separat produktiv freigegeben sind.

Pflicht:

versionierter Workflow
validierte Inputs
Safe Ranges
explizit verbotene Actions
Rollback-Strategie
Verification Requirements
Unified Operator Response
Changeplan-Artefakt

Ein Golden Path ersetzt keine Approval-ID und keine menschliche Entscheidung.

Scheduled Operational Workflows¶

Wiederkehrende Betriebsprüfungen laufen über Scheduled Workflows. Diese Schicht ist bewusst read-only:

keine automatischen Restores
keine automatischen Remediations
keine Infrastruktur-Writes
keine Approval-ID nötig
keine Dependency Locks nötig

Scheduled Workflows schreiben nur Reports, History, Trends und Changeplan-Artefakte. Operatoren prüfen Abweichungen und starten bei Bedarf separate, approval-basierte Changeplans.

Multi-System-Orchestrierung¶

Der erste vorbereitete Multi-System-Workflow ist lanstyle_ce_test_01_preflight. Er plant eine dedizierte Governance-Test-LXC, fuehrt aber keine produktive Erstellung aus.

Zielobjekt:

Feld	Wert
Name	`lanstyle-ce-test-01`
CTID	`124`
Node	`pve`
Storage	`local-zfs`
VLAN	`70`
IP-Konzept	`10.222.70.124/24`, Gateway `10.222.70.1`
Tenant	`Lanstyle IT Solutions GmbH`
Umgebung	`governance-test`

Preflight-Ergebnis am 2026-05-26:

CTID 124 ist frei.
lanstyle-ce-test-01 existiert in NetBox nicht.
10.222.70.124/32 ist in NetBox nicht belegt.
10.222.70.124 antwortet nicht auf Ping und hat keinen ARP-Eintrag.
Storage local-zfs hat ausreichend freien Platz.
Kein DNS-, NPM- oder Firewall-Step ist in v1 enthalten.

Dependency Graph¶

flowchart TD
  A["proxmox:plan_create_lxc"] --> B["proxmox:plan_set_resources"]
  B --> C["proxmox:plan_attach_vlan"]
  C --> D["proxmox:set_lxc_description"]
  D --> E["netbox:plan_create_vm_object"]
  E --> F["mkdocs:plan_create_doc_stub"]
  F --> G["verification"]
  G --> H["audit"]
  H --> I["rollback_plan_generation"]

Rollback-Reihenfolge¶

Der Rueckbau ist fuer den spaeteren Live-Test geplant, aber noch nicht aktiviert:

remove_doc_stub
remove_netbox_object
remove_vlan_attachment
stop_lxc
remove_lxc

Destruktive Schritte wie remove_lxc bleiben forbidden, bis es dafuer eine eigene eng gescopte Cleanup-Action mit separater Approval-ID gibt.

Cleanup Governance¶

Cleanup ist in drei getrennte Approval-Typen aufgeteilt:

Typ	Zweck	Live-Write
`cleanup_prepare`	Dependency Check, Archivplan, Risiko, Cooldown	nein
`cleanup_execute`	spaeterer eng gescopter Cleanup	ja, nur nach separater Freigabe
`cleanup_finalize`	Abschlusspruefung, Audit, Doku	optional, scoped

Destroy darf niemals in einem Schritt erfolgen. Fuer LXC 124 ist aktuell nur lanstyle_ce_test_01_cleanup_prepare aktiv und plan-only.

Pflichtbedingungen vor spaeterem Destroy:

destructive_action=true
requires_separate_cleanup_approval=true
mandatory_cooldown_minutes>=15
mandatory_double_confirmation=true
Dependency Check ohne offene DNS-/NPM-/Firewall-/NetBox-/MkDocs-Abhaengigkeiten
finaler LXC-Config-Export
Chain-/Audit-History-Export
explizite Warnung rollback_possible=false

State und Drift Governance¶

Der Infrastructure State Layer ist read-only und prueft Soll/Ist-Abweichungen ohne automatische Reparatur.

Pflichttrennung:

desired_state: freigegebener Sollzustand
observed_state: aktuell gelesener Zustand
execution_state: Approval, Backup, Chain und Rollback-Kontext
drift_state: Abweichung, Hashes und Reconciliation-Bedarf

Reconciliation ist nur plan-only vorbereitet. Sobald Drift erkannt wird, muss ein Mensch entscheiden, ob der Sollzustand noch gueltig ist oder ob die Dokumentation/Chain aktualisiert werden muss.

Automatisch verboten:

Drift ungefragt korrigieren
manuelle Aenderungen ueberschreiben
historische Rollbacks ohne frische Verification
Cleanup-Reconciliation ohne eigene Cleanup-Approval

Policy und Risk Governance¶

Die Policy-/Risk-Engine bewertet geplante Chains vor Execute. Sie ist aktuell read-only und liefert Blockgruende, Risk Badge, Blast Radius und Approval-Eskalation.

Bewertete Faktoren:

betroffenes Zielsystem
Destruktivitaet
Internet-Exposition
Shared Infrastructure
Rollback-Faehigkeit
Blast Radius
Anzahl Objekte
Cross-System Dependencies
Cleanup-Komplexitaet
Service-Kritikalitaet
Maintenance Window
parallele Chain-Ausfuehrung
unmanaged Drift

Policy-Blocker:

parallele destructive Chains
DNS/NPM/Firewall-Kombination in einer Chain
Cleanup Execute ohne Cooldown
produktive Changes ausserhalb Maintenance Window ohne Emergency Override
AD-/Exchange-/Intune-Writes in diesem Layer
aktive Dependency Locks

Approval Scope¶

Die Approval appr-preflight-lanstyle-ce-test-01-20260526 deckt nur Preflight und Governance-Validierung ab.

Der erste Live-Run wurde mit appr-chain-lanstyle-ce-test-01-create-20260526-134137 ausschliesslich fuer Proxmox ausgefuehrt:

proxmox:create_lxc
proxmox:set_resources
proxmox:attach_vlan
proxmox:set_lxc_description

Nicht freigegeben waren:

netbox:create_vm_object
mkdocs:create_doc_stub
DNS
NPM
Firewall
Softwareinstallation
freie Shell

Weitere System-Writes brauchen neue explizite Approvals:

netbox:create_vm_object
mkdocs:create_doc_stub

Risiken¶

proxmox:create_lxc waere der erste echte Infrastruktur-Create ueber den Chain Layer.
Rollback fuer echte Creates ist noch nicht produktiv validiert.
NetBox- und MkDocs-Objekte muessen vor Live-Run eindeutig rollbackbar modelliert werden.
Keine DNS-, NPM- oder Firewall-Kopplung in v1.

Rollenmodell¶

Das Rollenmodell ist vorbereitet, aber noch nicht an LDAP/SSO gekoppelt.

Rolle	Zweck	Approvals
`operator`	Preflights, Read-only Checks, Changeplan-Erstellung	keine
`approver`	Low-/Medium-Risk-Freigaben	low, medium
`senior_approver`	High-Risk-Freigaben	low, medium, high
`emergency_approver`	Incident-/Emergency-Freigaben	critical/emergency mit Incident-Kontext
`auditor`	History, Audit, Reports	keine

Token-Policy:

ein Token pro Benutzer und Client
Namensschema: vorname-nachname-client
Scopes serverseitig prüfen
Vaultwarden bleibt Source of Truth
keine Tokens in Git, Wiki oder Chat

RBAC Enforcement¶

Die Tools API erzwingt Rollen serverseitig. Das Mapping erfolgt über Token-Fingerprints:

LANSTYLE_TOOLS_API_RBAC_JSON

Schema:

{
  "<sha256-token-fingerprint-16>": {
    "token_name": "maximilian-eberhardt-mbp",
    "role": "senior_approver"
  }
}

Bis alle Tokens migriert sind, bleibt der bestehende Legacy-Token als Fallback aktiv. Dieser Fallback ist sichtbar über /ops/rbac-policy und soll später durch explizite Fingerprint-Mappings ersetzt werden.

Action-Klassen:

Action Class	Mindestrolle
`read_only`	auditor
`preflight_only`	operator
`mock_execution`	operator
`scoped_write`	senior_approver
`rollback`	senior_approver
`recovery`	approver
`destructive_prepare`	senior_approver
`destructive_execute`	emergency_approver
`emergency`	emergency_approver

Fehlende oder unbekannte Rollen werden fail-closed mit 403 blockiert.

Incident / Safe Mode¶

Safe Mode ist als Policy vorbereitet:

emergency_hold
global execution pause
read-only mode
writes disabled
destructive actions disabled
cleanup locks
incident report artifact

Während Safe Mode erlaubt bleiben nur Healthchecks, Backup Validation, Scheduled Read-only Workflows und History-/Audit-Reports. Es gibt keinen automatischen Rollback.