Your agent's audit log is a story, not evidence

개요

obstat는 에이전트 도구 호출에 대한 감사 가능한 결정 기록을 제공하는 라이브러리로, 도구 실행 이전에 권한 부여 결정이 디스크에 기록되고 동기화되도록 함으로써 기존 로깅 방식의 한계를 해결합니다.

주요 내용

• 기존 로깅 방식의 문제점: 대부분의 도구 거버넌스 레이어는 도구 호출이 반환된 후에 로그를 기록하며, 이로 인해 호출이 허가되지 않았거나 프로세스 충돌로 인해 로그 기록이 누락되었는지 구분할 수 없습니다. 이는 에이전트의 이전 활동에 대한 질문에 명확한 답변을 제공하지 못합니다.
• obstat의 작동 방식: obstat는 guard 데코레이터를 사용하여 도구 본문 실행 전에 권한 부여 결정(자원, 주체, 이유 등)을 디스크에 fsync까지 완료하여 기록합니다. 프로세스가 중단되더라도 기록은 유지됩니다.
• 내구성 보장: record.decision()은 fsync 완료 후에만 반환되며, 결정 기록은 도구 본문 실행 전에 완전히 내구성 있게 저장됩니다. 이는 테스트를 통해 검증 가능하며, 이 순서를 바꾸면 테스트가 실패합니다.
• 결과 기록의 비내구성: 성공 또는 실패와 같은 결과 기록은 도구 본문 실행 후에 기록되며, 이는 의도적으로 내구성이 떨어집니다. 프로세스 충돌 시 "권한 부여됨, 결과 알 수 없음"으로 기록되어 정직한 상태를 나타냅니다.
• 자원 기반 권한 부여: obstat는 단순한 권한 등급(READ/WRITE)을 넘어 특정 자원 ID를 식별하고 규칙을 매칭하여 세밀한 권한 제어를 가능하게 합니다 (예: "자신의 티켓만 편집 가능").
• 단일 사용 승인: 각 승인은 한 번의 호출에만 적용되며, 도구, 주체, 자원, 인자 다이제스트를 포함하고 단일 사용으로 강제됩니다.
• 인자 처리: 도구 인자에 포함될 수 있는 자격 증명이나 개인 데이터를 보호하기 위해, 사람이 볼 필요가 있는 인자만 기록하고 나머지는 다이제스트로 처리합니다.
• 불변성 보장: 각 레코드에는 이전 레코드의 해시값이 포함되어 있어, 레코드 편집 또는 삭제 시 감지할 수 있습니다.
• 실제 적용 사례: obstat를 개인 메일, Gmail, 비즈니스 주소의 IMAP/SMTP 서버에 적용한 결과, 에이전트가 보호되지 않은 경로를 통해 접근하여 기록되지 않은 정보를 얻는 문제를 발견했습니다.
• 기록의 범위: obstat 기록은 에이전트가 guard를 통해 접근한 호출을 추적하며, guard를 거치지 않은 접근은 기록되지 않습니다.
• 도구의 기능 확장: 누락되었던 count_unread와 같은 도구 기능이 추가되면서 기록의 중요성이 부각되었고, obstat_subject와 같이 라이브러리가 예약하는 접두사를 통해 혼동을 방지합니다.
• 개선된 결과 기록: 대량 삭제와 같은 작업에서 obstat.note()를 사용하여 삭제된 항목 수 등 더 상세한 정보를 결과 기록에 추가할 수 있습니다.
• 자원 ID 파싱: 자원 ID는 패턴 매칭 대신 자원 호출 가능 함수 내에서 파싱하여 보안을 강화합니다.
• 제한 사항: obstat는 위변조 방지(non-repudiation)보다는 위변조 탐지(tamper-evidence)에 초점을 맞춥니다. 또한, Windows 환경에서의 동시 쓰기 문제와 같이 특정 환경에서의 제약 사항이 문서화되어 있습니다.
• 테스트의 중요성: 명확한 주장이 있는 부분에 대한 테스트 부재는 버그를 야기할 수 있습니다. 사용자의 도구가 필터링하는 경우를 고려한 테스트 작성이 중요합니다.
• 간편한 설치 및 사용:obstat는 pip install obstat으로 설치 가능하며, 별도의 런타임 의존성이 없습니다. 익명 호출도 정책에 따라 처리할 수 있어 접근성이 높습니다.

시사점

obstat는 에이전트의 행위를 투명하고 감사 가능하게 기록하는 새로운 패러다임을 제시하며, 이는 에이전트 보안, 규정 준수 및 디버깅에 중요한 기여를 할 수 있습니다.