contexa-core 선택

Contexa SaaS 연결(선택)

Contexa 애플리케이션이 판정 결과와 통계를 Contexa SaaS로 보내고, 위협 신호 · 탐지 전략 · 기준선 씨앗을 받아 판정에 쓰는 선택 기능입니다. 기본으로 꺼져 있고, 켜지 않아도 Contexa의 모든 판정 기능은 그대로 동작합니다.

먼저 알아 둘 것. 이 기능의 보내는 쪽(클라이언트)은 OSS에 모두 있지만, 받는 서버는 OSS에 없습니다. 기본 연결 대상은 Contexa가 운영하는 https://saas.ctxa.ai이고, 그 서비스에서 받은 OAuth2 클라이언트 자격이 있어야 실제로 보낼 수 있습니다.

한눈에 보기

보내는 것과 받는 것보내는 채널과 받는 채널은 각각 따로 켭니다. 판정 전달만 contexa.saas.enabled=true로 함께 켜집니다.

보내기DB 보관함에 먼저 쌓고 비동기로 전송

  • 판정 전달허용 · 분석 대기가 아닌 판정(가명 처리)
  • 판정 피드백 · 위협 결과관리자가 차단을 풀 때
  • 프롬프트 맥락 감사프롬프트 원문 없이 해시만
  • 기준선 통계 · 성능 지표주기적으로 집계
OAuth2 client_credentials
Contexa SaaSsaas.ctxa.ai

받기한 시간마다 당겨와 프롬프트에 사용

  • 위협 신호맞는 신호를 최대 3개까지 고르고, 프롬프트 본문에는 가장 잘 맞는 1개를 싣습니다
  • 탐지 전략 묶음
  • 기준선 씨앗개인 · 조직 기준선이 부족할 때 보강

켜기

contexa:
  saas:
    enabled: true
    pseudonymization-secret: ${CONTEXA_SAAS_PSEUDONYM_SECRET}     # 32바이트 이상
    global-correlation-secret: ${CONTEXA_SAAS_CORRELATION_SECRET} # 32바이트 이상
    oauth2:
      client-id: ${CONTEXA_SAAS_CLIENT_ID}
      client-secret: ${CONTEXA_SAAS_CLIENT_SECRET}
  • 켜면 시작할 때 끝점 · 비밀값 · OAuth2 설정 · 범위(scope)를 검사하고, 맞지 않으면 시작하지 않습니다. 두 비밀값이 비었거나, 개발용 기본값이거나, 32바이트보다 짧으면 거부합니다.
  • 판정 전달은 Contexa DB의 보관함(outbox) 표에 먼저 저장한 뒤 보냅니다. 보관함 저장소가 없으면 아무것도 보내지 않습니다.
  • 보내기가 실패해도 판정 처리는 멈추지 않습니다.

무엇이 나가나

  • 가명 처리: 사용자 · 세션 · IP는 테넌트 범위의 HMAC-SHA256 가명으로 바꿔 보냅니다. IP는 테넌트를 넘어 같은 IP를 묶어 볼 수 있는 전역 상관 키도 함께 만듭니다.
  • 그대로 나가는 것: 요청 경로, 국가 · 도시, 새 단말 · 불가능한 이동 여부, 1차 · 2차 분석 평가, 자원 ID, 사용자 역할, 프롬프트 해시 · 토큰 수 등.
  • 기본으로 빠지는 것: 판정 근거 문장(include-reasoning, 기본 false), 분석 원자료(include-raw-analysis-data, 기본 false). 프롬프트 맥락 감사는 프롬프트 원문을 보내지 않고 해시만 보냅니다.

전송과 재시도

판정 전달은 상관 ID로 중복을 막고 보관함에 대기로 저장한 뒤, 트랜잭션이 끝나면 따로 보냅니다(POST {endpoint}/api/saas/runtime/xai/decision-ingestions, Bearer 토큰).

결과처리
성공전달 완료
429 · 5xx · 연결 실패지수 백오프로 다시 보냄(1초부터 retry-max-backoff-ms 60000까지)
429가 아닌 4xxDEAD_LETTER(다시 보내지 않음)
시도가 max-retry-attempts(10) 이상DEAD_LETTER

재시도는 dispatch-interval-ms(30초)마다 outbox-batch-size(50)건씩 하고, 여러 서버에서도 한 서버만 실행합니다.

채널별 켜기

채널설정언제 보내거나 받나
판정 전달contexa.saas.enabled판정마다(허용 · 분석 대기 제외)
판정 피드백contexa.saas.decision-feedback.enabled관리자가 차단을 풀 때
위협 결과contexa.saas.threat-outcome.enabled관리자가 차단을 풀 때
프롬프트 맥락 감사contexa.saas.prompt-context-audit.enabled1차 · 2차 분석이 프롬프트 맥락을 만들 때
성능 지표contexa.saas.performance-telemetry.enabled시간 단위로 집계해 보냄
기준선 통계 · 씨앗contexa.saas.baseline-signal.enabled조직 기준선 분포를 주(월요일 시작) 단위로 집계하고, 끝난 주의 집계를 보냄(조직 기준선 3개 · 사용자 기준선 25개 미만이면 보내지 않음). 집계 · 보내기는 contexa.saas.baseline-signal.publish-interval-ms마다 도는데, 이 값을 적지 않으면 1일입니다(설정 색인에 보이는 7일 기본값은 이 주기에 쓰이지 않음). 씨앗은 1시간마다 받음
위협 신호contexa.saas.threat-intelligence.enabled1시간마다 받음, 90분 캐시
탐지 전략contexa.saas.detection-strategy.enabled1시간마다 받음
현재 버전의 제한. 위협 지식 받기(contexa.saas.threat-knowledge.enabled)는 켜도 실제로 당겨오지 않습니다. 이 설정이 판정 엔진 쪽으로 전달되지 않기 때문입니다.

주요 설정

설정기본값뜻언제 바꾸나
contexa.saas.enabledfalseSaaS 연결 전체 켜기SaaS로 보내려면 true
contexa.saas.endpointhttps://saas.ctxa.ai받는 서버 주소다른 SaaS 주소를 받았을 때
contexa.saas.pseudonymization-secret개발용 값(켜면 거부)가명 HMAC 키(32바이트 이상)켤 때 반드시(32바이트 이상)
contexa.saas.global-correlation-secret개발용 값(켜면 거부)전역 IP 상관 키(32바이트 이상)켤 때 반드시(32바이트 이상)
contexa.saas.oauth2.token-urihttps://saas.ctxa.ai/oauth2/token토큰 발급 주소다른 토큰 주소를 받았을 때
contexa.saas.oauth2.client-id / client-secretdev-client / dev-secret발급받은 자격으로 바꿔야 합니다켤 때 반드시
contexa.saas.include-reasoningfalse판정 근거 문장도 보냄판정 근거 문장까지 보내기로 했을 때
contexa.saas.max-retry-attempts10이 횟수부터 DEAD_LETTER네트워크가 불안정할 때 늘림
contexa.saas.dispatch-interval-ms30000재시도 간격재전송을 더 빨리 · 느리게 할 때

나머지 채널별 경로 · 주기를 포함한 contexa.saas.* 설정 전체(64개)는 설정 색인에 있습니다.