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.

Deine Eingabe

Bestätige Anna Schmidt den Eingang auf DE89 3704 0044 0532 0130 00.

Geht an das Modell

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üsselBezeichnung im PortalErlaubte AktionenStandardPlatzhalter & Umfang
secretsGeheimnisse & API-Schlüsseloff, redact, blockblock[SECRET] – API-Schlüssel, private Schlüssel, Cloud-Tokens, Zugangsdaten und hochgradig zufällige Geheimnisse
piiFinanz- & Kontaktdatenoff, redact, blockredact[IBAN], [CREDIT_CARD], [EMAIL], [PHONE], [TAX_ID], [TAX_NUMBER], [VAT_ID], [SSN], [DATE_OF_BIRTH]
nerPersonennamen & Adressenoff, redact, blockredact[PERSON], [ADDRESS]
injectionPrompt-Injectionoff, blockblockKein redact. Prüft nur nicht vertrauenswürdige Rollen (user sowie tool- und Funktionsergebnisse); system, developer und assistant sind ausgenommen
customEigene Sperrbegriffeoff, redact, blockredact[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:

Shield pro Anfrage einschalten
Python
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"
TypeScript
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
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:

StufeEbeneRegel
1Aktive SchutzfilterStehen 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.
2Organisation enforcedShield prüft jede Anfrage verpflichtend; Schlüssel, Request-Tags und Header können die Prüfung nicht abschalten.
3API-Schlüssel (shield_mode)Unter Models → API-Schlüssel entscheidet on (Aktiv) oder off (Aus); inherit (Standard) gibt an Stufe 4 weiter.
4Request-Tags (X-Noirdoc-Tags)Unter Models → Tags oder /v1/tags gesetztes shield_mode; bei mehreren Tags gewinnt on vor off, während inherit weitergibt.
5Header & OrganisationsstandardX-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:

EndpunktGeprüfte Inhalte & Besonderheiten
/v1/chat/completionsmessages[].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/responsesinstructions (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/messagessystem, 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/embeddingsinput 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/rerankquery (Rolle user), instruction und documents[] (Strings und Textfelder von Dokumentobjekten ohne image/image_url).
/v1/audio/*, /v1/images/generations, /v1/files, /v1/skillsKeine 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:

InhaltstypVerhalten unter default_on / onVerhalten 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-8Textfelder 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 von tools[] 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

Python
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()
TypeScript
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
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}"]
    }
  }'
JSON
{
  "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.

FeldRichtungRegel
inputAnfrage (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).
roleAnfrage (optional)"user" (Standard), "tool", "system" oder "assistant". injection prüft "user" und "tool".
policyAnfrage (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, outputAntwort (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, usageAntwort (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.

Python
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()
TypeScript
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
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}"]
  }'
JSON
{
  "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 / FeldVerhalten
mode (shield_policy)"default_off", "default_on" oder "enforced" (Aliase "off", "advisory" sowie mask_policy werden akzeptiert).
PUT vs. PATCH bei rulesPUT setzt ausgelassene Schlüssel in rules auf ihre Shield-Standardwerte zurück; PATCH führt übergebene Schlüssel mit dem gespeicherten Stand zusammen.
custom_patterns0 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-UmstellungJeder 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:

Antwort-Header im Übergangsbetrieb
Deprecation: true
Sunset: Mon, 30 Nov 2026 23:59:59 GMT
X-Noirdoc-Masked: true

Wä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.