Введение

NOX — это специализированный движок киберразведки, предназначенный для операторов, которым требуется скорость, операционная безопасность и глубина в едином связном фреймворке. Это не обёртка вокруг существующих инструментов — это полностью асинхронная, управляемая плагинами платформа анализа угроз со строгим разделением логики выполнения и определений источников.

Возможности

Архитектура

Проектирование на основе плагинов

NOX работает по принципу строгого разделения обязанностей: nox.py — это чистый, агностический движок выполнения — он обрабатывает асинхронный ввод-вывод, JA3-отпечатки, управление SSL-сессиями, рекурсивный разворот и корреляцию результатов. Он не содержит жёстко заданной логики разведки.

Вся разведывательная информация определена как JSON-плагины в sources/. Эти плагины являются единственным источником правды о том, что NOX запрашивает, как он аутентифицируется и что извлекает. Инструмент сборки build_sources.py — единственный разрешённый способ создать или изменить их.``` build_sources.py ──► sources/*.json ──► nox.py (runtime loader) [Builder] [Plugins] [Execution Engine]

> [!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
}

Поддерживаемые поля: name, endpoint, method, headers, regex_pattern (или json_root + normalization_map), required_api_key_name, api_key_slots, input_type, output_type, pivot_types, confidence.

Конвейер автопоиска

--autoscan (CLI) / autoscan (REPL) выполняет полный конвейер разведки одной командой:``` For each asset (seed + every discovered identifier): ├─ Phase 1 — Breach Scan │ 124 sources queried in parallel (async) │ ├─ Phase 2 — Hash Crack (non-blocking, concurrent) │ Hashes found in breach data → rainbow-table APIs → cracked plaintext │ → password-recycling breach scan │ ├─ Phase 3 — Dorking │ Google/Bing/SearXNG dorks → leaked docs, .env files, SQL dumps │ → new identifiers extracted and re-injected │ └─ Phase 4 — Scraping Pastebin, IntelX, Telegram CTI channels → credential extraction → new identifiers extracted and re-injected

All identifiers discovered in phases 1–4 are re-injected as new seeds. Child assets are processed concurrently via asyncio.gather.

`scan` (без `--autoscan`) запускает только Фазу 1 — источники утечек, без пивота/дорка/скрапа.

---

### Движок рекурсивной лавины

Каждый идентификатор, обнаруженный во время сканирования — из записей утечек, результатов дорка или содержимого скрапированных paste/Telegram — рассматривается как новый источник разведданных. Для каждого актива движок последовательно выполняет четыре фазы: сканирование утечек → взлом хеша → дорк → скрап. Идентификаторы, извлечённые из **всех четырёх фаз**, собираются и повторно внедряются как новые источники. Затем дочерние активы обрабатываются параллельно с помощью `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]

• seen_assets set — глобальная дедупликация; ни один идентификатор не обрабатывается дважды, независимо от того, на какой фазе он был обнаружен
• Глобальный семафор — единое ограничение параллелизма для всего дерева обнаружения, соблюдающее --threads
• --depth N — настраиваемая глубина обхода (по умолчанию: 2); жёсткая граница предотвращает неконтролируемую рекурсию
• --no-pivot — отключает рекурсивное обогащение для быстрого сканирования только по утечкам

Хеш-пивотинг

Когда хеш найден в данных утечки во время --autoscan:

1. Определяется тип хеша (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Несколько API для rainbow-таблиц запрашиваются параллельно в фоновой задаче
3. Если расшифрован — открытый текст логируется, запись обновляется, и пароль помещается в очередь пивотинга для анализа повторного использования пароля по всем источникам утечек
4. Если не расшифрован — ошибка логируется в nox_system.log, хеш сохраняется в отчёте, и пивотинг по всем остальным активам продолжается немедленно

Процесс расшифровки полностью неблокирующий. Тайм-аут или сбой API никогда не приостанавливают сканирование. Используйте --no-online-crack, чтобы ограничить взлом только локальным списком слов (данные не отправляются сторонним API).

Guardианский прокси-движок

Guardианский движок — это нуль-конфигурационный слой OPSEC в NOX. Он активируется автоматически, если не указаны флаги --proxy или --tor.

Порядок разрешения:

1. proxies.txt — если файл присутствует в рабочем каталоге, NOX загружает и циклически перебирает перечисленные прокси.
2. Динамическая загрузка — если proxies.txt отсутствует, Guardианский движок получает свежий список публичных прокси с высокой анонимностью, проверяет каждый и хранит проверенный пул в памяти на время сессии. Ничего не записывается на диск.
3. Прямое подключение — если не найдено ни одного валидного прокси, NOX переключается на прямое подключение и выдаёт предупреждение.

[!WARNING] Публичные прокси-пулы по своей природе являются ненадёжной инфраструктурой. Для чувствительных заданий всегда используйте контролируемый прокси через --proxy или маршрутизацию через Tor через --tor.

Отчётность

Все форматы отчётов включают панель исполнительного резюме:

Отчёты также содержат визуализацию цепочки пивотинга с полным реляционным путём от начальной точки до последнего обнаружения:``` [[email protected]] -> [LeakA / username:jdoe] -> [Dork: leaked .env] -> [[email protected]]

JSON-экспорты содержат блок `_meta` с полями `scan_id`, `target`, `timestamp`, `nox_version` и `pivot_depth_reached` — что делает каждый экспорт самодокументируемым для загрузки в платформы управления инцидентами.

Все выходные данные очищаются — ошибки прокси, тайм-ауты и трассировки удаляются. Включается только полезная разведывательная информация.

---

## Filesystem Layout```
~/.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)

Предварительные требования

• Python 3.8+
• pip (python3-pip на Debian/Kali)
• Tor (необязательно) — требуется только для --tor. В Kali: sudo apt install tor -y. Служба tor должна быть запущена на порту 9050.

Установка

Вариант 1: Debian / Kali Linux — Изолированный .deb (рекомендуется)

Загрузите .deb-пакет со страницы релизов, затем выполните:```bash sudo dpkg -i nox-cli_*_all.deb nox-cli --help

Скрипт после установки автоматически:
1. Создаёт изолированное виртуальное окружение в `/opt/nox-cli/.venv`
2. Устанавливает все зависимости Python внутри venv (совместимо с 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

Быстрый старт

Шаг 1 — Сборка исходных плагинов (только из исходного кода — .deb делает это автоматически)```bash python build_sources.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

[!ПРИМЕЧАНИЕ] Любой ключ, установленный в INSERT_API_KEY_HERE или "", считается не настроенным — этот источник молча пропускается. Источники, не требующие ключа, всегда активны.

Приоритет загрузки: переменная окружения (например, export HIBP_API_KEY=xxx) → ~/.config/nox-cli/apikeys.json

Шаг 3 — Выполнение

[!ПРИМЕЧАНИЕ] Аварийный выключатель OPSEC: По умолчанию NOX активирует Guardian Engine (автоматическая ротация прокси). Используйте --guardian-off для прямого подключения.```bash

Breach scan — input type auto-detected (email / domain / ip / username / hash / phone)

nox-cli -t [email protected]

Full autoscan: breach + recursive pivot + dork + scrape

nox-cli -t [email protected] --autoscan

Autoscan with Tor routing

nox-cli -t [email protected] --autoscan --tor

Autoscan with SOCKS5 proxy + PDF report

nox-cli -t [email protected] --autoscan --proxy socks5://127.0.0.1:1080 -o report.pdf --format pdf

Autoscan with custom pivot depth

nox-cli -t [email protected] --autoscan --depth 3

Breach scan only — no pivot, no dork, no scrape

nox-cli -t [email protected] --no-pivot

Domain scan

nox-cli -t company.com

Hash identification and cracking

nox-cli --crack 5f4dcc3b5aa765d61d8327deb882cf99

Hash cracking — local wordlist only, no third-party API calls

nox-cli --crack 5f4dcc3b5aa765d61d8327deb882cf99 --no-online-crack

Password strength analysis

nox-cli --analyze "P@ssw0rd123"

Google dorking

nox-cli --dork [email protected]

Paste / Telegram scraping

nox-cli --scrape [email protected]

Compare scan against last cached result — show only new findings

nox-cli -t [email protected] --diff

Plugin debug: loaded sources, input types, confidence, key status

nox-cli --list-sources

Force resync of source plugins from package

nox-cli --reset-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

REPL

Запустите интерактивный REPL без аргументов:```bash nox-cli

```markdown
[comment]: # (This is a placeholder for translation)

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 Re-scan using result #n as new pivot seed search 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

**Примеры:**```
nox> autoscan [email protected]
nox> graph
nox> visualize
nox> pivot 3
nox> search admin
nox> export pdf investigation.pdf
nox> sources
nox> config threads 30
nox> config depth 3
nox> proxy socks5://127.0.0.1:1080
nox> tor

Управление источниками

Добавление источника

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)

**2. Пересборка:**```bash
python build_sources.py

[!NOTE] Сборщик проверяет каждый источник во время сборки: GET endpoints должны содержать {target}, нестабильные источники должны иметь reliability_score ≤ 4, а поле confidence может быть установлено явно, чтобы переопределить значение, полученное из формулы.

Сборка .deb пакета```bash

gem install fpm bash build_deb.sh sudo dpkg -i dist/nox-cli_*_all.deb

---

## Правовое предупреждение

> [!WARNING]
> **NOX предназначен исключительно для:**
> - Авторизованного тестирования на проникновение и red team-мероприятий при наличии явного письменного согласия
> - Анализа корпоративной подверженности рискам на активах, которые вам принадлежат или которые вы уполномочены оценивать
> - Цифровой криминалистики и реагирования на инциденты
> - Академических и исследовательских работ в области безопасности в контролируемых изолированных средах
>
> **Несанкционированное использование данного инструмента против систем, сетей или физических лиц без явного письменного разрешения является уголовным преступлением** в соответствии с Законом о компьютерном мошенничестве и злоупотреблениях (CFAA, 18 U.S.C. § 1030), Законом о неправомерном использовании компьютеров 1990 года (CMA) и аналогичным законодательством во всех крупных юрисдикциях мира.
>
> Авторы и участники NOX **не несут никакой ответственности** за любые прямые, косвенные, случайные или последующие убытки, возникшие в результате неправомерного использования данного программного обеспечения. Загружая, устанавливая или запуская NOX, вы безоговорочно соглашаетесь соблюдать все применимые местные, национальные и международные законы, а также воздействовать только на те системы и данные, на которые у вас есть явное документированное разрешение.
>
> **Если вы не согласны с этими условиями, не используйте данное программное обеспечение.**

---

## Лицензия

[Лицензия Apache 2.0](https://github.com/nox-project/nox-framework/blob/HEAD/LICENSE.txt)