Sentivex

패밀리 API 를 소비해 만든 통합 클라이언트. 외부 공개 API 는 없다.

개요

Sentivex 는 역할×퍼스펙티브 OpenXDR 통합 클라이언트다. 자체 분석엔진·데이터스토어가 없고, SOC 대시보드·인시던트/알럿/엔드포인트·TI·헌팅·보고서·코파일럿 전 화면을 패밀리 API(SEE·SIT·SCTI·Auth) 소비로 구성한다. 모든 엔드포인트는 이 문서의 다른 솔루션에서 온 것이며, Sentivex 자체가 노출하는 공개 API 는 없다. 퍼스펙티브 9종(analyst/hunter/ciso/responder/general/pm/tenant/super/sales)이 메뉴 가시성을 결정한다.

소비 백엔드

Sentivex 는 외부 공개 API 가 없다(전부 세션 게이트 BFF). 외부 개발자용 정본 스펙은 아래 백엔드다.

화면 영역	소비 백엔드
데이터 조회(OCSF) · SEE 특화 · 측정랩	SEE enrich API
인시던트·티켓·HITL·대시보드	SIT REST (세션교환 토큰)
TI 조회·헌팅	SCTI API
OSA 알럿	osawebhook
로그인·역할·메뉴 카탈로그	Auth IdP (OIDC·카탈로그 API)
보고서·개인화·코파일럿	prefs-store · SEE copilot · LiteLLM

인증 · svx_session · 브로드롤

항목	계약
로그인	OIDC(auth IdP) /api/auth/oidc/start → callback → HS256 JWT 쿠키 svx_session(7일). 페이로드: role(현재 퍼스펙티브)·roles[]·allowedTenants[](데이터 격리 경계 — tid 와 다른 네임스페이스)
브로드롤 계약	auth openxdr-roles.ts 롤 키 = sentivex roles.ts 퍼스펙티브 키 100% 동일 유지(한쪽 변경 시 양쪽 동기)
파생 토큰	SIT per-user = POST {SIT}/api/auth/exchange(BFF_EXCHANGE_SECRET). SEE 분석 트리거 = see_session 서명(SEE_SESSION_SECRET 동일값 계약)
OPEN 모드	무세션 시 데모 super(개발 기본) · 운영 fail-closed(SVX_OPEN_MODE)

BFF 라우트

전부 svx_session 게이트 · 서버 전용 프록시 · 점수 스트립 통과. 외부 공개 API 는 아니다.

카테고리	라우트	백엔드
데이터 조회(OCSF)	list · entity-kpi · bundle · compare · hashrefs · series · siem/query · logs · incidents · ingest-health · metric/[key] · verify · wazuh · news	SEE enrich
SEE 특화	see/ti-pipeline/{recent,state,top-threats} · ti/pipeline{,-state,-stream(SSE)} · agents/analyze · measure/*(12종)	SEE enrich
SIT 프록시	pm/{incidents, incident/[key]{,decision,agent-state}, incident-action, agent-queue, hitl-executions, dashboard, issues, me, projects, runbook, soc-roles, summary, notifications}	SIT (exchange 토큰)
SCTI 프록시	ti/[...path] · ti/benign · ti/threat-hunter	SCTI
OSA	osa/alerts{,/[id]} · osa/stats	osawebhook
보고서	report(CRUD) · report-template · report/{period,generate,revise,compliance,contribution,analyses,bundle,export,pdf}	prefs-store + SEE + LiteLLM
개인화/AI	dash-layout · copilot · copilot/conversations{,/[id]}	prefs-store · copilot-store · LiteLLM
인증/관리	auth/oidc/start · auth/callback · login · logout · admin/{health,license,db-counts,menus/[key]} · ops/[...path]	auth IdP 등

주의사항

패밀리 전 기능을 API 소비만으로 구축하며 실측으로 확정한 주의사항들. 이 랩의 API 를 소비할 모든 개발자에게 그대로 적용됩니다.

#	주의사항
1	RSC 는 쿠키를 안 보낸다 — 페이지/RSC 에서 자기 BFF 호출 시 세션 쿠키 수동 전달(internalGet). 잊으면 서버에서만 401
2	테넌트 2중 네임스페이스 — IdP tid ≠ 데이터 태그 tenant_name. 격리는 반드시 allowedTenants(+scopeByTenant), 빈 목록=fail-closed
3	벤더 스코프는 별개 축 — data_vendor_name 조합 뷰와 테넌트 보안 경계를 혼동 금지
4	소스 화이트리스트 강등 주의사항 — 미등록 source 는 묵시 강등되어 가짜 표기. 신규 소스는 ALLOWED_SOURCES 등록 필수
5	-latest 는 동결 스냅샷(2026-06-28) — 신규 문서는 DS 에만 있다. -latest 미발견 ≠ 버그
6	DS 번들은 top-level 요약을 안 채운다 — mitre/hashes/joins null → 원본 doc+evidences 직접 추출 폴백 필요
7	점수 비노출은 2중 가드 — BFF stripScores(키 제거) + 렌더 redactScore(자유텍스트). 신규 자유텍스트 경로는 반드시 후자 통과
8	LLM 게이트웨이는 HTTP 200 으로도 실패한다 — body error 검사 + 빈 content throw(가짜 완성 금지)
9	WS URL 은 헬퍼로만 — localhost 하드코딩은 원격 사용자에게 1006. 워커 이벤트는 .35 에만 존재
10	스토어 다운 = graceful(기능 축소), 404 = not_found 정상 계약({found:false}) — 오류로 오독 금지
11	외부 호출은 전부 타임아웃 가드(AbortController) — 실패 시 백엔드 URL 비노출 일반 메시지
12	exchange 시크릿 부재의 퇴행 경로 — dev 는 상대 OPEN 모드 편승, 운영은 unauthorized 로 정직 강등(무음 성공 금지)

퀵스타트

외부 키 발급 경로는 아직 없습니다(auth 소관 — 개발자 프로그램 트랙). 내부 개발자 기준: git clone → .env.example→.env.local(SEE_URL 등 원격 백엔드 지정) → pnpm i → pnpm pm2:dev(:42010, webpack 고정) → OPEN 모드로 즉시 데이터 화면.

첫 호출 예

curl 'http://localhost:42010/api/list?entity=alerts&source=ocsf_ds&size=5'

도메인 · 포트 · env

구분	값
운영 도메인	sentivex.in-bridge.com (.35 pm2 sentivex-web)
로컬 개발	:42010 (stag-sentivex.in-bridge.com 경유 권장) · 배포 = deploy.sh sentivex(오프박스 빌드)
env(서버 전용 원칙)	SEE_URL·SIT_URL·SCTI_URL·OSA_URL·OIDC 4종·SVX_SESSION_SECRET(운영 필수)·BFF_EXCHANGE_SECRET·SEE_SESSION_SECRET·COPILOT/PREFS/LITELLM 계약 키. NEXT_PUBLIC 금지 — 유일 예외 NEXT_PUBLIC_SEE_WS_URL
에러 규약	BFF 는 백엔드 내부(URL/스택) 비노출 일반 메시지 + 상태코드(401 UNAUTHENTICATED · 403 TENANT_FORBIDDEN · 502 프록시 실패). KPI 미지원=null→"—"(가짜 숫자 금지). rate limit 자체 없음(백엔드 의존)