봉인 증거와 공식 검증
판정이 어떤 프롬프트와 사실로 만들어졌는지를 나중에 그대로 다시 보는 방법을 설명합니다. 무엇을 언제 봉인하는지, 바뀌지 않았음을 어떻게 확인하는지, 관리 화면에서 증거를 보고 공식 검증 · 재생을 돌리는 방법, 보관 기간과 설정을 다룹니다.
한눈에 보기
AI 모델이 판정을 내리면 Contexa는 모델에 보낸 그대로의 프롬프트와 그 재료(요청 사실, 표준 맥락, 행위 기준선, 과거 판정 기록), 그리고 판정 결과를 한 묶음으로 만들어 해시와 서명으로 봉인합니다. 이 묶음(증거 묶음)을 봉인 증거라고 합니다. 봉인은 판정을 바꾸지 않고, 판정이 끝난 뒤 따로 저장됩니다.
- 프롬프트 포착판정 프롬프트가 만들어지는 순간 모델이 받을 글과 원본을 잡아 둡니다
- 봉인판정 뒤 일곱 구역을 한 묶음으로 만들고 SHA-256 해시를 계산합니다. 서명 키가 있으면 HMAC-SHA256으로 서명하고 앞 증거 묶음의 해시와 연결합니다
- 저장Contexa DB의
ctxa_sealed_evidence_package표에 넣기만 합니다(기본 90일 보관)
저장된 증거 묶음으로 하는 일
- 자동 검수30초마다 새 증거 묶음을 사실과 대조
- 공식 검증지표 12개로 규칙 평가(모델 호출 없음)
- 재생봉인된 입력으로 모델에 다시 묻기
무엇을 봉인하나
증거 묶음 하나에는 일곱 구역이 들어갑니다.
실행 정보 가운데 512자를 넘는 글은 길이와 해시만 남깁니다.
언제 봉인하나
- AI 모델이 판정한 경우만 봉인합니다. 모델을 부르지 않은 판정은 모델이 받은 프롬프트가 없으므로 봉인하지 않습니다.
- 사용자 ID가 없는 요청, 실패한 처리,
/actuator·/health·/.well-known/·/sse/경로는 봉인하지 않습니다. - 표본: 서버가 뜬 직후의 판정 1,000건은 모두 봉인하고, 그 밖에는 1%만 봉인합니다(
contexa.pqa.oss.sealed-evidence.full-capture-after-change,sample-percent). 판정이 쓰는 버전이 바뀌면(표지를 옮김, 되돌림, 설정) 그 뒤 1,000건도 모두 봉인합니다. 버전은 이름과 내용 해시로 가립니다. 먼저 적용이나 함께 시험으로 도는 버전은 자기 창을 따로 가져, 그 버전의 판정을 처음 봉인할 때부터 1,000건을 모두 봉인하고, 판정에 사용 중인 버전의 창을 다시 열지 않습니다. 이 수는 서버(노드)마다 따로 셉니다. - 봉인은 판정 처리 순서에서 집행(55) 다음, 감사(60) 앞(56)에 있지만, 증거 묶음을 조립 · 저장하는 일은 별도 스레드에서 합니다. 그 스레드가 밀리면 넘친 증거 묶음은 버리고, 판정에는 영향을 주지 않습니다.
- 포착한 프롬프트는 판정이 끝나 봉인될 때까지 최대 10분(
snapshot-ttl) 기다립니다.
바뀌지 않았음을 확인하기
증거 묶음의 해시는 일곱 구역, 프롬프트 해시들, 판 번호 등을 SHA-256으로 계산한 값입니다. 서명 키를 넣으면 증거 묶음은 판 3이 되어 테넌트 · 사용자 · 봉인 시각 · 앞 증거 묶음의 해시까지 해시에 들어가고, HMAC-SHA256으로 서명됩니다.
| 확인 결과 | 뜻 |
|---|---|
VERIFIED | 다시 계산한 해시가 같고, 판 3이면 서명까지 맞습니다. |
MISMATCH | 다시 계산한 해시가 다릅니다. 저장 뒤 내용이 바뀌었습니다. 직전 묶음이 보존 기간으로 설명되지 않게 없는 경우(LINK_BROKEN)도 여기에 속합니다. |
UNVERIFIABLE | 해시나 프롬프트 해시가 비었거나, 서명을 확인할 키가 없습니다. |
자동 검수의 SEAL_INTEGRITY 검사와 공식 검증이 이 확인을 합니다.
서명 키 넣기
contexa:
security:
evidence:
signing:
keys:
k2026: ${CONTEXA_EVIDENCE_KEY} # Base64, 32바이트 이상
active-key-id: k2026 # 키가 둘 이상이면 필수
- 키를 넣지 않으면 시작할 때 임시 키를 만들고 WARN 로그를 남깁니다. 임시 키로 한 서명은 재시작 뒤 확인할 수 없습니다(
UNVERIFIABLE). - 키를 바꿀 때는 물러난 키를 목록에 남겨 두어야 옛 서명을 확인할 수 있습니다. 키가 둘 이상인데
active-key-id가 없거나 목록에 없으면 시작하지 않습니다. - 판정 감사 기록(
ctxa_audit_log)도 같은 서명기로 연결 · 서명되며, 관리 콘솔의 보안 이벤트 기록이 기록마다 확인 결과를 보여 줍니다. 증거 묶음의 확인 결과는 보안 이벤트 기록이 아니라 검수 · 공식 검증 화면에서 봅니다. - 증거 묶음은 앞 증거 묶음의 해시를 담고, 묶음 하나를 확인할 때 직전 묶음을 찾아 봅니다. 직전 묶음이 없는데 보존 기간으로 설명되지 않으면
MISMATCH(LINK_BROKEN)입니다. 사슬 전체를 따라가며 확인하는 기능은 없습니다.
관리 화면에서 증거 보기
관리 콘솔(관리자 권한)에서 봅니다.
| 화면 · API | 하는 일 |
|---|---|
메뉴 "공식검사"/contexa/admin/prompt-quality/runtime-evidence | 증거 묶음을 찾고 하나를 열어 봅니다. |
GET /contexa/admin/api/prompt-quality/runtime-evidence/search | 증거 묶음 검색(packageId, tenantId, userId, resourceUrl, resourceId, httpMethod, from, to, page, size) |
GET /contexa/admin/api/prompt-quality/runtime-evidence/{packageId} | 증거 묶음 하나(요약, 프롬프트 수집 여부, 미리보기, 봉인 내용) |
메뉴 "봉인 프롬프트"/contexa/admin/prompt-inspection/packages/{packageId} | 증거 묶음 하나와 검수 결과. "버전으로 재생" 구역이 있습니다. |
공식 검증
공식 검증은 증거 묶음 하나를 골라 그 판정의 프롬프트가 판단에 필요한 재료를 제대로 담았는지를 지표 12개로 평가합니다. 평가는 규칙으로 하며 AI 모델을 부르지 않습니다. 시작할 때 증거 묶음의 무결성을 먼저 확인하고, 봉인된 표준 맥락으로 프롬프트의 맥락 구역을 다시 그려 봉인 원본과 같은지 대조합니다(결정적 재생).
| 지표 | 무엇을 보나 |
|---|---|
EIR | 현재 요청의 사용자 · 인증 · 권한 · 리소스 · 행위가 하나의 보안 사건으로 연결되는가 |
CCR | 판단에 필요한 정보와 부족한 정보를 구분할 수 있는가 |
CCSR | 입력 안에서 같은 뜻의 값이 서로 충돌하지 않는가 |
PFR | 공격 탐지에 필요한 판단 재료를 빠짐없이 전달하는가 |
MTR | 입력 기록 · 해시 · 계약 버전을 추적할 수 있는가 |
COR | RAG와 외부 맥락이 지시문이나 권한 밖 근거로 섞이지 않는가 |
RAP | RAG 근거가 권한 범위 안에서만 쓰이고 안전하게 들어가는가 |
RPI | 재검증 · 이전 라운드 정보가 현재 판단을 오염시키지 않는가 |
BMA | 기준선의 신뢰 수준과 한계를 알고 판단할 수 있는가 |
USNS | 사용자 기준선과 다른 미세한 변화 신호를 볼 수 있는가 |
BSR | 세션 흐름 · 행동 변화가 정상 예외인지 공격 징후인지 판단할 수 있는가 |
PRE | 검사 대상이 실제 보호 리소스인가 |
공식 검증 돌리기
| API | 하는 일 |
|---|---|
POST /contexa/admin/api/prompt-quality/verification/runtime-runs?packageId=... | 공식 검증을 시작합니다. |
GET .../verification/runtime-runs/package/{packageId}/execution-status | 진행 상태 |
GET .../verification/runtime-runs/package/{packageId} | 결과(/summary, /failure-details 등 하위 경로 있음) |
POST .../verification/runtime-runs/package/{packageId}/reverify | 다시 검증 |
한 증거 묶음의 검증이 15분 동안 진행되지 않으면 다음 요청이 그 실행을 실패로 처리하고 다시 돌릴 수 있게 합니다(contexa.pqa.official-verification.stale-execution-timeout).
재생: 봉인된 입력으로 다시 묻기
재생은 봉인된 입력(요청 사실, 인증 상태, 기준선 요약, 과거 기록, 표준 맥락)으로 같은 판정을 다시 물어 봅니다. 새 프롬프트 버전을 쓰기 전에 최근 판정으로 지금 버전과 비교하려면 버전 화면의 시험 판정을 씁니다(시험 판정).
- "봉인 프롬프트" 상세 화면의 "버전으로 재생"에서 버전과 2차 분석 모델을 고르고 확인 창을 거쳐 실행합니다. 목록에는 숨기지 않은 보안 판정 버전이 새것부터 나옵니다.
- API:
POST /contexa/admin/api/sealed-decisions/{requestId}/replay또는POST /contexa/admin/api/sealed-decisions/packages/{packageId}/replay. 본문{"bundleVersion", "secondPassModels", "userBaseline", "organizationBaseline"}, 2차 분석 모델은 최대 3개입니다. 경로의{requestId}는 봉인된 판정의 요청(상관) ID입니다. 재생이 받는 이름 목록은GET /contexa/admin/api/sealed-decisions/replay-bundles입니다. - 1차 분석을 한 번 묻고, 답이 ESCALATE면 고른 모델마다 2차 분석을 묻습니다. 1차가 과거 기록을 읽지 못한 상태였으면 2차는 묻지 않습니다.
- AI 모델을 실제로 부르므로 비용이 듭니다. 결과는 적용 · 학습 · 봉인하지 않고, 감사 기록
SEALED_DECISION_REPLAYED만 남깁니다. 시간 한도는 3분입니다. - 그 요청 ID · 증거 묶음의 봉인 판정이 없으면 404, 목록에 없는 이름이거나 요청이 잘못되면 400, 판정 파이프라인이 없으면 503입니다.
보관
- 증거 묶음은 봉인 시각부터 90일(
contexa.pqa.oss.sealed-evidence.retention.period) 뒤 만료되고, 매일 03:30에 지웁니다. - 마지막 검수 결과가 PASS 또는 NOT_APPLICABLE이고 공식 검증에 쓰이지 않은 증거 묶음은 30일(
retention.clean-period) 뒤 지웁니다.
설정
| 설정 | 기본값 | 뜻 | 언제 바꾸나 |
|---|---|---|---|
contexa.security.evidence.signing.keys | 없음(임시 키 + WARN 로그) | 키 ID → Base64 비밀값(32바이트 이상) | 운영에서는 반드시(임시 키 서명은 재시작 뒤 확인할 수 없음) |
contexa.security.evidence.signing.active-key-id | 없음(키가 하나면 그 키) | 새 서명에 쓸 키 | 키를 바꿀 때 |
contexa.pqa.oss.sealed-evidence.capture-enabled | true | 봉인 켜기 | 봉인을 끌 때 |
contexa.pqa.oss.sealed-evidence.sample-percent | 1 | 평소 봉인 비율(1~100) | 평소 봉인을 늘리거나 줄일 때(저장 용량과 맞바꿈) |
contexa.pqa.oss.sealed-evidence.full-capture-after-change | 1000 | 서버가 뜬 뒤와 판정이 쓰는 버전이 바뀐 뒤 모두 봉인할 판정 수(노드별). 먼저 적용 · 함께 시험 버전은 자기 창을 따로 가짐 | 뜬 뒤나 버전을 바꾼 뒤의 판정을 더 많이 · 적게 볼 때 |
contexa.pqa.oss.sealed-evidence.snapshot-ttl | 10m | 포착한 프롬프트가 봉인을 기다리는 최대 시간 | 판정이 10분 넘게 걸릴 때 |
contexa.pqa.oss.sealed-evidence.max-pending-snapshotscontexa.pqa.oss.sealed-evidence.max-completed-snapshots | 1000 / 1000 | 메모리에 잡아 두는 포착 수 상한 | 판정이 몰려 포착이 버려질 때 |
contexa.pqa.oss.sealed-evidence.retention.enabled | true | 보관 삭제 켜기 | 지우지 않고 모두 보관하려면 false |
contexa.pqa.oss.sealed-evidence.retention.period | 90d | 보관 기간 | 보관 정책이 다를 때 |
contexa.pqa.oss.sealed-evidence.retention.clean-period | 30d | 문제 없던 증거 묶음의 보관 기간 | 보관 정책이 다를 때 |
contexa.pqa.oss.sealed-evidence.retention.cleanup-cron | 0 30 3 * * * | 삭제 시각 | 지우는 시각을 옮길 때 |
contexa.pqa.official-verification.stale-execution-timeout | 15m | 멈춘 공식 검증을 다시 돌릴 수 있게 되는 시간 | 공식 검증이 오래 걸리는 환경 |
켜지는 조건과 확장점
- 봉인은
contexa-iam이 클래스패스에 있고 Contexa DB(contexa.datasource.*)가 연결되어 있으면 기본으로 켜집니다. - 다른 서명 방식(키 관리 서비스, HSM 등)을 쓰려면
EvidenceSigner빈을 선언합니다. 판정 감사 기록과 증거 묶음이 함께 그 서명기를 씁니다. - 다른 저장소에 두려면
SealedEvidencePackageRepository빈을, 봉인할 판정을 직접 고르려면SealedEvidenceCaptureSampling빈을 선언합니다.
봉인된 프롬프트를 사실과 대조하는 자동 검수는 프롬프트 검수와 재생에서 설명합니다.