Noirdoc Shield

Noirdoc Shield prüft eingehende Anfragen auf deutscher Infrastruktur, bevor Daten das Gateway in Richtung Modellanbieter verlassen. Je nach Schutzfilter schwärzt Shield erkannte Angaben direkt im Text durch feste Kategorie-Platzhalter wie [PERSON] oder [IBAN] oder blockiert die Anfrage vor der Weiterleitung mit Statuscode 403 (shield_violation).

Ablauf

Noirdoc Shield arbeitet zustandslos in eine Richtung:

1. Prüfen auf deutscher Infrastruktur: Das Gateway liest die Textsegmente der Anfrage (einschließlich eingebetteter UTF-8-Textdateien unter 4 MiB) aus und wendet die aktiven Schutzfilter Ihrer Organisation an, bevor eine Verbindung zum Modellanbieter genutzt wird. Welche Felder das je Endpunkt sind, listet Geprüfte Felder (Shield).
2. Blockieren oder Schwärzen: Schlägt ein Schutzfilter mit der Aktion block an – standardmäßig bei Geheimnissen und Prompt-Injections –, lehnt das Gateway die Anfrage vor der Weiterleitung mit Statuscode 403 und Fehlercode shield_violation ab. Treffer von Filtern mit der Aktion redact ersetzt Shield an Ort und Stelle durch feste Platzhalter wie [PERSON], [IBAN] oder [CUSTOM].
3. Bereinigt weiterleiten: Nur der bereinigte Text erreicht den Modellanbieter. Im Unterschied zur klassischen Maskierung legt Shield keine Zuordnungstabelle in Redis an und fügt keine zusätzliche Systemanweisung in den Prompt ein.
4. Direkt antworten: Das Gateway reicht die Antwort des Modells unverändert durch. Es findet keine Rückübersetzung in der Antwort statt, und beim Streaming entsteht keine Satzpuffer-Verzögerung.

Wurde der gesamte prüfbare Inhalt der Anfrage durch Noirdoc Shield geprüft, setzt das Gateway in der Antwort die Header X-Noirdoc-Shield: redacted=<n> (mit der Anzahl der geschwärzten Stellen, 0 ohne Treffer) und X-Noirdoc-Masked: true. Enthielt eine nicht erzwungene Anfrage neben Text auch Anhänge, die Shield nicht als Text prüfen kann, werden die Textfelder dennoch geprüft und geschwärzt; die Antwort trägt dann X-Noirdoc-Shield: partial; redacted=<n> und X-Noirdoc-Masked: false.

Die Erkennung arbeitet automatisch und senkt das Risiko versehentlich übermittelter Geheimnisse, personenbezogener Daten und Prompt-Injections, ersetzt aber keine fachliche Prüfung Ihrer Eingaben.

Schutzfilter

Unter Models → Shield (sowie per API über /v1/shield/policy) steuern Admins fünf Schutzfilter unabhängig voneinander:

Während injection bewusst nur user- und tool-Segmente auswertet, damit System-Prompts Ihrer Anwendung keine Fehlalarme auslösen, prüfen secrets, pii, ner und custom alle Rollen der Anfrage.

Für Eigene Sperrbegriffe (custom_patterns) können Sie bis zu 100 Einträge mit jeweils 2 bis 256 Zeichen hinterlegen:

• Literale Begriffe ohne Präfix (zum Beispiel "Projekt Helios") suchen unabhängig von Groß- und Kleinschreibung nach exakt dieser Zeichenfolge.
• Reguläre Ausdrücke mit Präfix re: (zum Beispiel "re:AZ-[0-9]{4}-[0-9]{5}") werden als reguläre Ausdrücke mit linearer Laufzeit kompiliert. Lookaround-Ausdrücke und Rückreferenzen sind nicht erlaubt, und das Muster darf nicht auf den leeren String passen.

Richtlinie und Vorrangfolge

Unter Models → Shield wählen Admins die Standard-Einstellung (mode bzw. shield_policy) der Organisation:

Bei jeder Anfrage wertet das Gateway fünf Stufen in fester Reihenfolge aus:

1. Aktive Schutzfilter: Stehen alle fünf Schutzfilter auf off, ist Shield inaktiv. Das Speichern von enforced mit fünf ausgeschalteten Filtern lehnt das Gateway mit Statuscode 422 (shield_policy_invalid) ab.
2. Organisation auf enforced: Shield ist immer aktiv; abweichende Angaben auf Schlüssel, Request-Tag oder Header können die Prüfung nicht abschalten.
3. API-Schlüssel (shield_mode): Die Einstellung Noirdoc Shield am Schlüssel (Aktiv on oder Aus off) entscheidet; Standard (inherit) gibt an die nächste Stufe weiter.
4. Request-Tags (X-Noirdoc-Tags): Tragen mitgesendete Tags eine shield_mode-Vorgabe, gewinnt on vor off, sobald mindestens ein Tag auf on steht; inherit gibt weiter.
5. Anfrage-Header und Organisationsstandard: Der Header X-Noirdoc-Shield: on bzw. off (Groß- und Kleinschreibung beliebig) überschreibt den Organisationsstandard; ohne Header gilt default_on (aktiv) bzw. default_off (inaktiv).

Auf Organisationen mit Noirdoc Shield funktioniert X-Noirdoc-Mask weiterhin als kompatibler Alias für X-Noirdoc-Shield. Auf Bestandsorganisationen, die während der Übergangsfrist noch die klassische Maskierung nutzen, steuert X-Noirdoc-Mask weiterhin die klassische Maskierung, während X-Noirdoc-Shield: on gezielt Noirdoc Shield für diese Anfrage auswählt. Vor der Weiterleitung entfernt das Gateway beide Header.

Dateien und Anhänge

Ob Anfragen überhaupt Datei-, Bild- oder Audioteile enthalten dürfen, steuert unter Models → Shield in den Erweiterten Einstellungen die Option Dateianhänge und Bilder in Anfragen erlauben (allow_file_content). Ist sie ausgeschaltet, lehnt das Gateway jede Anfrage mit Anhängen mit Statuscode 403 (file_content_not_allowed) ab.

Ist die Option eingeschaltet und Noirdoc Shield für die Anfrage aktiv, unterscheidet das Gateway nach Dateityp und Übertragungsweg:

• Eingebettete UTF-8-Textdateien unter 4 MiB (text/*, JSON, XML, CSV, Markdown, YAML als Base64-data:-URL oder als Text-document-Block bei Messages) dekodiert Shield, prüft den Text mit allen aktiven Schutzfiltern und schreibt die geschwärzte Fassung in die Anfrage zurück.
• Binärdokumente, Medien, Referenzen und große Dateien – etwa PDF, DOCX, XLSX, PPTX, Bilder, Audio, Video, Verweise per file_id oder URL sowie eingebettete Textdateien ab 4 MiB – kann Shield nicht als Text prüfen:
  • Unter enforced lehnt das Gateway die Anfrage vor der Weiterleitung mit Statuscode 422 und Fehlercode shield_uninspectable_content ab.
  • Unter default_on oder einzelner Aktivierung (on ohne enforced) prüft und schwärzt Shield alle Textfelder der Anfrage, leitet den nicht prüfbaren Anhang unverändert mit weiter und kennzeichnet die Antwort mit X-Noirdoc-Shield: partial; redacted=<n> sowie X-Noirdoc-Masked: false.

Unterstützte Endpunkte

Noirdoc Shield deckt sowohl generative Modell-Endpunkte als auch Retrieval-Endpunkte und einen eigenständigen Prüf-Endpunkt ab:

Auf den nicht geprüften Endpunkten (/v1/audio/*, /v1/images/generations sowie inhaltsführenden Aufrufen auf /v1/files und /v1/skills) lehnt das Gateway Anfragen unter enforced – ebenso Anfragen mit X-Noirdoc-Mask: on sowie auf /v1/images/generations mit X-Noirdoc-Shield: on – mit Statuscode 403 (masking_not_supported_for_endpoint) ab, damit kein Inhalt unbeabsichtigt ungeprüft weitergeleitet wird.

Abrechnung

Noirdoc Shield kostet pauschal +0,40 € je 1 Mio. geprüfter Eingabe-Tokens über alle aktiven Schutzfilter hinweg; einzelne Filter verursachen keine Aufpreise.

• Wann abgerechnet wird: Immer dann, wenn Shield Text prüft – sowohl auf von Noirdoc verwalteten Anbietern als auch bei eigenen Anbieter-Schlüsseln (BYOK, Belastung über das Organisationsguthaben bzw. die Rechnung), bei mit 403 shield_violation gestoppten Anfragen (da die Prüfung ausgeführt wurde und die Weiterleitung verhindert hat) sowie beim direkten Aufruf von POST /v1/shield/inspect.
• Wann keine Shield-Kosten anfallen: Wenn Shield für die Anfrage deaktiviert ist, auf den Vorab-Endpunkten zur Token-Zählung (/v1/messages/count_tokens, /v1/responses/input_tokens) oder wenn eine Anfrage bereits vor der Shield-Prüfung abgewiesen wird (etwa bei 422 shield_uninspectable_content).
• Preiskatalog: GET /v1/prices weist den Preis im obersten Feld "shield" aus ({"price_input": "0.40", "price_unit": "per1MTokens", "currency": "EUR", "price_currency": "EUR"}), siehe Modelle & Preise.

Klassische Maskierung

Bestandsorganisationen, die vor Einführung von Noirdoc Shield bereits die klassische umkehrbare Maskierung genutzt oder konfiguriert haben, laufen während einer Übergangsfrist bis zum 30. November 2026 (2026-11-30T23:59:59Z) zunächst unverändert weiter. Jede klassisch maskierte Antwort trägt in dieser Zeit neben X-Noirdoc-Masked: true die standardisierten Hinweis-Header nach RFC 8594:

Deprecation: true
Sunset: Mon, 30 Nov 2026 23:59:59 GMT
X-Noirdoc-Masked: true

Die wichtigsten Unterschiede zwischen beiden Verfahren:

Während der Übergangsfrist können Bestandsorganisationen Noirdoc Shield parallel erproben, ohne die gesamte Organisation sofort umzustellen:

• Pro Anfrage: Senden Sie X-Noirdoc-Shield: on (während X-Noirdoc-Mask bis zur Umstellung weiterhin die klassische Maskierung steuert).
• Pro API-Schlüssel oder Request-Tag: Setzen Sie shield_mode für ausgewählte Schlüssel oder Tags auf on.
• Eigenständig: Prüfen Sie Texte vorab über POST /v1/shield/inspect.

Admins können ihre Organisation jederzeit unter Models → Shield per Klick auf Jetzt auf Noirdoc Shield umstellen oder durch einen Schreibzugriff auf PUT /v1/shield/policy bzw. PATCH /v1/shield/policy dauerhaft umstellen (legacy_mask_active: false). Die bestehende Richtlinie (default_off, default_on oder enforced) wird dabei übernommen; ein Wechsel zurück zur klassischen Maskierung ist nicht vorgesehen. Nach dem 2026-11-30T23:59:59Z werden alle verbleibenden Bestandsorganisationen automatisch auf Noirdoc Shield umgestellt.