nox-framework - High-performance OSINT/CTI framework for automated

项目说明

<di="center">

Cyber Threat Intelligence Framework

![Status]()
![Python]()
![Kali Linux]()
![BlackArch]()
![Platform]()
![Sources]()

*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 cohesi. It is not a wrapper around existing tools — it is a fully async, plugin-dri 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 una. |
| 🧠 Risk Scoring | Dynamic 0–100 scoring with time-decay, source confidence weighting, password complexity analysis, persistence multipliers, and H. |
| 🔗 Recursi 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 pi. Global deduplication and configurable depth cap prevent runaway recursion. |
| 🔍 Autoscan | Single command triggers breach scan + recursi + 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 → recursi → Google/Bing/SearXNG dorking → paste/
| Recursi Engine | Every identifier discovered — from breach records, dork hits, or scraped paste/ach → 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 Pi | Hashes found in breach data are automatically identified (MD5/SHA1/SHA256/NTLM/bcrypt) and cracked background API queries. Cracked plaintexts are injected into the pi as password-recycling seeds. Failures are logged silently — the scan ne. |
| Guardian Proxy Engine | Zero-config OPSEC layer: reads proxies.txt if present; otherwise auto-fetches and 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 pi. |
| Enterprise Forensic Reports | Professional PDF/HTML/JSON/CS reports with Executi dashboard (Total Time, Nodes Discovered, Cleartext Passwords, Pi), interacti Chain , and strict data sanitization — no technical noise in output. JSON exports are self-describing with a full metadata block. |
| H | Auto-flags C-level, Admin, DevOps, and go domain accounts as High-Value Targets. |
| Dorking Engine | Passi discovery /Bing/SearXNG dorks with PDF/Office metadata extraction. |
| Scraping Engine | Paste site indexing, 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 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 are picked up automatically without restarting. |
| System Logging | All scan events, phase completions, pi, 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-Dri

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, recursi, 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.

> [!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 o on the next build.

#### Source Schema

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

---

Autoscan Pipeline

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

scan (without --autoscan) runs Phase 1 only — breach sources, no pivot/dork/scrape.

---

Recursi Engine

Every identifier discovered during a scan — from breach records, dork hits, or scraped paste/uns four phases sequentially: breach scan → hash crack → dork → scrape. Identifiers extracted from all four phases are har and re-injected as new seeds. Child assets are then processed concurrently via asyncio.gather.

---

Hash Pi

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

1. Hash type is identified (MD5/NTLM, SHA1, SHA256, bcrypt)
2. Multiple rainbow-table APIs are queried concurrently in a background task
3. If cracked — plaintext is logged, the record is updated, and the password is injected into the pi for password-recycling analysis across all breach sources
4. If not cracked — failure is logged to nox_system.log, the hash is preserved in the report, and pi on all other assets continues immediately

The crack process is fully non-blocking. A timeout or API failure ne the scan. Use --no-online-crack to restrict cracking to the local wordlist only (no data sent to third-party APIs).

---

Guardian Proxy Engine

The Guardian Engine is NOX's zero-config OPSEC layer. It activates automatically when no --proxy or --tor flag is supplied.

Resolution order:

1. proxies.txt — if present in the working directory, NOX loads and rotates through the listed proxies.
2. Dynamic fetch — if proxies.txt is absent, the Guardian Engine fetches a fresh list of high-anonymity public proxies, each one, and holds the pool in-memory for the session. Nothing is written to disk.
3. Direct connection — if no valid proxies are found, NOX falls back to a direct connection and emits a warning.

> [!WARNING]
> Public proxy pools are inherently untrusted infrastructure. For sensiti, always supply a controlled proxy via --proxy or route through Tor via --tor.

| Flag | Behaviour |
|-|-|
| --proxy <url> | Route all traffic through the specified HTTP/S or SOCKS5 proxy. Disables Guardian. |
| --tor | Route all traffic through Tor (requires tor service on port 9050). Disables Guardian. |
| --guardian-off | Bypass the OPSEC kill-switch and connect directly. |
| *(no flag)* | Guardian Engine activates automatically. |

---

Reporting

All report formats include an Executi dashboard:

| Metric | Description |
|-|-|
| Total Time | Wall-clock duration of the full scan |
| Nodes Discovered | Unique identities surfaced across all sources |
| Cleartext Passwords | Plaintext credentials found or cracked |
| Pi | Depth reached by the recursi engine |

Reports also include a Pi showing the full relational path from initial seed to final discovery:

JSON exports include a _meta block with scan_id, target, timestamp, nox_, and pi — making every export self-describing for ingestion into case management platforms.

All output is sanitized — proxy errors, timeouts, and tracebacks are stripped. Only actionable intelligence is included.

---

Filesystem Layout

---

Prerequisites

---

Installation

Option 1: Debian / Kali Linux — Isolated .deb (Recommended)

Download the .deb package from the Releases page, then run:

The post-install script automatically:
1. Creates an isolated en at /opt/nox-cli/.venv
2. Installs all Python dependencies inside the venv (PEP 668 compliant — zero system pollution)
3. Builds the 124 source plugins
4. Links /usr/bin/nox-cli → /opt/nox-cli/nox-wrapper.sh

Option 2: From Source

---

Quick Start

Step 1 — Build source plugins *(from source only — .deb does this automatically)*

Step 2 — Configure API keys

build_sources.py creates ~/.config/nox-cli/apikeys.json on first run, pre-populated with every supported service. The file is chmod 0600 and is ne to VCS.

This is the single canonical key store — all sources read from it at runtime.

> [!NOTE]
> Any key set to INSERT_API_KEY_HERE or "" is treated as unconfigured — that source is silently skipped. Sources without a key requirement are always active.
>
> Load priority: en (e.g. export HIBP_API_KEY=xxx) → ~/.config/nox-cli/apikeys.json

Step 3 — Execute

> [!NOTE]
> OPSEC Kill-Switch: By default, NOX activates the Guardian Engine (auto proxy rotation). Use --guardian-off to connect directly.

---

CLI Reference

---

REPL

Launch the interactive REPL with no arguments:

Examples:

---

Source Management

Adding a Source

1. Define in build_sources.py:

2. Rebuild:

> [!NOTE]
> The builder every source at build time: GET endpoints must contain {target}, sources must have reliability_score ≤ 4, and the confidence field can be set explicitly to o the formula-deri.

---

Building the .deb Package

---

Legal Disclaimer

> [!WARNING]
> NOX is intended exclusively for:
> - Authorised penetration testing and red team engagements with explicit written consent
> - Corporate exposure analysis on assets you own or are contracted to assess
> - Digital forensics and incident response
> - Academic and security research in controlled, isolated en
>
> Unauthorised use of this tool against systems, networks, or indi without explicit written permission is a criminal offence under the Computer Fraud and Abuse Act (CFAA, 18 U.S.C. § 1030), the Computer Misuse Act 1990 (CMA), and equi legislation in all major jurisdictions worldwide.
>
> The authors and contributors of NOX accept no liability for any direct, indirect, incidental, or consequential damages arising from misuse of this software. By downloading, installing, or executing NOX, you unconditionally agree to comply with all applicable local, national, and international laws, and to only target systems and data for which you hold explicit, documented authorisation.
>
> If you do not agree to these terms, do not use this software.

---

License

Apache License 2.0

项目信息

开发语言：Python

Star 数：333

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕High-performance OSINT/CTI framework for automated identity pivoting and risk analysis across 120+ sources.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。