정지 · 확인 · 제한
판정 결과와 설정에 따라 Contexa가 에이전트를 멈추고, 책임자의 확인을 받고, 속도와 범위를 제한하는 방법을 설명합니다. 에이전트가 받는 응답과 그 처리 방법, 관리자가 정지를 푸는 방법, 콘솔 화면도 함께 다룹니다.
한눈에 보기
- 에이전트 요청
- ①호출 상한분당 호출이 한도를 넘으면
429 AGENT_CALL_LIMIT - ②끝난 위임철회됐으면
403 DELEGATION_REVOKED, 만료 · 시작 전이면 책임자 확인 요청 - ③CHALLENGE 판정책임자 확인 요청(
403 AGENT_CONFIRMATION_REQUIRED), 승인된 확인이 있으면 한 번 통과 - ④좁혀진 범위위험 판정 뒤 읽기만 허용 중이면 다른 작업은
403 AGENT_SCOPE_NARROWED - ⑤
@Protectable메서드 앞판정이 없으면 그 자리에서 판정, 걸린 ALLOW는 몇 건만 재사용 - 실행
소유 방식에 따라 되는 일
관문(①~④)은 두 소유 방식 모두에서 돕니다. CONTEXA_OWNED에서는 Contexa가 만든 보안 체인 안에서, 기본 HOST_OWNED에서는 앱의 Spring Security 체인 바로 뒤의 서블릿 필터로, 위임 도장을 찍는 인증 브리지 다음에 돕니다. @Protectable 메서드(⑤)와 판정 뒤 처리도 두 방식 모두 동작합니다.
| 통제 | CONTEXA_OWNED( @EnableAISecurity(mode = SecurityMode.FULL)) | HOST_OWNED(기본) |
|---|---|---|
| 저장된 판정 집행(BLOCK · CHALLENGE · ESCALATE) | URL 단계와 @Protectable | URL 단계(앱 체인 바로 뒤의 필터)와 @Protectable |
| 판정 없는 에이전트 요청의 그 자리 판정, ALLOW 재사용 제한, 판정 통합 | 동작 | 동작(@Protectable) |
| BLOCK 뒤 정지(위임 철회 · 토큰 폐기 · 알림) | 동작 | 동작. 토큰 폐기는 AgentTokenRevoker를 둘 때만 |
| 책임자 확인(CHALLENGE · 끝난 위임) | 동작 | 동작. 에이전트의 CHALLENGE에는 403 AGENT_CONFIRMATION_REQUIRED와 확인 상태 주소로 답함 |
| 철회된 위임 거부, 호출 상한 · 거부율 경보, 좁혀진 범위 거부 | 동작 | 동작 |
정책 식 agentRequestConfirmed() | 동작 | 동작 |
| 정지된 에이전트의 토큰 거부 | Contexa 리소스 서버 · 인가 서버 | 앱의 리소스 서버 몫 |
| 위임자 권한으로 한 번 더 평가 | URL · 메서드 정책 | 메서드 정책 |
에이전트가 받는 응답
에이전트(또는 그 프레임워크 어댑터)는 아래 응답을 알아듣고 처리해야 합니다. 본문은 JSON이고 error · message · path에 아래 칸이 더해집니다.
상태 · error | 언제 | 에이전트가 할 일 |
|---|---|---|
429 AGENT_CALL_LIMIT | 분당 호출 상한을 넘음. 본문 scope(DELEGATION · AGENT) · limit · retryAfterSeconds | Retry-After 초 뒤에 다시 보냄 |
403 DELEGATION_REVOKED | 철회된 위임으로 요청함. 본문 delegationId | 멈춤. 사람이 다시 위임해야 함 |
403 AGENT_CONFIRMATION_REQUIRED | 판정이 CHALLENGE이거나 위임이 만료 · 시작 전 | statusUrl을 조회하고, APPROVED가 되면 같은 요청을 다시 보냄(책임자 확인) |
403 AGENT_SCOPE_NARROWED | 좁혀진 범위 밖의 작업. 본문 allowed · until · operation | until까지 허용 작업만 하거나, 그 요청의 확인을 받아 옴 |
413 AGENT_CONFIRMATION_UNBINDABLE | 확인이 필요한데 본문이 확인에 묶을 수 있는 크기(기본 1MB)를 넘음 | 작게 나눠 보냄 |
429 ZERO_TRUST_ANALYSIS_BUSY | 판정 통합이 켜져 있고 분석 자리 · 대기열이 모두 참 | Retry-After 초 뒤에 다시 보냄 |
책임자 확인
판정이 CHALLENGE이면 사람에게는 추가 인증(MFA)을 요구하지만, 에이전트는 MFA를 할 수 없습니다. 그래서 Contexa는 그 에이전트를 책임지는 사람에게 그 요청을 확인받습니다.
- 에이전트→앱요청
- Contexa→에이전트
403 AGENT_CONFIRMATION_REQUIRED, 확인 ID · 상태 주소 · 만료 시각 - Contexa→책임자알림(메일, 없으면 콘솔)과 확인 화면 링크
- 책임자→Contexa승인 · 거절 · 신고
- 에이전트→Contexa
GET statusUrl→APPROVED - 에이전트→앱같은 요청을 다시 보냄 → 한 번 실행(
USED)
{
"status": "PENDING",
"error": "AGENT_CONFIRMATION_REQUIRED",
"trigger": "DECISION_CHALLENGE",
"confirmationId": "6f1c2a90-…",
"statusUrl": "/contexa/api/agent-confirmations/6f1c2a90-…",
"expiresAt": "2026-11-02T06:15:00Z",
"confirmationHeader": "Contexa-Agent-Confirmation",
"message": "The person accountable for this agent must confirm this request; …",
"path": "/api/reports/export"
}
- 누가 확인하나: 위임 에이전트는 위임자, 단독 에이전트는 등록 책임자(sponsor)입니다. 책임자가 없으면 확인을 만들지 않고 거부합니다(본문에
confirmationId가 없음). - 확인은 그 요청에 묶입니다: 테넌트 · 사용자 · 에이전트 · 메서드 · 경로 · 질의 문자열 · 본문의 SHA-256까지 같은 요청에만 쓰이고, 한 번 쓰면
USED가 됩니다. 다시 보낼 때Contexa-Agent-Confirmation헤더에 확인 ID를 넣을 수 있습니다. - 시간: 책임자의 답을
confirmation-timeout(기본 15분) 동안 기다리고, 승인 뒤에도 같은 시간 안에 써야 합니다. 지나면EXPIRED(거부)이고 1분마다 정리합니다. - 신고: 책임자가 신고하면 그 요청은 거부되고 에이전트는 즉시 정지됩니다(정지와 같은 절차, BLOCK도 바로 저장).
- 승인은 검증 가능한 기록으로 남습니다. Contexa 인가 서버가 있으면 OAuth2 인가로, 없으면 증거 서명 키의 서명으로 남기고, 쓸 때 다시 검증합니다. 확인된 내용은 판정 맥락(
Confirmation줄)에도 실립니다. - 확인 화면에서는 그 확인을 받는 사람만 자기 세션으로 결정합니다. 그 사람의 토큰을 가진 에이전트의 요청이라도 거부합니다.
| 확인 상태 | 뜻 |
|---|---|
PENDING | 책임자의 답을 기다림 |
APPROVED | 승인됨, 아직 쓰지 않음 |
USED | 승인되어 그 요청에 쓰임 |
REJECTED · EXPIRED · REPORTED | 거절 · 시간 초과 · 신고(모두 최종 거부, 상태 조회의 refused가 true) |
에이전트가 먼저 확인을 요청하기
위임이 승인을 요구할 때 정책 !delegationRequiresApproval() or agentRequestConfirmed()를 두면, 에이전트는 실행 전에 직접 확인을 요청할 수 있습니다(트리거 REQUESTED).
POST /contexa/api/agent-confirmations
Content-Type: application/json
{ "method": "POST", "target": "/api/reports/export?month=2026-10",
"bodySha256": "9f86d081…", "reason": "월간 보고서 반출" }
202와 확인 상태를 돌려줍니다(책임자가 없으면 409, 에이전트가 아니면 403). target은 /로 시작하는 경로와 질의, bodySha256은 보낼 본문의 SHA-256(16진수)입니다. 상태는 GET /contexa/api/agent-confirmations/{id}로 조회합니다. 이 방법도 확인을 소비하는 관문이 있어야 하므로 CONTEXA_OWNED에서만 동작합니다.
알림의 확인 링크 앞부분은 confirmation-link-base-url(예: https://app.example.com)로 정합니다. 비우면 앱 경로만 쓴 상대 링크가 됩니다. 에이전트가 보낸 Host 헤더는 링크에 쓰지 않습니다.
정지와 해제
에이전트 요청에 BLOCK 판정이 나면 그 에이전트만 멈춥니다. 사람 차단 목록에는 넣지 않고, 사람 본인의 일은 계속됩니다.
위임 에이전트가 BLOCK되면
- 판정은 에이전트 키(
<사용자>::agent::<에이전트>)에 저장 - 그 위임을 철회
- 그 사람 몫으로 받은 토큰 폐기
- 위임자에게 알림
단독 에이전트가 BLOCK되면
- 등록을 정지(
SUSPENDED): 그 에이전트에 발급된 모든 토큰을 거부 - 토큰 폐기
- 책임자(sponsor)에게 알림
책임자의 신고와 호출 상한의 STOP도 같은 절차로 멈춥니다. 해제는 관리자 API · 콘솔 또는 책임자 확인 화면에서 합니다(킬 스위치로 멈춘 것은 관리자만).
action | 필요한 칸 | 하는 일 |
|---|---|---|
RELEASE_DELEGATION | userId, agentId | 그 사람에 대한 에이전트의 판정을 지워 다음 요청을 다시 판정. 철회된 위임은 그대로라 사람이 다시 위임해야 함 |
RELEASE_AGENT | agentId(tenantId 선택) | 등록을 다시 운영 중으로 바꾸고 에이전트의 판정을 지움 |
KILL_SWITCH | agentType · tenantId(선택) | 그 종류(비우면 전부)의 운영 중 에이전트를 한꺼번에 정지 |
KILL_SWITCH_RELEASE | 같음 | 킬 스위치로 멈춘 에이전트만 다시 운영. 다른 이유로 멈춘 것은 그대로 |
POST /contexa/admin/api/agents/stops
Content-Type: application/json
{ "action": "KILL_SWITCH", "agentType": "AGENT", "reason": "프롬프트 주입 사고 대응" }
reason은 필수이고 ADMIN 역할이 필요합니다. GET은 정지된 에이전트와 위임을 보여 줍니다. 정지를 처리하는 서비스(AgentContainmentService)가 없으면 503(the autonomous security plane is off)을 답합니다. BLOCK으로 좁혀진 범위는 해제한 뒤에도 그 기간이 끝날 때까지 유지됩니다.
범위 축소
에이전트 요청에 위험 판정이 나면, 그 에이전트의 다음 요청은 일정 시간 읽기만 허용됩니다.
- 언제: CHALLENGE · ESCALATE · BLOCK 판정, 또는 위험도가
risk-threshold(기본 0.7) 이상인 ALLOW 뒤. - 얼마나:
duration(기본 1시간). 범위는 좁히기만 하고 넓히지 않습니다. - 작업 종류는 메서드와 경로의 단어로 정합니다(
READ·WRITE·EXPORT·DELETE·ADMIN·EXECUTE). 예를 들어GET /api/exports는 반출(EXPORT)로 봅니다. - 범위 밖 요청은
403 AGENT_SCOPE_NARROWED입니다. 책임자가 그 요청을 확인하면 통과합니다. 사람의 요청은 좁히지 않습니다.
호출 상한과 거부율 경보
| 상한 | 기본값 | 세는 단위 |
|---|---|---|
| 위임 하나 | 분당 120 | 한 사람 몫의 일(에이전트의 판정 키) |
| 에이전트 전체 | 분당 600 | 그 에이전트가 대신하는 모든 사람 |
- 넘으면
on-exceed에 따라THROTTLE(기본,429+Retry-After) 또는STOP(에이전트 정지, 그 요청의 응답은 그대로429)입니다. - 거부율 경보: 5분 동안 요청이 10건 이상이고 그중 거부가 50% 이상이면 감사 기록을 남기고 책임자에게 알립니다(창마다 한 번).
- 집행 모드가
ENFORCE가 아니면(SHADOW 등) 넘어도 통과시키고 기록만 합니다. 계수는 인스턴스마다 따로 셉니다.
판정 없는 요청과 ALLOW 재사용
- 판정이 아직 없을 때: 사람의 요청은 통과하고 뒤에서 분석하지만, 에이전트 요청은 비동기
@Protectable메서드라도 그 요청 안에서 판정합니다(protectable.unrecorded-agent-request: DECIDE_IN_PLACE, 기본).PROCEED로 바꾸면 사람처럼 통과시킵니다. - 걸려 있는 ALLOW: 사람에게는 유효 시간 동안 다음 요청에도 쓰이지만, 에이전트에게는 같은 작업 · 서로 다른 자원 3개 · 요청 10건까지만 쓰입니다. 자원이 민감(
SENSITIVE·CRITICAL)하면 자원 1개까지입니다. 넘으면 그 자리에서 다시 판정합니다. 고객 목록을 한 건씩 훑는 에이전트가 첫 ALLOW 하나로 전부 읽지 못하게 하기 위해서입니다.
판정 통합(기본 꺼짐)
한 에이전트가 요청을 한꺼번에 보내면 요청마다 모델을 부르지 않고, 같은 질문은 한 번만 분석합니다. 첫 요청이 분석되는 동안 나머지는 그 판정을 기다렸다가 그 결과로 답을 받습니다.
설정(contexa.security.zerotrust.agent.flight.*) | 기본값 | 뜻 | 언제 바꾸나 |
|---|---|---|---|
enabled | false | 켜기 | 한 에이전트가 같은 요청을 몰아 보내 모델 호출이 많을 때 |
max-in-flight-analyses | 3 | 한 에이전트가 동시에 받는 분석 수 | 모델 처리량에 맞출 때 |
queue-capacity | 20 | 분석 자리를 기다릴 수 있는 요청 수 | 429가 자주 날 때 |
wait | 40s | 기다리는 최대 시간. 넘으면 429 ZERO_TRUST_ANALYSIS_BUSY | 판정이 오래 걸리는 모델을 쓸 때(2차 분석 포함) |
pass-budget | 3 | 첫 판정이 나오기 전에 통과시킬 수 있는 요청 수(0이면 없음) | 첫 판정 전에는 아무것도 통과시키지 않으려면 0 |
pass-families | [READ] | 먼저 통과할 수 있는 작업 종류. 앱이 민감하지 않다고 밝힌 자원만 | 먼저 통과시킬 작업 종류를 바꿀 때 |
- 판정이 없다는 이유로 요청을 통과시키지 않습니다. 예외는 위
pass-budget뿐입니다. - 기다리는 동안 그 에이전트에 제한(BLOCK · ESCALATE · CHALLENGE)이 저장되면 기다리던 요청에 바로 그 제한이 적용됩니다.
- 판정 통합 자체가 실패하면 판정으로 치지 않고, 요청마다 따로 분석합니다. 상태는 인스턴스마다 메모리에 둡니다.
집행하지 않는 모드에서(SHADOW 등)
집행 모드가 ENFORCE가 아니면(SHADOW · OBSERVE · DISABLED, 또는 contexa.security.zerotrust.enabled=false) 관문은 끝난 위임 · 좁혀진 범위 · 호출 상한을 기록하고 요청을 통과시킵니다. 위임자 권한 재평가도 기록만 합니다. 다만 걸려 있는 CHALLENGE는 여전히 확인을 기다립니다.
정책 식
| 식 | 뜻 |
|---|---|
agentRequestConfirmed() | 책임자가 바로 이 요청을 확인했는지(에이전트 요청일 때만 true) |
agentCallsInLastMinuteAtMost(n) | 이 위임의 최근 1분 호출이 이 요청을 포함해 n 이하인지. 사람이거나 센 것이 없으면 true |
위임 관련 식은 위임과 업무 목표 계약에 있습니다.
판정 기록과 위변조 확인
판정마다 감사 기록(ctxa_audit_log, 분류 SECURITY_DECISION)에 판정 기록이 하나 남습니다. 사람의 요청이면 에이전트 · 위임 칸이 비어 있습니다.
| 칸 | 내용 |
|---|---|
| 주체 | 주체 유형, 에이전트, 위임자, 위임 ID |
| 요청한 작업 | 요청의 행위 계열 |
| 위험 사실 | 판정이 근거로 든 근거 코드와 그 사실 ID |
| 집행 | 집행한 대응과 그 이유. 결과는 APPLIED(적용), KEPT_STRICTER(더 엄격한 대응이 이미 있어 그대로 둠), OBSERVED_ONLY(집행하지 않는 모드라 기록만), DISCARDED(처리 권한이 끊겨 결과를 버림) |
| 요청 맥락 해시 | 시각 · 테넌트 · 사용자 · 에이전트 · 위임 · 작업 · 메서드 · 경로 · 대상 · 요청 건수 · 인자 요약의 SHA-256 |
서명기가 있으면(봉인 증거의 서명 키) 판정 기록은 저장 순서대로 사슬로 묶입니다. 기록마다 칸과 앞 기록의 해시를 합친 SHA-256을 계산하고 서명합니다. 관리 콘솔의 보안 이벤트 기록은 기록마다 확인 결과를 보여 줍니다.
| 결과 | 뜻 |
|---|---|
VERIFIED | 봉인한 그대로입니다 |
MISMATCH | 칸이 바뀌었거나, 해시를 다시 계산해 넣어 서명이 맞지 않거나, 사슬 중간의 기록이 지워졌습니다 |
UNVERIFIABLE | 봉인 전에 쓴 기록이거나, 서명한 키를 더는 갖고 있지 않습니다(예: 임시 키로 서명한 뒤 재시작) |
감사 기록 보관 기간(기본 90일, 시스템 설정)이 지나 가장 오래된 기록이 지워진 것은 MISMATCH로 보지 않습니다.
판정 기록의 시각은 사건의 시각이고, 저장할 때 다시 쓰지 않으므로 봉인한 그대로 확인됩니다. 이 기능이 고쳐지기 전에 저장된 판정 기록은 저장 때 시각이 다시 쓰여 MISMATCH로 남습니다. 변조 증거라는 뜻을 지키기 위해 그 기록은 다시 봉인하지 않습니다(업그레이드 뒤 옛 판정 기록의 봉인 불일치).
콘솔 화면과 API
| 화면 · API | 경로 | 하는 일 |
|---|---|---|
| 에이전트 목록 · 상세 · 등록 | /contexa/admin/agents(/detail, /new) | 등록부, 상태, 위임, 판정 기록 |
| 에이전트 정지 탭 | /contexa/admin/blacklist/agents | 정지된 에이전트 · 위임 보기, 해제, 킬 스위치 |
| 책임자 확인 화면 | /contexa/agent-confirmations | 내 확인 요청과 알림, 승인 · 거절 · 신고, 내 에이전트의 정지 해제(이유 필수) |
| 학습 격리 API | /contexa/admin/api/agents/learning | 에이전트 또는 위임 하나의 학습을 QUARANTINE(남기되 읽지도 더 배우지도 않음) · RELEASE · REMOVE. 다른 에이전트와 사람의 학습은 건드리지 않음 |
정지 · 해제 · 확인 · 위임 기록은 모두 감사 기록(AGENT_* 분류)에 남습니다.
설정
모두 contexa.security.zerotrust.agent. 아래입니다(마지막 줄 제외).
| 설정 | 기본값 | 뜻 | 언제 바꾸나 |
|---|---|---|---|
confirmation-timeout | 15m | 확인 대기 시간, 승인 뒤 쓸 수 있는 시간 | 책임자가 답하는 데 시간이 더 필요하거나, 대기를 짧게 하고 싶을 때 |
confirmation-sweep-interval | 1m | 시간이 지난 확인을 정리하는 주기 | 거의 바꾸지 않음 |
confirmation-link-base-url | 없음 | 알림 링크의 절대 주소 앞부분 | 알림 메일의 링크를 절대 주소로 보내야 할 때 |
confirmation-max-body-bytes | 1048576 | 확인에 묶을 수 있는 최대 본문 크기 | 확인이 필요한 요청의 본문이 1MB를 넘을 때 |
scope-narrowing.enabled / .duration / .risk-threshold | true / 1h / 0.7 | 범위 축소 | 축소 기간 · 위험 기준을 업무에 맞추거나 끌 때 |
call-limit.enabled / .per-delegation-per-minute / .per-agent-per-minute / .on-exceed | true / 120 / 600 / THROTTLE | 호출 상한 | 정상 호출량이 상한에 가깝거나, 넘으면 정지(STOP)시키고 싶을 때 |
denial-alarm.enabled / .window / .min-requests / .rate | true / 5m / 10 / 0.5 | 거부율 경보 | 경보가 너무 잦거나 드물 때 |
allow-reuse.max-requests / .max-distinct-resources / .sensitive-max-distinct-resources | 10 / 3 / 1 | ALLOW 재사용 범위 | ALLOW 하나로 답할 범위를 넓히거나 좁힐 때(넓히면 판정 수는 줄고 위험은 커짐) |
flight.* | 위 표 | 판정 통합 | 위 표 |
contexa.security.zerotrust.protectable.unrecorded-agent-request | DECIDE_IN_PLACE | 판정 없는 에이전트 요청 처리(PROCEED면 사람처럼) | 에이전트 요청도 사람처럼 먼저 통과시키고 뒤에서 분석할 때(PROCEED) |
확장점
| 빈 | 언제 필요한가 | 기본 동작 |
|---|---|---|
AgentNoticeChannel | 메일 외 채널(채팅 · 푸시 · 티켓)로 알릴 때 | 메일 발송기가 있으면 메일(사람 계정의 주소 필요), 없으면 콘솔에만 남김 |
AgentTokenRevoker | 외부 인가 서버의 토큰을 정지할 때 폐기하려면 | Contexa 인가 서버면 그 서버에서 폐기, 아니면 폐기 없음(정지 · BLOCK에만 기댐) |
AgentConfirmationAuthorizer | 승인을 앱의 인가 서버에 남길 때 | Contexa 인가 서버 그랜트, 없으면 증거 서명 키 서명 |
AgentScopeNarrower / AgentScopeStore | 다르게 좁히거나 다른 저장소를 쓸 때 | 읽기만 1시간 / JDBC 또는 메모리 |
AgentConfirmationStore / AgentNoticeStore | 저장소를 바꿀 때 | JDBC(ctxa_agent_confirmation · ctxa_agent_notice 표) 또는 메모리 |
운영 메모
- 여러 인스턴스: 호출 상한 계수와 판정 통합 상태는 인스턴스마다 메모리에 있습니다. 메모리 등록부 · 보관소는 재시작하면 사라지므로 운영에서는 Contexa DB를 쓰세요.
- 정지 서비스(
AgentContainmentService)가 없으면 BLOCK 뒤 정지와 범위 축소가 없고, 정지 API는503을 답합니다.contexa.autonomous.enabled: false는 이 상태를 만들지 않고 Contexa 전체를 끕니다. - 에이전트의 판정 자체는 모델이 합니다. 엔진은 사실만 계산합니다(판정 엔진).