감사 로그는 조직에서 일어난 모든 상태 변경 작업을 기록합니다. 역할 할당, 엔진 수정, API 키 발급, 청구 변경까지 모두 검색 가능하고 필터링 가능한 타임라인에서 확인할 수 있습니다. Enterprise 플랜에서 역할 및 권한과 함께 제공됩니다.
이 로그는 데이터베이스 수준에서 append-only로 유지됩니다. 애플리케이션 연결로는 감사 레코드를 수정, 삭제, truncate할 수 없습니다. 한 번 기록되면 그대로 남습니다.
기록되는 항목#
각 이벤트에는 작업 주체, 작업 유형, 대상, 그리고 요청이 들어온 HTTP 컨텍스트가 담깁니다.
| 필드 | 설명 |
|---|---|
| 작업 주체 | 작업을 수행한 사용자 또는 API 키 |
| 작업 | engine.created 또는 member.role_changed처럼 타입이 정해진 값 |
| 대상 | 작업이 적용된 엔터티(예: 엔진, 역할, 용어집 항목) |
| 메타데이터 | 관련 엔터티의 ID만 저장 — 이름, 이메일, 콘텐츠 일부는 포함되지 않음 |
| 요청 컨텍스트 | request_id, IP 주소, 사용자 에이전트 — HTTP 요청 수신 시 함께 기록됨 |
| 타임스탬프 | UTC 기준, 누락 구간 탐지를 위한 단조 증가 시퀀스 번호 포함 |
의도적으로 ID만 저장합니다
메타데이터 컬럼에는 사람이 읽을 수 있는 값이 아니라 ID만 저장됩니다. UI는 조회 시점에 현재 이름을 조인하기 때문에, 엔진이나 사용자 이름이 바뀌어도 과거 이력은 다시 쓰이지 않습니다. 또한 감사 레코드가 GDPR 삭제권 요청과 충돌하지 않도록 해줍니다 — 마스킹할 콘텐츠 자체가 없기 때문입니다.
포함되는 작업#
이벤트는 대시보드 필터와 동일한 카테고리로 묶여 표시됩니다.
| 카테고리 | 현재 연결된 작업 |
|---|---|
| 조직 | org.created, org.settings_updated, org.ownership_transferred, org.deleted |
| 멤버 | member.invited, member.removed, member.role_changed |
| 역할 | role.created, role.updated, role.deleted |
| 엔진 | engine.created, engine.updated, engine.deleted |
| API 키 | api_key.created, api_key.revoked |
| 콘텐츠 | glossary_item.*, instruction.*, brand_voice.* (단일 작업만) |
로그에 접근하기#
조직에 해당 entitlement가 활성화된 경우에만 Organization 사이드바에 감사 로그 항목이 표시됩니다. 페이지 안에서는 다음 기능을 사용할 수 있습니다:
- 필터 가능한 목록 — 작업 주체, 작업 카테고리, 대상 유형, 날짜 범위로 결과를 좁힐 수 있습니다. 미래 날짜는 선택할 수 없고, 종료일은 항상 시작일보다 빠를 수 없습니다.
- 무한 스크롤 — 최신 이벤트가 먼저 보이며, 스크롤할수록 더 오래된 이벤트가 이어서 로드됩니다.
- 상세 패널 — 아무 행이나 클릭하면 전체 메타데이터, 요청 ID, IP, 사용자 에이전트를 볼 수 있습니다.
- 새로고침 — 현재 필터를 유지한 채 최신 이벤트를 불러옵니다. 필터와 열려 있는 이벤트는 URL에 반영되므로, 어떤 화면이든 그대로 공유할 수 있습니다.
조회 권한#
이 페이지 접근은 두 가지 조건으로 제어됩니다:
- Entitlement — 조직에 audit-logs 기능이 활성화되어 있어야 합니다(Enterprise 플랜).
- 권한 — 조회자의 역할에
org:view_audit_logs권한이 포함되어 있어야 합니다. 기본 제공되는 Full Access 역할에는 이 권한이 포함되어 있으며, Owners는 항상 이 권한을 가집니다.
해당 권한이 없는 멤버에게는 타임라인 대신 "접근 권한 없음" 페이지가 표시됩니다. entitlement가 없는 조직의 멤버에게는 페이월이 표시됩니다.
Enterprise 플랜이 만료되면
감사 로그는 동일한 RBAC 티어 entitlement에 포함됩니다. 과거 이벤트는 데이터베이스에 그대로 남아 있지만 페이지는 숨겨지며, 플랜이 복구될 때까지 읽기 엔드포인트는 403을 반환합니다.
변조 감지#
감사 로그는 단순한 기록이 아닙니다 — 사후에 손대기가 실질적으로 매우 어렵도록 설계되어 있습니다.
- 데이터베이스 수준의 append-only. 테이블을 생성하는 마이그레이션은 API 역할에 대해
REVOKE UPDATE, DELETE, TRUNCATE를 실행합니다. 이후 어떤 코드 경로든 — 버그, 새 엔드포인트, 심지어 SQL 인젝션까지 — 레코드를 바꾸기 전에 Postgres가 먼저 차단합니다. - 단조 증가 시퀀스. 모든 레코드에는 엄격하게 증가하는
seq컬럼이 들어 있습니다. 감사자가 이 시퀀스를 훑어보면 중간에 비는 구간으로 삭제 여부를 감지할 수 있습니다.
이 정도면 SOC 2 스타일의 통제 요건에는 충분합니다. 다만 프로덕션 데이터베이스 자격 증명에 직접 접근할 수 있는 공격자까지 막아주지는 않습니다 — 더 강한 수준의 보호(분리된 owner 역할, WORM 미러)는 요청 시 제공 가능합니다.
보존 기간#
감사 이벤트는 기본적으로 무기한 보존됩니다. Enterprise에서는 보통 1년, 3년, 7년 단위의 맞춤 보존 기간도 설정할 수 있습니다. 컴플라이언스나 보안 설문 대응을 위해 특정 보존 정책이 필요하다면 문의해 주세요.
포함되지 않는 항목#
v1에서 의도적으로 제외한 범위는 다음과 같습니다:
- 트랜잭션 보장 방식이 아닌 best-effort emit. 트랜잭션 보장형 emit은 가까운 로드맵에 올라가 있습니다. 감사 이벤트는 해당 작업이 끝난 뒤 기록되며, 같은 데이터베이스 트랜잭션 안에서 함께 기록되지는 않습니다. 드문 실패 상황에서는 작업은 성공했지만 감사 insert가 실패해, 해당 이벤트 없이 작업만 반영될 수 있습니다.
- 아직 연결되지 않은 작업 유형이 있습니다. 엔진 멤버십 변경, 통합 연결 / 업데이트 / 연결 해제, 모델 설정 수정, 청구 구독 변경, 대량 콘텐츠 작업(CSV 업로드,
createMany/updateMany/deleteMany)은 아직 이벤트를 생성하지 않습니다. 작업 vocabulary는 미리 예약되어 있어, 연결되는 즉시 기존 필터 카테고리 아래에 표시됩니다. - 조회 작업은 감사되지 않습니다. 감사 로그 자체를 보거나, 엔진 요청 로그를 탐색하거나, 용어집을 다운로드해도 이벤트는 생성되지 않습니다. 상태를 변경하는 작업만 기록됩니다.
- 아직 내보내기는 지원하지 않습니다. 감사 데이터는 현재 대시보드에서만 확인할 수 있습니다. CSV 내보내기, SIEM webhook, S3 미러는 로드맵에 있으니 필요하다면 알려주세요.
- 엔진 범위 전용 보기는 없습니다. 조직의 모든 감사 이벤트는 하나의 타임라인에 표시됩니다. 범위를 좁히려면 대상 유형이나 대상 ID로 필터링하세요.
- 실시간 tail은 없습니다. 목록은 필요할 때마다 또는 새로고침을 클릭했을 때 갱신됩니다 — WebSocket 스트림은 제공되지 않습니다.
