docs-masked

Lokale Anonymisierung von Dokumenten vor dem Senden an ein Sprachmodell — und Rückeinsetzung nach der Antwort.

Das Dokument verlässt den Rechner nie in seiner ursprünglichen Form. Personenbezogene Daten werden durch stabile Tags (#PERSON_1#, #PHONE_2#, #ADDRESS_1#) ersetzt, an das Modell wird nur der Text mit Tags gesendet, und die erhaltene Antwort wird lokal anhand des Sicherungsspeichers wieerhergestellt.

документ ──▶ маска ──▶ контроль утечки ──▶ модель ──▶ обратная подстановка
           локально      локально          сеть           локально

Funktioniert als Skil für Claude Code, als MCP-Server für jeden anderen Agenten und als normales Kommandozeilen-Werkzeug.

Wie es funktioniert

1. Maske. Das Dokument wird in Textfragmente zerlegt – Absätze, Zelen, Markup-Knoten. In jedem werden personenbezogene Daten gefunden, jeder Wert erhält einen stabilen Tag. Dieselbe Person erhält denselben Tag im gesamten Dokument, einschließlich Kasusvarianten und Initialen: „Иванов Иван Иванович“, „Иванову“ und „Иванов И.И.“ – das ist ein #PERSON_1#.

2. Leckontrolle. Der maskierte Text wird erneut durch alle Detektoren plus einen paranoiden Durchlauf gejagt: jedes @, jede Kette von sieben oder mer Ziffern, jede telefonähnliche Sequenz. Wenn etwas übrig blebt, wird der Versand blockiert – durch eine Exception, nicht durch eine Warnung im Log.

3. Senden. Nach außen geht nur der Text mit Tags. Der einzige Netzwerkausgang ist die Funktion lm.send(), und sie muss vor der Anfrage eine Prüfung aufrufen. Jeder Versand wird im Logbuch ~/.pii_shield/egress.jsonl protokoliert: Zeit, Anbeter, Model, Größe, sha256, Prüfstatus. Der Inhalt wird nicht geschrieben.

4. Rückeinsetzung. Die Antwort des Modells durchläuft den Sicherungsspeicher: Tags werden durch Originale ersetzt. Für vollständige Namen wird der wiederhergestellte Nominativ eingesetzt – wenn die Person im Dokument nur als „Кузнецову Ивану Петровичу“ erwehnt wird, wird sie in der Antwort zu „Кузнецов Иван Петрович“.

Related MCP server: Doc Sanitizer MCP Server

Installation

git clone https://github.com/kpshinnik/docs_masked.git ~/.docs_masked/src
cd ~/.docs_masked/src && ./install.sh

Das Skript installiert Abhängigkeiten, lekt den Skil in ~/.claude/skils/docs-masked ab und druckt das fertige MCP-Konfigurationsfragment aus. Details und Varianten – in docs/INSTALL.md.

Verbindung zum Agenten

Schritt für Schritt für jedes Harness – docs/HARNESSES.md.

Der MCP-Server ist ohne Abhängigkeiten geschrieben: nur python3 wird benötigt. Er bietet sechs Werkzeuge – mask_text, unmask_text, verify_text, scan_document, mask_document, unmask_document.

Verwendung

docs-masked scan   договор.docx                    # что будет скрыто
docs-masked mask   договор.docx                    # маска + сейф
docs-masked report договор.docx --open             # посмотреть глазами
docs-masked ask    договор.docx -p "Найди риски по срокам"
docs-masked unmask договор.masked.docx --vault договор.docx.vault.json

Befehle

Was erkannt wird

Vollständige Namen in jedem Kasus (Russisch, Lateinschrift, Transliteration), Organisationen, Adressen, E-Mail, Telefone, Pass und Code der Ausgabestelle, SNILS, INN, OGRN, KPP, BIK, Abrechnungskonten, Bankkarten, IBAN, OMS-Versicherungspolice, Führerscheine, Kennzeichen, IP-Adressen, @Benutzernamen, Geburtsdaten und Ausstellungsdaten von Dokumenten, Requisiten-Codes (OKTMO, OKPO, KBK), plus Ihre eigenen Zeilen.

Die Identifikatoren werden echt geprüft: Prüfsumme von SNILS, Prüfziffern von INN und OGRN, Luhn-Algorithm für Karten, mod-97 für IBAN. Vollständige Tabelle – references/coverage.md.

Formate

DOCX wird über XML durchlafen, nicht über document.paragraphs: sonst gehen Absätze in Inhaltsfeldern und Überschriften verloren – in einem richtigen Vertrag ging dadurch eine ganze Salte des Requisitenblocks verloren. In Tabellen wird der Saltenkopf als Kontext genutzt: eine Zelle 500100732259 ist an sich nicht von einer zufälligen Zahl unterscheidbar, aber in der Salte „INN“ wird sie sicher erkannt.

Python-API

from pii_shield import ask_document

res = ask_document("договор.docx", "Составь резюме и найди риски",
                   provider="anthropic")
print(res.answer)          # имена уже восстановлены

Manuelle Kontrol jedes Schrits:

from pii_shield import mask_text, assert_clean, unmask_text

r = mask_text(raw)                 # r.text — с тегами, r.vault — сейф
assert_clean(r.text)               # LeakGuardError, если что-то осталось
answer = call_model(r.text)        # наружу уходит только маска
final, unknown = unmask_text(answer, r.vault, mode="canonical")

Weiteres – references/api.md.

Sicherungsspeicher (Vault)

Der Sicherungsspeicher ist das Einzige, was Tags mit Originalen verbindet. Ohne ihn ist die Rückeinsetzung unmöglich.

• Wird neben dem Dokument als <datei>.vault.json geschrieben, Berechtigung 0600.

• Wird mit dem Flag --pass-env verschlüselt (scrypt + Fernet).* Speichert die kanonische Form, alle gefundene Varianten und ein Ereignisprotokol der Vorkommen in der Reihenfolge des Dokuments – dank des Protokolls stellt die genaue Wiederherstelling die ursprüngliche Wortform wieder her, nicht die kanonische.

• Ist in .gitignore aufgenommen. Commiten Sie ihn nicht.

Genauigkeit und Grenzen

Das Werkzeug ist so ausgelegt, dass es im Zweifel auf die sichere Seite irrt: lieber zu viel maskieren als etwas übersehen. Was Sie wissen solten:

• Scan-PDF ohne Textebene wird nicht verarbeitet – OCR wird benötigt.

• Namensvetter ohne Initialen erhalten getrennte Tags, verschmelzen nicht zu einer Person.

• Eine nackte Zahl ohne Hinweise kann als Identifikator nicht erkannt werden – aber der paranoide Durchlaf wird solhen Text dennoch nicht nach außen lasen.

• Beliebige lateinische Namen ohhe slawische Endungen und ohhe Anrede (Mr., Dr.) werden nicht erkannt: jedes Par von Großbuchtaben zu erfasen würde mehr Schaden als Nutzen bringen.

Bei einem kritishen Dokument lohnt es sich, docs-masked report einmal mit den Augen anzuschauen.

Entwicklung

python3 -m pytest tests/ -q          # тесты
python3 -m pii_shield.cli selftest
python3 samples/make_samples.py      # пересоздать тестовые документы

Invarianten, die nicht verletzt werden dörfen, sind in AGENTS.md aufgeführt. Ales in samples/ ist synthetisch; das Verzeichnis examples/ ist für Ihre lokalen Dokumente reserviert und gelangt nicht in das Repository.

Lizenz

MIT.