Introduzione

NOX è un motore di intelligence sulle minacce informatiche appositamente progettato per operatori che richiedono velocità, sicurezza operativa e profondità in un unico framework coeso. Non è un wrapper attorno a strumenti esistenti — è una piattaforma di intelligence completamente asincrona e guidata da plugin con una rigorosa separazione tra logica di esecuzione e definizioni delle sorgenti.

Caratteristiche

Architettura

Progettazione Guidata da Plugin

NOX opera su una rigorosa separazione delle responsabilità: nox.py è un motore di esecuzione puro e agnostico — gestisce I/O asincrono, impronte JA3, gestione delle sessioni SSL, pivot ricorsivo e correlazione dei risultati. Non contiene logica di intelligence hardcoded.

Tutta l'intelligence è definita come plugin JSON in sources/. Questi plugin sono l'unica fonte di verità per ciò che NOX interroga, come si autentica e cosa estrae. Lo strumento di build build_sources.py è l'unico modo autorizzato per crearli o modificarli.``` build_sources.py ──► sources/*.json ──► nox.py (runtime loader) [Builder] [Plugins] [Execution Engine]

> [!IMPORTANTE]
> **I file `sources/*.json` sono artefatti generati automaticamente. Non modificarli mai direttamente.**
> Tutte le aggiunte e modifiche alle sorgenti devono essere effettuate in `build_sources.py` e applicate eseguendo `python build_sources.py`. Le modifiche manuali verranno sovrascritte alla successiva build.

#### Schema delle Sorgenti```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
}

Supported fields: name, endpoint, method, headers, regex_pattern (o json_root + normalization_map), required_api_key_name, api_key_slots, input_type, output_type, pivot_types, confidence.

Pipeline Autoscan

--autoscan (CLI) / autoscan (REPL) esegue l'intera pipeline di intelligence in un unico comando:``` 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` (senza `--autoscan`) esegue solo la Fase 1 — fonti di violazione, nessun pivot/dork/scrape.

---

### Motore Valanga Ricorsivo

Ogni identificatore scoperto durante una scansione — da record di violazione, risultati dork o contenuti scraped da paste/Telegram — viene trattato come un nuovo seme di intelligence. Per ogni asset, il motore esegue quattro fasi in sequenza: scansione violazione → cracking hash → dork → scraping. Gli identificatori estratti da **tutte e quattro le fasi** vengono raccolti e reiniettati come nuovi semi. Gli asset figli vengono quindi elaborati concorrentemente tramite `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 — deduplicazione globale; nessun identificatore viene mai elaborato due volte, indipendentemente dalla fase che lo ha scoperto
• Semaforo globale — limite di concorrenza condiviso unico in tutto l'albero di scoperta, rispettando --threads
• --depth N — profondità di pivot configurabile (default: 2); un limite rigido impedisce la ricorsione incontrollata
• --no-pivot — disabilita l'arricchimento ricorsivo per una scansione rapida solo basata su violazioni

Hash Pivoting

Quando un hash viene trovato nei dati di una violazione durante --autoscan:

1. Il tipo di hash viene identificato (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Più API di tabelle arcobaleno vengono interrogate concorrentemente in un'attività in background
3. Se decifrato — il testo in chiaro viene registrato, il record viene aggiornato e la password viene inserita nella coda di pivot per l'analisi del riutilizzo delle password su tutte le fonti di violazione
4. Se non decifrato — il fallimento viene registrato in nox_system.log, l'hash viene conservato nel report e il pivot su tutte le altre risorse continua immediatamente

Il processo di decifratura è completamente non bloccante. Un timeout o un fallimento dell'API non mette mai in pausa la scansione. Usa --no-online-crack per limitare la decifratura solo alla wordlist locale (nessun dato inviato ad API di terze parti).

Guardian Proxy Engine

Il Guardian Engine è il layer OPSEC a configurazione zero di NOX. Si attiva automaticamente quando non viene fornito alcun flag --proxy o --tor.

Ordine di risoluzione:

1. proxies.txt — se presente nella directory di lavoro, NOX carica e ruota attraverso i proxy elencati.
2. Recupero dinamico — se proxies.txt è assente, il Guardian Engine recupera un elenco fresco di proxy pubblici ad alta anonimità, convalida ciascuno e conserva il pool convalidato in memoria per la sessione. Nulla viene scritto su disco.
3. Connessione diretta — se non vengono trovati proxy validi, NOX torna a una connessione diretta e emette un avviso.

[!WARNING] I pool di proxy pubblici sono intrinsecamente infrastrutture non fidate. Per operazioni sensibili, fornisci sempre un proxy controllato tramite --proxy o instrada attraverso Tor tramite --tor.

Reportistica

Tutti i formati di report includono un dashboard di Riepilogo Esecutivo:

I report includono anche una Visualizzazione della Catena di Pivot che mostra l'intero percorso relazionale dal seme iniziale alla scoperta finale:``` [[email protected]] -> [LeakA / username:jdoe] -> [Dork: leaked .env] -> [[email protected]]

Le esportazioni JSON includono un blocco `_meta` con `scan_id`, `target`, `timestamp`, `nox_version` e `pivot_depth_reached` — rendendo ogni esportazione auto-descrittiva per l'ingestione in piattaforme di gestione dei casi.

---

## Struttura del filesystem```
~/.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)

Prerequisiti

• Python 3.8+
• pip (python3-pip su Debian/Kali)
• Tor (opzionale) — richiesto solo per --tor. Su Kali: sudo apt install tor -y. Il servizio tor deve essere in esecuzione sulla porta 9050.

Installazione

Opzione 1: Debian / Kali Linux — Pacchetto .deb isolato (Consigliato)

Scarica il pacchetto .deb dalla pagina delle Release, quindi esegui:

sudo dpkg -i nox-framework*.deb
``````bash
sudo dpkg -i nox-cli_*_all.deb
nox-cli --help

Il post-install script automaticamente:

1. Crea un ambiente virtuale isolato in /opt/nox-cli/.venv
2. Installa tutte le dipendenze Python all'interno del venv (PEP 668 compliant — inquinamento zero del sistema)
3. Compila i 124 plugin sorgente
4. Collega /usr/bin/nox-cli → /opt/nox-cli/nox-wrapper.sh

Opzione 2: Da sorgente```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

---

## Avvio rapido

**Passaggio 1 — Compilare i plugin sorgente** *(solo da sorgente — .deb lo fa automaticamente)*```bash
python build_sources.py

Passaggio 2 — Configurare le chiavi API

build_sources.py crea ~/.config/nox-cli/apikeys.json al primo avvio, pre-popolato con ogni servizio supportato. Il file è chmod 0600 e non viene mai committato in VCS.

Questo è il singolo archivio chiave canonico — tutte le fonti lo leggono in fase di esecuzione.```bash

Edit the file directly

nano ~/.config/nox-cli/apikeys.json

Or inspect plugin status and key configuration

nox-cli --list-sources

> [!NOTE]
> Qualsiasi chiave impostata su `INSERT_API_KEY_HERE` o `""` viene considerata non configurata — quella fonte viene ignorata silenziosamente. Le fonti senza requisito di chiave sono sempre attive.
>
> **Priorità di caricamento:** variabile d'ambiente (es. `export HIBP_API_KEY=xxx`) → `~/.config/nox-cli/apikeys.json`

**Passaggio 3 — Esecuzione**

> [!NOTE]
> **Interruttore di sicurezza OPSEC:** Per impostazione predefinita, NOX attiva il Guardian Engine (rotazione automatica del proxy). Usa `--guardian-off` per connetterti direttamente.```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

Riferimento 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

Lancia il REPL interattivo senza argomenti:```bash
nox-cli

Imposta FINDOMAIN_BLACKLIST_URL con l'URL della blacklist dei domini. La blacklist predefinita contiene 4k sottodomini delle risposte dei record PTR come static, dyn e altro.``` 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

**Esempi:**```
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

Gestione delle sorgenti

Aggiunta di una sorgente

1. Definisci in 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. Ricostruzione:**```bash
python build_sources.py

[!NOTE] Il builder convalida ogni sorgente al momento della build: gli endpoint GET devono contenere {target}, le sorgenti volatili devono avere reliability_score ≤ 4 e il campo confidence può essere impostato esplicitamente per sovrascrivere il valore derivato dalla formula.

Creazione del pacchetto .deb```bash

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

---

## Disclaimer legale

> [!WARNING]
> **NOX è destinato esclusivamente a:**
> - Test di penetrazione autorizzati e impegni di red team con esplicito consenso scritto
> - Analisi dell'esposizione aziendale su asset di tua proprietà o per i quali hai un contratto di valutazione
> - Digital forensics e risposta agli incidenti
> - Ricerca accademica e di sicurezza in ambienti controllati e isolati
>
> **L'uso non autorizzato di questo strumento contro sistemi, reti o individui senza esplicita autorizzazione scritta è un reato penale** ai sensi del Computer Fraud and Abuse Act (CFAA, 18 U.S.C. § 1030), del Computer Misuse Act 1990 (CMA) e della legislazione equivalente in tutte le principali giurisdizioni a livello mondiale.
>
> Gli autori e i contributori di NOX non si assumono **alcuna responsabilità** per eventuali danni diretti, indiretti, incidentali o consequenziali derivanti dall'uso improprio di questo software. Scaricando, installando o eseguendo NOX, accetti incondizionatamente di rispettare tutte le leggi locali, nazionali e internazionali applicabili e di prendere di mira solo sistemi e dati per i quali detieni un'autorizzazione esplicita e documentata.
>
> **Se non accetti questi termini, non utilizzare questo software.**

---

## Licenza

[Apache License 2.0](https://github.com/nox-project/nox-framework/blob/HEAD/LICENSE.txt)