Noirdoc Shield.
Zustandslose Eingabeprüfung auf deutscher Infrastruktur: Geheimnisse, PII, Namen, Prompt-Injections und eigene Sperrbegriffe schwärzen oder blockieren.
Noirdoc Shield prüft eingehende Anfragen zustandslos auf deutscher Infrastruktur, bevor Daten das Gateway in Richtung Modellanbieter verlassen (+0,40 € je 1 Mio. geprüfter Eingabe-Tokens über alle aktiven Filter hinweg, auch auf BYOK-Routen und bei 403 shield_violation; 0,00 € auf /v1/messages/count_tokens und /v1/responses/input_tokens). Je nach Filter ersetzt Shield Treffer direkt im Text durch feste Platzhalter wie [PERSON] oder [IBAN] oder lehnt die Anfrage vor der Weiterleitung mit Statuscode 403 (shield_violation) ab.
Bestätige Anna Schmidt den Eingang auf DE89 3704 0044 0532 0130 00.
Bestätige [PERSON] den Eingang auf [IBAN].
Schutzfilter.
Unter Models → Shield sowie per API über /v1/shield/policy steuern Admins fünf unabhängige Schutzfilter. Shield legt keine Zuordnungstabelle in Redis an, stellt keine Systemanweisung voran und reicht Modellantworten, tool_calls / tool_use-Blöcke sowie Streaming-Deltas ohne Satzpuffer-Verzögerung unverändert durch:
| Schlüssel | Bezeichnung im Portal | Erlaubte Aktionen | Standard | Platzhalter & Umfang |
|---|---|---|---|---|
secrets | Geheimnisse & API-Schlüssel | off, redact, block | block | [SECRET] – API-Schlüssel, private Schlüssel, Cloud-Tokens, Zugangsdaten und hochgradig zufällige Geheimnisse |
pii | Finanz- & Kontaktdaten | off, redact, block | redact | [IBAN], [CREDIT_CARD], [EMAIL], [PHONE], [TAX_ID], [TAX_NUMBER], [VAT_ID], [SSN], [DATE_OF_BIRTH] |
ner | Personennamen & Adressen | off, redact, block | redact | [PERSON], [ADDRESS] |
injection | Prompt-Injection | off, block | block | Kein redact. Prüft nur nicht vertrauenswürdige Rollen (user sowie tool- und Funktionsergebnisse); system, developer und assistant sind ausgenommen |
custom | Eigene Sperrbegriffe | off, redact, block | redact | [CUSTOM] – custom_patterns mit bis zu 100 Einträgen à 2–256 Zeichen (literale Teilstrings ohne Groß-/Kleinschreibung wie "Projekt Helios" oder reguläre Ausdrücke mit Präfix re: wie "re:AZ-[0-9]{4}-[0-9]{5}" in linearer Laufzeit, ohne Lookaround/Rückreferenzen und ohne leeren Treffer) |
Während injection nur user- und tool-Segmente auswertet, prüfen secrets, pii, ner und custom sämtliche Rollen. Müssen lokale Werkzeuge deiner Anwendung nach einem Tool-Aufruf echte Stammdaten auflösen, übergib dem Modell interne Datensatz-IDs (etwa contact_id: "c_8492") statt Klartextnamen oder IBANs.
Richtlinie und Vorrangfolge.
Du kannst Shield pro Anfrage über den Header X-Noirdoc-Shield, dauerhaft über default_headers / defaultHeaders am SDK-Client, je API-Schlüssel, je Request-Tag oder organisationsweit unter Models → Shield einschalten:
from openai import OpenAI
client = OpenAI(base_url="https://api.noirdoc.de/v1")
raw = client.chat.completions.with_raw_response.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Anna Schmidt, +49 30 901820"}],
extra_headers={"X-Noirdoc-Shield": "on"},
)
print(raw.headers.get("x-noirdoc-shield")) # "redacted=2"import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.noirdoc.de/v1" });
const prompt = "Anna Schmidt, +49 30 901820";
const { data, response } = await client.chat.completions
.create(
{
model: "qwen3.8-27b",
messages: [{ role: "user", content: prompt }],
},
{ headers: { "X-Noirdoc-Shield": "on" } },
)
.withResponse();
console.log(response.headers.get("x-noirdoc-shield"));curl -si https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"messages": [
{"role": "user", "content": "Anna Schmidt, +49 30 901820"}
]
}'Wurde der gesamte prüfbare Inhalt geprüft, setzt das Gateway in der Antwort X-Noirdoc-Shield: redacted=<n> (0 ohne Treffer) und X-Noirdoc-Masked: true; bei ungeprüften Binär- oder Medienanhängen ohne enforced erscheint X-Noirdoc-Shield: partial; redacted=<n> mit X-Noirdoc-Masked: false.
Unter Models → Shield wählen Admins die Standard-Einstellung der Organisation (default_off Auf Abruf als Standard für neue Organisationen, default_on Standardmäßig aktiv bzw. Alias advisory, oder enforced Erzwungen). Bei jeder Anfrage wertet das Gateway fünf Stufen der Reihe nach aus:
| Stufe | Ebene | Regel |
|---|---|---|
| 1 | Aktive Schutzfilter | Stehen alle fünf Filter auf off, ist Shield inaktiv. enforced mit fünf ausgeschalteten Filtern lehnt das Gateway beim Speichern mit 422 shield_policy_invalid ab. |
| 2 | Organisation enforced | Shield prüft jede Anfrage verpflichtend; Schlüssel, Request-Tags und Header können die Prüfung nicht abschalten. |
| 3 | API-Schlüssel (shield_mode) | Unter Models → API-Schlüssel entscheidet on (Aktiv) oder off (Aus); inherit (Standard) gibt an Stufe 4 weiter. |
| 4 | Request-Tags (X-Noirdoc-Tags) | Unter Models → Tags oder /v1/tags gesetztes shield_mode; bei mehreren Tags gewinnt on vor off, während inherit weitergibt. |
| 5 | Header & Organisationsstandard | X-Noirdoc-Shield: on oder off (Groß-/Kleinschreibung beliebig, vor der Weiterleitung entfernt; X-Noirdoc-Mask wirkt auf Shield-Organisationen als Alias) überschreibt default_on / default_off. |
Geprüfte Felder und Anhänge.
Shield prüft Textsegmente und eingebettete UTF-8-Textdateien unter 4 MiB (text/*, JSON, XML, CSV, Markdown, YAML als Base64-data:-URL oder Text-document-Block), lässt tools[]-Definitionen, Antwort-Schemas (response_format, text.format) und signierte thinking-Blöcke jedoch unverändert:
| Endpunkt | Geprüfte Inhalte & Besonderheiten |
|---|---|
/v1/chat/completions | messages[].content (string und text-Teile; system, developer, assistant von injection ausgenommen, fehlende/unbekannte Rollen als user, tool/function als tool), alle JSON-String-Werte in messages[].tool_calls[].function.arguments (assistant), prediction.content (user), eingebettete UTF-8-file-Teile < 4 MiB (Dateitext immer tool, filename gemäß Nachrichtenrolle). |
/v1/responses | instructions (system), input als String (user) oder Nachrichten/input_text/output_text, JSON-String-Werte in function_call.arguments (assistant), function_call_output.output (tool), eingebettete UTF-8-input_file-Teile < 4 MiB (tool). /v1/responses/input_tokens überspringt Shield kostenfrei. |
/v1/messages | system, messages[].content, String-Werte in tool_use.input (assistant), tool_result.content (tool), Code-Ausführung (server_tool_use, bash_code_execution_tool_result, text_editor_code_execution_tool_result), document-Blöcke mit Text/Base64-UTF-8 < 4 MiB samt title und context, search_result-Blöcke, citations[] (cited_text, document_title). /v1/messages/count_tokens überspringt Shield kostenfrei. |
/v1/embeddings | input als String, string[], String-Felder multimodaler Objekte (ohne image/image_url) sowie Integer-Token-Arrays (über tiktoken dekodiert, geprüft und wieder in Token-IDs kodiert; nicht dekodierbare Arrays gelten unter enforced als 422 shield_uninspectable_content). Alle Segmente zählen als Rolle user. |
/v1/rerank | query (Rolle user), instruction und documents[] (Strings und Textfelder von Dokumentobjekten ohne image/image_url). |
/v1/audio/*, /v1/images/generations, /v1/files, /v1/skills | Keine Textprüfung durch Shield. Unter enforced, mit X-Noirdoc-Mask: on sowie auf /v1/images/generations mit X-Noirdoc-Shield: on antworten inhaltsführende Aufrufe mit 403 masking_not_supported_for_endpoint (Lesen, Auflisten, Herunterladen und Löschen auf /v1/files und /v1/skills bleiben erlaubt). |
Vor jeder Shield-Prüfung greift unter Models → Shield → Erweiterte Einstellungen das Gate Dateianhänge und Bilder in Anfragen erlauben (allow_file_content, Standard: an; wenn aus, endet jede Anfrage mit Datei-, Bild- oder Audioteilen mit 403 file_content_not_allowed). Ist allow_file_content aktiv, behandelt Shield Anhänge nach Inhaltstyp:
| Inhaltstyp | Verhalten unter default_on / on | Verhalten unter enforced |
|---|---|---|
Eingebettete UTF-8-Textdateien (< 4 MiB dekodiert) | Dekodiert, geprüft und in-place geschwärzt (X-Noirdoc-Shield: redacted=<n>, X-Noirdoc-Masked: true) | Vollständig geprüft und erlaubt |
Binärdokumente (PDF, DOCX, XLSX, PPTX), Medien (image_url, image, input_image, input_audio), Referenzen (file_id, URL) sowie Dateien >= 4 MiB oder ohne gültiges UTF-8 | Textfelder werden geprüft; Anhang geht unverändert mit (X-Noirdoc-Shield: partial; redacted=<n>, X-Noirdoc-Masked: false) | Abgelehnt mit 422 shield_uninspectable_content (Text aus PDF/Office vorab clientseitig extrahieren) |
Tool-Definitionen: Lege keine Namen, Aktenzeichen, Adressen oder Geheimnisse in Beschreibungen, Parameter-Schemas oder
enum-Werten vontools[]ab. Übergib vertrauliche Angaben immer in Nachrichten- oder Tool-Inhalten, damit Shield sie prüft.
Text eigenständig prüfen.
Vor dem Speichern in eigenen Vektordatenbanken, Suchindizes oder externen Werkzeugen prüfst du Texte ohne Modellaufruf direkt auf deutscher Infrastruktur (+0,40 € je 1 Mio. Eingabe-Tokens).
POST https://api.noirdoc.de/v1/shield/inspect
import os
import httpx
resp = httpx.post(
"https://api.noirdoc.de/v1/shield/inspect",
headers={
"Authorization": f"Bearer {os.environ['NOIRDOC_API_KEY']}",
"X-Noirdoc-Tags": "mandat-2026-042",
},
json={
"input": [
"Mandantin im Verfahren: Anna Schmidt",
"Kontoverbindung: DE89 3704 0044 0532 0130 00",
"Notiz zu Projekt Helios, Akte AZ-2026-00418.",
],
"role": "user",
"policy": {
"rules": {"custom": "redact"},
"custom_patterns": [
"Projekt Helios",
"re:AZ-[0-9]{4}-[0-9]{5}",
],
},
},
)
data = resp.json()const resp = await fetch("https://api.noirdoc.de/v1/shield/inspect", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
"X-Noirdoc-Tags": "mandat-2026-042",
"Content-Type": "application/json",
},
body: JSON.stringify({
input: [
"Mandantin im Verfahren: Anna Schmidt",
"Kontoverbindung: DE89 3704 0044 0532 0130 00",
"Notiz zu Projekt Helios, Akte AZ-2026-00418.",
],
role: "user",
policy: {
rules: { custom: "redact" },
custom_patterns: ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"],
},
}),
});
const data = await resp.json();curl https://api.noirdoc.de/v1/shield/inspect \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "X-Noirdoc-Tags: mandat-2026-042" \
-H "Content-Type: application/json" \
-d '{
"input": [
"Mandantin im Verfahren: Anna Schmidt",
"Kontoverbindung: DE89 3704 0044 0532 0130 00",
"Notiz zu Projekt Helios, Akte AZ-2026-00418."
],
"role": "user",
"policy": {
"rules": { "custom": "redact" },
"custom_patterns": ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"]
}
}'{
"id": "shld_7f3c9a12e4b048d19c2a6e10",
"model": "noirdoc-shield-v1",
"action": "redact",
"flagged": true,
"output": [
"Mandantin im Verfahren: [PERSON]",
"Kontoverbindung: [IBAN]",
"Notiz zu [CUSTOM], Akte [CUSTOM]."
],
"findings": [
{
"category": "ner",
"label": "PERSON",
"kind": "PERSON",
"action": "redact",
"replacement": "[PERSON]",
"start": 24,
"end": 36,
"index": 0
}
],
"findings_truncated": false,
"usage": { "input_tokens": 41 }
}Der Endpunkt antwortet auch bei action: “block” mit HTTP 200 OK und prüft ohne Kurzschluss (short_circuit=false), sodass findings sämtliche Treffer enthält.
| Feld | Richtung | Regel |
|---|---|---|
input | Anfrage (Pflicht) | Nicht leerer String oder Liste aus 1 bis 64 nicht leeren Strings, zusammen höchstens 256 KB (262.144 Byte UTF-8; darüber 413 shield_input_too_large). |
role | Anfrage (optional) | "user" (Standard), "tool", "system" oder "assistant". injection prüft "user" und "tool". |
policy | Anfrage (optional) | Überschreibung {"rules"?: {...}, "custom_patterns"?: [...]} (oder flache Regel-Map ohne custom_patterns; gemischt ergibt 422 shield_policy_invalid). Unter enforced darf policy keine aktive Regel abschwächen und keine gespeicherten custom_patterns weglassen (403 shield_policy_enforced). |
action, flagged, output | Antwort (200 OK) | action ist "pass", "redact" oder "block"; flagged ist true ab einem Treffer; output liefert den bereinigten String bzw. string[] in der Form von input. |
findings, findings_truncated, usage | Antwort (200 OK) | Treffer mit category, label, kind, action, replacement, start, end, index (Listenposition ab 0); usage.input_tokens nennt die abgerechneten Tokens (mindestens 1). |
Richtlinie per API verwalten.
GET https://api.noirdoc.de/v1/shield/policy
PUT https://api.noirdoc.de/v1/shield/policy
PATCH https://api.noirdoc.de/v1/shield/policy
Liest oder aktualisiert die Shield-Richtlinie deiner Organisation. Alle drei Methoden setzen am API-Schlüssel unter Models → API-Schlüssel die Berechtigung Shield-Richtlinie per API verwalten (can_manage_shield = true) voraus (403 insufficient_key_permissions); ein auf shield_mode: "on" festgelegter Schlüssel darf die Richtlinie nicht abschwächen.
import os
import httpx
resp = httpx.patch(
"https://api.noirdoc.de/v1/shield/policy",
headers={"Authorization": f"Bearer {os.environ['NOIRDOC_API_KEY']}"},
json={
"mode": "default_on",
"rules": {"pii": "redact", "custom": "block"},
"custom_patterns": [
"Projekt Helios",
"re:AZ-[0-9]{4}-[0-9]{5}",
],
},
)
policy = resp.json()const resp = await fetch("https://api.noirdoc.de/v1/shield/policy", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "default_on",
rules: { pii: "redact", custom: "block" },
custom_patterns: ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"],
}),
});
const policy = await resp.json();curl -X PATCH https://api.noirdoc.de/v1/shield/policy \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "default_on",
"rules": { "pii": "redact", "custom": "block" },
"custom_patterns": ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"]
}'{
"mode": "default_on",
"shield_policy": "default_on",
"rules": {
"secrets": "block",
"pii": "redact",
"ner": "redact",
"injection": "block",
"custom": "block"
},
"custom_patterns": ["Projekt Helios", "re:AZ-[0-9]{4}-[0-9]{5}"],
"price_per_1m_input_tokens_eur": "0.40",
"legacy_mask_active": false,
"legacy_mask_sunset_at": "2026-11-30T23:59:59Z"
}| Methode / Feld | Verhalten |
|---|---|
mode (shield_policy) | "default_off", "default_on" oder "enforced" (Aliase "off", "advisory" sowie mask_policy werden akzeptiert). |
PUT vs. PATCH bei rules | PUT setzt ausgelassene Schlüssel in rules auf ihre Shield-Standardwerte zurück; PATCH führt übergebene Schlüssel mit dem gespeicherten Stand zusammen. |
custom_patterns | 0 bis 100 Einträge à 2–256 Zeichen; wird custom_patterns bei PATCH übergeben, ersetzt die Liste den Bestand vollständig, ohne das Feld bleibt er erhalten. |
| Einweg-Umstellung | Jeder erfolgreiche Schreibzugriff per PUT oder PATCH /v1/shield/policy stellt eine Bestandsorganisation mit klassischer Maskierung dauerhaft auf Shield um (legacy_mask_active: false). |
| Status | Code | Bedeutung |
|---|---|---|
| 400 | invalid_request_error | Ein Parameter auf /v1/shield/inspect oder /v1/shield/policy ist ungültig (etwa leerer oder über 256 KB großer input, mehr als 64 Einträge, unbekannte Regel oder ungültiger Sperrbegriff), oder der JSON-Body ist für die Shield-Extraktion zu tief verschachtelt. |
| 403 | shield_violation | Noirdoc Shield hat die Anfrage vor der Weiterleitung an den Anbieter blockiert, weil ein aktiver Schutzfilter mit der Aktion block angeschlagen hat; message nennt die ausgelöste Regel (secrets, pii, ner, injection oder custom). |
| 403 | shield_policy_enforced | Die Shield-Richtlinie der Organisation steht auf enforced, und die Anfrage auf /v1/shield/inspect versucht über policy eine aktive Regel abzuschwächen oder eigene Sperrbegriffe wegzulassen. |
| 403 | masking_not_supported_for_endpoint | Der Endpunkt unterstützt weder Noirdoc Shield noch die klassische Maskierung, aber die Richtlinie steht auf enforced oder die Anfrage sendet X-Noirdoc-Mask: on (auf /v1/images/generations auch X-Noirdoc-Shield: on). Während der Übergangsfrist der klassischen Maskierung bis zum 30.11.2026 betrifft das auf Bestandsorganisationen ohne Shield auch /v1/embeddings und /v1/rerank. |
| 403 | file_content_not_allowed | Die Anfrage enthält Dateien, Bilder oder Audio, und die Organisation lässt keine Dateiinhalte zu. |
| 403 | insufficient_key_permissions | Dem API-Schlüssel fehlt die Berechtigung für /v1/tags (can_manage_tags) oder /v1/shield/policy (can_manage_shield), ein Schlüssel mit fest aktiviertem Shield (shield_mode: on) versucht die Shield-Richtlinie oder shield_mode eines Tags abzuschwächen, oder das Tag soll weiter reichende Modelle, Anbieter oder Compliance-Regeln erhalten als der aufrufende Schlüssel selbst besitzt. |
| 413 | shield_input_too_large | Der zu prüfende Text der Anfrage überschreitet das Limit des Shield-Dienstes von 4 MiB kodiertem Text in einem Aufruf. |
| 422 | shield_uninspectable_content | Die Shield-Richtlinie steht auf enforced, und die Anfrage enthält Inhalte, die Shield nicht als Text prüfen kann (binary_document wie PDF oder Office, media_not_inspectable wie Bilder, Audio oder Video, file_reference per ID oder URL, file_too_large ab 4 MiB, file_not_decodable oder unrecognised_content). Das Gateway hat die Anfrage nicht weitergeleitet. |
| 422 | shield_policy_invalid | Die übergebene Shield-Richtlinie ist widersprüchlich, etwa enforced mit allen fünf Schutzfiltern auf off oder eine Mischung aus rules/custom_patterns und flachen Regelschlüsseln. |
| 422 | shield_config_invalid | Die gespeicherte Shield-Konfiguration der Organisation ist ungültig (zum Beispiel enforced ohne aktiven Schutzfilter oder ein nicht kompilierbares Muster); das Gateway hat die Anfrage nicht weitergeleitet. |
| 503 | shield_unavailable | Der Noirdoc-Shield-Prüfdienst ist vorübergehend nicht erreichbar; das Gateway leitet eine zu prüfende Anfrage niemals ungeprüft weiter (Fail-closed). Die Antwort enthält Retry-After mit 5 Sekunden. |
Klassische Maskierung (Auslauf 30.11.2026).
Bestandsorganisationen, die vor Einführung von Noirdoc Shield die umkehrbare Maskierung (<<PERSON_1>> mit verschlüsselter Redis-Zuordnung, Satzpuffer beim Streaming und Base64-Dateianalyse file_analysis_mode auf Chat, Responses und Messages zu 0,00 € während der Übergangsfrist) genutzt haben, laufen bis zum 30. November 2026 (2026-11-30T23:59:59Z) weiter. Bis dahin kennzeichnet das Gateway jede klassisch maskierte Antwort nach RFC 8594:
Deprecation: true
Sunset: Mon, 30 Nov 2026 23:59:59 GMT
X-Noirdoc-Masked: trueWährend der Übergangsfrist testest du Noirdoc Shield parallel über X-Noirdoc-Shield: on pro Anfrage, shield_mode: "on" auf einzelnen Schlüsseln oder Tags sowie POST /v1/shield/inspect, während X-Noirdoc-Mask weiterhin die klassische Maskierung steuert (/v1/embeddings und /v1/rerank unterstützen die klassische Maskierung nicht; die klassische Dateianalyse für PDF/DOCX/XLSX meldet 403 file_pii_blocked bzw. 422 file_unprocessable). Admins stellen die Organisation jederzeit unter Models → Shield (Jetzt auf Noirdoc Shield umstellen) oder per PUT / PATCH /v1/shield/policy dauerhaft um; nach dem 2026-11-30T23:59:59Z wechseln alle verbleibenden Organisationen automatisch auf Noirdoc Shield.