Einleitung

NOX ist eine speziell entwickelte Engine für Cyber-Bedrohungsanalyse, die für Einsatzkräfte konzipiert wurde, die Geschwindigkeit, operative Sicherheit und Tiefe in einem einzigen kohärenten Framework benötigen. Es handelt sich nicht um einen Wrapper um vorhandene Tools – es ist eine vollständig asynchrone, plugin-gesteuerte Intelligence-Plattform mit einer strikten Trennung zwischen Ausführungslogik und Quellendefinitionen.

Funktionen

Architektur

Plugin-gesteuertes Design

NOX arbeitet mit einer strikten Trennung der Zuständigkeiten: nox.py ist eine reine, neutrale Ausführungs-Engine – sie übernimmt asynchrone E/A, JA3-Fingerprinting, SSL-Sitzungsverwaltung, rekursives Pivotieren und Ergebnis-Korrelation. Sie enthält keine fest codierte Intelligence-Logik.

Alle Intelligence wird als JSON-Plugins in sources/ definiert. Diese Plugins sind die alleinige Quelle der Wahrheit dafür, was NOX abfragt, wie es sich authentifiziert und was es extrahiert. Das Build-Tool build_sources.py ist die einzige autorisierte Möglichkeit, sie zu erstellen oder zu ändern.``` build_sources.py ──► sources/*.json ──► nox.py (runtime loader) [Builder] [Plugins] [Execution Engine]

> [!IMPORTANT]
> **`sources/*.json`-Dateien sind automatisch generierte Artefakte. Bearbeiten Sie sie niemals direkt.**
> Alle Ergänzungen und Änderungen an den Quellen müssen in `build_sources.py` vorgenommen und durch Ausführen von `python build_sources.py` angewendet werden. Manuelle Bearbeitungen werden beim nächsten Build überschrieben.

#### Quellenschema```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
}

Unterstützte Felder: name, endpoint, method, headers, regex_pattern (oder json_root + normalization_map), required_api_key_name, api_key_slots, input_type, output_type, pivot_types, confidence.

Autoscan-Pipeline

--autoscan (CLI) / autoscan (REPL) führt die vollständige Intelligence-Pipeline in einem einzigen Befehl aus:``` 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` (ohne `--autoscan`) führt nur Phase 1 aus — Verstoßquellen, kein Pivot/Dork/Scrape.

---

### Rekursive Lawinen-Engine

Jede während eines Scans entdeckte Kennung — aus Verstoßaufzeichnungen, Dork-Treffern oder gescraptem Paste/Telegram-Inhalt — wird als neuer Intelligenz-Saatkern behandelt. Für jedes Asset führt die Engine nacheinander vier Phasen aus: Breach-Scan → Hash-Crack → Dork → Scrape. Aus **allen vier Phasen** extrahierte Kennungen werden geerntet und als neue Saatkerne wieder injiziert. Kinder-Assets werden dann gleichzeitig über `asyncio.gather` verarbeitet.```
[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 — globale Deduplizierung; keine Kennung wird jemals zweimal verarbeitet, unabhängig davon, in welcher Phase sie entdeckt wurde
• Globales Semaphor — eine einzige gemeinsam genutzte Parallelitätsbegrenzung im gesamten Discovery-Baum, die --threads berücksichtigt
• --depth N — konfigurierbare Pivot-Tiefe (Standard: 2); harte Grenze verhindert unkontrollierte Rekursion
• --no-pivot — deaktiviert die rekursive Anreicherung für einen schnellen Nur-Breaches-Scan

Hash-Pivoting

Wenn ein Hash in Breach-Daten während des --autoscan gefunden wird:

1. Der Hash-Typ wird identifiziert (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Mehrere Regenbogentabellen-APIs werden gleichzeitig in einer Hintergrundaufgabe abgefragt
3. Wenn geknackt — der Klartext wird protokolliert, der Datensatz wird aktualisiert und das Passwort wird in die Pivot-Warteschlange für die Passwort-Recycling-Analyse über alle Breach-Quellen hinweg eingefügt
4. Wenn nicht geknackt — der Fehler wird in nox_system.log protokolliert, der Hash bleibt im Bericht erhalten, und das Pivoting auf allen anderen Assets wird sofort fortgesetzt

Der Crack-Vorgang ist vollständig nicht-blockierend. Ein Timeout oder ein API-Fehler pausiert den Scan nie. Verwenden Sie --no-online-crack, um das Knacken auf die lokale Wortliste zu beschränken (keine Daten werden an Drittanbieter-APIs gesendet).

Guardian Proxy Engine

Die Guardian Engine ist NOX‘ zerstörungsfreie OPSEC-Schicht. Sie aktiviert sich automatisch, wenn kein --proxy- oder --tor-Flag angegeben wird.

Auflösungsreihenfolge:

1. proxies.txt — falls im Arbeitsverzeichnis vorhanden, lädt NOX die aufgelisteten Proxys und rotiert durch sie.
2. Dynamischer Abruf — falls proxies.txt fehlt, ruft die Guardian Engine eine frische Liste hochanonymer öffentlicher Proxys ab, validiert jeden und hält den validierten Pool für die Sitzung im Speicher. Es wird nichts auf die Festplatte geschrieben.
3. Direktverbindung — falls keine gültigen Proxys gefunden werden, fällt NOX auf eine direkte Verbindung zurück und gibt eine Warnung aus.

[!WARNING] Öffentliche Proxy-Pools sind von Natur aus nicht vertrauenswürdige Infrastruktur. Verwenden Sie für sensible Einsätze immer einen kontrollierten Proxy über --proxy oder leiten Sie den Datenverkehr über Tor mittels --tor.

Berichterstattung

Alle Berichtsformate enthalten ein Executive Summary Dashboard:

Berichte enthalten auch eine Pivot-Ketten-Visualisierung, die den vollständigen relationalen Pfad vom initialen Seed zur endgültigen Entdeckung zeigt:``` [[email protected]] -> [LeakA / username:jdoe] -> [Dork: leaked .env] -> [[email protected]]

JSON-Exporte enthalten einen `_meta`-Block mit `scan_id`, `target`, `timestamp`, `nox_version` und `pivot_depth_reached` — was jeden Export selbsterklärend für die Aufnahme in Fallmanagement-Plattformen macht.

Die gesamte Ausgabe wird bereinigt — Proxy-Fehler, Timeouts und Tracebacks werden entfernt. Es werden nur umsetzbare Informationen aufgenommen.

---

## Dateisystem-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)

Voraussetzungen

• Python 3.8+
• pip (python3-pip auf Debian/Kali)
• Tor (optional) — nur erforderlich für --tor. Auf Kali: sudo apt install tor -y. Der tor-Dienst muss auf Port 9050 laufen.

Installation

Option 1: Debian / Kali Linux — Isoliertes .deb (Empfohlen)

Laden Sie das .deb-Paket von der Releases-Seite herunter, dann führen Sie aus:```bash sudo dpkg -i nox-cli_*_all.deb nox-cli --help

Das Post-Installationsskript führt automatisch Folgendes aus:
1. Erstellt eine isolierte virtuelle Umgebung unter `/opt/nox-cli/.venv`
2. Installiert alle Python-Abhängigkeiten in der venv (PEP 668 compliant — null Systemverschmutzung)
3. Baut die 124 Quell-Plugins
4. Verlinkt `/usr/bin/nox-cli` → `/opt/nox-cli/nox-wrapper.sh`

### Option 2: Aus dem Quellcode```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

Schnellstart

Schritt 1 — Quell-Plugins erstellen (nur aus dem Quellcode — .deb erledigt dies automatisch)```bash python build_sources.py

**Schritt 2 — API-Schlüssel konfigurieren**

`build_sources.py` erstellt bei erstem Start `~/.config/nox-cli/apikeys.json`, vorausgefüllt mit jedem unterstützten Dienst. Die Datei hat die Berechtigung `chmod 0600` und wird nie in VCS übertragen.

Dies ist der **einzige kanonische Schlüsselspeicher** — alle Quellen lesen zur Laufzeit daraus.```bash
# Edit the file directly
nano ~/.config/nox-cli/apikeys.json

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

[!NOTE] Jeder Schlüssel, der auf INSERT_API_KEY_HERE oder "" gesetzt ist, gilt als nicht konfiguriert – diese Quelle wird stillschweigend übersprungen. Quellen ohne Schlüsselanforderung sind immer aktiv.

Ladepriorität: Umgebungsvariable (z. B. export HIBP_API_KEY=xxx) → ~/.config/nox-cli/apikeys.json

Schritt 3 – Ausführen

[!NOTE] OPSEC-Kill-Switch: Standardmäßig aktiviert NOX die Guardian Engine (automatische Proxy-Rotation). Verwenden Sie --guardian-off, um direkt zu verbinden.```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-Referenz```
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

Starten Sie das interaktive REPL ohne Argumente:```bash nox-cli

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

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

---

## Quellenverwaltung

### Hinzufügen einer Quelle

**1. Definiere 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. Neuerstellung:```bash python build_sources.py

> [!NOTE]
> Der Builder validiert jede Quelle zur Build-Zeit: GET-Endpunkte müssen `{target}` enthalten, volatile Quellen müssen `reliability_score ≤ 4` aufweisen, und das Feld `confidence` kann explizit gesetzt werden, um den formelbasierten Wert zu überschreiben.

---

## Erstellen des .deb-Pakets```bash
gem install fpm
bash build_deb.sh
sudo dpkg -i dist/nox-cli_*_all.deb

Rechtlicher Hinweis

[!WARNING] NOX ist ausschließlich bestimmt für:

• Autorisierte Penetrationstests und Red-Team-Einsätze mit ausdrücklicher schriftlicher Zustimmung
• Unternehmensexpositionsanalysen an Assets, die Ihnen gehören oder für deren Bewertung Sie beauftragt wurden
• Digitale Forensik und Incident Response
• Akademische und Sicherheitsforschung in kontrollierten, isolierten Umgebungen

Die unbefugte Nutzung dieses Tools gegen Systeme, Netzwerke oder Personen ohne ausdrückliche schriftliche Genehmigung ist eine Straftat gemäß dem Computer Fraud and Abuse Act (CFAA, 18 U.S.C. § 1030), dem Computer Misuse Act 1990 (CMA) sowie gleichwertigen Gesetzen in allen wichtigen Rechtsordnungen weltweit.

Die Autoren und Beitragenden von NOX übernehmen keine Haftung für direkte, indirekte, zufällige oder Folgeschäden, die aus der missbräuchlichen Verwendung dieser Software entstehen. Durch das Herunterladen, Installieren oder Ausführen von NOX stimmen Sie bedingungslos zu, alle geltenden lokalen, nationalen und internationalen Gesetze einzuhalten und nur Systeme und Daten anzugreifen, für die Sie eine ausdrückliche, dokumentierte Autorisierung besitzen.

Wenn Sie diesen Bedingungen nicht zustimmen, nutzen Sie diese Software nicht.

Lizenz

Apache License 2.0