L'API self-hosted di promptShield esegue rilevazione e oscuramento sulle macchine del cliente, e i documenti non arrivano ai nostri server. Esce solo una verifica della licenza, ogni sei ore. Senza risposta, il servizio resta attivo per un massimo di tre giorni.
Chi tiene il documento mentre viene letto
Un'API di oscuramento in cloud chiede di spedirle il contratto intero. Dentro ci sono il codice fiscale, l'IBAN o il numero di tessera sanitaria da togliere. Per uno studio legale o un commercialista è anzitutto una questione di segreto professionale.
Per il GDPR chi riceve i file è un responsabile del trattamento, con il contratto dell'articolo 28 e le garanzie sui trasferimenti. Il titolare resta il cliente, ed è lui che risponde al Garante per la protezione dei dati personali. Nel marzo 2023 il Garante bloccò ChatGPT, primo regolatore occidentale a farlo.
La domanda utile non è dove gira il programma, ma chi tiene il documento quando il motore lo legge. Questo articolo descrive un nostro prodotto, e abbiamo interesse a farlo apparire bene. Per questo dice anche che cosa esce dal perimetro di chi lo installa.
Fra il cloud e il desktop
Un'API in cloud offre chiamate HTTP, grandi volumi e integrazione, ma il documento lo legge il fornitore. Un'applicazione desktop lo legge sul computer dell'utente, un file per volta. L'API self-hosted di promptShield sta in mezzo: lo stesso motore del desktop, in REST e da riga di comando, sulle macchine del cliente.
Il testo dei documenti non lascia la rete del cliente. Resta però un controllo della licenza, che la nostra documentazione per un periodo ha taciuto.
Che cosa esce dal container
Il servizio convalida la sua chiave presso il nostro server di licenze ogni sei ore. Se la risposta non arriva, per una rete caduta o un firewall chiuso, il container continua a lavorare con una cache locale.
La cache dura al massimo tre giorni: poi, senza una convalida riuscita, il servizio si ferma. Il solo intervallo farebbe pensare a una chiamata da bloccare. Il limite di tre giorni dice per quanto si può restare scollegati.
Quella chiamata riguarda solo la licenza: il contenuto dei documenti non vi transita. Un responsabile della sicurezza farà bene a verificarlo dal proxy aziendale nei primi giorni di prova, prima di firmare.
Una versione precedente di questa pagina descriveva un servizio senza legami con l'esterno, e la sua tabella si contraddiceva sulla licenza. Prometteva anche un pacchetto mai pubblicato e una documentazione interattiva che nessuna installazione può aprire nel browser. Erano errori nostri, e costosi: chi scopre una connessione non dichiarata smette di credere anche che i documenti restino dove sono.
E se la rete non c'è?
L'API non ha una modalità del tutto isolata: in un ambiente del tutto isolato funziona per tre giorni e poi si ferma. Il desktop offre invece, nel piano Pro, un funzionamento isolato senza verifica della licenza né segnalazione degli arresti anomali. È però un meccanismo distinto.
Allo stesso modo, «100% offline» vale solo per il desktop, perché l'app gratuita nel browser invia un segnale anonimo all'avvio. In tutte le versioni il documento non lascia la macchina.
Che cosa fa il motore
Rileva lavora per strati. Prima espressioni regolari ad alta precisione per valori con una forma fissa, come un codice fiscale (RSSMRA85T10A562S) o un IBAN. Poi un modello di entità, spaCy, BERT o GLiNER secondo la configurazione, per nomi, società e indirizzi. Infine uno strato facoltativo con un modello linguistico, spento per impostazione predefinita.
I risultati vengono fusi, privati dei doppioni, propagati fra le pagine e filtrati dal rumore. Nessun modello locale coglie ogni identificativo: la Revisione serve perché una persona guardi le rilevazioni prima che il file esca. In una pipeline automatica bisogna decidere dove mettere quel controllo.
Una pagina scansionata è un'immagine: viene convertita in immagine a 300 dpi e letta con Tesseract, nella lingua del documento più l'inglese. I pixel dei dati personali vengono coperti e sotto si aggiunge uno strato di testo ricercabile. I pacchetti di lingua sono sette, e con quello sbagliato si legge male, senza avviso.
Rimuovi elimina il contenuto invece di coprirlo con un rettangolo nero. L'esportazione tratta anche le parti invisibili del PDF, come testi alternativi, metadati XMP, destinazioni con nome e campi dei moduli.
Lì finisce il codice del valore, o un segnaposto neutro se il valore è stato rimosso. Le miniature create prima dell'oscuramento vengono scartate, perché in un'immagine raster non si può cercare e sostituire.
Codifica sostituisce il valore con un codice breve e reversibile. I codici valgono per cartella: nella stessa cartella un valore ha sempre lo stesso codice, e solo un codice fissato a mano vale per tutto l'archivio.
Via API un documento caricato da solo ha un proprio spazio di codici. Per la coerenza fra documenti bisogna caricarli nello stesso gruppo. La Decodifica avviene sul servizio locale, dove sta anche il Registro codici.
Come funziona l'installazione
Si parte da una copia del codice sorgente con pip install -e .: il pacchetto non è pubblicato sull'indice di Python con il nome del prodotto. Il servizio si avvia con promptshield serve e non parte se PROMPTSHIELD_API_KEY non contiene una chiave.
Ogni richiesta porta la chiave nell'intestazione Authorization: Bearer. Solo /health risponde senza, e basta per il bilanciatore di carico e per un primo curl.
Le pagine di documentazione interattiva, aperte nel browser, rispondono 401, perché il browser non aggiunge l'intestazione a una navigazione. Lo schema OpenAPI si scarica con curl passando la chiave, e si importa nel client preferito.
Il percorso tipico ha tre passaggi: caricamento, rilevazione, esportazione anonimizzata. Gli strumenti nati intorno a una stringa di testo, anziché a un documento, sono il tema di un articolo dedicato agli strumenti per sviluppatori.
Domande frequenti
L'API manda i miei documenti da qualche parte?
Nella configurazione predefinita no: esce solo la convalida della licenza, ogni sei ore. Fa eccezione lo strato facoltativo con un modello linguistico, spento per impostazione predefinita. Se lo si punta a un endpoint remoto, il testo delle pagine va lì, e conviene stabilire chi può accenderlo.
L'API può funzionare senza connessione?
Per un massimo di tre giorni, grazie alla cache locale, poi si ferma. Non esiste una modalità del tutto isolata per l'API.
Come si installa l'API self-hosted?
Da una copia del codice sorgente con pip install -e ., poi si imposta PROMPTSHIELD_API_KEY e si avvia promptshield serve. Si verifica con un curl su /health, l'unico percorso senza chiave.
Chi risponde di che cosa
Quando il Garante chiederà dove sono finiti i dati di un fascicolo, la domanda arriverà al titolare. Con il servizio in casa il contenuto non viene trasmesso al fornitore. Resta il rapporto di licenza, con la sua chiamata ogni sei ore.
Se basti per l'articolo 28, il Codice Privacy o il segreto professionale, va chiesto al Suo responsabile della protezione dei dati. Preferiamo perdere il cliente che ha bisogno di un ambiente del tutto isolato piuttosto che conquistarlo con una promessa che non regge alla prima verifica.