Security Configuration | Contexa Docs

Zero Trust 속성

contexa.security.zerotrust 아래의 속성으로, SecurityZeroTrustProperties에 바인딩됩니다. Zero Trust 결정 모드, 핵심 임계값, hot-path 처리, 캐시 기간, 요청 추적 동작을 제어합니다. HCAD는 별도의 hcad 접두사에서 구성합니다.

속성	타입	기본값	설명
`contexa.security.zerotrust`
`.enabled`	`boolean`	`true`	Zero Trust 엔진 활성화
`.mode`	`SecurityMode`	`ENFORCE`	실행 모드: `SHADOW`(관찰) 또는 `ENFORCE`(차단)
`.max-block-mfa-attempts`	`int`	`2`	차단 우회 MFA 최대 시도 횟수
`contexa.security.zerotrust.sampling`
`.rate`	`double`	`1.0`	요청 샘플링 비율 (0.0–1.0)
`contexa.security.zerotrust.hotpath`
`.enabled`	`boolean`	`true`	hot-path 빠른 결정 활성화
`contexa.security.zerotrust.thresholds`
`.skip`	`double`	`0.3`	점검 생략 임계값 (이하)
`.optional`	`double`	`0.5`	선택적 인증 임계값
`.required`	`double`	`0.7`	필수 인증 임계값
`.strict`	`double`	`0.9`	엄격 차단 임계값
`contexa.security.zerotrust.protectable`
`.rapid-reentry-window-ms`	`long`	`5000`	보호 자원 재진입 윈도우(ms)
`contexa.security.zerotrust.redis`
`.timeout`	`int`	`5`	Redis 작업 타임아웃(초)
`.update-interval-seconds`	`int`	`30`	Redis 상태 업데이트 간격(초)
`contexa.security.zerotrust.threat`
`.initial`	`double`	`0.3`	초기 위협 점수
`contexa.security.zerotrust.cache`
`.ttl-hours`	`int`	`24`	결정 캐시 TTL(시간)
`.session-ttl-minutes`	`int`	`30`	세션 캐시 TTL(분)
`.invalidated-ttl-minutes`	`int`	`60`	무효화 캐시 TTL(분)
`contexa.security.zerotrust.session`
`.tracking-enabled`	`boolean`	`true`	세션 추적 활성화

관련 문서: Zero Trust 플로우

HCAD 속성

hcad 접두사 아래의 속성으로, HcadProperties에 바인딩됩니다. 계층적 컨텍스트 인식 탐지(HCAD) 필터 파이프라인과 기준선 학습을 구성합니다.

속성	타입	기본값	설명
`hcad`
`.enabled`	`boolean`	`true`	HCAD 필터 파이프라인 활성화 또는 비활성화
`.filter-order`	`int`	`100`	서블릿 필터 체인에서의 HCAD 필터 순서
`hcad.resource`
`.sensitive-patterns`	`List<String>`	`[]`	강화된 분석이 필요한 민감 리소스 URL 패턴
`hcad.analysis`
`.max-age-ms`	`long`	`3600000`	캐시된 분석 결과의 최대 보관 시간(ms)
`hcad.threshold`
`.base`	`double`	`0.7`	기본 이상 탐지 임계값
`.min`	`double`	`0.3`	적응 조정 후 최소 임계값
`.max`	`double`	`0.95`	적응 조정 후 최대 임계값
`.adjustment-rate`	`double`	`0.01`	피드백 주기당 임계값 적응 속도
`.sensitivity`	`double`	`1.0`	탐지 감도 전역 배율
`.warn`	`double`	`0.7`	차단 전 경고 임계값
`hcad.cache`
`.max-size`	`int`	`100000`	캐시된 분석 항목 최대 수
`.ttl-ms`	`long`	`300000`	캐시 항목 TTL(밀리초)
`.clear-on-startup`	`boolean`	`false`	애플리케이션 시작 시 모든 캐시 항목 삭제
`.local.ttl-minutes`	`int`	`10`	로컬 캐시 TTL(분)
`hcad.baseline`
`.min-confidence`	`double`	`0.3`	기준선 데이터 최소 신뢰도
`.update-alpha`	`double`	`0.1`	기준선 업데이트용 지수이동평균 알파
`.learning.enabled`	`boolean`	`true`	실시간 트래픽으로부터의 기준선 학습 활성화
`.learning.alpha`	`double`	`0.1`	온라인 기준선 적응 학습률
`.bootstrap.enabled`	`boolean`	`true`	초기 기준선 구축을 위한 부트스트랩 모드 활성화
`.bootstrap.initial-samples`	`int`	`10`	적용 전 필요한 초기 샘플 수
`.bootstrap.max-anomaly-score`	`double`	`0.85`	부트스트랩 단계 최대 이상 점수
`.statistical.enabled`	`boolean`	`true`	통계적 기준선 분석 활성화
`.statistical.min-samples`	`int`	`20`	통계 분석 최소 샘플 수
`.statistical.z-score-threshold`	`double`	`3.0`	이상치 탐지 Z-점수 임계값
`.redis.ttl-days`	`int`	`30`	Redis 기준선 데이터 TTL(일)
`hcad.feedback`
`.learning-rate`	`double`	`0.1`	임계값 조정을 위한 피드백 루프 학습률
`.retrain-threshold`	`double`	`0.7`	모델 재학습을 트리거하는 정확도 임계값
`.window-size`	`int`	`1000`	피드백 수집 슬라이딩 윈도우 크기
`hcad.orchestrator`
`.enabled`	`boolean`	`true`	조율된 분석을 위한 HCAD 오케스트레이터 활성화
`.feedback-interval`	`int`	`300`	피드백 처리 간격(초)
`.sync-batch-size`	`int`	`50`	기준선 동기화 배치 크기
`hcad.vector`
`.embedding-dimension`	`int`	`384`	행동 분석용 임베딩 벡터 차원
`.similarity-threshold`	`double`	`0.85`	행동 패턴 매칭 유사도 임계값
`.scenario-detection-enabled`	`boolean`	`true`	벡터 기반 시나리오 이상 탐지 활성화
`hcad.session`
`.cookie-name`	`String`	`JSESSIONID`	HCAD 추적용 세션 쿠키 이름
`.header-name`	`String`	`X-Session-Id`	무상태 모드에서의 세션 ID 헤더 이름
`hcad.signal`
`.chi-square-threshold`	`double`	`14.07`	신호 이상 탐지 카이제곱 임계값
`.history-size`	`int`	`100`	보관할 과거 신호 수
`.geoip.provider`	`String`	`api`	GeoIP 제공자: `api` 또는 `local`
`hcad.adaptive`
`.adjustment-rate`	`double`	`0.1`	적응형 임계값 조정 속도
`.cusum.threshold`	`double`	`5.0`	CUSUM 변화점 탐지 임계값
`.cusum.slack`	`double`	`0.5`	CUSUM 드리프트 허용 슬랙 파라미터
`.baseline.window`	`int`	`100`	적응형 기준선 윈도우 크기
`hcad.geoip`
`.enabled`	`boolean`	`false`	GeoIP 기반 위치 분석 활성화
`.db-path`	`String`	`data/GeoLite2-City.mmdb`	MaxMind GeoLite2 데이터베이스 파일 경로
`hcad.redis`
`.key-prefix`	`String`	`hcad:baseline:v2:`	HCAD 기준선 데이터의 Redis 키 접두사

현재 OSS 코드에 추가로 존재하는 HCAD 필드

속성	기본값	설명
`hcad.baseline.statistical.update-interval`	`10`	통계 기준선 갱신 간격
`hcad.feedback.baseline.update-threshold`	`0.95`	피드백을 기준선에 반영하는 임계값
`hcad.orchestrator.performance-tracking`	`true`	오케스트레이터 성능 추적 활성화
`hcad.vector.cache-ttl-hours`	`24`	행동 임베딩 캐시 TTL(시간)
`hcad.vector.max-cached-embeddings`	`1000`	캐시할 임베딩 최대 수
`hcad.signal.covariance.min-samples`	`30`	공분산 분석 최소 샘플 수
`hcad.signal.geoip.api-url`	`https://ipapi.co/{ip}/json/`	원격 GeoIP API URL 템플릿
`hcad.signal.timing.bucket-count`	`7`	타이밍 버킷 수
`hcad.signal.timing.interval.history-size`	`100`	타이밍 구간 이력 크기
`hcad.sampling.random.floor`	`0.01`	최소 랜덤 샘플링 비율
`hcad.sampling.random.ceiling`	`0.03`	최대 랜덤 샘플링 비율
`hcad.sampling.composite.identifier.enabled`	`true`	복합 식별자 샘플링 활성화
`hcad.similarity.hot-path-threshold`	`0.7`	hot-path 판단에 사용하는 유사도 임계값
`hcad.adaptive.min.trust.score`	`0.7`	적응형 제어 최소 신뢰 점수
`hcad.pre-trigger.enabled`	`true`	전체 분석 전 pre-trigger 휴리스틱 활성화
`hcad.pre-trigger.cooldown-seconds`	`15`	반복 pre-trigger cooldown
`hcad.pre-trigger.in-flight-ttl-seconds`	`15`	in-flight pre-trigger TTL
`hcad.pre-trigger.negative-cache-seconds`	`3`	negative cache 유지 시간
`hcad.pre-trigger.redline-score`	`70`	redline 위험 점수
`hcad.pre-trigger.high-risk-score`	`50`	고위험 임계값
`hcad.pre-trigger.medium-risk-score`	`30`	중위험 임계값
`hcad.pre-trigger.low-baseline-confidence-threshold`	`0.35`	낮은 기준선 신뢰도 임계값
`hcad.pre-trigger.failed-login-burst-threshold`	`3`	실패 로그인 폭주 임계값
`hcad.pre-trigger.request-burst-threshold`	`12`	요청 폭주 임계값
`hcad.pre-trigger.rapid-request-interval-ms`	`1000`	급격한 요청 간격 윈도우
`hcad.pre-trigger.sensitive-path-indicators`	`[/admin/, /export, /download, /sensitive/, /critical/]`	민감 경로 패턴 (포함 매칭)

구성 예제

YAML

hcad:
  enabled: true
  filter-order: 100
  resource:
    sensitive-patterns:
      - /admin/api/security-test/sensitive/**
      - /admin/api/security-test/critical/**
  threshold:
    base: 0.7
    sensitivity: 1.0
  baseline:
    learning:
      enabled: true
      alpha: 0.1
    bootstrap:
      enabled: true
      initial-samples: 10
  geoip:
    enabled: false
    db-path: data/GeoLite2-City.mmdb

세션 보안 속성

contexa.security.session 아래의 속성으로, SecuritySessionProperties에 바인딩됩니다. 토큰 생성, 헤더/베어러 추출, hijack 이벤트 wiring, 쿠키 이름, 세션 이상 탐지에 사용하는 위험 임계값을 구성합니다.

속성	타입	기본값	설명
`contexa.security.session.create.allowed`	`boolean`	`true`	세션/토큰 생성 허용
`contexa.security.session.header.name`	`String`	`X-Auth-Token`	토큰 전달 헤더 이름
`contexa.security.session.bearer.enabled`	`boolean`	`true`	Bearer 토큰 파싱 활성화
`contexa.security.session.cookie.name`	`String`	`SESSION`	세션 쿠키 이름
`contexa.security.session.hijack.channel`	`String`	`security:session:hijack:event`	Hijack 이벤트 채널 이름
`contexa.security.session.hijack.detection.enabled`	`boolean`	`true`	Hijack 탐지 활성화
`contexa.security.session.threat.ip-change-risk`	`double`	`0.4`	IP 변경 위험 가중치
`contexa.security.session.threat.ua-change-risk`	`double`	`0.3`	User-Agent 변경 위험 가중치
`contexa.security.session.threat.rapid-access-threshold-ms`	`int`	`100`	짧은 간격 접근 임계값
`contexa.security.session.threat.rapid-access-risk`	`double`	`0.2`	짧은 간격 접근 위험 가중치
`contexa.security.session.threat.thresholds.monitoring`	`double`	`0.5`	모니터링 임계값
`contexa.security.session.threat.thresholds.grace-period`	`double`	`0.7`	유예 구간 임계값
`contexa.security.session.threat.thresholds.invalidation`	`double`	`0.9`	세션 무효화 임계값

관련 문서: 상태 관리 참조

Step-Up 속성

contexa.security.stepup 아래의 속성으로, SecurityStepUpProperties에 바인딩됩니다. 다요소 인증(MFA) 또는 추가 승인이 필요한 고위험 작업 시 Step-Up 인증의 최대 시도 횟수 및 잠금 시간을 정의합니다.

속성	타입	기본값	설명
`contexa.security.stepup`
`.max-attempts`	`int`	`3`	Step-Up 인증 실패 시 허용되는 최대 시도 횟수
`.lockout-duration`	`int`	`300`	최대 실패 시도 횟수 초과 시 계정 잠금 기간 (초)

Decision Plane 속성

contexa.saas 아래의 속성으로, Contexa SaaS Decision Plane 서비스와의 통합을 제어합니다. 로컬 결정 결과를 피드백 및 성능 메트릭과 함께 원격 Decision Plane으로 전송하기 위한 엔드포인트, 주기, 재시도 정책 및 OAuth2 클라이언트를 구성합니다.

속성	타입	기본값	설명
`contexa.saas`
`.enabled`	`boolean`	`false`	SaaS Decision Plane으로의 의사결정 포워딩 활성화 여부
`.endpoint`	`String`	`https://saas.ctxa.ai`	SaaS Decision Plane 기본 엔드포인트 URL
`.include-reasoning`	`boolean`	`false`	포워딩 데이터에 결정 근거 포함 여부
`.include-raw-analysis-data`	`boolean`	`false`	포워딩 데이터에 원시 분석 데이터 포함 여부
`.outbox-batch-size`	`int`	`50`	아웃박스 이벤트 전송 배치 크기
`.max-retry-attempts`	`int`	`10`	전송 실패 시 최대 재시도 횟수
`.retry-initial-backoff-ms`	`long`	`1000`	재시도 최초 대기 시간 (밀리초)
`.retry-max-backoff-ms`	`long`	`60000`	재시도 최대 대기 시간 (밀리초)
`.dispatch-interval-ms`	`long`	`30000`	이벤트 디스패치 간격 (밀리초)
`.pseudonymization-secret`	`String`	`default-dev-secret-change-in-prod`	데이터 가명화용 솔트/비밀키
`.global-correlation-secret`	`String`	`default-dev-correlation-secret`	글로벌 상관관계 ID 생성용 비밀키
`contexa.saas.oauth2`
`.enabled`	`boolean`	`true`	OAuth2 클라이언트 연동 활성화 여부
`.registration-id`	`String`	`contexa-saas-client`	OAuth2 클라이언트 등록 식별자
`.token-uri`	`String`	`https://saas.ctxa.ai/oauth2/token`	OAuth2 토큰 요청 URI
`.client-id`	`String`	`dev-client`	클라이언트 ID
`.client-secret`	`String`	`dev-secret`	클라이언트 시크릿
`.scope`	`String`	`saas.xai.decision.ingest,...`	OAuth2 요청 스코프 목록 (쉼표 구분)
`.expiry-skew-seconds`	`int`	`30`	액세스 토큰 만료 판정 보정 시간 (초)

Distributed Enforcement 속성

contexa.security.tiered 아래의 속성으로, TieredStrategyProperties에 바인딩됩니다. 로컬 에이전트와 클라우드/협업 에이전트 간의 계층형(Tiered) 보안 분석 및 통제 실행 정책을 구성합니다. 계층별 활성화 상태, 트런케이션 버퍼, 검색 제한, 보안 정책을 상세 튜닝합니다.

속성	타입	기본값	설명
`contexa.security.tiered`
`.enabled`	`boolean`	`true`	계층형 분석 및 통제 전략 활성화 여부
`.native-structured-output-enabled`	`boolean`	`true`	구조화된 출력(JSON/Schema)에 대한 LLM 네이티브 지원 활용 여부
`.telemetry-enabled`	`boolean`	`true`	Tiered 보안 텔레메트리 발행 여부
`.trusted-proxy-validation-enabled`	`boolean`	`true`	신뢰 프록시 IP 검증 활성화 여부
`contexa.security.tiered.layer1` / `layer2` (분석 계층 설정)
`.layer1.enabled`	`boolean`	`true`	1계층(로컬 신속 분석) 활성화 여부
`.layer1.default-budget-profile`	`String`	`CORTEX_L1_INTERACTIVE_STRICT`	1계층 기본 리소스 예산 프로필
`.layer2.enabled`	`boolean`	`false`	2계층(클라우드 정밀 분석) 활성화 여부
`.layer2.default-budget-profile`	`String`	`CORTEX_L2_EXPERT_STRICT`	2계층 기본 리소스 예산 프로필
`.layer2.enable-soar`	`boolean`	`false`	2계층 정밀 분석 결과에 따라 SOAR 액션 자동 트리거 여부
`contexa.security.tiered.security` (보안 의사결정 세부 튜닝)
`.security.vector-search-limit`	`int`	`3`	위협 판단 시 유사의사결정 벡터 검색 매칭 건수 상한
`.security.max-similar-events`	`int`	`2`	유사 위협 탐지를 위해 비교할 최근 이벤트 최대 수
`.security.max-rag-documents`	`int`	`3`	의사결정 보완을 위해 RAG로 주입할 컨텍스트 문서 상한
`.security.timeout-ms`	`long`	`7000`	2계층 원격 요청 처리 타임아웃 (밀리초)

보안 구성