GUI는 **순수한 뷰 레이어**입니다. 엔진 출력을 렌더링하고 분석가가 신뢰 기준(trust floor)을 이동할 수 있게 합니다. 자체적인 재구성 로직은 포함하지 않습니다.

---

## 신뢰도 모델 (제품 전체의 신뢰성)

각 단계는 [0, 1] 범위의 신뢰도를 가지며, **증거 확증(evidence corroboration)**을 통해 구축됩니다:```
confidence = per-technique base rate
           + bonus for each independent corroborating signal
                 (source IP, device, successful outcome, temporal adjacency, broad-consent flags)
           − penalty for missing signals (e.g. no source IP to corroborate origin)

**실측 자료(ground truth) 출처.** 정확한 입력은 실제 테넌트에서 실행된 BadZure / MAAD-AF 실행에서 수집된 원격 계측(telemetry)이며, 통합 감사 로그를 공격 도구 자체의 활동 기록과 조인해 레이블을 붙입니다(도구가 유발한 모든 이벤트는 온체인(on-chain)에 있고, 그 외 모든 것은 정상 활동입니다 — `nv/calibration.py`의 `LABELED_SCHEMA` 참조). 실제 실행을 가리키기 전까지는 `eval/calibration_cases.py`가 문서화된 형태의 **프록시** 말뭉치를 제공하며, 이로부터 피팅된 모든 아티팩트는 출처에 `source="proxy"`로 표시되어 프록시 피팅이 실제 실행으로 오인될 수 없습니다. `calibration.proxy.json`이 바로 번들된 프록시 아티팩트입니다.

번들된 프록시 말뭉치에서의 피팅은 명확한 개선입니다 — Brier 0.398 → 0.045, ECE 0.576 → 0.081, AUC 0.81 → 0.91, 그리고 0.60 기준선에서 정상 활동에 대한 오탐율은 0.69에서 0.00으로 급감합니다(v1 사전 확률은 정상 활동에 대해 심하게 과신하고 있었습니다). 프록시는 의도적으로 보수적입니다. 실제 배포할 가중치를 산출하는 것은 라이브 테넌트 실행입니다.

## 신뢰 무결성 (Phase 3)

두 가지 일급 제어 장치가 잘못된 입력으로부터 재구성을 보호합니다:

- **인가 범위 게이트** (`nv/scope.py`) — NV는 인가 목록에 없는 환경(estate)에서는 실행을 거부합니다. 조사가 허용된 각 환경마다 `--authorize <tenant-domain>`을 사용하여 실행하세요.

- **패턴 소스 검증** (`nv/validation.py`) — 패턴은 (1) 신뢰할 수 있는 소스 허용 목록, (2) 콘텐츠 체크섬/변조 검사, (3) 스키마 정상성, (4) 유효한 ATT&CK 스타일 기술 ID를 모두 통과하지 않으면 라이브러리에 들어갈 수 없습니다. 승인된 모든 패턴은 감사 기록을 유지하고, 거부된 패턴은 이유와 함께 기록됩니다. 오염되거나 잘못된 형태의 피드는 거짓 재구성을 제조하기 전에 상류에서 차단됩니다. 이는 엔진이 증거에 적용하는 것과 동일한 회의주의를 패턴 자체로 옮긴 것입니다.

---

## 지식 최신성 유지 (공격자의 진화에 앞서 나가기)

재구성 엔진의 최신성은 패턴 라이브러리와, 라이브러리가 한 번도 본 적 없는 것을 처리하는 능력에 달려 있습니다. NV는 설계상 **두 개의 독립된 전선**에서 노후화 문제를 해결합니다:

### 1. 알려진 계층은 검증된 업데이트 파이프라인을 통해 최신 상태를 유지합니다

라이브러리는 하드코딩되어 있지 않습니다 — `nv/patterns.py`는 (내장 세트를 포함한) 모든 패턴을 `nv/validation.py`를 통해 로드하므로 외부 피드도 동일한 신뢰 경로로 들어옵니다. 일정에 따라 이러한 피드를 가져오는 실제 네트워크 클라이언트는 `nv/feeds.py`에 구현되어 있으며 `update_feeds.py`가 구동합니다. 신뢰 계층별 소스는 다음과 같습니다:

- **MITRE ATT&CK (STIX)** — 권위 있는 테크닉 분류 체계입니다. 커넥터는 ATT&CK STIX 인덱스를 읽고 최신 enterprise 릴리스를 가져와 NV가 추론하는 모든 작업(operation)에 대한 권위 있는 테크닉 이름과 전술(tactic)을 갱신합니다 — ATT&CK가 이후 철회하거나 폐기한 테크닉은 제외합니다. NV는 작업→테크닉 바인딩과 기본 비율 사전(base-rate prior)의 소유권을 유지하고, ATT&CK는 분류 체계를 소유합니다.
- **TAXII 2.1을 통한 검증된 CTI** — 전체 discovery → api-root → collection → objects 클라이언트입니다. 검증된 CTI 컬렉션에서 STIX attack-pattern 객체를 가져와 NV가 추적하는 테크닉을 갱신합니다. ATT&CK보다 낮은 가중치를 가집니다.
- **Sigma 커뮤니티 규칙 세트** — git 아카이브로 가져옵니다. O365/Entra 작업을 명명하고 `attack.tXXXX` 태그를 포함하는 각 클라우드/아이덴티티 규칙은 작업→테크닉 후보가 되며, 기본 비율은 규칙 자체의 심각도 `level`에서 파생된 후 커뮤니티 소스 가중치로 축소됩니다. 매핑되지 않는 규칙은 이유와 함께 건너뛰며, 추측하지 않습니다.

작업 충돌이 발생하면 커밋 전에 합집합이 신뢰도 오름차순으로 정렬되므로 권위 있는 ATT&CK 바인딩이 항상 커뮤니티 바인딩을 이깁니다. 하위 계층 콘텐츠도 계속 승인되며 확인 증거(corroboration)로 감사 기록에 남습니다. `update_library(candidates)`는 전체 세트를 검증을 통해 다시 입력하고 라이브러리를 원자적으로 재구축하므로, 오염된 피드가 라이브러리를 절반만 업데이트된 상태로 남겨둘 수 없습니다.

**허용 목록은 하나가 아니라 두 개입니다.** 검증은 이미 소스 태그를 기준으로 차단하며, 커넥터는 네트워크 계층 *호스트* 허용 목록을 추가합니다. 따라서 커넥터는 TLS를 통해 신뢰할 수 있는 호스트에서만 가져올 수 있습니다 — 이는 소스 허용 목록의 전송 계층에 해당하며, 하이재킹되거나 잘못 입력된 피드 URL에 대한 방어입니다. 모든 가져오기는 원시 페이로드 sha256, URL 및 시간을 출처로 기록하므로 이후 다시 가져올 때 상류 변경을 감지할 수 있습니다.

**피드가 늘어날수록 검증 계층이 더 중요한 이유:** 업데이트를 자동화할수록 자동 업데이트 파이프라인은 위장된 신뢰 위험이 됩니다 — 잘못되었거나 오염된 피드는 거짓 패턴을 주입하고 거짓 재구성을 만들어냅니다. NV는 수집을 적대적 상황으로 취급합니다: 모든 패턴, 모든 업데이트에 대해 허용 목록, 체크섬, 스키마, 감사 추적을 적용합니다.

### 2. 가설적(abductive) 계층은 아직 어떤 피드도 명명하지 않은 것을 처리합니다

피드는 항상 최신 수법에 뒤처져 있습니다. 가설적 추론 코어가 그 방어막입니다: 관찰된 작업이 라이브러리의 어떤 패턴과도 일치하지 **않을** 때, NV는 이를 버리지 않고 — 기본 원리에서 가장 가능성 있는 경로를 재구성한 다음 신뢰도를 낮춰 `no known match`로 표시합니다. 이는 eval 스위트(`eval/ground_truth_cases.py`)에서 검증됩니다. 여기서 의도적으로 알려지지 않은 관리 ID 토큰 탈취 단계가 탐지되고, 올바르게 순서가 매겨지며, 신뢰 기준선 아래로 정직하게 가중치가 낮아집니다.

이 두 가지가 결합되어 NV는 결코 완전히 낡은 상태가 되지 않습니다: 알려진 계층은 오염 저항 파이프라인을 통해 공개된 최첨단을 추적하고, 가설적 계층은 최첨단이 아직 따라잡지 못한 침입에 도구가 장님이 되지 않게 해줍니다.

### 권장 업데이트 주기

`nv/feeds.py`는 피드별 주기를 가지며 `update_feeds.py`는 기한이 된 것만 가져오므로, 그대로 cron이나 systemd 타이머에 넣을 수 있습니다:

- ATT&CK STIX — 90일 (연간 몇 번의 공식 릴리스).
- CTI/TAXII — 7일 (피드가 게시될 때), 항상 검증을 거침.
- Sigma — 30일.```bash
# run whatever is due, keeping state under ./.nv_feeds  (cron-friendly)
python3 update_feeds.py

# force all feeds now but only report what would change
python3 update_feeds.py --force --dry-run

# run fully offline against captured fixtures (no network)
python3 update_feeds.py --offline eval/fixtures --force

이것은 로그인, 동의 부여, 서비스 사용자 및 역할 변경, 사서함 액세스를 유지합니다 — NV가 한 번도 명명하지 않은 ID 작업을 포함하므로 여전히 가추적 계층에 도달합니다 — 나머지는 버립니다. 표준 `AuditData` 열을 포함하는 CSV 또는 각 레코드가 `AuditData` 객체인 JSON/JSONL(invictus-ir 연구 코퍼스가 제공하는 형태)을 읽습니다.

**3 — 범위 제한 재구성.** 엔진은 명시적으로 승인하지 않은 테넌트에서는 실행을 거부합니다:```bash
python3 run_nv.py your_events.jsonl reconstruction.json \
    --authorize yourtenant.onmicrosoft.com

ingest는 IAM/STS/로그인 이벤트(새로운 IAM 작업 포함, abductive 레이어에 도달하도록)와 S3 객체 읽기를 유지하며, 테넌트 도메인이 아닌 AWS **계정**을 기준으로 범위를 제한한다. 동일한 abductive 코어, 신뢰도 모델, 신뢰 하한선이 변경 없이 적용된다.

GUI에는 또한 **데모 데이터 배너**와 앱 내 "자체 데이터 연결" 가이드가 포함되어 있어, 누구든 이 앱을 열면 자체 데이터를 연동하기 전까지는 재구성 결과가 공개 샘플 데이터임을 이해할 수 있다.

## 프로젝트 구조```
run_nv.py                        reconstruction engine entrypoint (scope-gated)
nv_extract_identity_events.py    ingest: M365/Entra unified audit log -> event model
nv_extract_cloudtrail_events.py  ingest: AWS CloudTrail -> event model      [iteration 3]
update_feeds.py     pull + validate threat-intel feeds on a cadence   [iteration 1]
calibrate.py        fit confidence weights from labeled ground truth  [iteration 2]
nv/                 the engine package
  graph.py  patterns.py  validation.py  confidence.py  reconstruct.py  scope.py
  providers.py      per-substrate op->ATT&CK vocabulary packs (Entra + AWS) [iteration 3]
  feeds.py          ATT&CK STIX / TAXII 2.1 / Sigma clients + scheduler [iteration 1]
  calibration.py    metrics + parameter fit                            [iteration 2]
eval/               evals + offline fixtures (no network, no tenant)
nv_gui.html         pure view layer (loads engine reconstruction.json)
calibration.proxy.json   bundled proxy calibration artifact           [iteration 2]

패턴 라이브러리를 최신 상태로 유지하고 신뢰도를 미세 조정하세요:```bash
python3 update_feeds.py                       # pull + validate feeds that are due
python3 calibrate.py --labeled run.jsonl --origin live --out calibration.json

---
## 상태

**실제 데이터에서 엔드투엔드(end-to-end)로 작동 중** (invictus-ir O365 데이터셋), 전체 계획에 걸쳐:

| 단계 | 항목 | 상태 |
|---|---|---|
| 1 | 정규화된 이벤트/엔티티 모델 | 완료 |
| 1 | 수집 + 정규화 (Entra/M365 교두보) | 완료 |
| 2 | 알려진 계층 (ATT&CK 패턴 라이브러리) | 완료 |
| 2 | 증거 확증 신뢰 모델 | 완료 |
| 2 | 출력 계약의 신뢰 하한 | 완료 |
| 2 | 가추적(abductive) 코어 (미지 계층) | 완료, 평가로 입증됨 |
| 2 | 순위가 매겨진 경쟁 가설 | 완료 |
| 3 | 패턴 소스 검증 계층 | 완료 |
| 3 | 승인 범위 제어 | 완료 |
| 3 | 실시간 피드 커넥터 (ATT&CK STIX / TAXII / Sigma) + 스케줄러 | 완료 |
| 4 | 실제 엔진 출력의 2열 화면 | 완료 |
| 4 | 임베딩 / 유사성 캔버스 | 완료 |
| 4 | 캔버스 기반 엔티티별 재구성 (클릭 시 체인 재실행) | 완료 |
| 4 | GUI가 엔진 `reconstruction.json`을 로드 (자신의 파일을 지정) | 완료 |
| 4 | 다중 공급자 기반 (AWS CloudTrail, 평가로 입증됨) | 완료 |
| 5 | 미관 / 테마 | 완료 |
| 5 | 신뢰도 보정 하네스 + 엔진 통합 | 완료 |

### 솔직히 밝히는 알려진 한계 (다음 반복)

- **실제 테넌트 보정 수치.** 보정 *하네스*는 완전하며
  인터페이스도 검증되었지만, 제공되는 `calibration.proxy.json`은 문서화된 형태의
  프록시 데이터에 맞추어 조정된 것입니다. 배포 가능한 가중치를 얻으려면 실제
  BadZure / MAAD-AF 실행에 하네스를 실행해야 합니다 — 이는 도입자가 수행해야 할 운영 단계입니다.
- **피드 기반 어휘 확장.** 커넥터는 NV가 이미 추론하는 작업(operations)들을 갱신할 뿐입니다.
  피드가 새 작업을 *도입*하고 이를 초기/피벗/수집 분류에 연결하도록 하는 것은
  향후 과제입니다.
- **두 번째 공급자의 지원 깊이.** AWS는 기반(substrate) 독립성의 증명(팩 + 수집 + 평가)으로 포함되어 있지만
  IAM/STS/S3만 지원합니다. AWS 팩을 확장하고, 공급자별 피드 커넥터를 추가하며,
  세 번째 기반(GCP, Okta)을 도입하는 것이 다음 단계입니다.

---


## 라이선스

Nimbus Vestige는 **source-available**(소스 공개) 방식으로 **PolyForm 비상업적 라이선스
1.0.0** 하에 제공됩니다 ([LICENSE](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/LICENSE) 참조). 전체 도구 — 재구성 엔진, 두
공급자의 수집(ingest) 모듈, GUI, 평가 하네스 —는 **비상업적** 목적, 즉
개인 프로젝트, 연구, 교육, 비영리 단체, 평가에 한해
자유롭게 열람, 실행, 사용할 수 있습니다. 결정하기 전에 모든 줄을 읽어보십시오.

**상업적 사용에는 유료 라이선스가 필요합니다** — 판매하거나 호스팅하는 제품 또는 서비스,
영리 기업의 프로덕션 또는 내부 시스템, 유료 침해 대응(incident-response) 또는
고객 용역 계약에서 사용하는 경우를 포함합니다. 자세한 내용은
[COMMERCIAL-LICENSE.md](https://gitlab.com/dobybaxter127/nimbus-vestige/-/blob/main/COMMERCIAL-LICENSE.md)를 참조하십시오.

---

### 저자

Doby Baxter 2026