yashmahajan10/llm-differential-privacy-gateway
Noisegate: una puerta de enlace de privacidad diferencial que permite que un agente LLM no confiable consulte datos sensibles a través de MCP (Model Context Protocol), con una garantía formal de que ningún registro individual puede filtrarse incluso si el agente es adversario - la aplicación de la garantía reside en código de confianza por debajo del modelo, validado por una galería de ataques ejecutable.
Un agente de IA que puede estudiar datos confidenciales sin poder identificar a una persona concreta. El límite es matemático, se aplica en código al que el agente no puede acceder, y el repositorio incluye los ataques que intentan romperlo.
Una sesión grabada de Claude Desktop (respuestas recortadas; las tarjetas de gráficos son las propias de la sesión). Un agente de IA desglosa a 20 pacientes por diagnóstico, y el ruido de ±12 inunda cada categoría. Al recordarle que no puede desactivar el ruido, agota un presupuesto de tres respuestas hasta que la puerta devuelve una negativa en lugar de una respuesta más silenciosa. En el censo de 32 561 filas, un segmento demasiado estrecho es rechazado en la frontera de confianza, mientras que un desglose completo por educación vuelve limpio a escala. La negativa y el rechazo son la aplicación real de la puerta en vivo, reproducida por python scripts/render_demo_gif.py.
Haces preguntas sobre un conjunto de datos confidencial en inglés sencillo. Un LLM convierte cada pregunta en una consulta pequeña y restringida. Un motor de privacidad diferencial la ejecuta bajo un presupuesto de privacidad rastreado y devuelve una respuesta deliberadamente ruidosa con un intervalo de confianza declarado. Como su homónimo de audio, la pasarela mantiene toda señal por debajo de un umbral establecido bajo el suelo de ruido: la contribución de cualquier individuo queda ahogada, mientras que la señal a escala de todo el conjunto de datos pasa casi intacta.
Lo interesante no es que un LLM pueda escribir consultas. Es que la garantía de privacidad no depende de que el LLM sea confiable. El modelo es una conveniencia que propone una consulta. No aplica nada. Cada propiedad de privacidad se aplica en las etapas posteriores, mediante componentes que se comportarían de la misma manera si un humano escribiera la consulta a mano. Esta es la disciplina de frontera de confianza que aplicarías a cualquier entrada no confiable en un sistema de producción, aplicada aquí a un agente de IA.
La galería de ataques se ejecuta en el proceso contra el motor DP real:```bash pip install -e . python -m attacks.patients_alice # re-identify Alice with privacy off, then watch # the guard, the noise, and the budget defeat it
### 2. Conectar un agente de IA
La puerta de enlace se ejecuta como un servidor MCP stdio para Claude Desktop. El agente se convierte en el autor de consultas no confiable y solo recibe herramientas estructuradas (`count`, `sum`, `average`, `histogram`, `get_budget`) cuyos esquemas de argumentos se generan a partir de la política del conjunto de datos. No se necesita ninguna clave API en ningún lugar, porque el agente que se conecta es la inteligencia.
**[Configuración y guía completa →](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/docs/CLAUDE_DESKTOP.md)**
### 3. La interfaz completa de lenguaje natural
Una demo local de un solo inquilino. Solo se necesita una clave API para el compilador no confiable de NL→consulta:```bash
export ANTHROPIC_API_KEY=... # used only by the untrusted NL→query compiler
docker compose up # brings up the engine, API, and UI
# open http://localhost:8501
Esa superficie HTTP + Streamlit es una demo local de un solo inquilino. La identidad proviene de un encabezado X-Identity que se puede suplantar, por lo que está pensada para un operador de confianza en su propia máquina, no para un despliegue público (consulta qué son y qué no son estas superficies). Para la configuración local sin Docker, la ejecución de los tests y las opciones de configuración, consulta SETUP.md.
Cualquiera puede afirmar que respeta la privacidad. Este repositorio incluye los exploits que romperían esa afirmación, los ejecuta contra su propio motor y fija los resultados en CI. La forma más rápida de entender qué garantiza el gateway es verlo derrotar tres ataques clásicos que rompen los sistemas ingenuos de "consultar una base de datos".
Un ataque de diferencias aísla a una persona haciendo dos preguntas agregadas que difieren exactamente en esa persona.``` Query A: "Total income of all 100 people in department X." → $7,240,000 Query B: "Total income of all people in department X except Alice." → $7,135,000 Attacker computes: A − B = $105,000 ← Alice's exact salary, leaked.
Ambas consultas son «solo agregados». Ninguna nombra una fila individual. Sin embargo, juntas exponen a una persona. La galería (`attacks/differencing.py`) muestra este ataque **teniendo éxito con la privacidad desactivada**: el valor privado del objetivo se recupera exactamente. (El boceto del salario es ilustrativo; en los datos reales UCI Adult, «Alice» es la única titular del máximo aumento de capital de su grupo.) A continuación, muestra el mismo ataque **derrotado una vez que DP está activada**: el ruido calibrado en cada respuesta hace que la resta sea inútil, y el contador de presupuesto cobra por la información liberada a través de *ambas* consultas en lugar de tratarlas como independientes.
### Ataque 2: Inferencia de pertenencia
Un ataque de inferencia de pertenencia determina si un *individuo concreto* está en el conjunto de datos. Para muchos conjuntos de datos (un estudio médico, una lista de morosos), ese hecho es en sí mismo sensible. Un atacante que solo tiene acceso a consultas intenta decidir: «¿está exactamente esta persona en los datos?»
La galería ejecuta este ataque en un barrido de presupuestos de privacidad (ε, el dial que intercambia precisión de respuestas por privacidad) y representa el resultado:
<sub>Un atacante **óptimo** (de Neyman–Pearson) decidiendo la pertenencia de una persona a partir de un único `COUNT` ruidoso, ejecutado contra el motor real a lo largo de ε. El éxito empírico (azul, intervalos de Wilson del 95%) se ajusta a la curva analítica de Laplace y se mantiene por debajo del techo DP del peor caso (discontinuo); se desploma desde la certeza (DP desactivado) hacia el lanzamiento de moneda 0.5 a medida que ε se reduce. La curva de **utilidad** verde (eje derecho) muestra el error relativo de una consulta agregada en el mismo barrido, apenas afectado donde el ataque es derrotado. Generado por `python -m attacks.membership` (10 000 pruebas por ε).</sub>
A medida que ε se reduce (mayor privacidad), el éxito del atacante se desploma hacia un lanzamiento de moneda. La superposición de utilidad muestra el precio que se paga: el mismo ruido que derrota al ataque contra una sola persona apenas mueve un agregado a escala de población. La privacidad no es gratis, y el gráfico muestra exactamente qué se intercambia por ella. El barrido abarca desde ε = 8 hasta 0.5 para cubrir todo el rango; el despliegue incluido cobra **ε = 0.05 por consulta**, fuera del borde izquierdo de este gráfico, donde el ataque de una sola consulta ya es indistinguible del azar.
### Ataque 3: Señalar a un individuo mediante reidentificación
Latanya Sweeney demostró en 2002 que código postal + fecha de nacimiento + sexo identifican de forma única a aproximadamente el 87% de los estadounidenses (una replicación posterior con datos de censo más recientes lo situó más cerca del 63%). No necesitas el nombre de alguien para encontrarlo en un conjunto de datos; bastan unos pocos atributos inocuos. El tercer ataque de la galería (`attacks/patients_alice.py`) reproduce esa estructura en 20 pacientes sintéticos: el sexo y la edad por sí solos reducen la cohorte a exactamente una persona, Alice, la única mujer mayor de 64.
Con la privacidad desactivada, restar dos histogramas demográficos perfectamente ordinarios recupera el diagnóstico de Alice exactamente. No se requiere ningún valor atípico; ser *reidentificable* es suficiente, lo que convierte a este en el ataque más fuerte de la galería. Con la privacidad activada, tres defensas independientes lo acaban: el filtro guardián rechaza de plano la consulta estrecha obvia (sin gastar nada); el ruido calibrado ahoga la resta de dos consultas (relación señal/ruido ≈ 0.13, por lo que el «diagnóstico» recuperado es esencialmente un sorteo aleatorio); y el presupuesto rechaza la escalada de promediado mucho antes de que pudiera funcionar (~256 repeticiones necesarias, 10 asequibles). Este es el ataque que el GIF de demostración al principio de esta página, y el [tutorial de Claude Desktop](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/docs/CLAUDE_DESKTOP.md), reproducen en vivo. Los resultados están probados por regresión en `tests/test_attack_patients.py`.
Estos experimentos, ejecutados contra el propio motor del sistema, son la evidencia central de que la garantía es real y está comprendida, no importada de una biblioteca y aceptada por fe.
### Verificación cruzada con OpenDP
Los ataques validan la garantía contra *nuestras propias* matemáticas. Para protegerse contra una implementación autocoherente pero incorrecta, el mecanismo también se verifica de forma cruzada contra [OpenDP](https://opendp.org/) como referencia independiente (`attacks/crosscheck_opendp.py`, opendp 0.15.1).
**En resumen: un mecanismo construido desde cero coincide con la referencia del sector hasta nueve decimales, y una versión calibrada intencionalmente de forma incorrecta no supera las mismas pruebas, por lo que la coincidencia significa algo.** La coincidencia se comprueba de dos maneras: la sensibilidad y la escala del ruido contra el límite certificado de OpenDP, y la distribución real del muestreador contra la de OpenDP, con un control positivo que demuestra que la prueba puede fallar. Las cifras medidas están en la sección 6.3 de [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/DESIGN.md).
OpenDP es la referencia, nunca la implementación: vive solo en las dependencias de desarrollo, y el sistema en ejecución no lo importa. La concordancia de escala se prueba por regresión en `tests/test_crosscheck_opendp.py` (se omite sin OpenDP local; CI lo instala y establece `REQUIRE_OPENDP=1` para que la comprobación nunca pueda omitirse silenciosamente allí).
### Reproducirlo
Los ataques se ejecutan en proceso contra el motor DP real. No se necesita clave API ni servidor, ya que construyen AST escritos a mano en lugar de pasar por el compilador LLM:```bash
python -m attacks.patients_alice # Attack 3: re-identify Alice and recover her diagnosis
# with DP off; watch guard + noise + budget
# defeat the same attack (no data fetch needed)
python scripts/fetch_data.py # fetch UCI Adult into data/ (gitignored; ~4 MB)
python -m attacks.differencing # Attack 1: recover Alice exactly with DP off, then watch
# noise + budget defeat the same subtraction
python -m attacks.membership # Attack 2: sweep ε and regenerate the chart above
python -m attacks.crosscheck_opendp # cross-check vs OpenDP (needs the dev
# extras: pip install -e ".[dev]")
Los resultados se someten a su vez a pruebas de regresión en tests/test_attack_differencing.py, tests/test_attack_membership.py y tests/test_attack_patients.py, de modo que un cambio que debilitara silenciosamente la garantía haría fallar la CI en lugar de simplemente producir un gráfico más bonito.
Tres etapas. Solo la primera no es de confianza, y esa asimetría es toda la idea.``` Natural language question │ ▼ ┌───────────────────┐ │ LLM compiler │ Emits a CONSTRAINED QUERY AST (not free SQL), │ (UNTRUSTED) │ via structured/schema-forced output. └───────────────────┘ │ query AST ▼ ┌───────────────────┐ │ Validation / │ Policy check: allowed columns only, aggregates │ guardrail layer │ only, declared value ranges, group-cardinality │ (TRUSTED) │ caps. Invalid → repair loop or refusal. └───────────────────┘ │ validated AST ▼ ┌───────────────────┐ │ Privacy engine │ Clamp to declared range (bounds sensitivity), │ (TRUSTED) │ add calibrated Laplace noise, decrement budget. └───────────────────┘ │ ▼ Noisy answer + confidence interval + remaining budget
La decisión de diseño más importante es la caja etiquetada como **UNTRUSTED**. Todo lo que está por encima de la capa de validación se trata como hostil, y todo lo que está por debajo de ella es la base de computación confiable que hace cumplir la garantía. El LLM compila a un *AST restringido* en lugar de SQL arbitrario porque esa restricción es lo que acota la sensibilidad de la consulta, y la sensibilidad acotada es lo que hace sólida la calibración del ruido. El SQL de forma libre reabriría exactamente la superficie de ataque que este proyecto cierra.
## El modelo de privacidad
Cada respuesta recibe ruido. Se mantiene un registro exacto de la divulgación acumulativa por identidad y se persiste en disco, y la puerta de enlace se niega a responder antes de que ese registro pueda superar la garantía que anuncia. Nunca se degrada en silencio a una respuesta más ruidosa.
El coste merece enunciarse con la misma claridad. La garantía es **privacidad diferencial (ε, δ), que es estrictamente más débil que la ε-DP pura.** Con probabilidad como máximo δ, se permite que el límite ε falle. δ no es ruido adicional, es masa de fallo, por eso se deriva del conjunto de datos en lugar de estar codificada de forma fija.
Las secciones 3 y 5.4 de [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/DESIGN.md) contienen la derivación completa: sensibilidad, el mecanismo de Laplace, el contador híbrido zCDP y de dónde sale δ. Ahí es donde fueron a parar todas las letras griegas.
---
## Qué es este proyecto, y qué no es
**Es** una demostración de que una capa no confiable de lenguaje natural puede situarse delante de datos sensibles sin comprometer una garantía formal de privacidad, con la garantía respaldada por ataques que funcionan, no por afirmaciones.
**No es** un producto de privacidad de producción, un sustituto de una biblioteca de DP verificada en un despliegue real, ni una afirmación de que las consultas generadas por LLM sean seguras de ejecutar sin protección. No lo son, y es exactamente por eso que existe la capa confiable.
Tanto el servidor MCP como la demo HTTP atienden a un **único principal local** que es propietario de la máquina, y ese principal puede rotar la época o eliminar el archivo de presupuesto para empezar de cero. Así que la propiedad de que "una parte externa consume presupuesto y no puede recuperarlo" está *demostrada en el mecanismo, no impuesta contra un adversario remoto*. Cerrar esa brecha requiere el desglose en identidad verificada (OAuth) y multi-tenant, que sigue en la hoja de ruta. El muestreador de ruido también tiene un canal lateral conocido de coma flotante (Mironov 2012, tratado en la sección 5.5 de [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/DESIGN.md)). **No** apunte ninguna de las dos superficies a datos regulados reales ni trate el proyecto como sustituto de una biblioteca de DP verificada en situaciones donde una parte no confiable pueda autenticarse.
El conjunto de datos incluido es el conjunto público **UCI Adult / Census Income**, el punto de referencia estándar en la literatura de privacidad diferencial, por lo que los resultados de ataque-vs-ε aquí son directamente comparables con el trabajo publicado. Ya es público, así que el repositorio es seguro de publicar. La maquinaria de privacidad se demuestra *como si* los registros fueran sensibles.
---
## Trabajo relacionado
Dónde se sitúa esto entre las herramientas existentes, y qué hace deliberadamente de manera diferente.
<details>
<summary><b>Bibliotecas de DP, motores de consulta DP, text-to-SQL, herramientas de seguridad para MCP y DP cerca de los LLM</b> (haz clic para expandir)</summary>
<br>
**Bibliotecas de DP.** [OpenDP](https://opendp.org/), las [bibliotecas de privacidad diferencial de Google](https://github.com/google/differential-privacy), [diffprivlib de IBM](https://github.com/IBM/differential-privacy-library) y [Tumult Analytics](https://github.com/opendp/tumult-analytics) (que impulsó las publicaciones de la Oficina del Censo de EE. UU., Wikimedia y el IRS antes de que su equipo se uniera a LinkedIn en 2025 y la biblioteca pasara a la organización OpenDP) son implementaciones verificadas de los propios mecanismos, escritas para que un analista confiable las llame desde su propio código. Este proyecto, en cambio, implementa su mecanismo a mano, para que cada línea de la ruta crítica de privacidad siga siendo pequeña, legible y comprobable en un solo repositorio, y luego lo [contrasta con OpenDP](#cross-checked-against-opendp), precisamente porque un mecanismo hecho a mano no significa nada sin un árbitro externo. Para un despliegue real, el consejo anterior sigue en pie: use una biblioteca verificada.
**Motores de consulta DP.** [PINQ](https://www.microsoft.com/en-us/research/publication/privacy-integrated-queries/) (McSherry, 2009) estableció la arquitectura que este proyecto hereda: un analista no confiable emite consultas a través de una capa confiable que garantiza privacidad diferencial sin importar lo que se pregunte. Sus descendientes de producción responden consultas SQL bajo DP: [smartnoise-sql](https://github.com/opendp/smartnoise-sdk), el [reescritor de sensibilidad elástica archivado de Uber](https://github.com/uber-archive/sql-differential-privacy) y el [SQL con privacidad diferencial de Wilson et al.](https://petsymposium.org/popets/2020/popets-2020-0025.php), disponible hoy como [privacidad diferencial de BigQuery](https://docs.cloud.google.com/bigquery/docs/differential-privacy). Este proyecto introduce dos diferencias deliberadas. Esos sistemas aceptan SQL y lo analizan o reescriben, mientras que esta puerta de enlace nunca acepta SQL en absoluto: el agente envía un AST pequeño y restringido, porque un lenguaje de consulta lo bastante pequeño como para enumerarse es un límite de confianza lo bastante pequeño como para probarse exhaustivamente. Y cada uno de ellos sitúa a un analista humano ante el teclado, mientras que aquí el autor de la consulta es un agente autónomo, y el modelo de amenazas así lo establece.
**Interfaces de bases de datos en lenguaje natural.** Text-to-SQL es un campo amplio y exitoso, pero la privacidad no es su tema: el SQL generado se ejecuta con la autoridad que la base de datos conceda. Cuando se aborda la seguridad, como en [SafeNLIDB](https://arxiv.org/abs/2511.06778) (AAAI 2026), se basa en la alineación (entrenar al modelo para que razone sobre qué es seguro responder), de modo que la garantía reside dentro del modelo. Este proyecto adopta la posición complementaria: asumir que el modelo no se puede hacer seguro, y hacer cumplir la garantía por debajo de él con matemáticas que se sostienen incluso cuando el modelo es adversarial.
**Herramientas de privacidad para agentes y MCP.** El envenenamiento de herramientas, la inyección de prompts y la exfiltración son riesgos reales, y la pila emergente de seguridad para MCP los aborda con puertas de enlace de políticas, redacción y tokenización de PII, y patrones de minimización de datos. Esos controles gobiernan lo que un agente puede *ver y enviar*. Ninguno de ellos acota lo que una secuencia de *respuestas* individualmente inofensivas revela de forma acumulativa, y ese es el canal que explota [la galería de ataques](#the-headline-an-attack-gallery). Un ataque de diferenciación filtra un salario a través de dos agregados que un proxy de redacción dejaría pasar encantado. La privacidad diferencial acota exactamente ese canal, lo que la hace complementaria al resto de esa pila, no competencia.
**DP cerca de los LLM, problemas diferentes.** El DP-SGD (p. ej., [Opacus](https://opacus.ai/)) protege los ejemplos de entrenamiento dentro de los pesos del modelo. El aprendizaje en contexto con DP, el texto sintético con DP y el DP-RAG protegen los prompts y los corpus de recuperación. El DP local, como en la telemetría de Apple y Google, añade ruido a los datos en el dispositivo antes de que se recojan siquiera. Este proyecto es el escenario de modelo centralizado y más antiguo del que todos esos descienden: un curador confiable, un consultante no confiable y un presupuesto entre ambos.
**La afirmación, formulada con cuidado.** No hay matemáticas nuevas de privacidad diferencial en este repositorio. La contribución es la combinación, y la evidencia: un artefacto abierto, validado mediante ataques, que sitúa el acceso agéntico en lenguaje natural frente a un backend de agregados con DP bajo un modelo de amenazas explícito que asume que el modelo no es confiable. Por lo que he podido encontrar, ningún otro servidor MCP abierto aplica privacidad diferencial con un presupuesto persistido bajo un agente no confiable. Si conoce alguno, abra un issue; de verdad me gustaría intercambiar impresiones.
</details>
---
## Documentación
- [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/DESIGN.md): arquitectura, modelo de amenazas, las matemáticas de sensibilidad y ruido, el diseño del presupuesto
- [`SETUP.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/SETUP.md): configuración local, ejecución de las pruebas, parámetros de configuración
- [`docs/CLAUDE_DESKTOP.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/docs/CLAUDE_DESKTOP.md): conexión de un agente y una sesión de ataque reproducible
- [`benchmarks/RESULTS.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/benchmarks/RESULTS.md): latencia medida en ambas superficies y las tablas de capacidad de composición
- [`SECURITY.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/SECURITY.md): las limitaciones divulgadas y cómo informar de cualquier otra cosa
- [`CHANGELOG.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/HEAD/CHANGELOG.md): historial de versiones
## Estructura del repositorio```
.
├── README.md ← you are here
├── DESIGN.md ← architecture, threat model, the math, the budget design
├── SETUP.md ← local setup, running the tests, configuration knobs
├── engine/ ← DP engine: mechanism, RNG, sensitivity, budget accountant + store
├── validation/ ← the trust boundary: policy checks, guards, and the repair loop
├── compiler/ ← the untrusted LLM NL→AST compiler
├── attacks/ ← the attack gallery: differencing, membership ε-sweep, patients singling-out
├── service/ ← AnalyticsService + audit log: the transport-agnostic core every surface shares
├── mcp_server/ ← the stdio MCP server: tool schemas generated from the dataset policy
├── datasets/ ← owner-authored dataset policies, ingestion, and the bundled patients demo
├── identity/ ← the identity layer the budget is keyed to
├── api/ ← FastAPI service
├── ui/ ← Streamlit front-end with the live budget meter
├── benchmarks/ ← manual latency benchmarks (run by hand, never by pytest)
├── docs/ ← the Claude Desktop walkthrough, the demo GIF, and the session chart assets
├── scripts/ ← fetch_data.py (pulls UCI Adult into data/, never committed) + the demo GIF renderer
└── tests/ ← unit, trust-boundary, privacy-guarantee, and attack regression tests (DESIGN.md section 8)
Este proyecto es donde desarrollo públicamente el diseño de sistemas de datos que preservan la privacidad y el acceso a datos con privilegios mínimos: el límite de confianza, la contabilidad del presupuesto y las demostraciones de ataque son las partes que defendería en una revisión de diseño.