Dvarapala

Puertas de permisos + registros de auditoría a prueba de manipulaciones para agentes de IA y servidores MCP. 3 líneas para añadirlo.

Los agentes ejecutan herramientas, lanzan comandos, mueven dinero. Cuando algo sale mal necesitas responder dos preguntas: ¿debería haberse permitido? y ¿exactamente dónde falló la ejecución? Dvarapala responde ambas — antes (control de acceso) y después (auditoría) — con cero dependencias.

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

Por qué

• Gate (antes): política declarativa (allow / warn / confirm / deny), puntuación de riesgo heurística, escalera de consentimiento (once / session / always), interruptor de emergencia, limitador de frecuencia.

• Auditoría (durante → después): JSONL de solo adición con una cadena SHA-256 por registro. Editar o eliminar el historial rompe la verificación: dvarapala verify audit.jsonl.

• Campos causales desde el primer día: cada registro lleva run_id, step, parent_step, context_refs, alternatives_considered, state_delta — de modo que la atribución del "¿por qué hizo eso el agente?" se pueda construir encima sin volver a instrumentar nada.

Recorrido de 30 segundos

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

Anota dónde se produce una llamada en el bucle de tu agente:

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

Las llamadas denegadas lanzan dvarapala.Denied (un PermissionError) — captúralo y deja que el modelo reintente con otra cosa.

Superficies

Reglas de diseño

• Núcleo solo con la biblioteca estándar. Sin dependencias; las políticas YAML son un extra opcional.

• Valores predeterminados seguros por denegación. Las sesiones no interactivas deniegan en lugar de solicitar confirmación; los comandos de shell desconocidos se evalúan como MEDIUM; los tokens destructivos como CRITICAL.

• El registro es evidencia. La verificación de la cadena es un solo comando, no se necesita servidor.

Estado

v0.1.0 (alpha). El núcleo de Gate y auditoría es estable; los adaptadores y la capa de atribución de fallos (why did step 24 fail because of step 6?) están en la hoja de ruta. Licencia MIT. Las contribuciones son bienvenidas.

Instalación

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

Licencia

MIT — consulta LICENSE.