docs-masked

Anonimización local de documentos antes de enviarlos al modelo de lenguaje — y restauración después de la respuesta.

El documento nunca sale de la máquina en su forma original. Los datos personales se reemplazan con etiquetas estables (#PERSON_1#, #PHONE_2#, #ADDRESS_1#), solo el texto con etiquetas se envía al modelo, y la respuesta recibida se restaura localmente mediante la caja fuerte de correspondencias.

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

Funciona como un skill para Claude Code, como un servidor MCP para cualquier otro agente y como una utilidad de línea de comandos normal.

Cómo funciona

1. Máscara. El documento se descompone en fragmentos de texto: párrafos, celdas, nodos de marcado. En cada uno se encuentran datos personales, cada valor recibe una etiqueta estable. La misma persona recibe la misma etiqueta en todo el documento, incluyendo variantes de caso e iniciales: «Иванов Иван Иванович», «Иванову» e «Иванов И.И.» — todo es un mismo #PERSON_1#.

2. Control de fugas. El texto enmascarado se vuelve a pasar por todos los detectores más un paso paranoico: cualquier @, cualquier cadena de siete o más dígitos, cualquier conjunto similar a un teléfono. Si queda algo, el envío se bloquea con una excepción, no con una advertencia en el registro.

3. Envío. Solo el texto con etiquetas sale al exterior. El único punto de salida a la red es la función llm.send(), y está obligada a realizar una verificación antes de la solicitud. Cada envío se registra en el archivo ~/.pii_shield/egress.jsonl: hora, proveedor, modelo, tamaño, sha256, estado de verificación. El contenido no se registra.

4. Restauración. La respuesta del modelo pasa por la caja fuerte: las etiquetas se reemplazan por los originales. Para nombres completos se restaura el caso nominativo — si en el documento la persona se menciona solo como «Кузнецову Ивану Петровичу», en la respuesta se convertirá en «Кузнецов Иван Петрович».

Related MCP server: Doc Sanitizer MCP Server

Instalación

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

El script instalará las dependencias, colocará el skill en ~/.claude/skills/docs-masked e imprimirá un fragmento de configuración MCP listo. Detalles y variantes en docs/INSTALL.md.

Conexión al agente

Paso a paso para cada harness — docs/HARNESSES.md.

El servidor MCP está escrito sin dependencias: solo necesita python3. Ofrece seis herramientas — mask_text, unmask_text, verify_text, scan_document, mask_document, unmask_document.

Uso

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

Comandos

Lista completa de banderas — skills/docs-masked/references/cli.md.

Qué se reconoce

Nombres completos en cualquier caso (rusos, latinos, transliterados), organizaciones, direcciones, correos electrónicos, teléfonos, pasaporte y código de unidad, SNILS, INN, OGRN, KPP, BIK, cuentas bancarias, tarjetas bancarias, IBAN, pólizas de seguro médico obligatorio, licencias de conducir, matrículas de automóviles, direcciones IP, @никнеймы, fechas de nacimiento y emisión de documentos, códigos de requisitos (OKTMO, OKPO, KBK), más sus propias cadenas.

Los identificadores se verifican realmente: suma de control de SNILS, dígitos de control de INN y OGRN, algoritmo de Luhn para tarjetas, mod-97 para IBAN. Tabla completa — references/coverage.md.

Formatos

DOCX se recorre mediante XML, no a través de document.paragraphs: de lo contrario se pierden párrafos dentro de campos de contenido y leyendas — en un contrato real, por eso desaparecía una columna entera del bloque de requisitos. En las tablas, el encabezado de columna se usa como contexto: la celda 500100732259 por sí sola es indistinguible de un número aleatorio, pero en la columna «ИНН» se reconoce con seguridad.

API de Python

from pii_shield import ask_document

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

Control manual de cada paso:

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")

Más detalles — references/api.md.

Caja fuerte de correspondencias

La caja fuerte es lo único que vincula las etiquetas con los originales. Sin ella, la restauración es imposible.

• Se escribe junto al documento como <archivo>.vault.json, permisos 0600.

• Se cifra con la bandera --pass-env (scrypt + Fernet).

• Almacena la forma canónica, todas las variantes encontradas y un registro de apariciones en el orden del documento — gracias al registro, la restauración exacta devuelve la forma de palabra original, no la canónica.

• Está incluido en .gitignore. No lo commitée.

Precisión y límites

La herramienta está diseñada para errar en el lado seguro: es mejor enmascarar de más que pasar por alto. Lo que hay que saber:

• PDF escaneado sin capa de texto no se procesa — se necesita OCR.

• Personas con el mismo apellido sin iniciales reciben etiquetas separadas, no se fusionan en una sola persona.

• Un número desnudo sin pistas puede no ser reconocido como identificador — pero el paso paranoico igualmente no dejará salir ese texto.

• Nombres latinos arbitrarios sin terminaciones eslavas y sin tratamiento (Mr., Dr.) no se reconocen: capturar cualquier par de palabras en mayúscula causaría más daño que beneficio.

En un documento crítico, vale la pena revisar docs-masked report visualmente una vez.

Desarrollo

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

Los invariantes que no se deben romper se enumeran en AGENTS.md. Todo en samples/ es sintético; el directorio examples/ está reservado para sus documentos locales y no se incluye en el repositorio.

Licencia

MIT.