Governance & Sicherheit

Governance und Sicherheit von Anfang an — nicht nachträglich angeflanscht

nr-llm bündelt genau die Punkte, nach denen ein Security-Review tatsächlich fragt: wo die Secrets liegen, wer was darf, was das Modell senden und empfangen darf, wie die Kosten gedeckelt sind und wohin die Daten gehen. Jede dieser Maßnahmen ist in einem Architecture Decision Record dokumentiert.

KI in einem CMS wirft jedes Mal dieselben Fragen auf: Sind unsere API-Keys sicher, kann eine Redakteurin die Kosten in die Höhe treiben, könnte das Modell ein Secret preisgeben, und verlassen unsere Daten das Haus? Weil nr-llm gemeinsame Infrastruktur ist und kein einzelnes Feature, beantwortet es diese Fragen einmal, an einer Stelle, für jede Extension der Website.

Die Kontrollen auf einen Blick

  • API-Keys als verschlüsselte nr-vault-Identifier gespeichert — nie im Klartext, nie protokolliert
  • Backend-Modul nur für Administratoren, dazu kapabilitätsbezogene Berechtigungen über TYPO3-Backend-Gruppen
  • Guardrail-Pipeline, die Eingabe, Ausgabe, Reasoning und gestreamte Chunks prüft und maskiert
  • Human-in-the-Loop-Freigabe für Aktionen mit Seiteneffekten
  • 71 Built-in-Tools in fail-closed-Gruppen — 48 nur lesend, dreiundzwanzig schreibend und freigabepflichtig — mit fail-closed-Netzwerkzugriff
  • Budgets pro Benutzer (Requests, Tokens, Kosten — täglich und monatlich) samt Nutzungsanalyse
  • Selbst gehostete Modelle über Ollama oder eine kompatible API anbinden
  • Signierte Releases: SLSA-Level-3-Provenance, Cosign-Signaturen, SBOMs in SPDX + CycloneDX

Secrets & Schlüsselverwaltung

nr-llm speichert einen LLM-API-Key nie im Klartext. Alle Zugangsdaten von Providern und spezialisierten Diensten liegen als nr-vault-Identifier — eine UUID — vor, während das Secret selbst in der Extension netresearch/nr-vault liegt, die Envelope-Verschlüsselung, Audit-Logging und Zugriffskontrolle bereitstellt.

Zum Aufrufzeitpunkt löst der sichere HTTP-Client des Vaults das Secret auf, fügt es in die ausgehende Anfrage ein, protokolliert den Zugriff und löscht es unmittelbar danach aus dem Speicher. Der Klartext-Schlüssel taucht weder in einem Datenbank-Dump noch in einer Log-Zeile auf, und bei Chat-, Completion- und anderen Inferenzaufrufen erreicht er den Code von nr-llm nicht. Ausgenommen sind im Backend das Abrufen der Modellliste eines Providers, die Erkennung von Modell-Limits und die Prüfung von Modellfähigkeiten: Sie lesen den Schlüssel aus dem Vault, um den Provider abzufragen. Zusätzlich werden Fehlermeldungen bereinigt: Secret-tragende Query-Parameter wie ?key= und ?token= werden entfernt, bevor etwas protokolliert oder angezeigt wird.

Entscheidungen: ADR 012ADR 030

Zugriffskontrolle

Das gesamte Backend-Modul von nr-llm ist ausschließlich Administratoren vorbehalten. Jeder Backend-Endpoint — Änderungen an Providern, Modellen und Konfigurationen, die Test-Aufrufe zur Entschlüsselung von Vault-Keys, die Task-Ausführung, der Tool-Playground — ist zusätzlich abgesichert, sodass ein Nicht-Administrator ein einheitliches 403 erhält, bevor ein Zustand geändert oder ein Schlüssel entschlüsselt wird.

Über das Administrator-Gate hinaus ist jede der elf KI-Kapabilitäten — Chat, Completion, Embeddings, Vision, Streaming, Tools, JSON-Modus, Audio, Bild, Text-to-Speech und Transkription — eine native Berechtigung der TYPO3-Backend-Gruppen. So kann ein Administrator eine einzelne Kapabilität websiteweit über die Standard-Gruppenbearbeitung erteilen oder entziehen. Benannte Konfigurationen tragen zudem ihre eigene Zugriffsgruppen-ACL, und ein Aufruf muss sowohl die Konfigurations-ACL als auch die Kapabilitäts-Berechtigung erfüllen.

Entscheidungen: ADR 023ADR 037

Guardrails: Eingabe, Ausgabe & Streaming-Maskierung

Modellausgaben und Benutzereingaben werden als nicht vertrauenswürdige Inhalte behandelt und durchlaufen eine Guardrail-Pipeline, die ein echtes Verdikt zurückgibt — zulassen, maskieren, wiederholen, Freigabe anfordern oder ablehnen — kein bloßes Boolean. Auf der Antwortseite läuft die Prüfung innerhalb der Persistenzschicht, sodass ein Secret, das ein Modell zurückgibt, maskiert oder die Antwort blockiert wird, bevor sie je gecacht oder erneut ausgeliefert wird. Auf der Eingabeseite wird der ausgehende Prompt geprüft und kann maskiert werden, bevor er die Extension verlässt.

Streaming, früher ein blinder Fleck, ist live abgedeckt: Ein Holdback-Puffer maskiert ein Secret auch dann, wenn es über zwei Chunks verteilt ist, und die Ausgabegrenze ist UTF-8-sicher. Die Prüfung umfasst jede Grenze, die dasselbe Secret überschreiten kann — die Antwort, das Reasoning des Modells, den Benutzer-Turn, den System-Prompt und Vision-Text. Secret-Maskierung und die Durchsetzung des Provider-Content-Filters sind aktiv ausgeliefert, und neue Guardrails werden allein dadurch aktiv, dass sie existieren.

Entscheidungen: ADR 085ADR 087ADR 088ADR 089

Human-in-the-Loop-Freigabe

Ein Tool, das schreibt oder Seiteneffekte hat, kann vor der Ausführung eine menschliche Freigabe verlangen. Das Tool meldet sich mit einem einzigen Marker an; die Agent-Schleife pausiert daraufhin den gesamten Turn, persistiert ein serialisiertes Transkript für diesen Durchlauf im Zustand „wartet auf Freigabe“ und legt es zur Freigabe oder Ablehnung vor.

Bei Freigabe setzt der Lauf genau dort fort, wo er pausiert hat; bei Ablehnung wird das dem Modell mitgeteilt, und es fährt fort. 48 der 71 heute ausgelieferten Tools sind nur lesend, sodass dieser Pfad für sie nie greift und ihr Verhalten unverändert bleibt. Die dreiundzwanzig schreibenden Tools deklarieren einen Write-Effect, und genau dieser deklarierte Effect löst die Pause aus — keines von ihnen handelt ohne vorherige menschliche Entscheidung. Ein „Freigabe anfordern“-Verdikt eines Guardrails läuft in dieselbe Prüfnahtstelle.

Entscheidungen: ADR 084

Tool-Sicherheit

48 der 71 Built-in-Tools sind nur lesend, und jedes folgt einem Sicherheitsvertrag: Vom Modell gewählte Argumente werden validiert und begrenzt, Ausgabemengen sind gedeckelt, und jede Secret-tragende Ausgabe wird maskiert oder hinter eine separate Raw-Variante gesperrt, die deaktiviert ausgeliefert wird. Die meisten Tools erfordern Administratorrechte; die nur lesenden Struktur-, Inhalts- und Datei-Tools, die Nicht-Administratoren angeboten werden, setzen die eigenen TYPO3-Berechtigungen dieser Benutzerin durch. Zweiundzwanzig der dreiundzwanzig schreibenden Tools sind bewusst eng geschnitten — jedes führt genau eine benannte Handlung an genau einem Datensatz oder einer Cache-Gruppe aus —, und das dreiundzwanzigste, create_record_draft, bedient nur die Tabellen, für die kein enges Tool existiert, unter einer geprüften Ausschlussliste; Inhalte, die eines von ihnen anlegt, werden verborgen angelegt, eine Weiterleitung dagegen gilt, sobald sie freigegeben ist. Die vier Website-Tools darunter — drei für Weiterleitungen und clear_cache — sind Administratoren vorbehalten, und die Freigabekarte benennt ein vollständiges Leeren aller Caches als solches. Alle dreiundzwanzig werden deaktiviert ausgeliefert, handeln als der handelnde Backend-Benutzer und warten zuvor auf eine menschliche Freigabe.

Tools sind in Gruppen mit einer dreistufigen, fail-closed-Freigabekaskade organisiert: Eine deaktivierte Gruppe lässt sich nicht durch eine Einzel-Tool-Übersteuerung reaktivieren, und ein Tool, das ein Skill nicht gewährt hat, ist über Prompt-Injection nie erreichbar. Der Netzwerkzugriff wird pro Gruppe geregelt und ist fail-closed — eine Gruppe ohne Deklaration sendet keine ausgehende Anfrage, und es gibt keinen „beliebiger Host“-Scope. Host-nahe Tools laufen über einen Path-Guard, der settings.php und Schlüsselmaterial selbst für Administratoren strukturell unlesbar macht, und die URL-Prüfung ist auf die eigene Website der Instanz begrenzt. Jeder Lauf ist eine begrenzte Agent-Schleife.

Entscheidungen: ADR 038ADR 043ADR 044ADR 047

Kosten-Governance

Pro Backend-Nutzer lassen sich tägliche und monatliche Grenzen für Anfragen, Tokens und geschätzte Kosten festlegen. Die Prüfung verwendet den erfassten Verbrauch und bekannte Plankosten. Sie reserviert kein Guthaben. Gleichzeitig laufende Anfragen und erst nachträglich erfasste Nutzung können das Limit überschreiten.

Lehnt die Vorabprüfung einen Aufruf ab, nennt sie den Grund. Die Nutzungsauswertung zeigt erfasste Anfragen und geschätzte Kosten nach Anbieter, Modell, Dienst und Nutzer. Tageslimits für eine einzelne Konfiguration werden gesondert geprüft.

Entscheidungen: ADR 025ADR 052

Datenhaltung & Datenschutz

nr-llm unterstützt Ollama und OpenAI-kompatible Dienste wie vLLM und LocalAI. Für einen internen Ablauf prüfen Sie den Modellendpunkt, sämtliche Rückfallanbieter und die aufgerufenen Werkzeuge und Modelldienste.

Weil Tool-Ausgaben und jede Modellantwort an den gewählten Provider gehen, behandelt die Extension beide als nicht vertrauenswürdig: Tool-Ergebnisse sind mengenbegrenzt und um personenbezogene Felder bereinigt, Antworten werden escaped gerendert, und HTML wird nur in einer Sandbox-Vorschau angezeigt.

Entscheidungen: ADR 001

Supply-Chain-Integrität

Jedes Release ist signiert und verifizierbar. Release-Artefakte tragen keyless Cosign-Signaturen (Sigstore), SHA-256-Prüfsummen, eine Software Bill of Materials in den Formaten SPDX und CycloneDX sowie SLSA-Level-3-Provenance-Attestierungen, die sich mit gh attestation verify prüfen lassen. Commits sind kryptografisch signiert und per DCO abgezeichnet.

Die CI-Pipeline führt CodeQL-Semantikanalyse, Gitleaks-Secret-Scanning, OpenSSF Scorecard, Dependency-Review mit CVE- und Lizenz-Gating sowie wöchentliche Dependency-Audits aus; GitHub Actions von Dritten sind auf vollständige Commit-SHAs gepinnt, und die Release-Orchestrierung läuft über einen gemeinsamen, per Scorecard überwachten Reusable Workflow.

Lizenz & Offenheit

nr-llm ist freie und quelloffene Software unter GPL-2.0-or-later, herausgegeben von der Netresearch DTT GmbH. Das Design ist offen dokumentiert: 302 Architecture Decision Records legen jede Sicherheits- und Architekturentscheidung dar — auch die auf dieser Seite — samt der geprüften Alternativen und der Gründe für ihre Ablehnung.

Sicherheitslücken werden über das private Vulnerability-Reporting von GitHub behandelt. Transparenz ist selbst Teil der Haltung: Nichts auf dieser Seite muss man auf Vertrauen hinnehmen, denn die Begründung hinter jeder Maßnahme ist als ADR veröffentlicht.

Entwickler

Für Entwickler: der Governance-Vertrag

Guardrails, Freigabe und Budgets werden von der Middleware-Pipeline durchgesetzt — du rufst sie nicht auf, du fängst ab, was sie werfen. Jeder Governance-Fehlschlag ist eine typisierte Exception, sodass eine konsumierende Extension sauber degradiert, statt einen Stacktrace zu zeigen.

php
use Netresearch\NrLlm\Exception\GuardrailViolationException;
use Netresearch\NrLlm\Exception\GuardrailApprovalRequiredException;
use Netresearch\NrLlm\Exception\BudgetExceededException;

try {
    $response = $this->llm->chat($messages);
} catch (GuardrailViolationException $e) {
    // Input or output blocked by policy — show a safe, generic message.
    return 'Diese Anfrage wurde von der Content-Policy blockiert.';
} catch (GuardrailApprovalRequiredException $e) {
    // Paused: a backend user must approve before the action runs.
    return 'Zur Freigabe eingereicht. Sie läuft, sobald ein Administrator sie freigibt.';
} catch (BudgetExceededException $e) {
    // This account's per-user AI budget is exhausted.
    return 'Das KI-Budget deines Kontos ist vorerst aufgebraucht.';
}

FAQ zu Governance & Sicherheit

Werden meine API-Keys jemals im Klartext preisgegeben?

Nein. Keys werden als nr-vault-Identifier (UUIDs) gespeichert, nicht als Werte. Das Klartext-Secret wird zum Aufrufzeitpunkt im auditierten HTTP-Client des Vaults aufgelöst und unmittelbar danach aus dem Speicher gelöscht; es taucht nie in der Datenbank, den Logs, den Fehlermeldungen oder der Backend-Ausgabe von nr-llm auf.

Kann ich das betreiben, ohne Daten an einen Drittanbieter-KI-Provider zu senden?

Ja. Für einen internen Ablauf prüfen Sie den Modellendpunkt, sämtliche Rückfallanbieter und die aufgerufenen Werkzeuge und Modelldienste.

Was hindert den KI-Agenten daran, Secrets zu lesen oder Daten zu ändern?

48 der 71 Built-in-Tools sind nur lesend; Secret-tragende Ausgaben werden maskiert oder hinter deaktivierten Raw-Varianten gehalten; Dateien wie settings.php sind strukturell unlesbar; Tool-Gruppen und Netzwerkzugriff sind fail-closed; und die dreiundzwanzig schreibfähigen Tools werden deaktiviert ausgeliefert und suspendieren den Lauf zunächst für eine menschliche Freigabe.

Wie verhindere ich, dass eine einzelne Redakteurin die Kosten in die Höhe treibt?

Richte ein Budget für die Redakteurin ein und verfolge den erfassten Verbrauch in der Nutzungsauswertung. Die Vorabprüfung kann weitere Aufrufe ablehnen. Parallel laufende Anfragen und später erfasste Kosten können das Budget dennoch überschreiten.

Könnte ein Modell ein Secret preisgeben, das es erhalten hat?

Die Guardrail-Pipeline prüft den Prompt, die Antwort, das Reasoning des Modells, den System-Prompt, Vision-Text und gestreamte Chunks und maskiert Secret-förmige Zeichenketten, bevor sie gecacht, gestreamt oder angezeigt werden — auch ein Secret, das über zwei Streaming-Chunks verteilt ist.

Wie überprüfe ich, dass ein Release nicht manipuliert wurde?

Jedes Release liefert eine Cosign-Signatur, SHA-256-Prüfsummen, SBOMs in SPDX und CycloneDX sowie SLSA-Level-3-Provenance, die du mit gh attestation verify prüfen kannst.