Handbuch für Betreiber und Administratoren: Inbetriebnahme und Härtung, Nutzer und Rollen, Mandanten und Budgets, Adapter-Governance, Policy-as-Code, Compliance-Profile, Attestierung und Audit-Export, Lieferkette, Betrieb.
Stand: Version 0.30.0. English version:
administration-manual.md. Das Handbuch für Endnutzer ist das Benutzerhandbuch.
Inhalt
- Für wen dieses Handbuch ist
- Inbetriebnahme und Härtung
- Nutzer und Rollen
- Mandanten
- Adapter- und Modell-Governance
- Freigaben und Segregation of Duties
- Policy-as-Code
- Compliance-Profile
- Attestierung und Kettenprüfung
- Warum-Trace und Audit-Export
- Lieferkette: SBOM und Dependency-Scan
- Kosten und Budgets
- Skill- und Plugin-Bibliothek
- Betrieb: Monitoring, Backup, Air-Gap
- Einstellungsreferenz
- Troubleshooting für Administratoren
- Bekannte Grenzen
1. Für wen dieses Handbuch ist
Dieses Handbuch richtet sich an Betreiber (Installation, Härtung, Backup) und Administratoren (Nutzer, Mandanten, Regeln, Nachweise). Es setzt das Benutzerhandbuch voraus — dort stehen Projektanlage, Runs und Quality-Gate aus Anwendersicht.
Betriebsformen, die die Plattform abdeckt:
| Form | Beschreibung |
|---|---|
| Einzelplatz | Eine Person, ein Rechner, meist Abo-Modus einer Coding-CLI |
| Team | Mehrere Nutzer auf einer Instanz, RBAC aktiv |
| Mehrmandantig | Mehrere voneinander abgeschottete Mandanten auf einer Instanz |
| Air-Gap | Ohne Netzzugang: lokales Modell, netzlose Sandbox, Lizenz ohne Rückkanal |
Nicht abgedeckt: öffentliche SaaS-Bereitstellung mit Selbstregistrierung (siehe ../production-scope.md).
2. Inbetriebnahme und Härtung
2.1 Pflichtwerte vor dem ersten Start
| Variable | Anforderung |
|---|---|
SOFTWAREFABRIK_DB_PASSWORD |
≥ 16 Zeichen, zufällig (openssl rand -base64 16) |
SOFTWAREFABRIK_SECRETS_MASTER_KEY |
≥ 32 Zeichen, zufällig (openssl rand -base64 48) |
SOFTWAREFABRIK_ADMIN_USER / _PASSWORD |
Bootstrap-Admin; ohne Passwort wird kein Admin angelegt |
SOFTWAREFABRIK_WORKSPACES_ROOT |
Verzeichnis für die Projekt-Workspaces |
Die Anwendung ist bewusst fail fast:
- Docker Compose bricht ohne
.envab (${VAR:?…}). SecretsEncryptorlehnt imcontainer-Profil bekannte Demo-Werte und zu kurze Master-Keys hart ab.DbCredentialsValidatorprüft die Datenbank-Zugangsdaten beim Start.- PostgreSQL ist im Compose-Stack auf
127.0.0.1gebunden.
2.2 Attestierungs-Schlüssel
SOFTWAREFABRIK_ATTESTATION_SIGNING_ENABLED=true
SOFTWAREFABRIK_ATTESTATION_KEY_ID=<sprechende-id>
SOFTWAREFABRIK_ATTESTATION_PRIVATE_KEY=/pfad/zum/ed25519-key.pem
# optional: SOFTWAREFABRIK_ATTESTATION_KEYRING_PATH für Schlüsselwechsel
In Entwicklung und Test wird ein ephemerer Schlüssel erzeugt. In den Profilen container/prod gilt: aktiviert ohne Schlüssel ist ein Startfehler. Wer ohne Signatur betreiben will, muss das explizit erklären (…SIGNING_ENABLED=false). Sicherheit soll eine Entscheidung sein, kein Versehen.
Der Schlüssel muss ins Backup. Ohne ihn lässt sich die Audit-Kette später nicht mehr verifizieren.
2.3 Remote-Härtung
SOFTWAREFABRIK_GIT_ALLOWED_HOSTS=github.com,git.firma.de # Allowlist
SOFTWAREFABRIK_GIT_PR_FEEDBACK_ENABLED=false # Default
Nur für Hosts der Allowlist verwendet die Fabrik den GitHub-Token und stellt API-Anfragen. Ohne diese Grenze könnte eine manipulierte Remote-URL den fabrikweiten Token exfiltrieren (SSRF). Zusätzlich wird GIT_ALLOW_PROTOCOL gesetzt, um Angriffe über git ext::-Remote-Helper auszuschließen.
Der PR-/CI-Poller ist bewusst opt-in: unbeaufsichtigte periodische Remote-Kontakte sollen eine bewusste Betriebsentscheidung sein.
2.4 Sandbox
Einstellungen → execution.sandbox.variant = local | container
execution.sandbox.image
execution.sandbox.docker-binary
Der Container-Modus startet jeden Agentenlauf in einem ephemeren Container mit --cpus 2 --memory 4g --pids-limit 512 --read-only, Bindmount ausschließlich auf den Workspace und --network=none. Fehlt Docker im PATH, fällt die Plattform mit Log-Warnung auf die lokale Prozess-Sandbox zurück.
Empfehlung: Build-Runs führen von Agenten erzeugten Code aus. Betreibe sie auf einem Host ohne sensible Zugänge und aktiviere den Container-Modus.
2.5 Demo-Profil
Das demo-Profil setzt einen Auto-Login-Filter, der jeden Besucher als gemeinsamen Demo-Nutzer einsetzt, und blendet ein Demo-Banner ein. Es ist ausschließlich für eine öffentliche Demo-Instanz gedacht, nie für den Produktivbetrieb.
3. Nutzer und Rollen
UI: /admin/nutzer (nur ADMIN)
Dort legst du Konten an, weist Mandant und Rolle zu, setzt Konten aktiv/inaktiv und setzt Passwörter zurück. Ein Lockout-Schutz greift bei wiederholten Fehlversuchen.
Rollenmodell
VIEWER < DEVELOPER < MAINTAINER < OWNER < ADMIN
| Fähigkeit | ab Rolle |
|---|---|
| lesen | VIEWER |
| Runs ausführen | DEVELOPER |
| Runs freigeben | MAINTAINER |
| Integrationen/Secrets verwalten | MAINTAINER |
| Mandanten-Administration | OWNER |
Wichtig: ADMIN ist kein Super-Admin für Daten. Auch ein Administrator bleibt für Projekte, Runs, Logs und Kosten mandanten-gescopt. Isolationsfrei sind nur Kontenverwaltung und Projektzuweisung. Wer eine echte Betreibersicht braucht, arbeitet über die Betreiber-Endpunkte, nicht über eine erweiterte Datenrolle.
SSO (OIDC)
Optional und konfigurationsgesteuert (siehe ../sso-oidc.md). JIT-provisionierte Nutzer erhalten bewusst VIEWER ohne Mandant — ein SSO-Anschluss darf nie versehentlich Zugriff erweitern. Die Zuordnung von Mandant und Rolle bleibt eine administrative Handlung.
4. Mandanten
UI: /mandanten
- Mandanten anlegen und Projekte zuordnen.
- Ein Nutzer gehört zu einem Mandanten (
app_user.tenant_id);nullbedeutet Einzel-Mandanten-Betrieb. - Projekte, Runs und alle abgeleiteten Daten sind mandanten-gescopt. Ein Zugriff über eine fremde ID scheitert (durch einen IDOR-Test abgesichert).
- Policy, Audit, Kosten und Export sind je Mandant getrennt.
Empfehlung für harte Trennung: Mandanten reichen für die meisten Fälle. Wo maximale Trennung gefordert ist (z. B. VS-NfD), bleibt eine Instanz je Mandant die konservativste Variante.
5. Adapter- und Modell-Governance
Drei Ebenen, von weit nach eng:
- Global:
execution.adapter.defaultundexecution.<adapter>.modelin den Einstellungen. - Projekt: erlaubte Adapter je Projekt (
project_allowed_adapters) sowie eine Modell-Policy (/projects/{id}→ Modell-Policy). Sie wird beim Anlegen eines Runs erzwungen und alsRUN_MODELL_AUFGELOESTattestiert. - Mandant: Policy-as-Code (Kapitel 7) kann die erlaubten Adapter mandantenweit einschränken; eine Mandanten-Policy kann die globale nur verschärfen, nicht unterlaufen (globaler Policy-Floor).
Capability-Routing: run.routing.plan-model und run.routing.build-model trennen die Modellwahl für Planung und Umsetzung. Planung darf ein stärkeres, teureres Modell bekommen als mechanische Umsetzung — ohne dass irgendwo ein Modellname hart verdrahtet wird.
Betriebsmodus: betrieb.modus unterscheidet Einzelplatz-Abo von Team-API-Pool.
Abo-Modi (execution.<adapter>.auth-mode = api-key | subscription) für Claude, Codex und Kimi. Im Abo-Modus strippt die Fabrik den jeweiligen API-Key aktiv aus dem Subprozess — sonst würde die CLI stillschweigend den kostenpflichtigen Pfad wählen.
6. Freigaben und Segregation of Duties
Es gibt zwei Freigabepunkte je Build-Run:
| Punkt | Wirkung |
|---|---|
vor EXECUTION |
Der Agent läuft erst nach Freigabe |
vor dem Merge (in VALIDATION) |
Der validierte Stand wird erst nach Freigabe gemerged bzw. als PR eröffnet |
Der zweite Punkt ist für regulierte Profile entscheidend: Ohne ihn wäre die signierte Zusage Fassade — der Code wäre bereits im Base-Branch, bevor jemand zugestimmt hat.
Steuerung:
run.approval-vor-merge— Pflichtfreigabe vor dem Mergerun.approval-segregation— Segregation of Duties: Wer den Run ausgelöst hat (run.triggered_by), darf ihn nicht selbst freigeben- Approval-Policies unter
/policies
Freigeben darf ab Rolle MAINTAINER. Jede Entscheidung wird als approval_decision und als attestiertes Audit-Ereignis festgehalten.
7. Policy-as-Code
UI: /policy-as-code (nur ADMIN)
Regeln sind kein Konfigurationszustand, sondern ein versioniertes, signiertes Dokument. Inhalt:
| Feld | Bedeutung |
|---|---|
erlaubteAdapter |
Vendor-Beschränkung (leer = keine Einschränkung) |
gateModus |
off / advisory / blocking |
pflichtFreigabePhasen |
z. B. EXECUTION, VALIDATION |
pflichtAttestierung |
Signaturpflicht |
Eigenschaften:
- Genau eine aktive Version je Mandant — technisch erzwungen.
- Ed25519-signiert über den kanonischen Text.
- Zweifache Durchsetzung: beim Anlegen eines Runs und erneut zur Ausführungszeit. Sonst könnte ein vor der Aktivierung angelegter Run die Policy umgehen; außerdem sollen Warum-Trace und Export die real durchgesetzte Version ausweisen.
Arbeitsablauf: Inhalt bearbeiten → Veröffentlichen (erzeugt eine neue signierte Version und deaktiviert die vorherige) → Verifizieren prüft die Signatur.
Abgelehnte Läufe erzeugen RUN_POLICY_DENIED — auch die Ablehnung ist Nachweis.
8. Compliance-Profile
UI: /compliance-profile (nur ADMIN)
Ein Profil anzuwenden veröffentlicht eine passende signierte Policy-Version und erzeugt COMPLIANCE_PROFILE_APPLIED.
| Profil | Gate | Pflichtfreigaben | Attestierung |
|---|---|---|---|
| Baseline | advisory | — | nein |
| EU AI Act | blocking | EXECUTION | ja |
| BAIT / MaRisk / DORA | blocking | EXECUTION, VALIDATION | ja |
| BSI-Grundschutz / VS-NfD | blocking | EXECUTION, VALIDATION | ja |
Regulatorischer Bezug: EU AI Act = VO (EU) 2024/1689, Art. 12 (Aufzeichnung) und Art. 14 (menschliche Aufsicht); BAIT/MaRisk (BaFin) und DORA (EU 2022/2554) = IKT- und Drittparteienrisiko, Nachweisführung; BSI IT-Grundschutz und VS-NfD für die öffentliche Hand.
Ehrliche Einordnung: Die Profile setzen die technisch erzwingbaren Anteile durch. Sie ersetzen keine Rechtsberatung und decken keine organisatorischen Pflichten ab. Für VS-NfD ist zusätzlich die Adapterwahl projektspezifisch auf lokale/souveräne Backends zu beschränken — regionale Datenhaltung wird über die Gateway-Konfiguration durchgesetzt, nicht über das Profil.
9. Attestierung und Kettenprüfung
UI: /attestierung (nur ADMIN)
Jedes Audit-Ereignis trägt seq, prev_hash, entry_hash, signature und key_id. Die Prüfung unterscheidet drei Fehlerbilder:
| Befund | Bedeutung |
|---|---|
HASH_MISMATCH |
Ein Eintrag wurde nachträglich verändert |
CHAIN_BREAK |
Ein Eintrag wurde entfernt oder eingefügt |
BAD_SIGNATURE |
Der Eintrag stammt nicht vom erwarteten Schlüssel |
Altbestand ohne Signatur wird transparent als solcher ausgewiesen, statt die Prüfung scheitern zu lassen.
Attestierte Ereignisse (Auswahl): Run-Lebenszyklus, Modellauflösung, Policy-Anwendung und -Ablehnung, Guardrails-Anwendung, Quality-Gate-Ergebnis, SBOM-Erzeugung, Artefaktsignatur, Policy-Veröffentlichung, Profil-Anwendung, Freigaben.
Betriebsempfehlung: Kettenprüfung nach jedem Restore und in regelmäßigen Abständen ausführen. Ein unvollständiges Backup fällt dabei als CHAIN_BREAK auf — die Nachweisstruktur ist zugleich eine Integritätsprüfung der Sicherung.
10. Warum-Trace und Audit-Export
Warum-Trace: /runs/{id}/trace beantwortet für einen einzelnen Run, warum der Code so entstanden ist: welches Modell, welche Policy-Version, welche Freigaben durch wen, welches Gate-Ergebnis, welche Plan-Herkunft, welche Kosten.
Audit-Export: /export (nur ADMIN) erzeugt ein prüffähiges Bundle je Projekt oder Run — als JSON und HTML — aus Warum-Trace, Kettenverifikation, geltendem Policy-Stand und dem öffentlichen Schlüssel.
Das Bundle ist bewusst deterministisch serialisiert (nur Strings, Primitive und UUIDs, Zeitstempel als ISO-8601). Ein Nachweis, der je nach Bibliotheksversion anders aussieht, ist keiner.
Typischer Auditfall: Prüfer fragt nach einer konkreten Änderung → Run suchen → Warum-Trace zeigt Modell, Regel, Freigabe → Export erzeugt das Bundle → Prüfer verifiziert die Signaturen offline mit dem beiliegenden Public Key.
11. Lieferkette: SBOM und Dependency-Scan
| Baustein | Steuerung |
|---|---|
| SBOM je Build | run.sbom.mode (Default off); benötigt Trivy im PATH, degradiert sonst geordnet |
| Artefaktsignatur | Ed25519 über den SBOM-Digest, Ereignis ARTEFAKT_SIGNIERT |
| Dependency-/Lizenz-Scan | Reviewer dependency-scan im Quality-Gate; CVE-Befunde der Kategorie SECURITY blockieren den Merge |
Für regulierte Umgebungen: SBOM auf on und das Quality-Gate auf blocking stellen; dann ist für jeden gelieferten Stand belegbar, welche Abhängigkeiten enthalten waren und dass sie geprüft wurden.
12. Kosten und Budgets
Sichten:
| Route | Inhalt |
|---|---|
/analytics |
Kosten je Projekt, Run, Provider, Vergleich; jeweils als CSV |
/mandanten/kosten |
Verbrauch je Mandant (+ .csv) |
/mandanten/seat-kosten |
Verbrauch je Seat — auslösender Nutzer, abgeleitet aus run.triggered_by (+ .csv) |
Grenzen setzen:
mandant_budget— monatliches EUR-Budget je Mandant, wahlweise nur beobachtend oder als Hard-Cap (enforce). Überschreitung verhindert neue Läufe.budget.daily.tokens/budget.weekly.tokens— Token-Limits mit Soft-Schwelle.- Kapazitätsschutz begrenzt die Zahl gleichzeitiger Läufe.
Preise: Die Modell-Preistabelle liegt in application.yml (softwarefabrik.models, Input/Output/Cached je 1 Mio. Token). Unbekannte Modelle werden mit 0 € bewertet — bewusst konservativ. Abo-Modelle (k3, kimi-for-coding) stehen ebenfalls auf 0 €, weil bei Flatrate keine Token-Kosten anfallen; die Kostensicht bildet also Grenzkosten ab, nicht Lizenzkosten.
13. Skill- und Plugin-Bibliothek
UI: /skills
Einträge sind mandanten-gescopt und versioniert; die Herkunft ist typisiert: CATALOG (kuratiert), INSTALLED (übernommen), FORKED (angepasst). Vor jedem Run materialisiert die Plattform sie in den Workspace:
<workspace>/.claude/skills/<name>/SKILL.md
<workspace>/.claude/agents/<rolle>.md
<workspace>/.claude/settings.local.json
Damit ist beantwortbar, welche Erweiterung in welcher Version zum Zeitpunkt eines Laufs im Kontext des Agenten war — die Frage, an der sonst jede Reproduzierbarkeitsdiskussion scheitert.
Engineering-Guardrails (run.guardrails.mode) sind davon getrennt: eine vendor-neutrale Verhaltens-Policy, die als AGENTS.md ins Repo projiziert wird (plus eine minimale CLAUDE.md, die darauf verweist). Die Version ist ein SHA-256-Kurzhash des Inhalts und wird als RUN_GUARDRAILS_ANGEWENDET festgehalten.
14. Betrieb: Monitoring, Backup, Air-Gap
Monitoring
| Endpunkt | Inhalt |
|---|---|
/actuator/health |
inkl. Secrets-Health-Indicator |
/actuator/info |
Version und Buildnummer |
/actuator/prometheus |
Metriken (nur ROLE_ADMIN) |
Logback schreibt projectId, runId und phase in den MDC.
Backup
Zu sichern sind drei Dinge:
- die PostgreSQL-Datenbank,
- das Workspace-Verzeichnis (enthält die Git-Repositories der Projekte),
- den Attestierungs-Schlüssel und den Secrets-Master-Key.
Verfahren: ../backup-restore.md. Nach dem Restore die Kettenprüfung unter /attestierung ausführen.
Air-Gap
| Anforderung | Umsetzung |
|---|---|
| Kein Vendor-Cloud-Zugriff | Adapter local-llm (Ollama/vLLM/LM Studio) |
| Kein Netz für den Agenten | Container-Sandbox mit --network=none |
| Keine Lizenz-Rückfrage | ADR-0009 (refresh-required=false) |
| Keine Remote-Kopplung | PR-Poller aus, Allowlist leer bzw. intern |
Auslieferung: ../runbooks/airgap-auslieferung.md.
15. Einstellungsreferenz
Alle Einstellungen folgen der Scope-Hierarchie PROJECT > USER > GLOBAL > YAML und wirken ohne Neustart (max. 5 Minuten Cache).
| Schlüssel | Bedeutung |
|---|---|
betrieb.modus |
Einzelplatz-Abo oder Team-API-Pool |
execution.adapter.default |
Standard-Adapter |
execution.<adapter>.model |
Standardmodell je Adapter |
execution.<adapter>.auth-mode |
api-key oder subscription (claude, codex, kimi) |
execution.<adapter>.subscription.config-dir |
abweichendes Credential-Verzeichnis |
execution.sandbox.variant |
local oder container |
execution.sandbox.image / .docker-binary |
Container-Sandbox-Details |
run.quality-gate.mode |
off / advisory / blocking |
run.quality-gate.policy |
strict oder lenient |
run.approval-vor-merge |
Pflichtfreigabe vor dem Merge |
run.approval-segregation |
Segregation of Duties |
run.auto-followup-plan |
Folge-Plan-Run nach erfolgreichem Build |
run.guardrails.mode |
Guardrails-Projektion |
run.sbom.mode |
SBOM-Erzeugung je Build |
run.routing.plan-model / .build-model |
Capability-Routing |
budget.daily.tokens / budget.weekly.tokens |
Token-Limits |
git.pr-feedback.enabled |
PR-/CI-Poller |
workspace.root |
Wurzel der Workspaces |
Vendor-Keys werden nicht hier, sondern unter /integrations gepflegt (AES-GCM-verschlüsselt, mit Provider-Validierung für Anthropic, OpenAI, Gemini, Kimi, GitHub und NVD).
16. Troubleshooting für Administratoren
- Anwendung startet nicht, Meldung zu Master-Key/Demo-Wert — im
container-Profil sind Demo-Werte und zu kurze Schlüssel bewusst verboten. Zufälligen Wert setzen. - Start bricht mit Attestierungsfehler ab — Signierung ist aktiviert, aber kein Schlüssel hinterlegt. Entweder Schlüssel bereitstellen oder
…SIGNING_ENABLED=falseexplizit setzen. - Kettenprüfung meldet
BAD_SIGNATUREnach einem Schlüsselwechsel — den alten Schlüssel über den Keyring-Pfad weiter bereitstellen; sonst sind Alt-Einträge nicht mehr verifizierbar. - Nutzer sieht fremde Projekte nicht (obwohl ADMIN) — korrekt:
ADMINist kein Super-Admin für Daten. Über Mandantenzuweisung arbeiten. - Run wird mit
RUN_POLICY_DENIEDabgelehnt — die aktive Policy erlaubt den gewählten Adapter oder das Modell nicht. Policy prüfen oder Adapter wechseln; die Ablehnung ist im Audit dokumentiert. - Run hängt in
WAITING_FOR_APPROVAL— Pflichtfreigabe aktiv. Prüfen, wer freigeben darf (abMAINTAINER) und ob Segregation of Duties den Auslöser ausschließt. - Quality-Gate meldet
ERROR— ein Reviewer ist abgestürzt (z. B. fehlende CLI). Bewusst kein stiller Pass: CLI installieren oder Gate-Modus anpassen. - SBOM wird nicht erzeugt —
run.sbom.modesteht aufoffoder Trivy fehlt im PATH. - Kosten erscheinen mit 0 € — entweder Abo-Modell (Flatrate, korrekt) oder ein Modell ohne Eintrag in der Preistabelle.
17. Bekannte Grenzen
| Grenze | Bedeutung |
|---|---|
| Ein aktiver Run je Projekt | Verschiedene Projekte laufen parallel, mehrere Runs desselben Projekts nacheinander |
| Budget-Caps je Mandant | Die Seat-Sicht wertet aus, begrenzt aber nicht |
| PR/CI-Rückkopplung nur GitHub | GitLab/Bitbucket/Azure DevOps nicht angebunden; dort greift der lokale Merge |
| Cloud-Gateways experimentell | Bedrock/Vertex/Azure OpenAI nicht end-to-end verifiziert |
| Sandbox-Default lokal | Container-Modus ist aktivierbar, aber nicht der Default |
Aktuelle Fassung: ../production-scope.md. Technische Tiefe: ../governance-compliance.md.