contexa-core contexa-iam

봉인 증거와 공식 검증

판정이 어떤 프롬프트와 사실로 만들어졌는지를 나중에 그대로 다시 보는 방법을 설명합니다. 무엇을 언제 봉인하는지, 바뀌지 않았음을 어떻게 확인하는지, 관리 화면에서 증거를 보고 공식 검증 · 재생을 돌리는 방법, 보관 기간과 설정을 다룹니다.

한눈에 보기

AI 모델이 판정을 내리면 Contexa는 모델에 보낸 그대로의 프롬프트와 그 재료(요청 사실, 표준 맥락, 행위 기준선, 과거 판정 기록), 그리고 판정 결과를 한 묶음으로 만들어 해시와 서명으로 봉인합니다. 이 묶음(증거 묶음)을 봉인 증거라고 합니다. 봉인은 판정을 바꾸지 않고, 판정이 끝난 뒤 따로 저장됩니다.

봉인 증거의 일생봉인 · 저장은 자동이고, 검수는 주기적으로, 공식 검증 · 재생은 관리자가 요청할 때 돕니다.
  1. 프롬프트 포착판정 프롬프트가 만들어지는 순간 모델이 받을 글과 원본을 잡아 둡니다
  2. 봉인판정 뒤 일곱 구역을 한 묶음으로 만들고 SHA-256 해시를 계산합니다. 서명 키가 있으면 HMAC-SHA256으로 서명하고 앞 증거 묶음의 해시와 연결합니다
  3. 저장Contexa DB의 ctxa_sealed_evidence_package 표에 넣기만 합니다(기본 90일 보관)

저장된 증거 묶음으로 하는 일

  • 자동 검수30초마다 새 증거 묶음을 사실과 대조
  • 공식 검증지표 12개로 규칙 평가(모델 호출 없음)
  • 재생봉인된 입력으로 모델에 다시 묻기

무엇을 봉인하나

증거 묶음 하나에는 일곱 구역이 들어갑니다.

증거 묶음의 일곱 구역프롬프트는 압축 전 원본과 모델이 실제로 받은 글을 함께 담고, 각각의 해시도 남깁니다.
1요청 사실누가 · 어떤 자원에 · 무엇을 했나
2인증 상태로그인 방식, MFA 여부 등
3표준 맥락판정에 쓰인 사실 전체(JSON)
4행위 기준선 요약평소 행동의 요약
5과거 판정 기록 검색찾은 기록의 요약과 관련도
6프롬프트원본 · 모델이 받은 글 · 각 해시, 실행 정보
7판정대응, 위험 점수, 근거 코드, 가설, 모델 출력, 재시도

실행 정보 가운데 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입력 기록 · 해시 · 계약 버전을 추적할 수 있는가
CORRAG와 외부 맥락이 지시문이나 권한 밖 근거로 섞이지 않는가
RAPRAG 근거가 권한 범위 안에서만 쓰이고 안전하게 들어가는가
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-enabledtrue봉인 켜기봉인을 끌 때
contexa.pqa.oss.sealed-evidence.sample-percent1평소 봉인 비율(1~100)평소 봉인을 늘리거나 줄일 때(저장 용량과 맞바꿈)
contexa.pqa.oss.sealed-evidence.full-capture-after-change1000서버가 뜬 뒤와 판정이 쓰는 버전이 바뀐 뒤 모두 봉인할 판정 수(노드별). 먼저 적용 · 함께 시험 버전은 자기 창을 따로 가짐뜬 뒤나 버전을 바꾼 뒤의 판정을 더 많이 · 적게 볼 때
contexa.pqa.oss.sealed-evidence.snapshot-ttl10m포착한 프롬프트가 봉인을 기다리는 최대 시간판정이 10분 넘게 걸릴 때
contexa.pqa.oss.sealed-evidence.max-pending-snapshots
contexa.pqa.oss.sealed-evidence.max-completed-snapshots
1000 / 1000메모리에 잡아 두는 포착 수 상한판정이 몰려 포착이 버려질 때
contexa.pqa.oss.sealed-evidence.retention.enabledtrue보관 삭제 켜기지우지 않고 모두 보관하려면 false
contexa.pqa.oss.sealed-evidence.retention.period90d보관 기간보관 정책이 다를 때
contexa.pqa.oss.sealed-evidence.retention.clean-period30d문제 없던 증거 묶음의 보관 기간보관 정책이 다를 때
contexa.pqa.oss.sealed-evidence.retention.cleanup-cron0 30 3 * * *삭제 시각지우는 시각을 옮길 때
contexa.pqa.official-verification.stale-execution-timeout15m멈춘 공식 검증을 다시 돌릴 수 있게 되는 시간공식 검증이 오래 걸리는 환경

켜지는 조건과 확장점

  • 봉인은 contexa-iam이 클래스패스에 있고 Contexa DB(contexa.datasource.*)가 연결되어 있으면 기본으로 켜집니다.
  • 다른 서명 방식(키 관리 서비스, HSM 등)을 쓰려면 EvidenceSigner 빈을 선언합니다. 판정 감사 기록과 증거 묶음이 함께 그 서명기를 씁니다.
  • 다른 저장소에 두려면 SealedEvidencePackageRepository 빈을, 봉인할 판정을 직접 고르려면 SealedEvidenceCaptureSampling 빈을 선언합니다.

봉인된 프롬프트를 사실과 대조하는 자동 검수는 프롬프트 검수와 재생에서 설명합니다.