Introducción

NOX es un motor de inteligencia contra amenazas cibernéticas diseñado específicamente para operadores que requieren velocidad, seguridad operativa y profundidad en un único marco cohesivo. No es un envoltorio de herramientas existentes — es una plataforma de inteligencia completamente asíncrona basada en plugins, con una separación estricta entre la lógica de ejecución y las definiciones de fuentes.

Características

Arquitectura

Diseño Basado en Plugins

NOX opera con una estricta separación de responsabilidades: nox.py es un motor de ejecución puro y agnóstico — maneja E/S asíncrona, huellas JA3, gestión de sesiones SSL, pivoteo recursivo y correlación de resultados. No contiene lógica de inteligencia codificada.

Toda la inteligencia se define como plugins JSON en sources/. Estos plugins son la única fuente de verdad para lo que NOX consulta, cómo se autentica y qué extrae. La herramienta de construcción build_sources.py es la única forma autorizada de crearlos o modificarlos.``` build_sources.py ──► sources/*.json ──► nox.py (runtime loader) [Builder] [Plugins] [Execution Engine]

> [!IMPORTANT]
> **`sources/*.json` archivos son artefactos generados automáticamente. Nunca los edites directamente.**
> Todas las adiciones y modificaciones de fuentes deben realizarse en `build_sources.py` y aplicarse ejecutando `python build_sources.py`. Las ediciones manuales se sobrescribirán en la próxima compilación.

#### Esquema de Fuentes```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
}

Campos admitidos: 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 de Autoscan

--autoscan (CLI) / autoscan (REPL) ejecuta el pipeline de inteligencia completo en un solo 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` (sin `--autoscan`) ejecuta solo la Fase 1 — fuentes de breach, sin pivot/dork/scrape.

---

### Motor de Avalancha Recursivo

Cada identificador descubierto durante un escaneo — desde registros de breach, hits de dork, o contenido scraped de paste/Telegram — es tratado como una nueva semilla de inteligencia. Para cada activo, el motor ejecuta cuatro fases secuencialmente: breach scan → hash crack → dork → scrape. Los identificadores extraídos de **todas las cuatro fases** son recolectados y reinyectados como nuevas semillas. Los activos hijos son luego procesados concurrentemente mediante `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 — desduplicación global; ningún identificador se procesa dos veces, independientemente de la fase que lo descubrió
• Semáforo global — límite de concurrencia compartido único en todo el árbol de descubrimiento, respetando --threads
• --depth N — profundidad de pivote configurable (predeterminado: 2); tope duro evita recursión descontrolada
• --no-pivot — deshabilita el enriquecimiento recursivo para un escaneo rápido solo de brechas

Pivoteo de Hashes

Cuando se encuentra un hash en datos de brecha durante --autoscan:

1. Se identifica el tipo de hash (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Se consultan múltiples APIs de rainbow-table concurrentemente en una tarea en segundo plano
3. Si se descifra — se registra el texto claro, se actualiza el registro y la contraseña se inyecta en la cola de pivote para análisis de reciclaje de contraseñas en todas las fuentes de brecha
4. Si no se descifra — el fallo se registra en nox_system.log, el hash se conserva en el informe y el pivoteo sobre todos los demás activos continúa inmediatamente

El proceso de descifrado es completamente no bloqueante. Un tiempo de espera o fallo de API nunca pausa el escaneo. Use --no-online-crack para restringir el descifrado solo a la lista de palabras local (no se envían datos a APIs de terceros).

Motor Proxy Guardian

El Motor Guardian es la capa OPSEC de configuración cero de NOX. Se activa automáticamente cuando no se proporciona la bandera --proxy o --tor.

Orden de resolución:

1. proxies.txt — si está presente en el directorio de trabajo, NOX carga y rota entre los proxies listados.
2. Obtención dinámica — si proxies.txt está ausente, el Motor Guardian obtiene una lista nueva de proxies públicos de alto anonimato, valida cada uno y mantiene el grupo validado en memoria para la sesión. No se escribe nada en disco.
3. Conexión directa — si no se encuentran proxies válidos, NOX recurre a una conexión directa y emite una advertencia.

[!WARNING] Los pools de proxies públicos son infraestructura inherentemente no confiable. Para compromisos sensibles, siempre proporcione un proxy controlado mediante --proxy o enrute a través de Tor mediante --tor.

Informes

Todos los formatos de informe incluyen un panel de resumen ejecutivo:

Los informes también incluyen una Visualización de Cadena de Pivote que muestra la ruta relacional completa desde la semilla inicial hasta el descubrimiento final:``` [[email protected]] -> [LeakA / username:jdoe] -> [Dork: leaked .env] -> [[email protected]]

Las exportaciones JSON incluyen un bloque `_meta` con `scan_id`, `target`, `timestamp`, `nox_version` y `pivot_depth_reached`, lo que hace que cada exportación se autodescriba para su ingesta en plataformas de gestión de casos.

Todo el resultado está saneado: se eliminan errores de proxy, tiempos de espera y trazas. Solo se incluye inteligencia procesable.

---

## Estructura del sistema de archivos```
~/.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)

Requisitos previos

• Python 3.8+
• pip (python3-pip en Debian/Kali)
• Tor (opcional) — requerido solo para --tor. En Kali: sudo apt install tor -y. El servicio tor debe estar ejecutándose en el puerto 9050.

Instalación

Opción 1: Debian / Kali Linux — .deb aislado (Recomendado)

Descargue el paquete .deb desde la página de lanzamientos, luego ejecute:```bash sudo dpkg -i nox-cli_*_all.deb nox-cli --help

El script de post-instalación automáticamente:
1. Crea un entorno virtual aislado en `/opt/nox-cli/.venv`
2. Instala todas las dependencias de Python dentro del venv (compatible con PEP 668 — cero contaminación del sistema)
3. Construye los 124 plugins fuente
4. Enlaza `/usr/bin/nox-cli` → `/opt/nox-cli/nox-wrapper.sh`

### Opción 2: Desde el código fuente```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

Inicio rápido

Paso 1 — Compilar plugins desde el código fuente (solo desde el código fuente — .deb lo hace automáticamente)```bash python build_sources.py

**Paso 2 — Configurar claves API**

`build_sources.py` crea `~/.config/nox-cli/apikeys.json` en la primera ejecución, prellenado con todos los servicios compatibles. El archivo tiene permisos `chmod 0600` y nunca se confirma en VCS.

Este es el **único almacén de claves canónico** — todas las fuentes lo leen en tiempo de ejecución.```bash
# Edit the file directly
nano ~/.config/nox-cli/apikeys.json

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

[!NOTE] Cualquier clave configurada como INSERT_API_KEY_HERE o "" se considera no configurada — esa fuente se omite silenciosamente. Las fuentes sin requisito de clave siempre están activas.

Prioridad de carga: variable de entorno (ej. export HIBP_API_KEY=xxx) → ~/.config/nox-cli/apikeys.json

Paso 3 — Ejecutar

[!NOTE] Interruptor de seguridad OPSEC: Por defecto, NOX activa el motor Guardian (rotación automática de proxies). Use --guardian-off para conectarse directamente.```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

## Referencia de 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

Iniciar el REPL interactivo sin argumentos:```bash nox-cli

Tenemos la función `proc_find_suspect_task` a la que podemos engancharnos para localizar una estructura de tarea que coincida con nuestros criterios de búsqueda. Por ejemplo, buscar una tarea con un PID o nombre de comando específico.```
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

Ejemplos:``` 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

---

## Gestión de fuentes

### Añadir una fuente

**1. Define en `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. Reconstruir:```bash python build_sources.py

> [!NOTE]
> El constructor valida cada fuente en tiempo de compilación: los puntos finales GET deben contener `{target}`, las fuentes volátiles deben tener `reliability_score ≤ 4`, y el campo `confidence` se puede establecer explícitamente para anular el valor derivado de la fórmula.

---

## Construyendo el paquete .deb```bash
gem install fpm
bash build_deb.sh
sudo dpkg -i dist/nox-cli_*_all.deb

Aviso Legal

[!WARNING] NOX está diseñado exclusivamente para:

• Pruebas de penetración autorizadas y compromisos de equipo rojo con consentimiento explícito por escrito
• Análisis de exposición corporativa en activos que posee o que está contratado para evaluar
• Forense digital y respuesta a incidentes
• Investigación académica y de seguridad en entornos controlados y aislados

El uso no autorizado de esta herramienta contra sistemas, redes o individuos sin permiso explícito por escrito es un delito penal según la Ley de Fraude y Abuso Informático (CFAA, 18 U.S.C. § 1030), la Ley de Uso Indebido de Computadoras de 1990 (CMA) y la legislación equivalente en todas las jurisdicciones principales del mundo.

Los autores y contribuyentes de NOX no aceptan ninguna responsabilidad por daños directos, indirectos, incidentales o consecuentes que surjan del mal uso de este software. Al descargar, instalar o ejecutar NOX, acepta incondicionalmente cumplir con todas las leyes locales, nacionales e internacionales aplicables, y atacar únicamente sistemas y datos para los cuales posea autorización explícita y documentada.

Si no acepta estos términos, no utilice este software.

Licencia

Apache License 2.0