Skip to main content

PII guardrails

The Model Gateway scans model calls for personal data before and after they reach a model. What it does with a finding depends on where the text is going. By default it refuses to send strong identifiers, such as card numbers, to an external provider, and records everything else. Text that Orchestrate keeps, such as run records and audit events, is redacted.

What it looks for​

The detector is a fixed set of rules, vois-bundled-ruleset version 1.2.0. Each rule matches a pattern and, where there is one, a check digit. The rules are grouped in packs: the core pack is always on, and the regional packs can be narrowed per install or per guardrail profile.

TypePackWhat matchesStrong
credit_cardcore12 to 19 digit card numbers that pass the Luhn checkYes
ibancoreIBANs that pass the mod-97 checkYes
secret_tokencoreProvider-prefixed credentials (such as sk-, AKIA and ghp_ keys), JWTs and PEM private keysYes
emailcoreEmail addresses, including shared mailboxes such as support@No
phonecore and regionalPhone numbers, including Gulf, Indian, UK and European formatsNo
ipv4coreIPv4 addresses. Version numbers with four parts also match.No
emirates_idGulfUAE Emirates ID numbers (784, 15 digits, Luhn checked)Yes
saudi_national_idGulfSaudi national ID and Iqama numbers (10 digits, Luhn checked)No
aadhaarIndiaAadhaar numbers (12 digits, Verhoeff checked)Yes
india_panIndiaPermanent Account NumbersYes
uk_ninoUKNational Insurance numbersYes
nhs_numberUKNHS numbers written 3-3-4, mod-11 checkedNo
fr_nirEUFrench social security numbers, key checkedYes
es_dniEUSpanish DNI and NIE numbers, check letter verifiedYes
it_codice_fiscaleEUItalian codice fiscale, check letter verifiedYes
de_tax_idEUGerman tax IDs (Steuer-ID), check digit verifiedNo
us_ssnUSUS Social Security numbers written with hyphensYes

The Saudi ID, NHS number and German tax ID are observed by default rather than refused, because their digits look like many phone and reference numbers.

Digits written in Arabic-Indic, Persian and Indic scripts are read as ordinary digits before matching, so a number in an Arabic or Hindi transcript is seen. The context words that mark a business reference (below) have French and Arabic equivalents.

What it does not look for​

No detector finds everything. This one does not detect:

  • person names
  • postal and street addresses
  • dates of birth
  • passport and driving licence numbers
  • national IDs outside the regional packs, such as Qatari, Kuwaiti, Omani and Bahraini civil IDs, Dutch BSNs and Indian voter cards
  • US Social Security numbers written without hyphens
  • bank account numbers with no check digit, which covers most domestic formats
  • medical, biometric and other sensitive facts written in prose
  • names, addresses and other facts written out in words, in any script
  • anything spelled out, obfuscated, or split across messages, such as a number read out as words

Every scan report lists what was checked and what was not, so a report never claims a text is free of personal data.

Where text is going​

DirectionMeansDefault action
Prompt to an external providerA prompt about to leave your clusterRefuse strong types. Observe the rest.
Prompt to an in-cluster modelA prompt that stays in your clusterObserve
CompletionA model's answer, or a transcriptObserve
AuditText Orchestrate writes into its own recordsRedact

The actions:

  • Observe: record what was found and pass the text through unchanged.
  • Redact: replace the match in the text before it goes on.
  • Refuse: block the call. The gateway answers 422 with detail.code set to guardrail_refused, and the audit log records a guardrail_refuse event.

The scan runs on chat, speech-to-text and text-to-speech calls. Embeddings requests are not scanned by default.

What is scanned​

  • The content of every message in a chat request, whatever its role. This includes tool results that an agent feeds back to the model.
  • Tool call arguments. JSON arguments are read field by field, and field names count as evidence: a plausible value under password, card_number or email is a finding even where no pattern matches, and a value under a field such as order_id is treated as a reference. Tool results that are JSON are read the same way.
  • The text of a text-to-speech request, and the transcript returned by a speech-to-text call.
  • The answer of a chat call, streamed or not. A streamed answer is scanned as it streams. With the default actions nothing is held back. If your operator sets redact or refuse for answers, text is released a sentence at a time, once it has been scanned.
  • Up to 100,000 characters per text by default. A longer text is scanned in part, and the report says so.

Reading a report​

Every chat response has a guardrail object. A streamed response carries it in the X-Vois-Guardrail header and in its final chunk.

FieldWhat it is
actionobserve, redact or refuse
directionWhich way the text was going
detector_id, detector_versionWhich ruleset ran
findingsEach type found, with a count
refused_typesThe types that caused a refusal
suppressedMatches dropped because of a context word, with counts
entity_types_checked, entity_types_not_checkedWhat the ruleset covers
chars_scanned, chars_total, truncatedHow much of the text was scanned
unscanned_partsParts of the request that could not be read
statementOne sentence that sums up the scan
completionOn a chat response, the report for the answer

Scan reports, and the audit records the scan writes, carry types and counts only. The matched text is never in them.

Stored run content​

What a caller is waiting for gets the model's answer as it is. What Orchestrate keeps goes through the Audit direction first, so it is redacted:

  • Agent API runs: the answer, the input, the trace's step outputs, tool arguments and results, and errors
  • thread turns, Playground sessions and turns
  • voice session records and their events, including transcripts
  • code agents' tool calls and trace spans (span content is off by default)
  • audit event metadata

What is read back later, such as GET /v1/runs/{id}, a webhook, a thread's history, Runs & traces or a restored Playground session, is the redacted record. The next turn on a thread sees the redacted record of earlier turns. If the redactor fails, the value is withheld rather than stored as it was.

The orchestration engine's own history isn't redacted, because a run must act on what was really said. Instead every payload is encrypted with AES-256-GCM before the engine stores it, and closed runs' history is deleted after 24 hours by default.

Eval runs keep the inputs the suite was written with, and citations keep knowledge-base passages as they are in the knowledge base.

Regional formats​

By default every regional pack is on. Your operator can narrow the install to some packs, and a guardrail profile can narrow further for an agent. A profile can narrow, never widen, and never for prompts going to an external provider. In the console, the profile editor calls this Regional PII formats.

Change what it does​

The install's defaults come from the Helm chart, modelGateway.guardrails or a guardrails.json file: the action per direction and type, which call paths are scanned, the packs, your own ignore patterns (for example your order number format) and the context words. See Configuration. Per organization, project, agent or version, use guardrail profiles.

By default, a number that follows a word such as "order", "invoice", "ticket", "tracking" or "reference" is treated as a business reference, not a card number. These suppressed matches are counted in the report.

To see the configuration in force, open Governance and look under Rules in force. It is read from the Model Gateway itself, so it shows what the gateway is really doing.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →