contexa-core 에이전트 보안

정지 · 확인 · 제한

판정 결과와 설정에 따라 Contexa가 에이전트를 멈추고, 책임자의 확인을 받고, 속도와 범위를 제한하는 방법을 설명합니다. 에이전트가 받는 응답과 그 처리 방법, 관리자가 정지를 푸는 방법, 콘솔 화면도 함께 다룹니다.

한눈에 보기

에이전트 요청 관문관문은 위에서부터 차례로 검사하고, 걸리면 그 자리에서 답합니다. 사람의 요청은 이 관문을 지나지 않습니다.
  1. 에이전트 요청
  2. ①호출 상한분당 호출이 한도를 넘으면 429 AGENT_CALL_LIMIT
  3. ②끝난 위임철회됐으면 403 DELEGATION_REVOKED, 만료 · 시작 전이면 책임자 확인 요청
  4. ③CHALLENGE 판정책임자 확인 요청(403 AGENT_CONFIRMATION_REQUIRED), 승인된 확인이 있으면 한 번 통과
  5. ④좁혀진 범위위험 판정 뒤 읽기만 허용 중이면 다른 작업은 403 AGENT_SCOPE_NARROWED
  6. ⑤@Protectable 메서드 앞판정이 없으면 그 자리에서 판정, 걸린 ALLOW는 몇 건만 재사용
  7. 실행

소유 방식에 따라 되는 일

관문(①~④)은 두 소유 방식 모두에서 돕니다. CONTEXA_OWNED에서는 Contexa가 만든 보안 체인 안에서, 기본 HOST_OWNED에서는 앱의 Spring Security 체인 바로 뒤의 서블릿 필터로, 위임 도장을 찍는 인증 브리지 다음에 돕니다. @Protectable 메서드(⑤)와 판정 뒤 처리도 두 방식 모두 동작합니다.

통제CONTEXA_OWNED
(@EnableAISecurity(mode = SecurityMode.FULL))
HOST_OWNED(기본)
저장된 판정 집행(BLOCK · CHALLENGE · ESCALATE)URL 단계와 @ProtectableURL 단계(앱 체인 바로 뒤의 필터)와 @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 · retryAfterSecondsRetry-After 초 뒤에 다시 보냄
403 DELEGATION_REVOKED철회된 위임으로 요청함. 본문 delegationId멈춤. 사람이 다시 위임해야 함
403 AGENT_CONFIRMATION_REQUIRED판정이 CHALLENGE이거나 위임이 만료 · 시작 전statusUrl을 조회하고, APPROVED가 되면 같은 요청을 다시 보냄(책임자 확인)
403 AGENT_SCOPE_NARROWED좁혀진 범위 밖의 작업. 본문 allowed · until · operationuntil까지 허용 작업만 하거나, 그 요청의 확인을 받아 옴
413 AGENT_CONFIRMATION_UNBINDABLE확인이 필요한데 본문이 확인에 묶을 수 있는 크기(기본 1MB)를 넘음작게 나눠 보냄
429 ZERO_TRUST_ANALYSIS_BUSY판정 통합이 켜져 있고 분석 자리 · 대기열이 모두 참Retry-After 초 뒤에 다시 보냄

책임자 확인

판정이 CHALLENGE이면 사람에게는 추가 인증(MFA)을 요구하지만, 에이전트는 MFA를 할 수 없습니다. 그래서 Contexa는 그 에이전트를 책임지는 사람에게 그 요청을 확인받습니다.

확인 주고받기승인은 그 요청 하나에만, 한 번만 쓰입니다.
  1. 에이전트→앱요청
  2. Contexa→에이전트403 AGENT_CONFIRMATION_REQUIRED, 확인 ID · 상태 주소 · 만료 시각
  3. Contexa→책임자알림(메일, 없으면 콘솔)과 확인 화면 링크
  4. 책임자→Contexa승인 · 거절 · 신고
  5. 에이전트→ContexaGET statusUrl → APPROVED
  6. 에이전트→앱같은 요청을 다시 보냄 → 한 번 실행(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 뒤에 하는 일각 단계는 판정 기록에 순서대로 남습니다.

위임 에이전트가 BLOCK되면

  • 판정은 에이전트 키(<사용자>::agent::<에이전트>)에 저장
  • 그 위임을 철회
  • 그 사람 몫으로 받은 토큰 폐기
  • 위임자에게 알림

단독 에이전트가 BLOCK되면

  • 등록을 정지(SUSPENDED): 그 에이전트에 발급된 모든 토큰을 거부
  • 토큰 폐기
  • 책임자(sponsor)에게 알림

책임자의 신고와 호출 상한의 STOP도 같은 절차로 멈춥니다. 해제는 관리자 API · 콘솔 또는 책임자 확인 화면에서 합니다(킬 스위치로 멈춘 것은 관리자만).

action필요한 칸하는 일
RELEASE_DELEGATIONuserId, agentId그 사람에 대한 에이전트의 판정을 지워 다음 요청을 다시 판정. 철회된 위임은 그대로라 사람이 다시 위임해야 함
RELEASE_AGENTagentId(tenantId 선택)등록을 다시 운영 중으로 바꾸고 에이전트의 판정을 지움
KILL_SWITCHagentType · 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.*)기본값뜻언제 바꾸나
enabledfalse켜기한 에이전트가 같은 요청을 몰아 보내 모델 호출이 많을 때
max-in-flight-analyses3한 에이전트가 동시에 받는 분석 수모델 처리량에 맞출 때
queue-capacity20분석 자리를 기다릴 수 있는 요청 수429가 자주 날 때
wait40s기다리는 최대 시간. 넘으면 429 ZERO_TRUST_ANALYSIS_BUSY판정이 오래 걸리는 모델을 쓸 때(2차 분석 포함)
pass-budget3첫 판정이 나오기 전에 통과시킬 수 있는 요청 수(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-timeout15m확인 대기 시간, 승인 뒤 쓸 수 있는 시간책임자가 답하는 데 시간이 더 필요하거나, 대기를 짧게 하고 싶을 때
confirmation-sweep-interval1m시간이 지난 확인을 정리하는 주기거의 바꾸지 않음
confirmation-link-base-url없음알림 링크의 절대 주소 앞부분알림 메일의 링크를 절대 주소로 보내야 할 때
confirmation-max-body-bytes1048576확인에 묶을 수 있는 최대 본문 크기확인이 필요한 요청의 본문이 1MB를 넘을 때
scope-narrowing.enabled / .duration / .risk-thresholdtrue / 1h / 0.7범위 축소축소 기간 · 위험 기준을 업무에 맞추거나 끌 때
call-limit.enabled / .per-delegation-per-minute / .per-agent-per-minute / .on-exceedtrue / 120 / 600 / THROTTLE호출 상한정상 호출량이 상한에 가깝거나, 넘으면 정지(STOP)시키고 싶을 때
denial-alarm.enabled / .window / .min-requests / .ratetrue / 5m / 10 / 0.5거부율 경보경보가 너무 잦거나 드물 때
allow-reuse.max-requests / .max-distinct-resources / .sensitive-max-distinct-resources10 / 3 / 1ALLOW 재사용 범위ALLOW 하나로 답할 범위를 넓히거나 좁힐 때(넓히면 판정 수는 줄고 위험은 커짐)
flight.*위 표판정 통합위 표
contexa.security.zerotrust.protectable.unrecorded-agent-requestDECIDE_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 전체를 끕니다.
  • 에이전트의 판정 자체는 모델이 합니다. 엔진은 사실만 계산합니다(판정 엔진).