yashmahajan10/llm-differential-privacy-gateway
Noisegate: шлюз дифференциальной приватности, позволяющий недоверенному LLM-агенту запрашивать конфиденциальные данные через MCP (Model Context Protocol), с формальной гарантией того, что запись ни одного отдельного человека не может утечь, даже если агент является злонамеренным — принудительное исполнение реализовано в доверенном коде ниже уровня модели и подтверждено рабочей галереей атак.
AI-агент, способный изучать конфиденциальные данные, не имея возможности выделить кого-либо конкретного. Ограничение носит математический характер, оно обеспечивается кодом, до которого агент не может добраться, а репозиторий поставляет атаки, которые пытаются его сломать.
Записанная сессия Claude Desktop (ответы сокращены; карточки графиков принадлежат самой сессии). AI-агент разбивает 20 пациентов по диагнозам, и шум ±12 перекрывает каждый интервал. Напомнив, что он не может отключить шум, он исчерпывает бюджет из трёх ответов, пока шлюз не возвращает отказ вместо более тихого ответа. На переписи из 32 561 строки слишком узкий срез отклоняется на границе доверия, тогда как полная разбивка по образованию возвращается чистой в масштабе. Отказ и отклонение — это реальное принудительное исполнение работающего шлюза, воспроизводимое командой python scripts/render_demo_gif.py.
Вы задаёте вопросы о конфиденциальном наборе данных на простом английском. LLM компилирует каждый вопрос в небольшой ограниченный запрос. Движок дифференциальной приватности выполняет его в рамках отслеживаемого бюджета приватности и возвращает намеренно зашумлённый ответ с указанным доверительным интервалом. Подобно своему звуковому тёзке, шлюз удерживает каждый сигнал ниже заданного порога под уровнем шума: вклад любого отдельного человека заглушается, тогда как сигнал в масштабе всего набора данных проходит почти нетронутым.
Интересно не то, что LLM может писать запросы. Интересно то, что гарантия приватности не зависит от того, заслуживает ли LLM доверия. Модель — это удобство, предлагающее запрос. Она ничего не обеспечивает. Каждое свойство приватности обеспечивается ниже по потоку компонентами, которые вели бы себя так же, если бы запрос вручную набрал человек. Это дисциплина границы доверия, которую вы применяли бы к любому недоверенному вводу в производственной системе, применённая здесь к AI-агенту.
Галерея атак выполняется внутри процесса против настоящего DP-движка:```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. Подключение AI-агента
Шлюз работает как MCP stdio-сервер для Claude Desktop. Агент становится недоверенным автором запросов и получает только структурированные инструменты (`count`, `sum`, `average`, `histogram`, `get_budget`), схемы аргументов которых генерируются из политики набора данных. API-ключ нигде не нужен, поскольку подключающийся агент и есть интеллект.
**[Настройка и полное руководство →](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/docs/CLAUDE_DESKTOP.md)**
### 3. Полноценный интерфейс на естественном языке
Локальная однопользовательская демонстрация. API-ключ нужен только для недоверенного компилятора NL→запрос:```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
Эта поверхность HTTP + Streamlit представляет собой локальную однопользовательскую демонстрацию. Идентификация осуществляется через подделываемый заголовок X-Identity, поэтому она предназначена для одного доверенного оператора на его собственной машине, а не для публичного развёртывания (см. что представляют собой эти поверхности, а чем не являются). Для локальной настройки без Docker, запуска тестов и параметров конфигурации см. SETUP.md.
Любой может заявить о приватности. Этот репозиторий поставляет эксплойты, которые опровергли бы это заявление, запускает их против собственного движка и фиксирует результаты в CI. Самый быстрый способ понять, что гарантирует шлюз, — увидеть, как он отражает три классические атаки, которые ломают наивные системы «запрос к базе данных».
Атака вычитания изолирует одного человека, задавая два агрегированных вопроса, которые различаются ровно на этого человека.``` 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.
Оба запроса — «просто агрегаты». Ни один из них не называет отдельную строку. И всё же вместе они раскрывают конкретного человека. Галерея (`attacks/differencing.py`) показывает, как эта атака **удаётся при отключённой приватности**: приватное значение цели восстанавливается точно. (Пример с зарплатой выше — иллюстративный; на реальных данных UCI Adult «Alice» — единственная обладательница максимального прироста капитала в своей группе.) Затем она показывает ту же атаку **побеждённой, как только DP включён**: калиброванный шум на каждом ответе делает вычитание бесполезным, а бюджетный учёт списывает средства за информацию, раскрытую в *обоих* запросах, а не рассматривает их как независимые.
### Атака 2: Вывод о принадлежности
Атака вывода о принадлежности определяет, входит ли *конкретный человек* в набор данных вообще. Для многих наборов данных (медицинское исследование, список неплательщиков) сам этот факт является чувствительным. Злоумышленник, имеющий только доступ к запросам, пытается решить: «есть ли этот конкретный человек в данных?»
Галерея запускает эту атаку по развёртке бюджетов приватности (ε — регулятор, обменивающий точность ответа на приватность) и строит график результата:
<sub>**Оптимальный** (Неймана–Пирсона) атакующий, определяющий принадлежность одного человека по одному зашумлённому `COUNT`, запущенный против реального движка по развёртке ε. Эмпирическая успешность (синий, 95% интервалы Уилсона) близко следует аналитической кривой Лапласа и остаётся ниже наихудшего потолка DP (пунктир); она обрушивается от определённости (DP выключен) к подбрасыванию монеты 0.5 по мере уменьшения ε. Зелёная **кривая полезности** (правая ось) показывает относительную ошибку агрегатного запроса на той же развёртке, едва затронутую там, где атака побеждена. Сгенерировано `python -m attacks.membership` (10 000 испытаний на каждое ε).</sub>
По мере уменьшения ε (усиление приватности) успешность атакующего обрушивается к подбрасыванию монеты. Наложение полезности показывает цену: тот же шум, который побеждает атаку на одного человека, едва сдвигает агрегат популяционного масштаба. Приватность не бесплатна, и график показывает ровно то, чем вы за неё платите. Развёртка охватывает ε = 8 вплоть до 0.5, чтобы покрыть весь диапазон; входящее в комплект развёртывание списывает **ε = 0.05 за запрос**, за левым краем этого графика, где атака по одному запросу уже неотличима от случайности.
### Атака 3: Выделение путём реидентификации
Латанья Суини показала в 2002 году, что почтовый индекс + дата рождения + пол однозначно идентифицируют примерно 87% американцев (более поздняя репликация на новых данных переписи дала ближе к 63%). Вам не нужно имя человека, чтобы найти его в наборе данных; достаточно нескольких безобидных атрибутов. Третья атака галереи (`attacks/patients_alice.py`) воспроизводит эту структуру на 20 синтетических пациентах: только пол и возраст сужают когорту ровно до одного человека — Alice, единственной женщины старше 64.
При отключённой приватности вычитание двух совершенно обычных демографических гистограмм точно восстанавливает диагноз Alice. Никакого выбросного значения не требуется; быть *реидентифицируемым* достаточно, что делает эту атаку сильнейшей в галерее. При включённой приватности её прекращают три независимые защиты: фильтр-страж отклоняет очевидный узкий запрос сразу (не тратя ничего); калиброванный шум топит вычитание двух запросов (отношение сигнал/шум ≈ 0.13, так что восстановленный «диагноз» — по сути случайная выборка); а бюджет отказывает в эскалации усреднения задолго до того, как она могла бы сработать (нужно ~256 повторений, доступно 10). Именно эту атаку демонстрационный GIF в верхней части этой страницы и [руководство по Claude Desktop](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/docs/CLAUDE_DESKTOP.md) воспроизводят вживую. Результаты покрыты регрессионными тестами в `tests/test_attack_patients.py`.
Эти эксперименты, запущенные против собственного движка системы, — ключевое доказательство того, что гарантия реальна и понята, а не импортирована из библиотеки и принята на веру.
### Перекрёстная проверка с OpenDP
Атаки проверяют гарантию против *нашей собственной* математики. Чтобы защититься от самосогласованной, но неверной реализации, механизм также перекрёстно проверяется против [OpenDP](https://opendp.org/) как независимого эталона (`attacks/crosscheck_opendp.py`, opendp 0.15.1).
**Коротко: механизм, построенный с нуля, совпадает с отраслевым эталоном до девяти знаков после запятой, а версия, намеренно плохо откалиброванная, проваливает те же тесты, так что совпадение что-то значит.** Совпадение проверяется двумя способами: чувствительность и масштаб шума против сертифицированной границы OpenDP, и фактическое распределение сэмплера против распределения OpenDP, с положительным контролем, доказывающим, что тест может провалиться. Измеренные значения приведены в [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/DESIGN.md), раздел 6.3.
OpenDP — эталон, но никогда не реализация: он живёт только в dev-дополнениях, и работающая система его не импортирует. Совпадение масштаба покрыто регрессионным тестом в `tests/test_crosscheck_opendp.py` (пропускается без OpenDP локально; CI устанавливает его и задаёт `REQUIRE_OPENDP=1`, чтобы проверка там никогда не могла молча пропуститься).
### Воспроизведение
Атаки выполняются внутри процесса против реального DP-движка. Ни API-ключ, ни сервер не нужны, поскольку они строят написанные вручную AST, а не проходят через 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]")
Результаты сами по себе проходят регрессионное тестирование в tests/test_attack_differencing.py, tests/test_attack_membership.py и tests/test_attack_patients.py, поэтому изменение, которое незаметно ослабило бы гарантию, провалило бы CI, а не просто выдало бы более красивый график.
Три этапа. Только первый является недоверенным, и именно в этой асимметрии заключается вся идея.``` 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
Наиболее важным проектным решением является блок, помеченный **UNTRUSTED**. Всё, что находится выше слоя валидации, считается враждебным, а всё, что ниже него, — это доверенная вычислительная база, обеспечивающая гарантию. LLM компилируется в *ограниченное AST*, а не в произвольный SQL, потому что именно это ограничение задаёт границы чувствительности запроса, а ограниченная чувствительность — это то, что делает калибровку шума корректной. Свободная форма SQL вновь открыла бы ровно ту поверхность атаки, которую закрывает этот проект.
## Модель приватности
Каждый ответ зашумлён. Точный реестр совокупного раскрытия ведётся для каждой идентичности и сохраняется на диск, и шлюз отказывается отвечать прежде, чем этот реестр сможет превысить гарантию, которую он заявляет. Он никогда не деградирует тихо до более зашумлённого ответа.
Цену стоит назвать так же прямо. Гарантия — это **(ε, δ)-дифференциальная приватность, которая строго слабее чистой ε-DP.** С вероятностью не более δ граница ε может быть нарушена. δ — это не дополнительный шум, это масса отказа, поэтому она выводится из набора данных, а не задаётся жёстко.
Разделы 3 и 5.4 в [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/DESIGN.md) содержат полный вывод: чувствительность, механизм Лапласа, гибридный учёт zCDP и откуда берётся δ. Вот куда делись все греческие буквы.
---
## Чем этот проект является и чем не является
Он **является** демонстрацией того, что недоверенный слой на естественном языке может находиться перед чувствительными данными, не компрометируя формальную гарантию приватности, причём гарантия подкреплена работающими атаками, а не утверждениями.
Он **не является** production-продуктом для приватности, заменой проверенной библиотеки DP в реальном развёртывании или утверждением, что сгенерированные LLM запросы безопасно выполнять без защиты. Они не безопасны, и именно поэтому существует доверенный слой.
И MCP-сервер, и HTTP-демо обслуживают **единственного локального принципала**, которому принадлежит машина, и этот принципал может сменить эпоху или удалить файл бюджета, чтобы начать заново. Таким образом, свойство «внешняя сторона сжигает бюджет и не может вернуть его обратно» *демонстрируется в механизме, но не обеспечивается против удалённого противника*. Для закрытия этого разрыва нужны проверенная идентичность (OAuth) и разделение на мультитенантность, всё ещё находящиеся в дорожной карте. У сэмплера шума также есть известный побочный канал с плавающей точкой (Mironov 2012, описан в разделе 5.5 [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/DESIGN.md)). **Не** направляйте ни одну из этих поверхностей на реальные регулируемые данные и не рассматривайте её как замену проверенной библиотеки DP там, где недоверенная сторона может аутентифицироваться.
Входящий в комплект набор данных — это публичный набор **UCI Adult / Census Income**, стандартный бенчмарк в литературе по дифференциальной приватности, поэтому результаты атак против ε здесь напрямую сопоставимы с опубликованными работами. Он уже публичен, поэтому репозиторий безопасно публиковать. Механизм приватности демонстрируется *так, как если бы* записи были чувствительными.
---
## Смежные работы
Где это находится среди существующих инструментов и что он намеренно делает иначе.
<details>
<summary><b>Библиотеки DP, движки запросов DP, text-to-SQL, инструменты безопасности MCP и DP рядом с LLM</b> (нажмите, чтобы развернуть)</summary>
<br>
**Библиотеки DP.** [OpenDP](https://opendp.org/), [библиотеки дифференциальной приватности Google](https://github.com/google/differential-privacy), [diffprivlib от IBM](https://github.com/IBM/differential-privacy-library) и [Tumult Analytics](https://github.com/opendp/tumult-analytics) (которые обеспечивали релизы Бюро переписи населения США, Wikimedia и IRS, прежде чем их команда присоединилась к LinkedIn в 2025 году, а библиотека перешла в организацию OpenDP) — это проверенные реализации самих механизмов, написанные для того, чтобы доверенный аналитик вызывал их из своего кода. Этот проект вместо этого реализует свой механизм вручную, чтобы каждая строка критического для приватности пути оставалась небольшой, читаемой и тестируемой в одном репозитории, а затем [сверяет его с OpenDP](#cross-checked-against-opendp), именно потому что механизм, реализованный вручную, ничего не значит без внешнего арбитра. Для реального развёртывания остаётся в силе приведённый выше совет: используйте проверенную библиотеку.
**Движки запросов DP.** [PINQ](https://www.microsoft.com/en-us/research/publication/privacy-integrated-queries/) (McSherry, 2009) заложил архитектуру, которую наследует этот проект: недоверенный аналитик отправляет запросы через доверенный слой, который гарантирует дифференциальную приватность независимо от того, что запрашивается. Его production-потомки отвечают на SQL под DP: [smartnoise-sql](https://github.com/opendp/smartnoise-sdk), [архивный переписыватель elastic-sensitivity от Uber](https://github.com/uber-archive/sql-differential-privacy) и [дифференциально приватный SQL Wilson et al.](https://petsymposium.org/popets/2020/popets-2020-0025.php), поставляемый сегодня как [дифференциальная приватность BigQuery](https://docs.cloud.google.com/bigquery/docs/differential-privacy). Здесь есть два намеренных отличия. Те системы принимают SQL и анализируют или переписывают его, тогда как этот шлюз вообще не принимает SQL: агент отправляет небольшое ограниченное AST, потому что язык запросов, достаточно малый для перечисления, — это граница доверия, достаточно малая для исчерпывающего тестирования. И в каждой из них за клавиатурой сидит человек-аналитик, тогда как здесь автором запроса является автономный агент, и модель угроз это учитывает.
**Интерфейсы к базам данных на естественном языке.** Text-to-SQL — это большая и успешная область, но приватность не является её предметом: сгенерированный SQL выполняется с теми полномочиями, которые предоставляет база данных. Там, где безопасность всё же рассматривается, как в [SafeNLIDB](https://arxiv.org/abs/2511.06778) (AAAI 2026), она основана на выравнивании (обучение модели рассуждать о том, на что безопасно отвечать), поэтому гарантия живёт внутри модели. Этот проект занимает комплементарную позицию: предположить, что модель невозможно сделать безопасной, и обеспечить гарантию ниже неё с помощью математики, которая работает даже тогда, когда модель враждебна.
**Инструменты приватности для агентов и MCP.** Отравление инструментов, инъекция промптов и эксфильтрация — реальные риски, и формирующийся стек безопасности MCP решает их с помощью шлюзов политик, редактирования и токенизации PII, а также паттернов минимизации данных. Эти меры контролируют то, что агент может *видеть и отправлять*. Ни одна из них не ограничивает то, что последовательность по отдельности безобидных *ответов* совокупно раскрывает, а именно этот канал эксплуатирует [галерея атак](#the-headline-an-attack-gallery). Атака вычитанием раскрывает зарплату через два агрегата, которые прокси-редактор с радостью пропустил бы. Дифференциальная приватность ограничивает именно этот канал, что делает её дополнением к остальной части этого стека, а не конкурентом.
**DP рядом с LLM, другие задачи.** DP-SGD (например, [Opacus](https://opacus.ai/)) защищает обучающие примеры внутри весов модели. DP в контекстном обучении, DP-синтетический текст и DP-RAG защищают промпты и корпуса для извлечения. Локальная DP, как в телеметрии Apple и Google, зашумляет данные на устройстве ещё до того, как они собраны. Этот проект — это более старая, центральная модель, от которой все они происходят: доверенный куратор, недоверенный спрашивающий и бюджет между ними.
**Утверждение, сформулированное аккуратно.** В этом репозитории нет новой математики дифференциальной приватности. Вклад — это комбинация и доказательства: открытый, проверенный атаками артефакт, который ставит агентный доступ на естественном языке перед агрегирующим бэкендом DP в рамках явной модели угроз с недоверенной стороной. Насколько мне удалось выяснить, никакой другой открытый MCP-сервер не обеспечивает дифференциальную приватность с сохраняемым бюджетом под недоверенным агентом. Если вы знаете такой, откройте issue; я искренне хотел бы сравнить заметки.
</details>
---
## Документация
- [`DESIGN.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/DESIGN.md): архитектура, модель угроз, математика чувствительности и шума, дизайн бюджета
- [`SETUP.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/SETUP.md): локальная настройка, запуск тестов, параметры конфигурации
- [`docs/CLAUDE_DESKTOP.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/docs/CLAUDE_DESKTOP.md): подключение агента и воспроизводимая сессия атаки
- [`benchmarks/RESULTS.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/benchmarks/RESULTS.md): измеренная задержка на обеих поверхностях и таблицы ёмкости композиции
- [`SECURITY.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/SECURITY.md): раскрытые ограничения и как сообщить о чём-либо ещё
- [`CHANGELOG.md`](https://github.com/yashmahajan10/llm-differential-privacy-gateway/blob/main/CHANGELOG.md): история релизов
## Структура репозитория```
.
├── 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)
Этот проект — место, где я публично прорабатываю дизайн систем обработки данных с сохранением приватности и доступа к данным по принципу наименьших привилегий: граница доверия, учёт бюджета и демонстрации атак — это те части, которые я бы отстаивал на ревью дизайна.