> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 감사 로그

> 사용자 활동 기록을 통한 보안 감사 및 컴플라이언스 — 인증, 리소스 변경, 권한 변경 추적

<Info>관리자 › 모니터링 › 감사 로그</Info>

감사 로그(Audit Log)는 시스템에서 발생하는 **모든 주요 활동을 시간순으로 기록**합니다.

* 누가, 언제, 무엇을, 어떻게 변경했는지 투명하게 추적하여 보안 감사와 컴플라이언스 요구사항을 충족합니다.

<Frame caption="감사 로그 메인 화면 — 필터 영역, 로그 테이블">
  <img src="https://mintcdn.com/cloocus/Nim6rqpdwJuim_F0/images/monitoring/audit-logs-main.png?fit=max&auto=format&n=Nim6rqpdwJuim_F0&q=85&s=24dc65743f83674a4d6cac024ba38d9b" alt="감사 로그 메인 화면 — 필터 영역, 로그 테이블" width="1436" height="983" data-path="images/monitoring/audit-logs-main.png" />
</Frame>

<Note>
  감사 로그는 라이선스 기능입니다. `audit_log` 피처가 활성화된 라이선스가 필요합니다.
</Note>

***

## 기록되는 활동

감사 로그는 시스템의 주요 변경·접근을 **액션**과 **리소스** 단위로 남깁니다. 전체 목록은 탭에서 확인하세요.

<Tabs>
  <Tab title="액션 유형">
    **핵심 액션**

    | 액션                                        | 설명                  |
    | ----------------------------------------- | ------------------- |
    | **CREATE**                                | 리소스 생성              |
    | **UPDATE**                                | 리소스 수정              |
    | **DELETE**                                | 리소스 삭제              |
    | **ACCESS\_CONTROL\_CHANGE**               | 리소스 접근 권한 변경        |
    | **PERMISSION\_CHANGE**                    | 그룹 기능 권한 변경         |
    | **MEMBER\_ADD**                           | 그룹/조직 멤버 추가         |
    | **MEMBER\_REMOVE**                        | 그룹/조직 멤버 제거         |
    | **ROLE\_CHANGE**                          | 사용자 역할 변경           |
    | **SETTINGS\_CHANGE**                      | 시스템 설정 변경           |
    | **LOGIN / LOGOUT / LOGIN\_FAILED**        | 로그인 · 로그아웃 · 로그인 실패 |
    | **API\_KEY\_CREATED / API\_KEY\_DELETED** | API 키 발급 · 폐기       |
    | **GUEST\_SESSION**                        | 임베드 위젯 게스트 세션 시작    |

    **통합 기능 액션** (Google Workspace · DbSphere)

    | 액션                          | 설명                 |
    | --------------------------- | ------------------ |
    | **GMAIL\_SEND**             | Gmail 발송           |
    | **CALENDAR\_CREATE\_EVENT** | 캘린더 일정 생성          |
    | **DRIVE\_CREATE\_DOC**      | Google Drive 문서 생성 |
    | **SQL\_FAILED**             | DbSphere SQL 실행 실패 |

    <Note>
      통합 기능 사용도 감사에 남으며, 실패 이벤트는 `*_FAILED` 형태(예: `DRIVE_CREATE_DOC_FAILED`)로 기록됩니다.
    </Note>
  </Tab>

  <Tab title="리소스 유형 (자동/명시적)">
    | 리소스                      | 자동 추적 | 설명                                                |
    | ------------------------ | :---: | ------------------------------------------------- |
    | **model**                |   ✅   | AI 모델                                             |
    | **knowledge**            |   ✅   | 지식 기반                                             |
    | **dbsphere**             |   ✅   | 데이터베이스 연결                                         |
    | **glossary**             |   ✅   | 용어집                                               |
    | **prompt**               |   ✅   | 프롬프트                                              |
    | **tool**                 |   ✅   | 도구                                                |
    | **user**                 |   ✅   | 사용자                                               |
    | **organization**         |   ✅   | 조직                                                |
    | **organizational\_unit** |   ✅   | 조직 단위                                             |
    | **group**                |   ✅   | 그룹                                                |
    | **agent**                |   ⚠️  | 에이전트 — 명시적 로깅 호출만 기록 (자동 추적 미지원)                  |
    | **chat**                 |   ⚠️  | 채팅 — 명시적 로깅 호출만 기록 (자동 추적 미지원)                    |
    | **admin\_settings**      |   ⚠️  | 관리자 설정 변경 — `SETTINGS_CHANGE` 액션과 함께 명시적 로깅       |
    | **auth**                 |   ⚠️  | 인증 이벤트 — LOGIN/LOGOUT/LOGIN\_FAILED는 자동, 그 외는 명시적 |
    | **memory**               |   ⚠️  | 메모리 — 명시적 로깅 호출만 기록                               |
    | **embed\_widget**        |   ⚠️  | 임베드 위젯 게스트 세션 — `GUEST_SESSION` 액션으로 자동           |
    | **knowledge\_graph**     |   ⚠️  | 지식 그래프 — 명시적 로깅 호출만 기록                            |
    | **gmail\_message**       |   ⚠️  | Gmail 발송 (Google Workspace)                       |
    | **calendar\_event**      |   ⚠️  | 캘린더 일정 (Google Workspace)                         |
    | **drive\_document**      |   ⚠️  | Google Drive 문서 (Google Workspace)                |

    <Note>
      ✅ 표시된 리소스는 DB 변경이 일어나면 **자동으로** 감사 로그에 기록됩니다.
      ⚠️ 표시된 리소스는 **백엔드가 명시적으로 로깅을 호출한 지점에서만** 기록됩니다 — 인증(LOGIN/LOGOUT/LOGIN\_FAILED), 게스트 세션(GUEST\_SESSION), 설정 변경(SETTINGS\_CHANGE) 등 일부 이벤트는 자동이지만, agent/chat/memory의 일반 CRUD는 자동 추적되지 않습니다.

      조회(READ)는 별도로 로깅되지 않습니다 (성능 영향 고려).
    </Note>
  </Tab>
</Tabs>

***

## 로그 항목 구조

각 감사 로그 항목은 다음 정보를 포함합니다.

<Accordion title="로그 항목 전체 필드 (11개)" icon="list">
  | 필드           | 설명                        |
  | ------------ | ------------------------- |
  | **타임스탬프**    | 이벤트 발생 시간                 |
  | **사용자**      | 활동 수행자 (이름, 이메일)          |
  | **액션**       | 수행된 작업 (CREATE, UPDATE 등) |
  | **리소스 유형**   | 대상 리소스 종류                 |
  | **리소스 ID**   | 대상 리소스 식별자                |
  | **리소스 이름**   | 대상 리소스 이름                 |
  | **IP**       | 요청 출처 IP                  |
  | **변경 전 상태**  | 변경 이전 값 (JSON)            |
  | **변경 후 상태**  | 변경 이후 값 (JSON)            |
  | **변경된 필드**   | 변경된 필드 목록                 |
  | **권한 변경 상세** | 접근 권한 변경 내역 (해당 시)        |
</Accordion>

***

## 로그 조회

### 필터 옵션

| 필터         | 설명                              |
| ---------- | ------------------------------- |
| **기간**     | 시작/종료 날짜 범위 (Unix timestamp)    |
| **리소스 유형** | model, knowledge, user 등        |
| **액션**     | CREATE, UPDATE, DELETE, LOGIN 등 |
| **사용자**    | 사용자 이름으로 검색                     |
| **조직**     | 특정 조직 ID                        |
| **리소스 ID** | 특정 리소스의 변경 이력 추적                |

## 로그 상세 보기

로그 항목을 클릭하면 상세 정보를 모달로 확인할 수 있습니다.

<Frame caption="감사 로그 상세 — 변경 전/후, 요청 경로, 메타데이터">
  <img src="https://mintcdn.com/cloocus/Nim6rqpdwJuim_F0/images/monitoring/audit-logs-detail.png?fit=max&auto=format&n=Nim6rqpdwJuim_F0&q=85&s=a691f4d8a37f956e911b2a048efef67b" alt="감사 로그 상세 모달" width="1436" height="983" data-path="images/monitoring/audit-logs-detail.png" />
</Frame>

**표시 정보:**

* 전체 요청 메타데이터
* 변경 전/후 상태 비교 (JSON diff)
* 변경된 필드 하이라이트
* 권한 변경 시 이전/이후 접근 제어 상세

***

## 통계

감사 로그 화면 상단에는 **전체 감사 로그 건수**가 표시됩니다.

* 리소스 유형·액션 필터를 조합하면 아래 관점으로 활동 분포를 파악할 수 있습니다.

| 통계             | 설명                              |
| -------------- | ------------------------------- |
| **액션별 분포**     | CREATE, UPDATE, DELETE 등 액션별 건수 |
| **리소스 유형별 분포** | model, user, chat 등 리소스별 건수     |
| **총 건수**       | 기간 내 전체 감사 로그 수                 |

***

## 활용 사례

<Accordion title="보안 사고 조사">
  1. **감사 로그** 탭에서 사고 발생 시점의 기간을 설정합니다
  2. 관련 사용자 또는 리소스 유형으로 필터링합니다
  3. 활동 이력을 시간순으로 확인합니다
  4. 상세 보기에서 변경 내용을 검증합니다
  5. 상세 로그를 증거로 보존합니다
</Accordion>

<Accordion title="컴플라이언스 감사">
  1. 정기적으로(월간/분기) 감사 로그 통계를 확인합니다
  2. 권한 변경 로그를 검토하여 비인가 접근을 확인합니다
  3. 설정 변경 이력을 추적하여 정책 준수 여부를 확인합니다
  4. 감사 로그를 기반으로 감사 보고서를 작성합니다
</Accordion>

<Accordion title="이상 활동 탐지">
  * 비업무 시간 대량 리소스 삭제
  * 단기간 반복적인 권한 변경
  * 비정상적인 로그인 실패 패턴
  * 관리자 권한 에스컬레이션
</Accordion>

***

## 모범 사례

<Warning>
  감사 로그는 시스템이 자동으로 기록합니다. 감사 로그 자체를 삭제하거나 수정하는 기능은 제공되지 않으며, 이는 기록의 무결성을 보장하기 위함입니다.
</Warning>

* **정기 검토**: 최소 월 1회 감사 로그를 검토하여 이상 패턴을 탐지하세요
* **장기 보관**: 컴플라이언스 요구사항에 따라 최소 1년 이상 보관을 권장합니다
* **백업**: 정기적으로 감사 로그 데이터를 외부 저장소에 백업하세요
* **알림 연동**: 중요 이벤트(권한 변경, 대량 삭제)에 대한 알림을 구성하세요