> [!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`（不带`--autoscan`）仅运行第一阶段——仅针对泄露源，无后续的 pivot/dork/scrape 步骤。

---

### 递归雪崩引擎

在扫描过程中发现的每一个标识符——无论来自泄露记录、dork 命中结果，还是从 paste 或 Telegram 内容中抓取的信息——都被视为一个新的情报种子。对于每个资产，引擎依次执行四个阶段：泄露扫描 → 哈希破解 → dork → 抓取。**全部四个阶段**中提取出的标识符都会被收集并重新注入作为新的种子。随后，子资产会通过 `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. 在虚拟环境中安装所有 Python 依赖（符合 PEP 668 — 零系统污染）
3. 构建 124 个源插件
4. 创建软链接 `/usr/bin/nox-cli` → `/opt/nox-cli/nox-wrapper.sh`

### 选项二：从源码安装```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

**步骤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]
> The builder validates every source at build time: GET endpoints 必须包含 `{target}`，volatile sources 必须有 `reliability_score ≤ 4`，并且 `confidence` 字段可以显式设置以覆盖公式推导的值。

---

## 构建 .deb 软件包```bash
gem install fpm
bash build_deb.sh
sudo dpkg -i dist/nox-cli_*_all.deb