콘텐츠로 이동

감사와 컴플라이언스

관리형 설치는 게이팅되거나 차단된 모든 동작을 기록하고, 선택적으로 그 기록을 정책 서버에 보고한다. 기록은 구조적으로 비밀이 없어 중앙 집계해도 안전하다. 이 문서는 무엇이 기록되는지, 보고가 어떻게 동작하는지, 기록을 어떻게 수집·보존하는지 다룬다.

무엇이 기록되는가

관리형 설치는 두 종류의 감사 기록을 같은 로컬 감사 채널(tracing 타깃 audit)에 남긴다.

  • 정책 게이팅 거부: 정책으로 차단된 모든 동작은 정확히 하나의 구조화된 기록, 곧 reason = "policy_gated"인 authz_denial 이벤트를 남긴다. 기록은 동작(도구, 명령, 경로), 거부한 전송 경로(agent, tauri, rest, mcp), 결정 정책(정책이 조직을 명명한 경우 그 조직)을 담는다. 각 전송 경로의 가장 바깥 강제 지점에서 기록하므로, 차단된 동작 하나는 계층마다가 아니라 한 건이다.
  • 이그레스 결정: 이그레스 감사가 켜지면 이그레스 방화벽이 허용·차단 결정을 기록한다. 이 기록은 비밀이 없다. 결정과 호스트만 담고, 요청 본문·토큰·키는 담지 않는다.

스코프 거부(필요한 API 스코프가 없는 요청)는 같은 채널을 공유하므로, 단일 필터로 정책 게이팅 거부, 이그레스 결정, 스코프 거부를 함께 잡는다.

클라이언트-서버 보고

관리형 설치는 감사 기록을 정책 서버로 다시 보고할 수 있어, 관리자가 각 기기에 로그인하지 않고도 플릿 전체 강제 현황을 본다. 기록은 <app_data>/enterprise/audit/ 아래에 로컬 버퍼링되고, 배치로 묶여, 기기 ID로 서명되어 POST /api/v1/audit로 전송된다. 서버는 각 이벤트를, 보고한 기기 id를 태그로 달아, 자신의 감사 채널로 다시 내보내며 로그 파이프라인이 이를 수집한다.

보고는 경계가 있고 자기 보호적이다.

  • 한 배치는 최대 1,000개 이벤트를 담는다.
  • 기기는 자신에 대해서만 보고할 수 있다. 인증된 기기 id가 배치와 일치해야 한다.
  • 이벤트 필드는 비밀 필드 가드로 검사되어, 이름이 비밀(토큰, 비밀번호, 비공개 키, 서명)처럼 보이는 필드는 거부된다. 비밀에 가까운 유일한 필드는 마스킹된 자격 증명이며, 기기를 떠나기 전에 앞뒤 몇 글자 형태로 이미 축약된다.

정책 서버 바이너리의 서버는 등록 기기에 부여된 enterprise_read 스코프 아래에서 이 배치를 수신한다. 정책 서버 배포와 운영을 참고한다.

감사 이벤트 필드

보고되는 감사 이벤트는 비밀이 없는 필드만 담는다. 형태는 안정적이며 와이어에서 camelCase다.

필드 등장 대상 의미
event 전체 이벤트 종류(authz_denial 또는 auth_failure).
reason 대부분 거부 또는 실패 사유(예: policy_gated, insufficient_scope).
action 정책 게이팅 거부 차단된 동작(도구, 명령, 경로).
path 정책 게이팅 거부 거부한 전송 경로(agent, tauri, rest, mcp).
policy 정책 게이팅 거부 명명된 경우 결정 조직.
endpoint 스코프 거부, 인증 실패 관련 엔드포인트.
keyId 스코프 거부 키 식별자.
requiredScope 스코프 거부 빠진 스코프.
maskedKey 인증 실패 마스킹된 자격 증명(원시 키 아님).
timestamp 전체 RFC3339 타임스탬프.

원시 API 키, 등록 토큰, 비공개 서명 키, 프록시 비밀번호, CA 번들은 절대 나타나지 않는다. 이는 관행이 아니라 강제다. 빌드 경로가 자격 증명을 마스킹하고, 비밀 필드 가드가 이름으로 비밀처럼 보이는 것을 거부한다.

수집과 보존

기록이 비밀이 없으므로 표준 도구로 수집·보존할 수 있다. 두 수집 패턴이 동작하며, 둘을 함께 써도 된다.

  • 기기별 수집: 감사 채널이 기기의 로그 스트림에 쓴다. Linux에서는 저널, 헤드리스 호스트에서는 프로세스 로그다. 기존 로그 에이전트로 (예: SIEM이나 로그 집계기로) 전달한다. 서버에 보고하지 않는 기기에서도 기록을 잡는다.
  • 정책 서버에서 중앙 수집: 클라이언트 보고를 켜 기기가 배치를 정책 서버로 전송하게 하고, 서버가 다시 내보낸 감사 스트림을 수집한다. 각 기기를 건드리지 않고 단일 플릿 전체 피드를 얻되, 각 기기에서 서버로의 네트워크 경로가 필요하다.

보존은 기록을 운영 보안 로그로 취급한다. 컴플라이언스 기간(접근·권한 부여 로그는 흔히 90일에서 1년)을 충족할 만큼 보관하고, 기존 불변 또는 1회 쓰기 로그 저장소에 둔다. 기록에 비밀이 없으므로 이를 담는 저장소의 민감도를 높이지 않는다. <app_data>/enterprise/audit/ 아래의 로컬 버퍼는 경계가 있는 추가 전용이다. 이는 시스템 오브 레코드가 아니라 보고용 스테이징 영역이다. 장기 보존은 집계기나 SIEM에 맡긴다.

다루는 것과 다루지 않는 것

감사 표면은 권한 부여와 강제 결정을 기록한다. 정책 게이팅 거부, 스코프 거부, 이그레스 허용·차단 결정, 인증 실패다. 콘텐츠나 대화 로그가 아니다. 프롬프트, 모델 출력, 파일 내용을 기록하지 않는다. 배포가 무엇을 할 수 있는지(정책 자체)의 권위 있는 출처는 정책 서버가 서빙하는 서명된 정책과 각 기기의 해석된 관리 상태다.

다음 단계