인프라 구성

Contexa 코어 속성 (요약)

최상위 ContexaProperties 클래스(접두사 contexa)는 인프라 모드, Redis, Kafka, 관측성의 마스터 스위치를 포함합니다. 이 속성들은 구성 개요 페이지에 완전히 문서화되어 있습니다. 인프라 관련 주요 항목은 다음과 같습니다:

전체 ContexaProperties 참조는 구성 개요를 확인하세요.

캐시 속성

contexa.cache 아래의 속성으로, ContexaCacheProperties에 바인딩됩니다. Identity, 정책, 행동 데이터를 위해 Contexa 전반에서 사용되는 다중 계층 캐싱 하위 시스템을 제어합니다. 로컬(Caffeine), Redis, 하이브리드 캐싱 전략과 선택적 pub/sub 기반 캐시 무효화를 지원합니다.

일반 설정

도메인별 TTL

각 캐시 도메인은 로컬 및 Redis 계층에 대해 독립적인 TTL 값을 가질 수 있습니다. 이를 통해 세밀한 제어가 가능합니다 - 예를 들어, 자주 변경되는 정책 데이터는 짧은 TTL을 사용하고 안정적인 HCAD 기준선 데이터는 긴 TTL을 사용할 수 있습니다.

각 도메인 항목은 local-ttl-seconds 및 redis-ttl-seconds 필드를 가진 TtlConfig 객체입니다. 각 도메인을 독립적으로 재정의할 수 있습니다:

contexa:
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "myapp:contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 60
      hcad:
        local-ttl-seconds: 43200
        redis-ttl-seconds: 86400

Bridge 속성

BridgeProperties는 contexa.bridge에 바인딩됩니다. 외부(레거시) 인증 시스템과 Contexa 사이의 사용자/권한/위임/세션 정보를 양방향으로 매핑하는 브리지 계층을 제어합니다. SecurityContext 추출 키, 세션 attribute 후보, request attribute 키, HTTP 헤더 이름, 동기화 정책, 신뢰 프록시 목록을 정의합니다.

Bridge 핵심 토글

동기화 (Sync)

신뢰 프록시 (Network)

Authentication SecurityContext 키

contexa.bridge.authentication.security-context 아래의 속성으로, Authentication.SecurityContext 에 바인딩됩니다. 외부 인증 토큰의 claim/attribute 에서 표시 이름·principal 타입·인증 방식·assurance·MFA 상태·인증 시각·기타 추가 attribute 를 추출할 때 시도하는 키 목록을 정의합니다. 첫 번째 매칭 키의 값이 사용됩니다.

Authentication Session 키

contexa.bridge.authentication.session 아래의 속성으로, 공통 Bridge.Session 에 바인딩됩니다. 외부 시스템이 HTTP 세션의 attribute 로 인증된 사용자 객체를 보관할 때, Contexa 가 어떤 attribute 이름을 시도하고, 그 객체에서 어떤 키로 principal id, 표시 이름, 권한, 인증 방식, MFA 상태, 인증 시각, 추가 attribute 를 추출할지 정의합니다.

Authentication RequestAttributes 키

contexa.bridge.authentication.request-attributes 아래의 속성으로, 공통 Bridge.RequestAttributes 에 바인딩됩니다. 외부 필터가 사용자 객체를 HttpServletRequest attribute 로 보관할 때 어떤 attribute 후보를 시도할지, 그 객체에서 어떤 키로 정보를 읽을지, Contexa 가 다시 request attribute 로 노출할 때 어떤 평면 key 이름을 쓸지를 정의합니다.

탐색 / 추출 (공통 13)

평면 인증 attribute 키 (flat-*, 8)

Contexa 가 request attribute 로 다시 평탄화해서 노출할 때 사용하는 단일 키 이름입니다. 다운스트림 컴포넌트가 이 키로 직접 읽을 수 있습니다.

Authorization 매핑 키 (7)

Delegation 매핑 키 (11)

Authentication HTTP 헤더 이름

contexa.bridge.authentication.headers 아래의 속성으로, 공통 Bridge.Headers 에 바인딩됩니다. 외부 reverse proxy 또는 게이트웨이가 인증·인가·위임 정보를 HTTP 헤더로 전달할 때 Contexa 가 어떤 헤더 이름을 읽거나 발행할지 정의합니다. 모든 헤더 이름은 변경 가능합니다.

토글

인증 헤더 (8)

Authorization 헤더 (7)

Delegation 헤더 (11)

Authorization SecurityContext 키

contexa.bridge.authorization.security-context 아래의 속성으로, Authorization.SecurityContext 에 바인딩됩니다. 외부 시스템이 Spring SecurityContext 의 Authentication 객체에 인가 결정 결과(effect, 정책 ID, 권한 등)를 attribute 로 보관할 때, Contexa 가 어떤 키를 시도해서 그 정보를 읽을지 정의합니다. 첫 번째 매칭 키의 값이 사용됩니다.

Authorization Session 키

contexa.bridge.authorization.session 아래의 속성으로, Authorization.Session 에 바인딩됩니다. 외부 시스템이 HTTP 세션 attribute 의 사용자 객체에 인가 결정 정보를 담아 둘 때 어떤 attribute 후보를 시도하고, 그 객체에서 어떤 키로 effect/정책/스코프/역할/권한을 추출할지 정의합니다.

Authorization RequestAttributes / Headers

Authorization 도 동일한 공통 Bridge.RequestAttributes / Bridge.Headers 클래스를 재사용합니다. 키 구조와 기본값은 위 Authentication RequestAttributes 키 · Authentication HTTP 헤더 이름 표와 100% 동일하며, prefix 만 다음과 같이 다릅니다:

• contexa.bridge.authorization.request-attributes.* — 39 필드, 표 동일
• contexa.bridge.authorization.headers.* — 27 필드, 표 동일

같은 표를 다시 그리지 않고 prefix 만 안내하는 이유는 코드(BridgeProperties.java) 가 한 클래스를 3개 위치에서 참조하기 때문입니다 — 표 본문은 단일 진실의 출처를 유지합니다.

Delegation Session 키

contexa.bridge.delegation.session 아래의 속성으로, Delegation.Session 에 바인딩됩니다. 외부 시스템이 위임(agent delegation) 관련 정보 — agent ID, objective, 허용 operation/resource, 승인 필요, 만료 등 — 를 세션 attribute 의 사용자 객체에 담아둘 때 어떤 키를 시도할지 정의합니다.

Delegation RequestAttributes / Headers

Delegation 도 동일한 공통 Bridge.RequestAttributes / Bridge.Headers 클래스를 재사용합니다. 키 구조와 기본값은 Authentication RequestAttributes 키 · Authentication HTTP 헤더 이름 표와 100% 동일하며, prefix 만 다음과 같이 다릅니다:

• contexa.bridge.delegation.request-attributes.* — 39 필드, 표 동일
• contexa.bridge.delegation.headers.* — 27 필드, 표 동일

보안 Kafka 속성

contexa.security.kafka 아래의 속성으로, SecurityKafkaProperties에 바인딩됩니다. Contexa 보안 이벤트 파이프라인의 Kafka 토픽 이름을 구성합니다.

security:
  kafka:
    topic:
      authorization: security-authorization-events
      authentication: auth-events
      incident: security-incident-events
      threat: threat-indicators
      audit: security-audit-events
      general: security-events
      dlq: security-events-dlq
      soar-action: soar-action-events
    dlq:
      max-retries: 3
      retry-delay-ms: 5000
      alert-threshold: 10

관련 문서: Zero Trust 보안 참조 | SOAR 자동화 참조

OpenTelemetry 속성

contexa.opentelemetry 아래의 속성으로, OpenTelemetryProperties에 바인딩됩니다. 분산 추적, 메트릭 내보내기, 관측성을 위한 OpenTelemetry 통합을 구성합니다.

contexa:
  opentelemetry:
    enabled: true
    service-name: "my-application"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

Security Plane 속성

contexa.security.plane 아래의 속성으로, SecurityPlaneProperties에 바인딩됩니다. 분산 security-plane agent, Kafka 토픽, Redis relay, 모니터링 배치, deduplication 윈도우, 비동기 보안 분석에 사용하는 LLM executor pool을 구성합니다.

security:
  plane:
    agent:
      name: SecurityPlaneAgent-1
      auto-start: true
      organization-id: default-org
      execution-mode: ASYNC
      auto-approve-low-risk: false
      event-timeout-ms: 30000
      max-deferred-retries: 3
    llm-executor:
      core-pool-size: 2
      max-pool-size: 2
      queue-capacity: 50
    deduplication:
      enabled: true
      window-minutes: 5
      cache-size: 10000

관련 문서: Zero Trust 플로우, SOAR 참조

라우터 속성

contexa.security.router 아래의 속성으로, SecurityRouterProperties에 바인딩됩니다. 이벤트 라우팅 결정에 사용하는 점수 임계값을 정의합니다 (SOAR 자동화 / 차단 / 분석 신뢰도 / pass-through).

이벤트 속성

contexa.security.event 아래의 속성으로, SecurityEventProperties에 바인딩됩니다. 이벤트 발행 게이트, 비동기 executor pool, 계층별 지연 예산, 중복 제거 캐시를 구성합니다.

콜드패스 속성

contexa.security.coldpath 아래의 속성으로, SecurityColdPathProperties에 바인딩됩니다. 비동기 LLM 분석 경로의 계층별 신뢰도 기준값을 정의합니다.

파이프라인 속성

contexa.security.pipeline 아래의 속성으로, SecurityPipelineProperties에 바인딩됩니다. 보안 이벤트 파이프라인의 Redis · Kafka 전송 경로를 구성합니다.

참고: contexa.security.pipeline.redis 는 빈 marker 그룹입니다. 실제 Redis 동작은 contexa.security.plane.redis · security.zerotrust.redis 에서 구성합니다.

보안 Redis 속성

contexa.security.redis 아래의 속성으로, SecurityRedisProperties에 바인딩됩니다. Contexa 보안 이벤트의 Redis pub/sub 채널 이름, Redis stream 키, TTL, 메모리 임계값을 구성합니다.

스케줄러 락 속성

contexa.scheduler.lock 아래의 속성으로, ContexaSchedulerLockProperties (record) 에 바인딩됩니다. 다중 JVM 환경에서 @Scheduled + @SchedulerLock 메서드의 단일 실행을 보장하는 ShedLock auto-configuration 을 제어합니다. 단일 인스턴스 배포에서도 기본값을 유지해도 됩니다 — 락은 항상 성공하고 오버헤드는 무시 가능합니다.

데이터소스 속성

contexa.datasource 아래의 속성으로, ContexaDataSourceProperties 에 바인딩됩니다. Contexa 가 자체 메타데이터(정책, 사용자, 감사 로그 등)를 저장하는 데이터베이스 연결을 정의합니다. 호스트 application 의 spring.datasource 와 격리할 수 있습니다.

전체 구성 예제

Redis, Kafka, 외부 OpenTelemetry 수집기를 사용하는 분산 배포를 위한 프로덕션 준비 application.yml로 모든 인프라 속성을 결합한 것입니다.

# Infrastructure configuration for Contexa distributed deployment
contexa:
  enabled: true
  infrastructure:
    mode: DISTRIBUTED
    redis:
      enabled: true
    kafka:
      enabled: true
    observability:
      enabled: true
      open-telemetry-enabled: true

  # Multi-tier caching
  cache:
    type: HYBRID
    local:
      max-size: 5000
      default-ttl-seconds: 120
    redis:
      default-ttl-seconds: 600
      key-prefix: "contexa:cache:"
    pubsub:
      enabled: true
      channel: "contexa:cache:invalidation"
    domains:
      users:
        local-ttl-seconds: 1800
        redis-ttl-seconds: 3600
      roles:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      permissions:
        local-ttl-seconds: 14400
        redis-ttl-seconds: 28800
      groups:
        local-ttl-seconds: 7200
        redis-ttl-seconds: 14400
      policies:
        local-ttl-seconds: 15
        redis-ttl-seconds: 120
      soar:
        local-ttl-seconds: 900
        redis-ttl-seconds: 900
      hcad:
        local-ttl-seconds: 86400
        redis-ttl-seconds: 86400

  # OpenTelemetry
  opentelemetry:
    enabled: true
    service-name: "contexa-production"
    exporter-endpoint: "http://otel-collector.monitoring:4317"
    sampling-probability: 0.1

  # Security Infrastructure
  security:
    kafka:
      topic:
        dlq: "security-events-dlq"
    redis:
      ttl:
        minutes: 60
      memory:
        max-mb: 1024
    plane:
      agent:
        organization-id: "default-org"
        execution-mode: "ASYNC"
      llm-executor:
        core-pool-size: 2
        max-pool-size: 2
      deduplication:
        enabled: true
        window-minutes: 5
        cache-size: 10000