mcp-permission-server

Уровень разрешений перед инструментами MCP и журнал, который может доказать, что он решил.

Каждый журнал аудита фиксирует, что произошло. Почти ни один не фиксирует достаточно, чтобы пересчитать, почему было разрешено, и большинство фиксирует только успешные действия — поэтому, когда кто-то спрашивает «как агент добрался до этого файла», журнал не может ответить. Он может лишь повторить утверждение, что решение было принято.

                                 NAIVE     GUARDED
calls in the session                17          17
calls that must be denied            8           8
EXECUTED WITHOUT A GRANT             7           0
LEGITIMATE CALLS REFUSED             0           0      ← no over-blocking
DECISIONS THAT CANNOT BE            16           0      ← the number nobody reports
  RECONSTRUCTED FROM THE LOG
denials that left no trace           1           0
secrets sitting in the log           2           0
entry removable unnoticed            1           0

NAIVE — это модель разрешений, с которой поставляется MCP-сервер, когда разрешения не были в центре внимания: список разрешённых инструментов и журнал того, что успешно выполнено. Каждый вызов в этой сессии, кроме одного, проходит.

python3 demo.py
python3 gate.py --log audit.json     # run the session
python3 gate.py --verify audit.json  # re-decide every entry from the log alone

chain:  OK - the chain is intact
replay: 17/17 entries recompute to the verdict they record
secrets in the log: none

Код выхода: 0 — всё разрешено, 1 — что-то отклонено, 2 — журнал не проверяется.

Грант — это четыре вещи одновременно

То есть четыре отдельные причины, по которым живой грант всё ещё может не покрывать вызов, — и вопрос «есть ли у этого вызывающего разрешение на этот инструмент» — это неправильный вопрос.

{"id": "G1", "tool": "fs.read", "scope": "/data/reports",
 "purpose": "q3-report", "expires_at": 100, "max_uses": 10}

Есть тест, который для каждого из этих случаев отключает только ту проверку, что названа, и требует, чтобы вызов прошёл. Отказ, который ловят несколько проверок, — это отказ, который ничего не доказывает ни об одной из них.

Related MCP server: MCP Airlock

Запутанный посредник

render_template разрешён. /templates/leak.md находится внутри разрешённой области. Шаблон содержит {{include:/etc/service-token}}.

Сервер обладает правами, которых нет у вызывающего, и его просят потратить их на ресурс, который вызывающий никогда не называл. Уровень разрешений, который проверяет ресурс в аргументах, проверяет не то именно для тех инструментов, где это важно.

Поэтому проверка смотрит на то, чего достигает вызов, до того, как он этого достигает, — и затем всё равно говорит «да» для /templates/report.md, который достигает /data/reports/q3.csv, на который у этого вызывающего действительно есть грант. Половина проверки разрешений — это «да». Правило, которое блокирует каждый шаблон, потому что шаблоны могут включать в себя что угодно, — это не правило.

Путевое вхождение — вот где обычно ошибаются

Обе ошибки — длиной в одну строку.

path.startswith(scope)     # /data/reports-private is "inside" /data/reports
".." in path               # and this breaks ordinary callers to catch nothing

Второй случай заслуживает отдельного разбора. /data/reports/../reports/q3.csv разрешается обратно внутрь разрешённой области, и в корпусе вызовов он есть и должен быть разрешён. Запрет символов — это дешёвое исправление; разрешение пути ловит всё, что запрет ловит, и ничего из того, что запрет не ловит.

Разрешение здесь — лексическое и никогда не касается файловой системы — есть тест, который ищет realpath, os.stat и open(. Решение принимается до вызова, на пути, который указал вызывающий, и оно не должно зависеть от того, что произойдёт дальше.

Журнал — это продукт

Два свойства делают его доказательством, а не просто записями.

Он фиксирует отказы. Журнал того, что прошло, не может ответить на вопрос «что пытался сделать агент» — а это именно то, что спрашивают потом. Восемь из семнадцати записей — это отказы, и каждая содержит проверку, которая сработала, и причину на простом языке.

Его можно воспроизвести. Каждая запись несёт в себе грант, на основании которого принималось решение, и версию политики, так что решение можно пересчитать из журнала и сравнить с вердиктом:

python3 gate.py --verify audit.json
replay: 17/17 entries recompute to the verdict they record

При выключенном поле replay это число — 0/17 — записи просто говорят, что было решено, и не дают никому возможности это проверить.

А записи связаны хеш-цепочкой, так что удаление или изменение одной видно:

entry 6 does not follow the one before it -- something was removed or edited

Секреты в него не попадают. Журнал аудита, хранящий секрет, — это вторая копия секрета, в файле, который читает больше людей. secrets.get разрешён в этой сессии, и его значение не появляется в журнале; наивный журнал содержал бы два.

Девять проверок и доказательство, что каждая на своём месте

check         what turning it off lets through
grant          1 more unauthorised, 1 more unreconstructable, 1 more egress
scope          3 more unauthorised, 3 more unreconstructable
expiry         2 more unauthorised, 2 more unreconstructable
purpose        1 more unauthorised, 1 more unreconstructable
deputy         1 more unauthorised, 1 more unreconstructable
redact         1 more secret in the log
deny_log       8 more denials that left no trace
replay        17 more decisions that cannot be reconstructed
chain          1 more entry removable unnoticed

python3 ablate.py

Одна поправка, которую стоит записать: первая версия абляции scope не отключала проверку — она подменяла сравнение строк на сравнение по префиксу, а это другая проверка, а не отсутствие проверки, и она по-тихому продолжала отклонять вызов, который должен был доказать, что проверка нужна. Отключить проверку — значит действительно её отключить, иначе абляция измеряет не то.

Тот же эксперимент показал, что грант, рассчитанный так, что последний вызов был отклонён за превышение лимита использований, а не за то, что он не покрыт по имени ключа, — это была не та проверка, и она проходила. Исправление было в самой тестовой обвязке, и тест, который нашёл эту ошибку, — это тот, который требует, чтобы каждый отказ изолированно проверял свою собственную проверку.

Известные ограничения, заявленные открыто, а не скрытые

• Это уровень решений, а не транспорт. Он принимает решения, исполняет их через внутрипроцессную таблицу инструментов и ведёт журнал. Подключение его к реальному MCP-транспорту — это обычная работа; то, что здесь есть, — это та часть, которой обычно не хватает, и она работает без сети и без ключей.

• Гранты записываются, а не извлекаются. Реальное развёртывание спрашивает человека и сохраняет ответ. То, что должен содержать ответ, — инструмент, область действия, назначение, срок действия, счётчик использований, — это та часть, о которой здесь идёт спор.

• purpose объявляется вызывающим и принимается как есть. Вызывающий, который лжёт о своём назначении, обходит проверку. Но это всё равно даёт что-то реальное: объявленное назначение попадает в журнал, так что ложь остаётся в записи, и область действия гранта от этого не расширяется.

• Проверка посредника знает охват одного инструмента. render_template разбирает свои включения. Инструмент, охват которого сервер не может вычислить, нельзя проверить таким способом, и честный ответ для такого инструмента — более узкий грант, а не более широкая проверка.

• Цепочка доказывает порядок и целостность, а не хранение. Любой, кто может переписать весь файл, может переписать всю цепочку. Это делает выборочное изменение видимым — а это реальная угроза; append-only хранилище или внешнее якорение — это то, что делает видимым всё остальное, и это уже работа по развёртыванию.

Структура

fixtures/spec.py     the session, the grants, the world, and the answer key
build_fixtures.py    renders session.json, policy.json, world.json, truth.json
mcpgate/scope.py     is this path inside that scope
mcpgate/policy.py    a grant is four things at once
mcpgate/tools.py     the tool table, and what a call actually reaches
mcpgate/audit.py     the hash-chained, redacted, replayable log
mcpgate/server.py    naive() and guarded(), and replay()
gate.py              the CLI: run a session, or verify a log
score.py             every number above
ablate.py            each check off, one at a time
tests/               38 tests

Запуск

python3 demo.py                        # both servers + ablation
python3 gate.py --log audit.json       # the product
python3 gate.py --verify audit.json    # the proof
python3 -m pytest tests -q             # 38 tests

Docker, с отключённой сетью:

docker compose run --rm gate

Тесты

Один проверяет, что разрешающий список по-прежнему пропускает почти всё. Один воспроизводит каждое зафиксированное решение и требует того же вердикта. Один требует, чтобы каждый отказ проходил только из-за той проверки, что названа, — чтобы числа абляции значили ровно то, что говорят. Один ищет в резолвере путей вызовы файловой системы.