Geprüfte Felder (Shield)

Diese Seite gilt für Anfragen, bei denen Noirdoc Shield aktiv ist. Ob Shield für eine Anfrage läuft, bestimmt die fünfstufige Vorrangfolge aus Organisationsrichtlinie, API-Schlüssel, Request-Tags und dem Header X-Noirdoc-Shield, siehe Noirdoc Shield und Shield konfigurieren & nutzen.

Endpunkte

Endpunkt	Shield-Prüfung	Verhalten
`/v1/chat/completions`	ja	Prüft Nachrichten, Tool-Argumente und eingebettete UTF-8-Textdateien unter 4 MiB
`/v1/responses`	ja	Prüft `instructions`, `input`, Funktionsaufrufe und -ausgaben; `/v1/responses/input_tokens` überspringt Shield kostenfrei
`/v1/messages`	ja	Prüft `system`, `messages`, Tool-Blöcke, Textdokumente und Zitate; `/v1/messages/count_tokens` überspringt Shield kostenfrei
`/v1/embeddings`	ja	Prüft Strings, String-Listen, Textfelder multimodaler Objekte sowie Token-ID-Arrays (`tiktoken`)
`/v1/rerank`	ja	Prüft `query`, `instruction` und `documents[]`
`POST /v1/shield/inspect`	ja	Eigenständige Textprüfung ohne Modellaufruf, siehe Shield (`/v1/shield`)
`/v1/audio/transcriptions`, `/v1/audio/speech`	nein	Keine Shield-Prüfung; unter `enforced` oder mit `X-Noirdoc-Mask: on` 403 `masking_not_supported_for_endpoint`
`/v1/images/generations`	nein	Keine Shield-Prüfung; unter `enforced` oder mit `X-Noirdoc-Shield: on` bzw. `X-Noirdoc-Mask: on` 403 `masking_not_supported_for_endpoint`
`/v1/files`, `/v1/skills`	nein	Uploads und Skill-Inhalte unter `enforced` oder mit `X-Noirdoc-Mask: on` 403 `masking_not_supported_for_endpoint`; Lesen, Auflisten und Löschen erlaubt

Chat Completions

/v1/chat/completions

Feld	Geprüft	Rolle für `injection`
`messages[].content` als String	ja	`system`, `developer` und `assistant` ausgenommen; alle übrigen Rollen geprüft (`user`, `tool`/`function` als `tool`, fehlende oder unbekannte Rollen als `user`)
`messages[].content[]`, Teile vom Typ `text`	ja	wie die Rolle der Nachricht
`messages[].tool_calls[].function.arguments`, jeder String-Wert im JSON	ja	`assistant` (ausgenommen von `injection`)
`file`-Teile mit eingebettetem UTF-8-Text unter 4 MiB (`data:`-URL)	ja	Dateitext immer `tool` (geprüft); `filename` gemäß Nachrichtenrolle
`prediction.content` als String oder `text`-Teile	ja	`user` (geprüft)
`image_url`-, `input_audio`- sowie binäre, referenzierte oder große `file`-Teile	nein, siehe Dateien und Bilder	–
`tools[]` (Name, Beschreibung, `parameters`) und `response_format`	nein	–

Tool-Argumente sind JSON-Strings. Shield zerlegt das JSON, prüft und schwärzt jeden String-Wert einzeln und setzt das JSON valide wieder zusammen; Schlüsselnamen und Struktur bleiben erhalten. Ist ein Argument kein gültiges JSON, wird es als einfacher Text geprüft.

Der Filter injection nimmt ausschließlich system, developer und assistant aus, damit System- und Entwickleranweisungen sowie frühere Modellantworten keine Fehlalarme auslösen. Alle übrigen Rollen werden geprüft – darunter user, tool und function (abgebildet auf tool) sowie fehlende oder unbekannte Rollen (abgebildet auf user). Die vier übrigen Schutzfilter (secrets, pii, ner, custom) prüfen alle Rollen.

Responses

/v1/responses

Feld	Geprüft	Rolle für `injection`
`instructions` als String oder Liste von Einträgen	ja	`system` (ausgenommen von `injection`)
`input` als String	ja	`user` (geprüft)
`input[]`, Nachrichten mit String-Inhalt oder Teilen vom Typ `input_text` bzw. `output_text`	ja	gemäß Nachrichtenrolle
`input[]`, Einträge vom Typ `function_call`: `arguments`, jeder String-Wert im JSON	ja	`assistant` (ausgenommen von `injection`)
`input[]`, Einträge vom Typ `function_call_output`: `output` als String oder Textteile	ja	`tool` (geprüft)
`input_file`-Teile mit eingebettetem UTF-8-Text unter 4 MiB (`data:`-URL)	ja	Dateitext immer `tool` (geprüft); `filename` gemäß Nachrichtenrolle
`input_image`- sowie binäre, referenzierte oder große `input_file`-Teile	nein, siehe Dateien und Bilder	–
`tools[]` (Name, Beschreibung, `parameters`) und `text.format`	nein	–

Messages

/v1/messages

Feld	Geprüft	Rolle für `injection`
`system` als String oder `text`-Blöcke	ja	`system` (ausgenommen von `injection`)
`messages[].content` als String oder `text`-Blöcke	ja	`user` geprüft; `assistant` ausgenommen
`tool_use.input`, alle String-Werte (auch verschachtelt)	ja	`assistant` (ausgenommen von `injection`)
`tool_result.content` als String oder `text`-Blöcke	ja	`tool` (geprüft)
Blöcke der Code-Ausführung (`server_tool_use`, `bash_code_execution_tool_result`, `text_editor_code_execution_tool_result`)	ja	`assistant` bzw. `tool`
`document`-Blöcke mit Textquelle (`text`, `content` oder Base64-UTF-8 unter 4 MiB), dazu `title` und `context`	ja	`user` bzw. `tool` (immer geprüft)
`search_result`-Blöcke (`text`-Blöcke in `content[]` sowie `title`)	ja	`user` bzw. `tool` (immer geprüft)
`citations[]` in `text`-Blöcken: `cited_text` und `document_title`	ja	gemäß Nachrichtenrolle
`image`-Blöcke sowie binäre, referenzierte oder große `document`-Blöcke	nein, siehe Dateien und Bilder	–
`thinking`-Blöcke aus früheren Antworten	nein	–
`tools[]` (Name, Beschreibung, `input_schema`)	nein	–

Beim Code-Ausführungs-Tool prüft Shield in server_tool_use-Blöcken alle String-Werte in input (außer festen Befehlsnamen des Text-Editors) sowie in den Ergebnisblöcken stdout, stderr, content und lines.

Tool-Definitionen in tools[], Antwort-Schemas (response_format, text.format) sowie signierte thinking-Blöcke lässt Shield bewusst unverändert, damit Funktionsaufrufe und Signaturen beim Modellanbieter gültig bleiben.

Embeddings

/v1/embeddings

Feld	Geprüft	Verhalten
`input` als einzelner String	ja	Direkt geprüft und mit `[LABEL]`-Platzhaltern an den Anbieter weitergeleitet
`input` als Liste von Strings	ja	Jeder Eintrag wird als eigenes Segment geprüft
`input` als multimodales Objekt oder Objektliste	ja	Alle String-Felder außer `image` und `image_url` werden geprüft; Bildfelder zählen als nicht prüfbare Medien
`input` als Integer-Token-Array oder Liste von Integer-Token-Arrays	ja	Über `tiktoken` passend zum Modell dekodiert, durch Shield geprüft und vor der Weiterleitung wieder in Token-IDs kodiert

Alle Segmente auf /v1/embeddings werden als Rolle user geprüft. Lässt sich ein Token-Array nicht dekodieren, gilt es als nicht lesbarer Inhalt (unrecognised_content) und führt unter enforced zu Statuscode 422 (shield_uninspectable_content).

Rerank

/v1/rerank

Feld	Geprüft	Verhalten
`query`	ja	Als String oder über die Textfelder eines Objekts geprüft (Rolle `user`)
`instruction`	ja	Falls als String angegeben, vor der Weiterleitung geprüft
`documents[]`	ja	Jeder String bzw. jedes Textfeld eines Dokumentobjekts (ohne `image`/`image_url`) wird geprüft

Keine Änderung der Antwort

Noirdoc Shield verändert ausschließlich die ausgehende Anfrage und speichert keinen Zustand zwischen Anfrage und Antwort:

Das Modell sieht feste Kategorie-Platzhalter wie [PERSON], [IBAN] oder [CUSTOM] und verwendet diese gegebenenfalls in seiner Antwort.
Textantworten, tool_calls / tool_use-Blöcke, Zitate und Streaming-Deltas reicht das Gateway unverändert und ohne Satzpuffer-Verzögerung an Ihre Anwendung durch.
Es wird keine zusätzliche Systemanweisung vorangestellt.

Wenn lokale Werkzeuge Ihrer Anwendung nach einem Tool-Aufruf des Modells auf echte Stammdaten zugreifen müssen, übergeben Sie dem Modell interne Datensatz-IDs (zum Beispiel contact_id: "c_8492") statt Klartextnamen oder IBANs.

Dateien und Bilder

Vor jeder Shield-Prüfung greift die Organisationseinstellung Dateianhänge und Bilder in Anfragen erlauben (allow_file_content unter Models → Shield → Erweiterte Einstellungen). Ist sie ausgeschaltet, lehnt das Gateway jede Anfrage mit Datei-, Bild- oder Audioteilen mit Statuscode 403 (file_content_not_allowed) ab.

Ist allow_file_content aktiv, behandelt Shield Anhänge wie folgt:

Inhaltstyp	Verhalten unter `default_on` / `on`	Verhalten unter `enforced`
Eingebettete UTF-8-Textdateien (`text/*`, JSON, XML, CSV, Markdown, YAML) unter 4 MiB dekodiert	Dekodiert, durch Shield geprüft, in-place geschwärzt (`X-Noirdoc-Shield: redacted=<n>`, `X-Noirdoc-Masked: true`)	Wie links (vollständig geprüft und erlaubt)
Binärdokumente (PDF, DOCX, XLSX, PPTX)	Textfelder werden geprüft; Datei geht unverändert mit (`X-Noirdoc-Shield: partial; redacted=<n>`, `X-Noirdoc-Masked: false`)	Abgelehnt mit 422 `shield_uninspectable_content`
Bilder, Audio und Video (`image_url`, `image`, `input_image`, `input_audio`)	Textfelder werden geprüft; Medium geht unverändert mit (`partial; redacted=<n>`, `X-Noirdoc-Masked: false`)	Abgelehnt mit 422 `shield_uninspectable_content`
Externe Verweise per `file_id` oder URL sowie eingebettete Dateien ab 4 MiB oder ohne gültiges UTF-8	Textfelder werden geprüft; Verweis/Datei geht unverändert mit (`partial; redacted=<n>`, `X-Noirdoc-Masked: false`)	Abgelehnt mit 422 `shield_uninspectable_content`

Um PDF-, Word- oder Excel-Dokumente auch unter enforced durch Shield prüfen zu lassen, extrahieren Sie den Text vor dem API-Aufruf in Ihrer Anwendung und senden ihn als Nachrichtentext oder UTF-8-Textdatei unter 4 MiB.

Klassische Maskierung

Bestandsorganisationen im Übergangsbetrieb bis zum 30. November 2026 (2026-11-30T23:59:59Z), die noch nicht auf Noirdoc Shield umgestellt haben, nutzen auf /v1/chat/completions, /v1/responses und /v1/messages weiterhin das klassische Verfahren (sofern nicht X-Noirdoc-Shield: on oder shield_mode: "on" gesetzt ist):

Nummerierte Platzhalter & Rückübersetzung: Erkannte Werte werden zu <<TYP_N>> (etwa <<PERSON_1>>), die Zuordnung wird verschlüsselt in Redis gespeichert (Mapping-TTL, Standard 30 Tage), eine kurze Systemanweisung wird ergänzt, und Antworten, Tool-Argumente sowie satzweise gepufferte Streams werden zurückübersetzt.
Keine Prüfung auf Embeddings und Rerank: /v1/embeddings und /v1/rerank unterstützen die klassische Maskierung nicht (403 masking_not_supported_for_endpoint unter enforced oder mit X-Noirdoc-Mask: on).
Klassische Dateianalyse: Base64-Dateien (darunter PDF, DOCX, XLSX und optional OCR) folgen dem hinterlegten file_analysis_mode (passthrough, detect_only, pseudonymize, block; Fehlercodes 403 file_pii_blocked und 422 file_unprocessable).

Details zu den Deprecation-/Sunset-Headern und zur Ein-Klick-Umstellung unter Models → Shield finden Sie unter Noirdoc Shield – Klassische Maskierung.