Dvarapala

AI 에이전트와 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

왜 필요한가

• 게이트(사전): 선언적 정책(allow / warn / confirm / deny), 휴리스틱 위험 점수, 동의 사다리(once / session / always), 킬 스위치, 속도 제한기.

• 감사(중 → 후): 레코드마다 SHA-256 체인이 있는 추가 전용 JSONL. 기록을 편집하거나 삭제하면 검증이 깨집니다: 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 정책은 선택적 추가 기능입니다.

• 거부-안전 기본값. 비대화형 세션은 묻는 대신 거부합니다; 알 수 없는 셸 명령은 MEDIUM으로 평가됩니다; 파괴적 토큰은 CRITICAL로 평가됩니다.

• 로그는 증거입니다. 체인 검증은 서버 없이도 단일 명령으로 가능합니다.

상태

v0.1.0(알파). 게이트와 감사 코어는 안정적입니다; 어댑터와 실패 원인 규명 계층(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 참조.