contexa-core 에이전트 보안

위임과 업무 목표 계약

사람이 에이전트에게 맡긴 일의 범위(작업 · 대상 · 기간 · 수량)를 Contexa에 알려 주는 방법과, Contexa가 그 범위를 실제 요청과 비교해 판정 모델에 사실로 건네는 방식을 설명합니다. 범위를 벗어났다고 엔진이 차단하지는 않습니다. 엔진은 비교만 하고, 판정은 모델이 합니다.

한눈에 보기

위임이 판정 사실이 되기까지요청이 밝힌 위임은 위임 기록으로 좁혀진 뒤 실제 요청과 비교됩니다.
  1. 요청이 밝힌 위임토큰 클레임 · 세션 · 요청 속성 · 헤더에서 읽은 위임 도장
  2. 위임 기록기록으로 좁히기사람이 남긴 위임 기록(또는 앱의 업무 시스템)으로 범위를 좁힘. 넓히지는 않음
  3. Contexa범위 비교지금 작업 · 대상 · 건수가 위임 범위와 업무 목표 계약 안인지 비교해 "이탈 예 / 아니오"를 사실로 만듦
  4. AI 모델판정비교 사실과 다른 맥락을 함께 보고 허용 · 추가 확인 · 차단을 정함

위임 한 건에 담는 것

칸뜻예
agentId일을 맡은 에이전트(필수)report-bot
objectiveId / objectiveFamily맡긴 일의 ID / 일의 종류(앱이 선언한 업무 목표 계열)RPT-2026-10 / MONTHLY_REPORT
objectiveSummary위임자가 쓴 일 설명(1000자까지). 판정에서는 믿지 않는 글로 따로 다룸10월 매출 보고서 작성
allowedOperations허용 작업. @Protectable의 actions 이름과 같은 말(대문자로 바뀜)["READ"]
allowedResources허용 대상: 경로 패턴 또는 앱의 업무 ID["/api/reports/**"]
approvalRequired일하기 전에 위임자의 승인이 필요한지false
privilegedExportAllowed특권 데이터 반출을 허용하는지(밝히지 않으면 비움)false
containmentOnly읽기 · 봉쇄만 하도록 맡겼는지false
validFrom / expiresAt시작(기본 지금) / 끝(필수)2026-11-30T00:00:00Z
maxItemsPerRequest / maxItemsTotal반출 한 번의 최대 건수 / 세션 누계 최대 건수(1 이상, 밝히지 않으면 없음)100 / 1000

작업 · 대상 목록은 각각 100개까지입니다. 위임은 만료되거나 철회되면 끝나지만 기록은 남습니다. 끝난 시각 자체가 판정이 따지는 사실이기 때문입니다.

위임을 알려 주는 길

길누가어떻게
위임 API위임자 본인POST /contexa/api/agent-delegations. 로그인한 사람 이름으로만 기록됩니다.
관리 API관리자 · 연동 시스템POST /contexa/admin/api/agent-delegations(ADMIN 역할). 위임자 · 기록자 · 기록 시각을 앱의 기록대로 넣습니다.
토큰 클레임인가 서버delegation_id, objective_*, allowed_*, authorization_details(RFC 9396) 등(클레임 이름)
업무 시스템 조회앱DelegationRecordLookup 빈. 위임을 앱의 업무 시스템에 두는 경우의 주된 방법입니다(확장점).
세션 · 요청 속성 · 헤더앱 · 게이트웨이세션 속성, 요청 속성 ctxa.delegation.*, 헤더 X-Contexa-*(기본 꺼짐, 신뢰 프록시 필요)
에이전트는 위임을 기록할 수 없습니다. 위임은 사람의 말이어야 하므로, 사람 대신 받은 토큰(act), 에이전트 자기 토큰, 에이전트 계정으로 위임 API를 부르면 403으로 거부합니다.

위임 API

POST /contexa/api/agent-delegations
Content-Type: application/json

{
  "agentId": "report-bot",
  "objectiveFamily": "MONTHLY_REPORT",
  "objectiveSummary": "10월 매출 보고서 작성",
  "allowedOperations": ["READ"],
  "allowedResources": ["/api/reports/**"],
  "expiresAt": "2026-11-30T00:00:00Z",
  "maxItemsPerRequest": 100,
  "maxItemsTotal": 1000
}
  • 성공하면 201과 위임을 돌려줍니다. 응답의 state는 VALID · NOT_STARTED · EXPIRED · REVOKED 중 하나입니다.
  • 끝 시각은 시작보다 뒤여야 하고, 기간은 contexa.security.zerotrust.agent.delegation-max-validity(기본 30일)를 넘을 수 없습니다. 일이 이어지면 다시 위임합니다.
  • GET은 내 위임을 최신순으로 200개까지, POST /{delegationId}/revoke(본문 {"reason": "..."})는 내 위임을 철회합니다. 관리 API의 철회는 이유가 필수입니다.
  • 한 사람이 같은 에이전트에 여러 위임을 남기면, 요청이 delegation_id로 고른 위임을 쓰고, 없으면 지금 유효한 위임 가운데 가장 늦게 시작한 것, 그것도 없으면 끝난 위임까지 포함해 가장 늦게 시작한 것을 씁니다.
  • 위임을 기록하거나 철회할 때마다 감사 기록에 AGENT_DELEGATION_RECORDED · AGENT_DELEGATION_REVOKED가 누가 했는지와 함께 남습니다. 위임자의 계정을 지우면 그 사람의 위임도 함께 지웁니다.

위임 기록은 범위를 좁히기만 합니다

토큰 · 세션이 밝힌 위임과 위임 기록이 다르면, Contexa는 항상 더 좁은 쪽을 씁니다. 그래서 토큰을 넓게 받아도 기록이 범위를 묶습니다.

좁히기 예작업은 둘 다 말한 것만, 대상은 겹치는 항목이 없어 기록의 목록, 끝은 이른 쪽, 한도는 낮은 쪽.

토큰이 밝힌 위임

  • 작업 READ, EXPORT
  • 대상 /api/**
  • 끝 18:00
  • 건수 한도 없음

위임 기록

  • 작업 READ
  • 대상 /api/reports/**
  • 끝 17:00
  • 요청당 100건

판정에 쓰는 위임

  • 작업 READ
  • 대상 /api/reports/**
  • 끝 17:00
  • 요청당 100건
항목규칙
목표다르면 기록의 목표
허용 작업 · 대상둘 다 말한 항목만. 겹치는 항목이 없으면 기록의 목록(빈 목록은 "밝히지 않음"이라 범위를 넓히게 되므로)
승인 필요 · 봉쇄 전용어느 한쪽이라도 요구하면 요구
특권 반출둘 다 막지 않을 때만 허용
끝 시각 · 수량 한도이른 끝, 낮은 한도
다른 에이전트의 기록적용하지 않음

조회 결과는 판정 맥락에 delegationRecordLookup으로 남습니다: FOUND(적용), NOT_FOUND(기록 없음, 요청이 밝힌 위임 그대로), AGENT_MISMATCH(다른 에이전트의 기록), FAILED(조회 실패). 기록이 덮어쓴 항목은 충돌 목록으로, 기록 작성자 · 시각도 함께 남습니다. 사람 본인의 요청은 조회하지 않습니다.

단독 에이전트의 상시 위임

단독 에이전트는 위임자가 없습니다. 이때 Contexa는 등록 책임자(sponsor)가 그 에이전트에 남긴 위임을 한 번 더 찾아 상시 위임으로 같은 규칙을 적용합니다. 책임자가 위임 API로 그 에이전트에 위임을 기록해 두면 됩니다. 에이전트는 여전히 자기 이름으로 일하므로 요청을 "위임됨"으로 표시하지는 않습니다.

업무 목표 계약

앱은 업무 목표 계열마다 그 일에 필요한 작업과 자원 계열을 선언할 수 있습니다. 위임이 허용 작업 · 대상 계열을 밝히지 않았으면 이 계약이 비교 기준이 됩니다.

contexa:
  security:
    zerotrust:
      agent:
        objective-contracts:
          MONTHLY_REPORT:                 # 위임의 objectiveFamily와 같은 이름
            operations: [READ]            # @Protectable의 actions와 같은 말
            resource-families: [REPORT]   # @Protectable의 category와 같은 말
            max-export-items: 500         # 반출 한 번의 최대 건수
  • Contexa 자체 보안 목표 계열(감사 · 봉쇄 · 학습 등)은 이미 알고 있고, 앱이 같은 이름을 선언하면 앱의 계약이 대신합니다.
  • 코드로 선언하려면 ObjectiveContractSource 빈을 둡니다. Contexa 자체 계약 → 설정의 계약 → 소스 빈의 계약 순서로 읽고, 같은 계열은 나중 것이 앞의 것을 대신합니다.
  • 설정에는 read-only · privileged-export-allowed 칸도 있지만, 현재 버전의 범위 비교에는 쓰이지 않습니다. 특권 반출 금지는 위임의 privilegedExportAllowed로 비교합니다.

범위 이탈: 엔진은 비교, 판정은 모델

엔진은 요청마다 아래 항목을 비교하고, 결과를 "이탈 예 / 아니오"와 비교 문장으로 판정 맥락에 넣습니다. 비교할 입력이 하나도 없으면 "비교 불완전"으로 남깁니다.

비교기준
지금 작업이 허용 작업에 있나위임의 목록, 없으면 계약의 operations. 작업을 알 수 없으면 비교하지 않음
지금 자원 계열이 허용 계열에 있나위임의 목록, 없으면 계약의 resource-families
지금 대상이 허용 경로 · 업무 ID에 맞나위임의 allowedResources에 적은 경로 패턴 · ID
봉쇄 전용 위임에서 다른 작업인가읽기 · 조회 · 봉쇄만 범위 안
반출 건수가 한도 안인가계약의 max-export-items, 위임의 maxItemsPerRequest, 세션 누계와 maxItemsTotal
특권 반출을 막은 위임에서 반출인가위임의 privilegedExportAllowed = false
  • 건수는 앱이 알려 줄 때만 비교합니다. 요청 속성 ctxa.context.requestItems(또는 requestItems)에 요청 건수를 넣어 주세요.
  • 이탈을 이유로 판정을 강제하는 규칙은 없습니다. 모델이 사실을 보고 판정합니다. 모델이 근거로 DELEGATION_SCOPE_DRIFT를 들면, Contexa는 그 사실이 실제로 맥락에 있는지만 검사합니다.

정책 식으로 위임 확인하기

모델 판정과 별도로, URL · 메서드 정책에서 위임을 결정적으로 따질 수 있습니다. 이 식들은 요청의 위임 도장(토큰 · 세션 등)을 읽습니다. 위임 기록으로 좁힌 결과는 모델 판정에 쓰입니다.

식뜻
isAgent() / isDelegatedAgent() / isAutonomousAgent()에이전트 요청인지 / 위임 에이전트인지 / 단독 에이전트인지
agentId / isAgentIn('a', 'b')요청한 에이전트 ID / 그 가운데 하나인지
delegatorId위임자(위임 에이전트일 때)
delegationChainDepth / delegationChainDepthAtMost(n)위임 사슬 깊이(사람 · 단독 에이전트 0, 직접 위임 1) / n 이하인지
delegationAllowsOperation('READ')위임이 그 작업을 허용하는지
delegationAllowsResource('/api/reports/1')위임이 그 대상을 허용하는지(목록 항목이 *로 끝나면 앞부분이 같은 모든 대상)
delegationRequiresApproval()위임이 위임자 승인을 요구하는지
isDelegatedAgent() and delegationAllowsOperation('READ') and delegationChainDepthAtMost(1)

확인 · 호출 수 관련 식(agentRequestConfirmed(), agentCallsInLastMinuteAtMost(n))은 정지 · 확인 · 제한에 있습니다. 식 전체 목록은 AI 보안 표현식을 보세요.

설정

토큰 클레임 이름(contexa.bridge.delegation.token.*)

설정기본값
enabledtrue
actor-claims / may-act-claims[act] / [may_act](may_act는 참고로만 기록)
client-id-claims / agent-id-claims[azp, client_id, appid] / [agent_id, agentId]
tenant-claims / delegation-id-claims[tid, tenant_id] / [delegation_id, delegationId]
subject-type-claims / user-subject-types[idtyp, sub_profile] / [user]
scope-claims / authorization-details-claims[scope, scp] / [authorization_details]
objective-id-claims / objective-family-claims / objective-summary-claims[objective_id, objectiveId] / [objective_family, objectiveFamily] / [task_purpose, objective_summary, objectiveSummary]
allowed-operations-claims / allowed-resources-claims[allowed_operations, allowedOperations] / [allowed_resources, allowed_resource_families, allowedResources]
approval-required-claims / privileged-export-allowed-claims / containment-only-claims[approval_required, approvalRequired] / [privileged_export_allowed, privilegedExportAllowed] / [containment_only, containmentOnly]
expires-at-claims[delegation_expires_at, execution_expires_at, delegationExpiresAt]. 없으면 위임은 토큰 만료보다 늦게 끝나지 않음

에이전트 표지(agent-actor-markers, delegated-markers, agent-client-ids)는 에이전트를 알아보는 길에 있습니다. 세션 · 요청 속성 · 헤더에서 읽는 설정(contexa.bridge.delegation.session.* · request-attributes.* · headers.*)은 인증 브리지 설정을 보세요.

그 밖의 설정

설정기본값뜻언제 바꾸나
contexa.security.zerotrust.agent.delegation-max-validity30d위임 API로 기록하는 위임의 최대 기간더 긴 위임(예: 분기 업무)을 허용하거나 더 짧게 묶을 때
contexa.security.zerotrust.agent.objective-contracts.<계열>.*비어 있음업무 목표 계약앱의 업무 목표를 선언할 때
contexa.auth.oauth2.delegation-claim-enabledtrueContexa 인가 서버의 교환 토큰에 유효한 위임의 delegation_id를 실음(CONTEXA_OWNED)교환 토큰에 위임 ID를 싣지 않으려면 false

확장점

위임을 앱의 업무 시스템에서 읽기

위임을 이미 앱의 결재 · 업무 시스템에 두고 있다면 DelegationRecordLookup 빈 하나로 연결합니다. 빈을 두면 Contexa가 모든 에이전트 요청에 그 기록을 적용합니다.

@Bean
DelegationRecordLookup delegationRecordLookup(WorkOrderRepository workOrders) {
    return query -> workOrders
            .findActive(query.delegatorId(), query.agentId(), query.requestedAt())
            .map(order -> new DelegationRecord(
                    order.id(), order.requester(), order.agentId(),
                    order.taskId(), "MONTHLY_REPORT", order.title(),
                    List.of("READ"), List.of("/api/reports/**"),
                    false, false, false,
                    order.dueAt(), order.approver(), order.approvedAt(),
                    100, 1000));
}
  • 분석 스레드에서, 에이전트나 위임을 밝힌 요청마다 한 번 불립니다. 맞는 기록이 없으면 Optional.empty()를 돌려줍니다. 예외는 "조회 실패"로 남고 판정은 요청이 밝힌 위임으로 계속됩니다.
  • 끝난 위임도 돌려주세요. 끝 시각이 판정이 따지는 사실입니다.
  • query.standing()이 true이면 단독 에이전트의 상시 위임 조회이고, delegatorId는 그 에이전트의 책임자입니다.
빈언제 필요한가기본 동작
DelegationRecordLookup위임을 앱 업무 시스템에 둘 때Contexa 위임 보관소 조회
DelegationRegistry위임 보관소를 바꿀 때Contexa DB가 있으면 JDBC(ctxa_agent_delegation_record 표), 없으면 메모리
DelegationContextProvider(추가) / RecordedDelegationContextProvider(교체)위임 사실을 더 붙이거나 좁히기 규칙을 바꿀 때위 좁히기 규칙
DelegationStampResolver(추가)다른 통로에서 위임을 읽을 때(@Order로 순서)토큰 · 세션 · 요청 속성 · 헤더 · 에이전트 계정 5종
ObjectiveContractSource업무 목표 계약을 코드로 선언할 때설정의 계약만