평가 실행
컴플라이언스 평가(Assessment)는 특정 프레임워크를 기준으로 현재 시스템의 규정 준수 상태를 검사하는 과정입니다. 자동 검사와 수동 검토를 병행하여 종합적인 준수율을 산정합니다.
평가 절차
- ⚙ 관리 콘솔 → 접근 제어 & 보안 → 컴플라이언스 메뉴에서 프레임워크 카드를 확인합니다.
- 각 프레임워크 카드 우측의 평가 실행 버튼을 클릭합니다.
- 평가가 생성되고 자동 검사가 즉시 시작됩니다 (PII 탐지, 보존 정책, 접근 통제 등).
- 자동 검사 완료 후 준수율이 대시보드에 반영됩니다.
manual타입 항목은 관리자가 직접 결과를 입력합니다.- 평가 리포트를 조회하여 감사에 활용합니다.
동작 원리
평가 실행 버튼은 두 개의 API를 순차 호출합니다.
[UI] 평가 실행 클릭
│
├─① POST /api/v1/compliance/assessments
│ └─ ComplianceAssessment 레코드 1개 생성
│ + 프레임워크의 모든 통제 항목에 대해
│ ComplianceCheckResult(status="not_assessed") 일괄 INSERT
│
└─② POST /api/v1/compliance/assessments/{id}/run
├─ check_type="auto" 이고 auto_check_key 가 있는 항목만 필터링
├─ asyncio.gather 로 자동 점검 함수 병렬 실행
├─ 각 결과의 status 를 compliant / non_compliant / manual_review 로 갱신
└─ 점수·상태 재계산 후 commit
자동 점검 함수는 gend_api.services.compliance_engine 모듈의 @register("key") 데코레이터로 등록되어 있으며, 각 함수는 DB 상태 또는 settings 값을 조회해 (passed: bool, evidence: dict) 를 반환합니다.
자동 점검 항목 (auto_check_key)
시드 데이터에 등록된 자동 점검 키와 통과 조건입니다. 미등록 키는 manual_review 로 마킹되어 관리자 입력을 기다립니다.
| auto_check_key | 통과 조건 | 검사 대상 |
|---|---|---|
pii_masking_applied | PIIColumnRegistry 에 confirmed=true 인 컬럼이 1개 이상 | PII 컬럼 식별·확정 여부 |
access_control_exists | AccessPolicy.enabled=true 인 정책이 1개 이상 | 접근 통제 정책 활성화 |
encryption_enabled | settings.vault_enabled == True | Vault 암호화 활성화 |
data_retention_policy | RetentionPolicy.enabled=true 인 정책이 1개 이상 | 데이터 보존 정책 |
rbac_configured | settings.auth_enabled + role 기반 AccessPolicy 1개 이상 | 인증 + 역할 기반 정책 |
audit_log_retention | settings.opensearch_url 가 설정됨 | 감사 로그 저장소 |
자동 점검 함수에서 예외가 발생하면 해당 항목은 non_compliant 로 기록되고 evidence_json.error 에 사유가 남습니다.
평가 결과 상태 (check result status)
| 상태 | 점수 산식 반영 | 의미 |
|---|---|---|
compliant | 분자(O) / 분모(O) | 자동/수동 점검 모두 통과 |
non_compliant | 분자(X) / 분모(O) | 점검 실패 — 미준수 |
not_applicable | 분자(X) / 분모(X) | 해당 시스템에 적용되지 않음 |
manual_review | 분자(X) / 분모(O) | 수동 확인 필요 — 자동 점수에서는 미충족으로 집계 |
not_assessed | 분자(X) / 분모(O) | 아직 평가 안 됨 (초기 상태) |
점수 산식
assessable = total_items − not_applicable_items
compliance_score (%) = compliant_items / assessable × 100
not_applicable만 분모에서 제외됩니다.manual_review와not_assessed는 분모에 포함되어 점수를 낮춥니다.- 따라서 자동 점검만 실행하면 수동 항목 수만큼 점수가 떨어진 채로 표시됩니다. 100% 달성하려면 수동 항목까지 관리자가 결과를 입력해야 합니다 (아래 PATCH 엔드포인트 참조).
Assessment status 판정
평가 전체 상태는 검사 결과의 분포로 결정됩니다.
| Assessment status | 판정 조건 | UI 라벨 / 배지 색 | DB 저장 |
|---|---|---|---|
completed | not_assessed + manual_review 가 0건 | 완료 / 초록 | ✅ |
in_progress | 일부만 평가됨 (대부분의 자동 점검만 끝난 상태) | 진행 중 / 파랑 | ✅ |
draft | 평가는 생성됐지만 어떤 점검도 안 끝남 | 초안 / 회색 | ✅ |
not_assessed | 평가 이력 없음 (해당 프레임워크에 ComplianceAssessment row 가 0건) | 미평가 / 회색 | ❌ — 대시보드에서만 사용하는 합성 상태 |
마지막 not_assessed 는 ComplianceAssessment.status 컬럼에 저장되지 않는 대시보드 표현용 합성 상태입니다. GET /dashboard 응답에서 latest_status="not_assessed" 로 노출됩니다. 실제 DB enum 은 위 3 종 (draft/in_progress/completed) 만 사용합니다.
자주 묻는 질문
왜 점수가 40~50% 에서 멈춰 있나요?
시드된 프레임워크의 통제 항목은 자동 점검(auto) + 수동 점검(manual) 이 섞여 있습니다. 평가 실행 버튼은 auto 항목만 즉시 평가하므로, 수동 항목은 not_assessed 로 남아 점수를 끌어내립니다.
예) 10개 항목 중 자동 4건이 모두 compliant, 수동 6건이 not_assessed 라면:
score = 4 / (10 − 0) × 100 = 40%
status = in_progress (not_assessed > 0 이므로)
이는 화면의 40% / 진행 중 / 4/10 준수 카드와 일치합니다.
100% 만들려면 어떻게 하나요?
수동 항목을 PATCH /api/v1/compliance/assessments/{id}/results/{result_id} 로 compliant (또는 시스템에 무관하면 not_applicable) 로 입력하세요. UI 에서 항목별 입력 화면은 평가 상세 조회 페이지에 있습니다.
"평가 실행" 을 여러 번 누르면 어떻게 되나요?
매번 새로운 ComplianceAssessment 레코드가 생성됩니다 (이력 누적). 대시보드의 카드는 가장 최근 평가 의 점수만 보여 주고, "총 평가 27" 카운터는 전체 이력 개수입니다.
API 엔드포인트
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/compliance/assessments | 평가 생성 (모든 결과를 not_assessed 로 초기화) |
| GET | /api/v1/compliance/assessments | 평가 목록 조회 |
| GET | /api/v1/compliance/assessments/{id} | 평가 상세 + 항목별 결과 조회 |
| POST | /api/v1/compliance/assessments/{id}/run | 자동 점검 실행 (asyncio.gather 병렬) |
| PATCH | /api/v1/compliance/assessments/{id}/results/{result_id} | 수동 결과 입력 — 점수 재계산 트리거 |
| GET | /api/v1/compliance/assessments/{id}/report | 평가 리포트 조회 |
POST/PATCH 계열은 require_admin 의존성으로 관리자 권한이 필요합니다.
관련 문서
- 컴플라이언스 개요 — 대시보드 화면의 숫자·색상 의미
- 프레임워크 관리
- 변경 이력 (ChangeLog)