Dvarapala

Berechtigungs-Gates + manipulationssichere Audit-Logs für KI-Agenten und MCP-Server. Drei Zeilen genügen.

Agenten rufen Tools auf, führen Befehle aus und bewegen Geld. Wenn etwas schiefgeht, müssen Sie zwei Fragen beantworten: Hätte das erlaubt sein dürfen? und Wo genau ist der Lauf schiefgegangen? Dvarapala beantwortet beide — vorher (Gating) und nachher (Audit) — ganz ohne Abhängigkeiten.

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

Warum

• Gate (vorher): deklarative Richtlinie (allow / warn / confirm / deny), heuristische Risikobewertung, Zustimmungsleiter (einmalig / Sitzung / immer), Notausschalter, Ratenbegrenzer.

• Audit (während → danach): Append-only-JSONL mit einer SHA-256-Kette pro Datensatz. Das Bearbeiten oder Löschen des Verlaufs bricht die Verifikation: dvarapala verify audit.jsonl.

• Kausalfelder von Anfang an: jeder Datensatz trägt run_id, step, parent_step, context_refs, alternatives_considered, state_delta — sodass die Zuschreibung „Warum hat der Agent das getan?“ direkt darauf aufgebaut werden kann, ohne irgendetwas neu zu instrumentieren.

30-Sekunden-Tour

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

Annotieren Sie wo ein Aufruf in Ihrer Agenten-Schleife stattfindet:

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

Abgelehnte Aufrufe lösen dvarapala.Denied aus (einen PermissionError) — fangen Sie die Ausnahme ab und lassen Sie das Modell etwas anderes versuchen.

Schnittstellen

Designregeln

• Nur-Stdlib-Kern. Keine Abhängigkeiten; YAML-Richtlinien sind ein optionales Extra.

• Deny-sichere Standardeinstellungen. Nicht-interaktive Sitzungen lehnen ab, statt nachzufragen; unbekannte Shell-Befehle werden als MEDIUM bewertet; destruktive Tokens als CRITICAL.

• Das Log ist Beweis. Die Kettenverifikation ist ein einziger Befehl, kein Server nötig.

Status

v0.1.0 (Alpha). Der Gate- und Audit-Kern ist stabil; Adapter und die Fehlerattributionsschicht (why did step 24 fail because of step 6?) stehen auf der Roadmap. MIT-lizenziert. Beiträge sind willkommen.

Installation

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

Lizenz

MIT — siehe LICENSE.