Dvarapala

Шлюзы доступа и защищённые от подделки журналы аудита для ИИ-агентов и MCP-серверов. Добавление занимает 3 строки.

Агенты выполняют инструменты, запускают команды, перемещают деньги. Когда что-то идёт не так, нужно ответить на два вопроса: должно ли было это быть разрешено? и где именно в ходе вызов пошло не так? Dvarapala отвечает и на тот и на другой — до (контроль доступа) и после (аудит) — с нулевыми зависимостями.

import dvarapala

gate = dvarapala.Gate(policy="policy.json", audit="audit.jsonl")

@gate(risk="critical")
def refund(customer_id: str, amount_cents: int):
    ...  # nothing runs unless policy + consent approve; every decision is hash-chained

Зачем

• Gate (до): декларативная политика (allow / warn / confirm / deny), эвристическая оценка риска, лестница согласий (один раз / на сессию / всегда), аварийный отключатель, ограничитель частоты.

• Audit (во время → после): журнал JSONL с дрописыванием и цепочкой SHA-256 для каждой записи. Изменение или удаление истории нарушает проверку: dvarapala verify audit.jsonl.

• Причинно-следственные поля с первого дня: каждая запись содержит run_id, step, parent_step, context_refs, alternatives_considered, state_delta — поэтому ответ на вопрос «почему агент это сделал?» можно надстроить поверх журнала без повторной инструментировки.

Экскурсия на 30 секунд

gate = dvarapala.Gate(
    policy={
        "rules": [
            {"id": "reads-free",   "match": {"tool": "read_*"}, "effect": "allow"},
            {"id": "refunds-human","match": {"tool": "refund"}, "effect": "confirm"},
            {"id": "no-drop",      "match": {"keywords": ["drop table"]}, "effect": "deny"},
        ]
    },
    audit=".dvara/audit.jsonl",
)

Укажите, где в цикле агента происходит вызов:

with dvarapala.step(run_id="r1", step_no=17,
                    alternatives_considered=["cancel_order"]):
    refund("c1", 5000)     # audited with step=17, alternatives recorded

Запрещённые вызовы выбрасывают dvarapala.Denied (подкласс PermissionError) — перехватите его и позвольте модели попробовать что-то другое.

Поверхности

Принципы проектирования

• Ядро только на стандартной библиотеке. Без зависимостей; YAML-политики — опциональное расширение.

• Безопасный отказ по умолчанию. В неинтерактивных сессиях применяется отказ, а не запрос; неизвестные команды shell оцениваются как MEDIUM; разрушительные токены — как CRITICAL.

• Журнал — это доказательство. Проверка цепи — одна команда, сервер не нужен.

Статус

v0.1.0 (alpha). Ядро Gates и аудита стабильно; адаптеры и слой атрибуции сбоев (why did step 24 fail because of step 6?) — в дорожной карте. Лицензия MIT. Принимаются пулл-реквесты.

Установка

pip install dvarapala          # core, stdlib-only
pip install dvarapala[yaml]    # + YAML policy support
pip install dvarapala[dev]     # + pytest/ruff

Лицензия

MIT — см. LICENSE.