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가 아닌 4xx | DEAD_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.enabled | 1차 · 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.enabled | 1시간마다 받음, 90분 캐시 |
| 탐지 전략 | contexa.saas.detection-strategy.enabled | 1시간마다 받음 |
현재 버전의 제한. 위협 지식 받기(
contexa.saas.threat-knowledge.enabled)는 켜도 실제로 당겨오지 않습니다. 이 설정이 판정 엔진 쪽으로 전달되지 않기 때문입니다.
주요 설정
| 설정 | 기본값 | 뜻 | 언제 바꾸나 |
|---|---|---|---|
contexa.saas.enabled | false | SaaS 연결 전체 켜기 | SaaS로 보내려면 true |
contexa.saas.endpoint | https://saas.ctxa.ai | 받는 서버 주소 | 다른 SaaS 주소를 받았을 때 |
contexa.saas.pseudonymization-secret | 개발용 값(켜면 거부) | 가명 HMAC 키(32바이트 이상) | 켤 때 반드시(32바이트 이상) |
contexa.saas.global-correlation-secret | 개발용 값(켜면 거부) | 전역 IP 상관 키(32바이트 이상) | 켤 때 반드시(32바이트 이상) |
contexa.saas.oauth2.token-uri | https://saas.ctxa.ai/oauth2/token | 토큰 발급 주소 | 다른 토큰 주소를 받았을 때 |
contexa.saas.oauth2.client-id / client-secret | dev-client / dev-secret | 발급받은 자격으로 바꿔야 합니다 | 켤 때 반드시 |
contexa.saas.include-reasoning | false | 판정 근거 문장도 보냄 | 판정 근거 문장까지 보내기로 했을 때 |
contexa.saas.max-retry-attempts | 10 | 이 횟수부터 DEAD_LETTER | 네트워크가 불안정할 때 늘림 |
contexa.saas.dispatch-interval-ms | 30000 | 재시도 간격 | 재전송을 더 빨리 · 느리게 할 때 |
나머지 채널별 경로 · 주기를 포함한 contexa.saas.* 설정 전체(64개)는 설정 색인에 있습니다.