Nox Framework

<div align="center">

    ███╗   ██╗ ██████╗ ██╗  ██╗
    ████╗  ██║██╔═══██╗╚██╗██╔╝
    ██╔██╗ ██║██║   ██║ ╚███╔╝
    ██║╚██╗██║██║   ██║ ██╔██╗
    ██║ ╚████║╚██████╔╝██╔╝ ██╗
    ╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝

Cyber Threat Intelligence Framework

OSINT framework for red teaming, digital forensics, and corporate exposure analysis.

</div>

---

Introduction

NOX is a purpose-built cyber threat intelligence engine designed for operators who require speed, operational security, and depth in a single cohesive framework. It is not a wrapper around existing tools — it is a fully async, plugin-driven intelligence platform with a strict separation between execution logic and source definitions.

| Capability | Detail | |-|-| | ⚡ Async Execution Engine | Massively parallel scanning across 124 intelligence feeds with no sequential bottlenecks and no blocking I/O. | | 🛡️ Guardian Engine | Integrated OPSEC layer with automatic proxy rotation and SOCKS5 support. Fail-safe kill-switch halts all traffic if the transport circuit is unavailable. | | 🧠 Risk Scoring | Dynamic 0–100 scoring with time-decay, source confidence weighting, password complexity analysis, persistence multipliers, and HVT detection. | | 🔗 Recursive Avalanche Engine | Every discovered asset — username, email, cracked password, phone — is automatically re-injected as a new scan seed. Per-asset pipeline runs sequentially (breach → crack → dork → scrape); child assets run concurrently. Identifiers from all four phases feed the pivot queue. Global deduplication and configurable depth cap prevent runaway recursion. | | 🔍 Autoscan | Single command triggers breach scan + recursive pivot + dorking + paste scraping — fully automated, no manual chaining. |

---

Features

| Feature | Description | |-|-| | 124 JSON Plugin Sources | Every intelligence source is a JSON plugin. The execution engine contains zero hardcoded source logic. | | Async Core | Full asyncio event loop with JA3 fingerprinting, SSL session management, per-request jitter, and configurable concurrency. | | Autoscan Pipeline | --autoscan triggers: breach scan → recursive pivot → Google/Bing/SearXNG dorking → paste/Telegram scraping — all in one command. | | Recursive Avalanche Engine | Every identifier discovered — from breach records, dork hits, or scraped paste/Telegram content — is re-injected as a new seed. Per-asset pipeline is sequential (breach → crack → dork → scrape); child assets run concurrently via asyncio.gather. A global seen_assets set prevents infinite loops. Concurrency and depth are fully configurable at runtime via --threads and --depth. | | Hash Pivoting | Hashes found in breach data are automatically identified (MD5/SHA1/SHA256/NTLM/bcrypt) and cracked via concurrent background API queries. Cracked plaintexts are injected into the pivot queue as password-recycling seeds. Failures are logged silently — the scan never stops. | | Guardian Proxy Engine | Zero-config OPSEC layer: reads proxies.txt if present; otherwise auto-fetches and validates a high-anonymity proxy pool in-memory. Full SOCKS5/HTTP/S and Tor support. | | API Key Rotation | api_key_slots per source — NOX round-robins across multiple keys to bypass per-key rate limits. | | Identity Graphing | Union-Find correlation engine unifies breach records into identity clusters across all sources, using type-aware pivot classification. | | Enterprise Forensic Reports | Professional PDF/HTML/JSON/CSV/Markdown reports with Executive Summary dashboard (Total Time, Nodes Discovered, Cleartext Passwords, Pivot Depth), interactive Pivot Chain Visualization, and strict data sanitization — no technical noise in output. JSON exports are self-describing with a full metadata block. | | HVT Detection | Auto-flags C-level, Admin, DevOps, and government domain accounts as High-Value Targets. | | Dorking Engine | Passive document discovery via Google/Bing/SearXNG dorks with PDF/Office metadata extraction. | | Scraping Engine | Paste site indexing, Telegram CTI channel monitoring, credential extraction, and misconfiguration discovery. Each autoscan asset gets a dedicated scrape session — no shared state. | | Proxy / Tor | SOCKS5, HTTP/S proxy, full Tor routing via stem, and automatic Guardian fallback. SOCKS5 proxies are validated and routed correctly via aiohttp-socks. | | Secure Key Store | API keys managed via ~/.config/nox-cli/apikeys.json (chmod 0600). Unconfigured keys are silently skipped. Keys set via environment variable are picked up automatically without restarting. | | System Logging | All scan events, phase completions, pivot discoveries, API events, rate-limits, and crack attempts are written to ~/.nox/logs/nox.log. Only actionable intelligence reaches the terminal. | | Plugin Debug | --list-sources prints a full operator debug table: plugin name, input type, confidence score, key status (configured / not configured / public), and any JSON parse errors. |

---

Architecture

Plugin-Driven Design

NOX operates on a strict separation of concerns: nox.py is a pure, agnostic execution engine — it handles async I/O, JA3 fingerprinting, SSL session management, recursive pivoting, and result correlation. It contains no hardcoded intelligence logic.

All intelligence is defined as JSON plugins in sources/. These plugins are the sole source of truth for what NOX queries, how it authenticates, and what it extracts. The build tool build_sources.py is the only authorised way to create or modify them.

build_sources.py  ──►  sources/*.json  ──►  nox.py (runtime loader)
   [Builder]              [Plugins]           [Execution Engine]

[!IMPORTANT] sources/*.json files are auto-generated artifacts. Never edit them directly. All source additions and modifications must be made in build_sources.py and applied by running python build_sources.py. Manual edits will be overwritten on the next build.

Source Schema

{
  "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 (or json_root + normalization_map), required_api_key_name, api_key_slots, input_type, output_type, pivot_types, confidence.

---

Autoscan Pipeline

--autoscan (CLI) / autoscan (REPL) executes the full intelligence pipeline in a single command:

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 (without --autoscan) runs Phase 1 only — breach sources, no pivot/dork/scrape.

---

Recursive Avalanche Engine

Every identifier discovered during a scan — from breach records, dork hits, or scraped paste/Telegram content — is treated as a new intelligence seed. For each asset, the engine runs four phases sequentially: breach scan → hash crack → dork → scrape. Identifiers extracted from all four phases are harvested and re-injected as new seeds. Child assets are then processed concurrently via asyncio.gather.

target@company.com
  └─► [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] new@email.com          ──► [Breach + Crack + Dork + Scrape]
  └─► [Scrape/paste] admin@corp.com ──► [Breach + Crack + Dork + Scrape]

• seen_assets set — global deduplication; no identifier is ever processed twice, regardless of which phase discovered it
• Global semaphore — single shared concurrency cap across the entire discovery tree, respecting --threads
• --depth N — configurable pivot depth (default: 2); hard backstop prevents runaway recursion
• --no-pivot — disable recursive enrichment for a fast breach-only scan

---

Hash Pivoting

When a hash is found in breach data during --autoscan:

1. Hash type is identified (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Multip