Terug naar de blog

Hoe het PII-filter van binnen werkt

· Door Bee Flow · 5 min. lezen

Patronen met controlegetallen voor elf landen, een GLiNER-model op de CPU voor namen en adressen, een betrouwbaarheidsdrempel en een filter dat dichtgaat bij twijfel. En de plekken waar het nog niet werkt.

A magnifying glass over a page of text, with a few words covered

In Wat er gebeurt als medewerkers klantgegevens in een AI-chat plakken leggen we Privacy Shield uit voor de mensen die het gebruiken. Dit stuk is voor de mensen die het beheren: wat de detectieservice met een bericht doet, hoe de twee lagen het werk verdelen en wat er gebeurt als de service eruit ligt.

De guard-service

De detectie draait in een eigen container, guard-service, een FastAPI-app in Python 3.12 die het compose-profiel guard start:

PROFILES="core guard" ./selfhost.sh

De Bee Flow-server roept hem aan over het compose-netwerk op PII_SERVICE_URL. Elk request draagt de SERVICES_API_KEY mee in een X-API-Key-header, en zonder die sleutel start de service niet. CORS is er niet, want geen enkele browser praat met deze service. Het belangrijkste endpoint is POST /pii. Daar gaat tekst in, eventueel met een drempel, categorieën en regio's. Eruit komt een lijst met gevonden gegevens, elk met categorie, positie, lengte en betrouwbaarheid, plus een vlag degraded als het resultaat onvolledig kan zijn.

Voor de detectie verlaat niets de container. Resultaten blijven standaard 600 seconden in Redis staan. Zo'n cache-regel bevat posities, labels en scores zonder de gevonden tekst zelf, onder een HMAC-sleutel.

Laag één: patronen met een controlegetal

Ongeveer vijftig patronen voor elf landen (NL, BE, DE, FR, ES, IT, PL, SE, AT, GB, US) stellen gestructureerde nummers voor: IBAN's, kaartnummers, nationale en fiscale nummers, kentekens, e-mailadressen, IP-adressen, API-sleutels. Een patroon doet alleen een voorstel. Veel kandidaten moeten daarna door een controle: mod-97 voor een IBAN, Luhn voor een kaartnummer, de elfproef voor een BSN. Sommige tellen alleen mee als er vlak voor het nummer een woord als "BSN", "kenteken" of "polisnummer" staat.

Aan het BSN zie je waarom er twee lagen zijn. Staat er in de tekst wat het nummer is ("het burgerservicenummer is ..."), dan vindt het model het aan de context. Een kale reeks van negen cijfers geeft een taalmodel niets om te lezen, en daar beslist de elfproef met rekenwerk. Dat heeft een bekende prijs: ongeveer één op de elf willekeurige getallen van negen cijfers komt toevallig door de elfproef, dus een zaaknummer wordt af en toe als BSN aangemerkt.

Treffers van een patroon krijgen een vaste betrouwbaarheid. Een controlegetal kan de score van iets wat het model vond verhogen of verlagen, maar haalt de vondst nooit weg. Een kaartnummer met een tikfout blijft een persoonsgegeven.

Laag twee: GLiNER op de CPU

Namen, organisaties, adressen, geboortedata en gezondheidsgegevens hebben geen vaste vorm, dus leest een model de context. We gebruiken GLiNER (standaard E3-JSI/gliner-multi-pii-domains-v1, Apache-2.0) via ONNX Runtime, alleen op de CPU. Hetzelfde model vangt de gevallen die een patroon fout heeft: "factuurnummer 0123456789" is geen telefoonnummer, een los 0644137044 wel.

Als de patroonlaag een categorie volledig dekt, wordt het model er niet eens naar gevraagd. Dat geldt altijd voor e-mail, URL, IP-adres, IBAN, kaartnummer en API-sleutel. Geef je op in welke landen je werkt (GUARD_PII_REGIONS, bijvoorbeeld NL, of per organisatie), dan gaan nationale nummers, fiscale nummers en kentekens voor die landen ook naar de patroonlaag, en dat maakt scans sneller. Welke categorieën gedekt zijn, wordt per actieve regio berekend.

Het model wordt bevraagd in groepen labels, elk over een eigen set categorieën. Valt één groep uit, dan ontbreekt een stuk van de categorieën terwijl de rest van het resultaat er schoon uitziet. Daarom geldt een gedeeltelijke storing standaard als onvolledig voor het hele resultaat.

De drempel

De betrouwbaarheidsdrempel staat standaard op 0,7. Elke categorie heeft een eigen minimumscore, en de schuif in de beheeromgeving verschuift ze allemaal tegelijk. Lager vangt meer en geeft vaker vals alarm, hoger vangt minder. Op treffers van patronen heeft de schuif geen invloed. Boven ongeveer 0,85 vallen veel echte vondsten weg, want een telefoonnummer in een kort bericht met weinig context kan rond de 0,5 scoren.

Blokkeren of vervangen

Blokkeren is de standaard en zit in elke licentie, ook in de gratis licentie. Het bericht wordt niet verstuurd en de medewerker ziet welke categorieën er gevonden zijn.

Vervangen (Tokenize) zit niet in elke licentie. Op de pagina met abonnementen zie je in welke wel. Elke waarde wordt een plaatshouder zoals [email_1] of [person_2] voordat de prompt vertrekt, en in het antwoord op je scherm komen de echte waarden terug. De koppeling wordt bij het gesprek in Postgres bewaard (versleuteld als versleuteling is ingesteld), tot 2.000 plaatshouders per gesprek. Een vervolgbeurt op een andere replica of na een herstart kan ze dus nog steeds terugzetten.

Bij twijfel dicht

Is de guard niet bereikbaar, of is het model nog niet klaar met laden, dan wordt het resultaat als onvolledig gemarkeerd en wordt een chatbericht tegengehouden in plaats van ongescand verstuurd. De instelling daarachter, piiFailureMode, staat bewust niet in de interface. Reken op laadtijd van het model na een herstart, en draai meer dan één replica als een herstart de chat niet mag onderbreken.

Andere plekken gedragen zich anders zolang de guard eruit ligt:

Plek Als detectie niet beschikbaar is
Chatberichten Tegengehouden
Grote bijlagen Het ongescande deel wordt afgekapt en gemarkeerd
Tool-resultaten, geheugen, passages uit kennisbanken Ongescand doorgegeven
Tool-aanroepen met een geblokkeerde categorie Geweigerd bij Blokkeren, anders niet gecontroleerd

Om dezelfde reden laat selfhost.sh de variabele PII_SERVICE_URL leeg zolang het profiel guard niet meedraait. Een URL naar een container die niet bestaat, maakt van "niet ingesteld" de toestand "ingesteld maar onbereikbaar", en in die tweede toestand wordt elk bericht tegengehouden.

Nog niet gedekt

Deze plekken sturen tekst naar het model zonder de berichtscan:

  • de Swarm-tier in de directe chat
  • getypte berichten in de templatechat en in de chat van de webpaginabouwer (hun bijlagen worden wel gescand)
  • spraaktranscripten
  • de leercoach
  • de bouwchats voor automatiseringen, App Studio en het CMS
  • AI-chatonderdelen in apps van App Studio
  • AI op openbaar gedeelde webpagina's en hun voorbeeldweergave

De detectie draait op de Bee Flow-server. Voor gebruikers van Nextcloud gebeurt het vervangen dus pas nadat de connector de prompt heeft doorgestuurd. En de detectie leunt op een model, dus er glipt soms iets door. Een waarde zonder enige aanwijzing eromheen, zoals een kaal getal in een tabelcel, is lastiger te vangen dan dezelfde waarde in een zin.

De volledige naslag staat in de documentatie van Privacy Shield, de service zelf staat in guard-service/, en bij privacy en beveiliging zie je hoe het samengaat met versleuteling en de rest van de stack.

Om het te proberen voeg je het profiel guard toe aan je stack, zoals bovenaan staat. Blokkeren werkt ook met de gratis licentie.

#privacy #security