> [!IMPORTANT]
> **`sources/*.json` 파일은 자동 생성된 산출물입니다. 직접 편집하지 마십시오.**
> 모든 소스 추가 및 수정은 `build_sources.py`에서 이루어져야 하며, `python build_sources.py`를 실행하여 적용해야 합니다. 수동 편집은 다음 빌드 시 덮어쓰여집니다.

#### 소스 스키마```json
{
  "name": "MyPrivateDB",
  "endpoint": "https://api.myprivatedb.com/search?q={target}",
  "method": "GET",
  "headers": { "Authorization": "Bearer {MY_API_KEY}" },
  "regex_pattern": "([\\w.+-]+@[\\w-]+\\.[\\w.]+):([\\S]+)",
  "required_api_key_name": "MY_API_KEY",
  "api_key_slots": ["{MY_API_KEY}"],
  "input_type": "email",
  "output_type": ["username", "ip"],
  "pivot_types": ["email", "username"],
  "confidence": 0.9
}

`scan` (without `--autoscan`) runs Phase 1 only — breach sources, no pivot/dork/scrape.

---

### 재귀적 눈사태 엔진

스캔 중 발견된 모든 식별자(침해 기록, 도크 히트, 스크래핑된 페이스트/텔레그램 콘텐츠 등)는 새로운 정보 시드로 처리됩니다. 각 자산에 대해 엔진은 4단계를 순차적으로 실행합니다: 침해 스캔 → 해시 크랙 → 도크 → 스크래핑. **모든 4단계**에서 추출된 식별자는 수집되어 새로운 시드로 재주입됩니다. 그런 다음 하위 자산은 `asyncio.gather`를 통해 동시에 처리됩니다.```
[email protected]
  └─► [Breach] username: j.doe      ──► [Breach + Crack + Dork + Scrape]
  │         └─► github.com/jdoe     ──► [Breach + Crack + Dork + Scrape]
  └─► [Breach] hash: 5f4dcc...      ──► [AutoCrack] → "password123"
  │         └─► [Breach] password-recycling scan across all sources
  └─► [Dork] [email protected]          ──► [Breach + Crack + Dork + Scrape]
  └─► [Scrape/paste] [email protected] ──► [Breach + Crack + Dork + Scrape]

JSON 내보내기에는 `_meta` 블록이 포함되어 있으며, 여기에는 `scan_id`, `target`, `timestamp`, `nox_version`, `pivot_depth_reached`가 포함되어 있습니다. 이로 인해 모든 내보내기 파일은 사건 관리 플랫폼에 수집하기 위해 자체 설명이 가능합니다.

모든 출력은 정리됩니다 — 프록시 오류, 시간 초과, 추적 정보는 제거됩니다. 실행 가능한 정보만 포함됩니다.

---

## 파일시스템 레이아웃```
~/.nox/
├── sources/               # Auto-generated JSON source plugins
├── reports/               # Generated forensic reports
├── logs/                  # Runtime log (nox.log)
├── wordlists/             # Hash cracking wordlists
├── vault/                 # Secure storage
└── nox_cache.db           # Forensic persistence database (SQLite)

~/.config/nox-cli/
├── apikeys.json           # API keys — chmod 0600, never committed to VCS
└── logs/
    └── nox_system.log     # Silent system log: API events, rate-limits, crack attempts

# .deb install (isolated venv)
/opt/nox-cli/
├── nox.py
├── build_sources.py
├── requirements.txt
├── sources/
└── .venv/                 # Isolated Python environment (PEP 668 compliant)

설치 후 스크립트는 자동으로 다음을 수행합니다:
1. `/opt/nox-cli/.venv`에 격리된 가상 환경을 생성합니다.
2. venv 내부에 모든 Python 종속성을 설치합니다 (PEP 668 준수 — 시스템 오염 제로).
3. 124개의 소스 플러그인을 빌드합니다.
4. `/usr/bin/nox-cli` → `/opt/nox-cli/nox-wrapper.sh`를 링크합니다.

### 옵션 2: 소스에서```bash
git clone https://github.com/nox-project/nox-framework.git
cd nox-framework
pip install -r requirements.txt
python build_sources.py
python3 nox.py

**Step 2 — API 키 구성**

`build_sources.py`는 첫 실행 시 `~/.config/nox-cli/apikeys.json` 파일을 생성하며, 지원되는 모든 서비스가 미리 채워져 있습니다. 이 파일은 `chmod 0600` 권한으로 설정되며, VCS에 커밋되지 않습니다.

이것은 **단일 정식 키 저장소**입니다. 모든 소스는 런타임에 이 파일에서 읽어옵니다.```bash
# Edit the file directly
nano ~/.config/nox-cli/apikeys.json

# Or inspect plugin status and key configuration
nox-cli --list-sources

## CLI 참조```
usage: nox-cli [-h] [-t TARGET] [-i] [--version]
               [--autoscan] [--fullscan] [--no-pivot] [--depth N]
               [--dork TARGET] [--scrape TARGET]
               [--crack HASH] [--no-online-crack]
               [--analyze PASS] [--list-sources] [--reset-sources]
               [--tor] [--proxy URL] [--guardian-off] [--allow-leak]
               [--threads N] [--timeout N]
               [-o FILE] [--format {json,csv,html,md,pdf}]
               [--diff]

  -t, --target TARGET     Target to scan (auto-detected type)
  -i, --interactive       Launch interactive REPL
  --version               Show version and exit
  --autoscan              Full pipeline: breach + pivot + dork + scrape
  --fullscan              Breach + pivot only (no dork/scrape)
  --no-pivot              Disable recursive pivot enrichment
  --depth N               Avalanche pivot depth (default: 2)
  --dork TARGET           Google/Bing/SearXNG dorking for leaked documents
  --scrape TARGET         Paste site + Telegram scraping
  --crack HASH            Identify and crack a hash
  --no-online-crack       Local wordlist only — no data sent to third-party APIs
  --analyze PASS          Deep password strength analysis
  --list-sources          Plugin debug: input type, confidence, key status
  --reset-sources         Force resync of source plugins from package
  --tor                   Route all traffic through Tor (port 9050)
  --proxy URL             HTTP/S or SOCKS5 proxy URL
  --guardian-off          Bypass OPSEC kill-switch (direct connection)
  --allow-leak            Allow direct connection if proxy/Tor is unavailable
  --threads N             Concurrency limit (default: 20)
  --timeout N             Request timeout in seconds (default: 15)
  -o, --output FILE       Output file path
  --format FORMAT         Output format: json, csv, html, md, pdf
  --diff                  Show only new findings vs last cached scan

## 경로, 디렉토리의 구성 프로필 정보

### 경로, 브라우저 , 프로그램, 운영 체제

사용자 경로를 편집하고 도구, 함수 및 사용자가 선택한 단어 목록의 위치를 변경하는 옵션:```
Command        Description
-----------    ---------------------------------------------------------------
autoscan       Full pipeline: breach + pivot + dork + scrape
scan           Breach intelligence scan only
dork           Google/Bing/SearXNG dorking for leaked documents
scrape         Paste site + Telegram scraping
crack          Identify and crack a hash
analyze        Deep password strength analysis
graph          ASCII identity graph of last scan
visualize      ASCII relationship map (Target → Data → Pivots)
pivot <n>      Re-scan using result #n as new pivot seed
search <q>     Filter in-memory records by keyword
sources        Plugin debug: input type, confidence, key status
export         Export results (json / csv / html / md / pdf)
tor            Toggle Tor routing on/off
proxy          Set or clear proxy URL
config         Configure threads / timeout / depth
help           Show this menu
quit           Exit NOX

---

## 소스 관리

### 소스 추가

**1. `build_sources.py`에서 정의하세요:**```python
_auth("NewIntelDB", "breaches",
      "https://api.newinteldb.com/v1/search?q={target}", "GET",
      {"results": "$.results"},
      headers={"X-API-Key": "{NEWINTELDB_API_KEY}"},
      api_key_slots=["{NEWINTELDB_API_KEY}"],
      normalization_map={"email": "email", "password": "password"},
      input_type="email",
      output_type=["username", "ip"],
      confidence=0.85)

> [!NOTE]
> 빌더는 빌드 시점에 모든 소스를 검증합니다: GET 엔드포인트는 `{target}`을 포함해야 하며, 변동 가능한 소스는 `reliability_score ≤ 4`여야 하고, `confidence` 필드를 명시적으로 설정하여 공식에서 도출된 값을 재정의할 수 있습니다.

---

## .deb 패키지 빌드하기```bash
gem install fpm
bash build_deb.sh
sudo dpkg -i dist/nox-cli_*_all.deb