> ## 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.

# KMS 감사

> 암호화 키 관리(KMS) 작업의 변조 감지용 해시 체인 기록 — wrap/unwrap/rotate 등 모든 암호화 작업 추적 및 무결성 검증

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

KMS 감사(KMS Audit)는 시스템이 **암호화 키로 수행한 모든 작업**(wrap·unwrap·rotate 등)의 기록입니다.

* 각 기록이 앞 기록과 **해시 체인으로 이어져** 있어, 과거 기록을 한 줄이라도 고치거나 지우면 사슬이 끊어져 **무결성 검증**에서 즉시 드러납니다.
* [일반 감사 로그](/ko/monitoring/audit-logs)가 "누가 어떤 리소스를 바꿨는지"라면, KMS 감사는 "암호화 키에 어떤 작업이 있었는지"를 기록합니다.

<Frame caption="KMS 감사 로그 — 작업/결과 필터, 무결성 검증, 로그 테이블, CSV 내보내기">
  <img src="https://mintcdn.com/cloocus/N40ovjDOvSugfNqc/images/monitoring/kms-audit-main.png?fit=max&auto=format&n=N40ovjDOvSugfNqc&q=85&s=4e55d2239539016ee018fee5f19ec88e" alt="KMS 감사 로그 화면 — 작업/결과 필터, 무결성 검증 버튼, 로그 테이블" width="2880" height="1800" data-path="images/monitoring/kms-audit-main.png" />
</Frame>

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

<Note>
  KMS 감사는 [관리자 › 설정 › 암호화](/ko/admin/settings/encryption)의 KMS 공급자와 짝을 이룹니다.
  기본 공급자인 **로컬 (Fernet)** 환경에서는 공급자 전환(`provider_change`) · 마이그레이션(`migrate`) · CSV 내보내기(`audit_export`)를 실행했을 때만 행이 생깁니다.
  이런 환경에서 `전체: 0`인 것은 정상이며, 암호화 작업이 실제로 일어나지 않았다는 뜻은 아닙니다.
</Note>

***

## 감사 로그 구성

KMS 감사 로그가 **어떤 작업을 기록하는지**, **각 행이 어떤 필드로 구성되는지** 두 단면으로 정리합니다.

<Tabs>
  <Tab title="기록되는 작업">
    기록되는 작업은 사용 중인 KMS 공급자에 따라 다릅니다. `wrap` · `unwrap` · `rotate` · `health_check`는 **Azure Key Vault (엔벨로프)** 공급자에서만 남고, 기본값인 **로컬 (Fernet)** 공급자에서는 기록되지 않습니다.

    | 작업                   | 무슨 작업인가                                                                                        |
    | -------------------- | ---------------------------------------------------------------------------------------------- |
    | **wrap**             | 비밀값을 **암호화해 잠그는** 작업 (Azure Key Vault 공급자 전용)                                                  |
    | **unwrap**           | 잠긴 값을 **다시 풀어 읽는**(복호화) 작업 (Azure Key Vault 공급자 전용)                                            |
    | **rotate**           | 암호화에 쓰는 **열쇠(키)를 새 것으로 교체** (Azure Key Vault 공급자 전용)                                           |
    | **health\_check**    | KMS가 **정상 작동하는지 점검** (Azure Key Vault 공급자 전용)                                                  |
    | **provider\_change** | 암호화 방식(KMS 공급자) **전환** (예: 로컬 ↔ 외부)                                                            |
    | **migrate**          | 예전 방식으로 잠긴 값을 **현재 방식으로 다시 잠금** ([기존 데이터 마이그레이션](/ko/admin/settings/encryption#기존-데이터-마이그레이션)) |
    | **audit\_export**    | KMS 감사 로그 **CSV 내보내기** — 내보내기 행위 자체도 기록                                                        |

    <Note>
      대상 시크릿은 설정 시크릿 · DbSphere 데이터베이스 연결 정보 · 도구 연결 키 · **사용자 API 키** 등 시스템의 **민감한 값**입니다.
      라이선스·기능 토큰은 서명으로 진위가 보장되는 값이라 KMS 암호화 대상에서 의도적으로 제외됩니다.
      암호화되는 값 자체는 기록되지 않으며, "어떤 설정 경로의 값에 어떤 작업이 일어났는지"만 남습니다.
    </Note>
  </Tab>

  <Tab title="로그 항목 구조">
    각 KMS 감사 행은 다음 정보를 포함합니다.

    | 필드           | 설명                                                                                                                                       |
    | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
    | **id**       | 기록 순번 식별자                                                                                                                                |
    | **시간 (UTC)** | 작업 발생 시각 (UTC 기준)                                                                                                                        |
    | **작업**       | 수행된 KMS 작업 (wrap, unwrap, rotate 등)                                                                                                      |
    | **결과**       | 성공은 `OK`, 실패는 `FAIL` 배지로 표시                                                                                                              |
    | **액터**       | 작업을 수행한 주체 유형 — `user`(관리자가 화면에서 직접 실행) · `system`(시스템 내부 암·복호화) · `scheduled`(자동 키 회전). 주체 ID가 있으면 앞 8자리가 함께 표시됩니다 (예: `user:a1b2c3d4`) |
    | **설정 경로**    | 작업 대상이 된 설정값의 경로. `rotate`·`migrate`·`audit_export` 행에는 대신 작업 요약(내보내기 사유·건수, 회전 전/후 키, 마이그레이션 대상별 건수)이 표시됩니다                             |
    | **IP**       | 요청 출처 IP                                                                                                                                 |
    | **오류**       | 실패 시 오류 코드 (예: `AAD_MISMATCH`) — 성공 시 `-`                                                                                                |

    <Tip>
      시각이 **UTC**로 표시됩니다. 한국 시간(KST)으로 환산하려면 +9시간 하세요.
    </Tip>
  </Tab>
</Tabs>

***

## 무결성 검증

**무결성 검증** 버튼을 누르면 기록을 순서대로 따라가며 **사슬이 끊긴 곳은 없는지** 확인합니다. 한 번에 최대 **10만 행**까지 검사하며, 실제로 검사한 행 수는 결과 메시지에 표시됩니다.

<Steps>
  <Step title="검증 실행">
    화면 상단의 **무결성 검증** 버튼을 클릭합니다.
  </Step>

  <Step title="결과 확인">
    사슬이 온전하면 `체인 OK (N개 행 검사)`처럼 검사한 행 수와 함께 정상 메시지가 표시됩니다.
    누군가 중간 기록을 고치거나 지웠다면 그 지점에서 사슬이 끊겨 검증이 실패합니다.
  </Step>
</Steps>

<Warning>
  무결성 검증이 실패한다는 것은 감사 기록이 변조되었을 가능성을 의미합니다.
  컴플라이언스·보안 사고 조사 시 가장 먼저 확인해야 하는 항목입니다.
</Warning>

<Note>
  감사 기록이 10만 행을 넘는 환경에서는 결과 메시지의 `체인 OK (N개 행 검사)`의 N과 화면 하단 `전체: N`을 비교해 전량이 검사되었는지 확인하세요.
</Note>

***

## 로그 조회

### 필터 옵션

| 필터     | 설명                                                              |
| ------ | --------------------------------------------------------------- |
| **기간** | 최근 1시간 · 6시간 · 1일 · 7일 · 30일 · 전체 · 사용자 정의 (기본 **최근 7일**)       |
| **작업** | 특정 KMS 작업만 필터 (wrap·unwrap·rotate 등, 위 [기록되는 작업](#감사-로그-구성) 참고) |
| **결과** | `전체` / `성공만` / `실패만`                                            |

감사 로그 탭의 기본값(최근 1시간)과 다르니, 오래된 기록을 찾을 때는 기간을 먼저 넓히세요.

행이 25건을 넘으면 하단에 페이지 번호 버튼과 좌·우 화살표 버튼이 나타나며, 이를 눌러 페이지를 이동합니다.

* 화면 하단에 `전체: N`으로 현재 필터에 해당하는 총 건수가 표시됩니다. 현재 페이지는 페이지 번호 버튼 중 강조 표시된 번호로 확인합니다.

***

## CSV 내보내기

감사 기록을 외부 보관·분석용으로 내보낼 수 있습니다.

* 일반 다운로드와 달리 **내보내기 사유를 반드시 입력**해야 합니다.

<Steps>
  <Step title="사유 입력">
    하단 **내보내기 사유 (감사 체인에 기록됨)** 입력란에 사유를 적습니다. (예: `분기별 컴플라이언스 검토`)
  </Step>

  <Step title="CSV 내보내기">
    **CSV 내보내기** 버튼을 누르면 현재 필터에 해당하는 기록이 CSV로 다운로드됩니다.
    한 번에 최대 **10만 행**까지 내보내며, 그 이상은 기간을 나눠 여러 번 내보내세요.
  </Step>
</Steps>

<Note>
  내보내기 행위는 그 자체가 `audit_export` 작업으로 **사슬에 새 기록으로 추가**됩니다.
  입력한 사유와 건수는 그 행의 **설정 경로** 칸에 `reason=사유|rows=건수` 형태로 표시되므로, "누가, 언제, 어떤 사유로 감사 로그를 추출했는지"까지 확인할 수 있습니다.
</Note>

***

## 일반 감사 로그와의 차이

KMS 감사는 [감사 로그](/ko/monitoring/audit-logs)와 별개의 탭입니다.

* 추적 대상과 보장 방식이 다릅니다.

| 구분         | 감사 로그                          | KMS 감사                                     |
| ---------- | ------------------------------ | ------------------------------------------ |
| **추적 대상**  | 사용자·리소스 활동 (CRUD, 로그인, 권한 변경)  | 암호화 키 작업 (wrap/unwrap/rotate 등)            |
| **주 사용자**  | 보안 담당자, 컴플라이언스                 | 보안 담당자, 인프라 관리자                            |
| **무결성 보장** | 별도 무결성 장치 없음 (보존 정책에 따라 정리 가능) | 기록끼리 **사슬로 묶여 변조 시 탐지 가능** + **무결성 검증** 버튼 |
| **내보내기**   | 필터 기반 조회                       | 사유 입력 후 CSV (내보내기도 사슬에 기록)                 |

***

## 활용 사례

<Accordion title="키 회전 이력 추적">
  1. **작업** 필터에서 `rotate`를 선택합니다
  2. 기간을 지정해 키 회전이 정책 주기대로 수행되었는지 확인합니다
  3. 실패한 회전이 있는지 **결과** 필터를 `실패만`으로 좁혀 점검합니다
</Accordion>

<Accordion title="암호화 작업 실패 진단">
  1. **결과** 필터를 `실패만`으로 설정합니다
  2. 실패한 작업의 **설정 경로**·**오류** 컬럼으로 어떤 시크릿에서 문제가 났는지 파악합니다 — 오류 칸은 상세 설명이 아니라 짧은 코드이므로, 자세한 원인은 서버 로그를 함께 확인하세요
  3. [암호화 설정](/ko/admin/settings/encryption)에서 공급자 **연결 테스트**로 KMS 상태를 확인합니다
</Accordion>

<Accordion title="컴플라이언스 증빙 확보">
  1. **무결성 검증**으로 사슬이 온전한지 먼저 확인합니다
  2. 보고 대상 기간으로 필터링합니다
  3. **내보내기 사유**에 검토 목적을 명시하고 CSV로 내보냅니다
  4. 내보내기 기록(`audit_export`)이 사슬에 남았는지 확인하여 추출 이력까지 증빙합니다
</Accordion>

***

## 모범 사례

* **정기 무결성 검증**: 컴플라이언스 검토 시 가장 먼저 **무결성 검증**을 실행해 사슬이 온전한지 확인하세요
* **실패 모니터링**: `실패만` 필터로 암호화 작업 오류를 주기적으로 점검하세요 — KMS 연결 문제의 조기 신호입니다
* **사유 명확화**: CSV 내보내기 사유는 추후 감사 추적에 활용되므로 구체적으로 작성하세요
* **공급자 전환 검토**: `provider_change`·`migrate` 기록으로 암호화 공급자 전환과 재암호화가 의도대로 완료되었는지 확인하세요