helix-osint 3.3.0__tar.gz

helix_osint-3.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thalha Ahmed (@thalha-a9)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

helix_osint-3.3.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: helix-osint
+Version: 3.3.0
+Summary: Decode the digital DNA of any identity — OSINT Identity Mapper
+Author-email: Thalha Ahmed <sheikthalah035@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/thalha-a9/helix
+Project-URL: Repository, https://github.com/thalha-a9/helix
+Project-URL: Issues, https://github.com/thalha-a9/helix/issues
+Keywords: osint,reconnaissance,security,bug-bounty,username,identity
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Environment :: Console
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: tls
+Requires-Dist: curl-cffi>=0.6.2; extra == "tls"
+Provides-Extra: phash
+Requires-Dist: imagehash>=4.3.1; extra == "phash"
+Requires-Dist: Pillow>=10.0.0; extra == "phash"
+Provides-Extra: email
+Requires-Dist: holehe>=1.4.4; extra == "email"
+Provides-Extra: ai
+Requires-Dist: anthropic>=0.25.0; extra == "ai"
+Requires-Dist: openai>=1.0.0; extra == "ai"
+Provides-Extra: full
+Requires-Dist: curl-cffi; extra == "full"
+Requires-Dist: imagehash; extra == "full"
+Requires-Dist: Pillow; extra == "full"
+Requires-Dist: holehe; extra == "full"
+Requires-Dist: anthropic; extra == "full"
+Requires-Dist: openai; extra == "full"
+Requires-Dist: weasyprint; extra == "full"
+Dynamic: license-file
+
+<div align="center">
+
+```
+  ██╗  ██╗███████╗██╗     ██╗██╗  ██╗
+  ██║  ██║██╔════╝██║     ██║╚██╗██╔╝
+  ███████║█████╗  ██║     ██║ ╚███╔╝
+  ██╔══██║██╔══╝  ██║     ██║ ██╔██╗
+  ██║  ██║███████╗███████╗██║██╔╝ ██╗
+  ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝╚═╝  ╚═╝
+```
+
+### Decode the digital DNA of any identity
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![Version](https://img.shields.io/badge/Version-3.1.0-00ff88?style=flat-square)](https://github.com/thalha-a9/helix/releases)
+[![License](https://img.shields.io/badge/License-MIT-f59e0b?style=flat-square)](LICENSE)
+[![Platforms](https://img.shields.io/badge/Platforms-70%2B%20builtin%20·%20700%2B%20WMN%20·%20400%2B%20Sherlock%20·%20Maigret-a78bfa?style=flat-square)](https://github.com/thalha-a9/helix)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](https://github.com/thalha-a9/helix/pulls)
+
+**Helix** is a next-generation open-source OSINT framework that goes far beyond username checking.<br>
+It maps the *actual connections* between a target's online identities — then renders them as a<br>
+live, interactive D3.js relational graph you can explore, filter, and export.
+
+[**Quick Start**](#-quick-start) · [**Features**](#-what-makes-helix-different) · [**Modules**](#-intelligence-modules) · [**Graph**](#-the-graph) · [**Install**](#-installation)
+
+</div>
+
+---
+
+## Why Helix?
+
+Most OSINT tools answer one question: *"Does this username exist on Platform X?"*
+
+Helix answers a harder one: **"How do all these accounts connect to the same person?"**
+
+It extracts cross-platform links from bios, matches profile pictures by perceptual hash, infers timezone from commit patterns, discovers domains via certificate transparency, and plots every relationship as a glowing edge in a browser-based network graph — all in a single command.
+
+```bash
+python helix.py -u johndoe --wayback --crt --paste --pivot --phash
+```
+
+---
+
+## ⚡ What Makes Helix Different
+
+| Capability | Sherlock | SpiderFoot | Maltego | **Helix** |
+|---|:---:|:---:|:---:|:---:|
+| Username enumeration | ✓ | ✓ | ✓ | ✓ |
+| Relational bio-link graph | ✗ | ✗ | Partial | **✓** |
+| Recursive alias pivot | ✗ | ✗ | Manual | **✓ auto** |
+| Perceptual avatar matching | ✗ | ✗ | ✗ | **✓** |
+| Timezone inference | ✗ | ✗ | ✗ | **✓** |
+| Wayback identity timeline | ✗ | Partial | ✗ | **✓** |
+| Certificate transparency | ✗ | ✓ | ✓ | **✓** |
+| GitHub commit email extraction | ✗ | ✗ | ✗ | **✓** |
+| Local heuristic verifier | ✗ | ✗ | ✗ | **✓ always-on** |
+| Multi-AI false-positive filter | ✗ | ✗ | ✗ | **✓ 3 providers** |
+| Async speed | ✗ | ✗ | ✗ | **✓** |
+| 100% free & open source | ✓ | ✓ | ✗ | **✓** |
+
+---
+
+## 🔍 Intelligence Modules
+
+### Always On
+- **Local Heuristic Verifier** — Zero-dependency false-positive engine. Scores every result across 8 signals (WAF pages, generic titles, login redirects, homepage redirects). Runs before anything else, every single scan.
+
+### Core Flags
+| Flag | What it does |
+|---|---|
+| `--wmn` | Loads WhatsMyName database at runtime — **700+ platforms**, community-maintained |
+| `--maigret` | Loads **Maigret** database at runtime — sophisticated detection with `presenceStrs`/`absenceStrs`, 24h cached |
+| `--sherlock` | Loads Sherlock's database at runtime — **400+ platforms**, cached 24h locally |
+| `--pivot` | **Recursive bio pivot** — finds aliases in bios and auto-scans them, up to 4 hops deep |
+| `--phash` | **Perceptual avatar hash** — downloads profile pics, hashes them, cross-matches across platforms. Finds the same person even if they changed their username |
+| `--wayback` | **Wayback Machine** — fetches snapshot history + parses archived HTML for old usernames, historic emails, and past bios |
+| `--crt` | **Certificate Transparency** — queries crt.sh for SSL certs containing the target's name or email. Finds personal domains that never appeared in any bio |
+| `--paste` | **Paste Intelligence** — searches GitHub Gists and public Pastebin index for mentions |
+| `--breach` | **Breach check** — queries XposedOrNot for breach metadata (names, dates, data types exposed). No credentials returned |
+| `--holehe` | **Deep email scan** — hands off to holehe for 120+ platform email-registration checks |
+| `--ai` | **AI false-positive filter** — second verification pass via Claude, OpenRouter (free), or NVIDIA NIM (free) |
+
+### Auto-Triggered
+- **GitHub Deep Recon** — runs automatically when a GitHub profile is found. Extracts real emails from public commits (filters noreply), org memberships, language stats, npm packages, and infers timezone from commit timestamp distribution (requires ≥15 commits for confidence)
+
+---
+
+## 🕸 The Graph
+
+The HTML output is a standalone zero-dependency interactive network — no server needed, just open in a browser.
+
+```
+White pulsing node     →  Username root
+Amber pulsing node     →  Email root
+Amber/orange nodes     →  Pivot-discovered aliases
+Green solid edges      →  Bio-extracted cross-links (proven connections)
+Pink dashed edges      →  Avatar hash matches (same person across accounts)
+Amber dashed edges     →  Email-matched platforms
+Green ring on node     →  High confidence (OG meta validated)
+Blue ring on node      →  Medium confidence
+```
+
+**Controls:** drag nodes · scroll to zoom · click node to open profile · hover for tooltip (confidence, og:title, cross-link partners, bio-extracted alias details) · ⌕ search · ◌ not-found overlay · ☰ labels · ↓ SVG export · filter by confidence
+
+---
+
+## 🚀 Quick Start
+
+```bash
+git clone https://github.com/thalha-a9/helix.git
+cd helix
+pip install -r requirements.txt
+python helix.py -u johndoe
+```
+
+---
+
+## 📦 Installation
+
+**Required**
+```bash
+pip install aiohttp
+```
+
+**Optional — unlock more power**
+```bash
+pip install curl-cffi        # WAF bypass for Twitter, Instagram, TikTok, Patreon
+pip install imagehash Pillow # Perceptual avatar hash matching (--phash)
+pip install holehe            # Deep email scanning 120+ platforms (--holehe)
+pip install anthropic         # Claude AI verification (--ai claude)
+pip install openai            # OpenRouter / NVIDIA AI verification (--ai openrouter)
+```
+
+**Or install everything at once**
+```bash
+pip install "helix-osint[full]"
+```
+
+**Set GITHUB_TOKEN for 5000 req/hr on GitHub API** (optional, default is 60/hr):
+```bash
+export GITHUB_TOKEN=ghp_yourtoken
+```
+
+---
+
+## 💻 Usage
+
+```bash
+# Basic scan — opens interactive graph automatically
+python helix.py -u johndoe
+
+# Full power — all intelligence modules
+python helix.py -u johndoe --wayback --crt --paste --pivot --phash
+
+# Username + email — two root nodes, cross-matched in graph
+python helix.py -u johndoe -e johndoe@gmail.com --breach --holehe
+
+# Massive scan — 1100+ platforms
+python helix.py -u johndoe --wmn --sherlock
+
+# AI-verified scan (free — no API key cost)
+python helix.py -u johndoe --ai openrouter
+
+# Recursive pivot — auto-scan aliases up to 4 hops deep
+python helix.py -u johndoe --pivot --pivot-depth 4
+
+# Permutations — scan johndoe1, john.doe, realjohndoe, etc.
+python helix.py -u johndoe --permutations
+
+# Everything, saved to custom dir, no browser
+python helix.py -u johndoe -e johndoe@gmail.com \
+  --wmn --sherlock --wayback --crt --paste \
+  --pivot --phash --breach --holehe \
+  --ai openrouter --format all --no-browser --output ~/Desktop/report
+
+# Check which AI providers are configured
+python helix.py --providers
+```
+
+---
+
+## 🤖 AI Verification
+
+Helix has a two-layer false-positive filter:
+
+**Layer 1 — Local heuristic verifier** (always on, zero cost)
+Scores every result across 8 signals. A single generic title (e.g. `"Pinterest"` instead of a username) instantly purges the result. WAF/Cloudflare pages scored separately at 80 points. Threshold: 60 for normal results, 85 for OG-validated high-confidence results.
+
+**Layer 2 — AI verifier** (`--ai`, optional)
+Sends uncertain results to an LLM with a strict system prompt. Three providers:
+
+| Provider | Flag | Cost | Setup |
+|---|---|---|---|
+| Anthropic Claude | `--ai claude` | Paid | `export ANTHROPIC_API_KEY=...` |
+| OpenRouter Llama 3.1 | `--ai openrouter` | **Free tier** | `export OPENROUTER_API_KEY=...` → [openrouter.ai](https://openrouter.ai) |
+| NVIDIA NIM Llama 3.1 | `--ai nvidia` | **Free tier** | `export NVIDIA_API_KEY=...` → [build.nvidia.com](https://build.nvidia.com) |
+
+---
+
+## 🏗 Architecture
+
+```
+helix/
+├── helix.py                         ← CLI entry point + orchestrator
+├── pyproject.toml                   ← pip installable (helix-osint)
+├── osint/
+│   ├── checker.py                   ← Async engine (aiohttp + optional curl_cffi)
+│   ├── platforms.py                 ← 70+ platform definitions with OG/API detection
+│   ├── verifier.py                  ← Local heuristic false-positive engine
+│   ├── graph.py                     ← D3.js relational graph generator
+│   ├── report.py                    ← JSON / CSV / TXT exporters
+│   ├── permutations.py              ← Username variation generator
+│   ├── pivot.py                     ← Concurrent BFS alias pivot engine
+│   ├── phash.py                     ← Perceptual avatar hash matcher
+│   └── modules/
+│       ├── wayback.py               ← Archive.org CDX API + archived HTML parser
+│       ├── github_deep.py           ← GitHub API deep recon + timezone inference
+│       ├── crt.py                   ← Certificate transparency (crt.sh)
+│       └── paste.py                 ← Gist + Pastebin intelligence
+│   └── adapters/
+│       ├── sherlock_adapter.py      ← Sherlock data.json loader (24h cached)
+│       ├── wmn_adapter.py           ← WhatsMyName loader
+│       ├── holehe_adapter.py        ← holehe email scanner wrapper
+│       ├── breach_adapter.py        ← XposedOrNot breach metadata
+│       └── ai_verifier.py           ← Multi-provider async AI verification
+└── results/                         ← Output (git-ignored)
+    └── username/
+        ├── username_graph.html      ← Interactive D3.js network graph
+        ├── username_TIMESTAMP.json  ← Full structured report
+        ├── username_TIMESTAMP.csv
+        └── username_TIMESTAMP.txt
+```
+
+---
+
+## 🔬 How False Positive Prevention Works
+
+Helix uses the right detection method per platform instead of naive HTTP 200 checks:
+
+| Platform | Method | Why |
+|---|---|---|
+| Reddit | `reddit.com/user/{u}/about.json` → `"is_employee"` field | JSON API; field only exists for valid users |
+| Bluesky | AT Protocol API | SPA — static HTML is useless |
+| Chess.com | `api.chess.com/pub/player/{u}` | Official public API |
+| Lichess | `lichess.org/api/user/{u}` | Official public API |
+| GitHub | `og:title` parsed + validated against known error strings | Server-side rendered, reliable |
+| Medium | `og:title` rejects homepage redirect string | Catches "Where good ideas find you" |
+| Twitter/X | `curl_cffi` TLS impersonation | Skipped gracefully without it |
+
+---
+
+## 📋 Output Formats
+
+| Format | Contents |
+|---|---|
+| `.html` | Standalone interactive D3.js graph — no server needed |
+| `.json` | Full structured report including intel bundle (wayback, GitHub deep, CRT, paste) |
+| `.csv` | Spreadsheet-friendly, all platforms |
+| `.txt` | Clean terminal-style summary |
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome. For major changes open an issue first.
+
+When adding a platform to `platforms.py`:
+- Prefer `og_meta` or API endpoints over `text_not_present`
+- Always test against a non-existent username first — if it returns `found=True`, your detection is wrong
+- Add `bio_extract: True` + `bio_patterns` if the platform renders bio text server-side
+
+---
+
+## ⚠️ Legal & Ethics
+
+Helix is built for **security research, bug bounty reconnaissance, and OSINT education**.
+All data sources used are publicly accessible. Always ensure you have proper authorization
+before running reconnaissance on any target. The author is not responsible for misuse.
+
+---
+
+## 📎 Related Projects
+
+- [esp32-iot-audit](https://github.com/thalha-a9/esp32-iot-audit) — ESP32 IoT security scanner
+- [esp-pentest-toolkit](https://github.com/thalha-a9/esp-pentest-toolkit) — Wireless ESP32/8266 pentest toolkit
+
+---
+
+<div align="center">
+
+Built by **Thalha Ahmed** · [@thalha-a9](https://github.com/thalha-a9)
+
+*If Helix helped you — drop a ⭐ and share it with your security community.*
+
+</div>

helix_osint-3.3.0/README.md

@@ -0,0 +1,295 @@
+<div align="center">
+
+```
+  ██╗  ██╗███████╗██╗     ██╗██╗  ██╗
+  ██║  ██║██╔════╝██║     ██║╚██╗██╔╝
+  ███████║█████╗  ██║     ██║ ╚███╔╝
+  ██╔══██║██╔══╝  ██║     ██║ ██╔██╗
+  ██║  ██║███████╗███████╗██║██╔╝ ██╗
+  ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝╚═╝  ╚═╝
+```
+
+### Decode the digital DNA of any identity
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-3776ab?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![Version](https://img.shields.io/badge/Version-3.1.0-00ff88?style=flat-square)](https://github.com/thalha-a9/helix/releases)
+[![License](https://img.shields.io/badge/License-MIT-f59e0b?style=flat-square)](LICENSE)
+[![Platforms](https://img.shields.io/badge/Platforms-70%2B%20builtin%20·%20700%2B%20WMN%20·%20400%2B%20Sherlock%20·%20Maigret-a78bfa?style=flat-square)](https://github.com/thalha-a9/helix)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](https://github.com/thalha-a9/helix/pulls)
+
+**Helix** is a next-generation open-source OSINT framework that goes far beyond username checking.<br>
+It maps the *actual connections* between a target's online identities — then renders them as a<br>
+live, interactive D3.js relational graph you can explore, filter, and export.
+
+[**Quick Start**](#-quick-start) · [**Features**](#-what-makes-helix-different) · [**Modules**](#-intelligence-modules) · [**Graph**](#-the-graph) · [**Install**](#-installation)
+
+</div>
+
+---
+
+## Why Helix?
+
+Most OSINT tools answer one question: *"Does this username exist on Platform X?"*
+
+Helix answers a harder one: **"How do all these accounts connect to the same person?"**
+
+It extracts cross-platform links from bios, matches profile pictures by perceptual hash, infers timezone from commit patterns, discovers domains via certificate transparency, and plots every relationship as a glowing edge in a browser-based network graph — all in a single command.
+
+```bash
+python helix.py -u johndoe --wayback --crt --paste --pivot --phash
+```
+
+---
+
+## ⚡ What Makes Helix Different
+
+| Capability | Sherlock | SpiderFoot | Maltego | **Helix** |
+|---|:---:|:---:|:---:|:---:|
+| Username enumeration | ✓ | ✓ | ✓ | ✓ |
+| Relational bio-link graph | ✗ | ✗ | Partial | **✓** |
+| Recursive alias pivot | ✗ | ✗ | Manual | **✓ auto** |
+| Perceptual avatar matching | ✗ | ✗ | ✗ | **✓** |
+| Timezone inference | ✗ | ✗ | ✗ | **✓** |
+| Wayback identity timeline | ✗ | Partial | ✗ | **✓** |
+| Certificate transparency | ✗ | ✓ | ✓ | **✓** |
+| GitHub commit email extraction | ✗ | ✗ | ✗ | **✓** |
+| Local heuristic verifier | ✗ | ✗ | ✗ | **✓ always-on** |
+| Multi-AI false-positive filter | ✗ | ✗ | ✗ | **✓ 3 providers** |
+| Async speed | ✗ | ✗ | ✗ | **✓** |
+| 100% free & open source | ✓ | ✓ | ✗ | **✓** |
+
+---
+
+## 🔍 Intelligence Modules
+
+### Always On
+- **Local Heuristic Verifier** — Zero-dependency false-positive engine. Scores every result across 8 signals (WAF pages, generic titles, login redirects, homepage redirects). Runs before anything else, every single scan.
+
+### Core Flags
+| Flag | What it does |
+|---|---|
+| `--wmn` | Loads WhatsMyName database at runtime — **700+ platforms**, community-maintained |
+| `--maigret` | Loads **Maigret** database at runtime — sophisticated detection with `presenceStrs`/`absenceStrs`, 24h cached |
+| `--sherlock` | Loads Sherlock's database at runtime — **400+ platforms**, cached 24h locally |
+| `--pivot` | **Recursive bio pivot** — finds aliases in bios and auto-scans them, up to 4 hops deep |
+| `--phash` | **Perceptual avatar hash** — downloads profile pics, hashes them, cross-matches across platforms. Finds the same person even if they changed their username |
+| `--wayback` | **Wayback Machine** — fetches snapshot history + parses archived HTML for old usernames, historic emails, and past bios |
+| `--crt` | **Certificate Transparency** — queries crt.sh for SSL certs containing the target's name or email. Finds personal domains that never appeared in any bio |
+| `--paste` | **Paste Intelligence** — searches GitHub Gists and public Pastebin index for mentions |
+| `--breach` | **Breach check** — queries XposedOrNot for breach metadata (names, dates, data types exposed). No credentials returned |
+| `--holehe` | **Deep email scan** — hands off to holehe for 120+ platform email-registration checks |
+| `--ai` | **AI false-positive filter** — second verification pass via Claude, OpenRouter (free), or NVIDIA NIM (free) |
+
+### Auto-Triggered
+- **GitHub Deep Recon** — runs automatically when a GitHub profile is found. Extracts real emails from public commits (filters noreply), org memberships, language stats, npm packages, and infers timezone from commit timestamp distribution (requires ≥15 commits for confidence)
+
+---
+
+## 🕸 The Graph
+
+The HTML output is a standalone zero-dependency interactive network — no server needed, just open in a browser.
+
+```
+White pulsing node     →  Username root
+Amber pulsing node     →  Email root
+Amber/orange nodes     →  Pivot-discovered aliases
+Green solid edges      →  Bio-extracted cross-links (proven connections)
+Pink dashed edges      →  Avatar hash matches (same person across accounts)
+Amber dashed edges     →  Email-matched platforms
+Green ring on node     →  High confidence (OG meta validated)
+Blue ring on node      →  Medium confidence
+```
+
+**Controls:** drag nodes · scroll to zoom · click node to open profile · hover for tooltip (confidence, og:title, cross-link partners, bio-extracted alias details) · ⌕ search · ◌ not-found overlay · ☰ labels · ↓ SVG export · filter by confidence
+
+---
+
+## 🚀 Quick Start
+
+```bash
+git clone https://github.com/thalha-a9/helix.git
+cd helix
+pip install -r requirements.txt
+python helix.py -u johndoe
+```
+
+---
+
+## 📦 Installation
+
+**Required**
+```bash
+pip install aiohttp
+```
+
+**Optional — unlock more power**
+```bash
+pip install curl-cffi        # WAF bypass for Twitter, Instagram, TikTok, Patreon
+pip install imagehash Pillow # Perceptual avatar hash matching (--phash)
+pip install holehe            # Deep email scanning 120+ platforms (--holehe)
+pip install anthropic         # Claude AI verification (--ai claude)
+pip install openai            # OpenRouter / NVIDIA AI verification (--ai openrouter)
+```
+
+**Or install everything at once**
+```bash
+pip install "helix-osint[full]"
+```
+
+**Set GITHUB_TOKEN for 5000 req/hr on GitHub API** (optional, default is 60/hr):
+```bash
+export GITHUB_TOKEN=ghp_yourtoken
+```
+
+---
+
+## 💻 Usage
+
+```bash
+# Basic scan — opens interactive graph automatically
+python helix.py -u johndoe
+
+# Full power — all intelligence modules
+python helix.py -u johndoe --wayback --crt --paste --pivot --phash
+
+# Username + email — two root nodes, cross-matched in graph
+python helix.py -u johndoe -e johndoe@gmail.com --breach --holehe
+
+# Massive scan — 1100+ platforms
+python helix.py -u johndoe --wmn --sherlock
+
+# AI-verified scan (free — no API key cost)
+python helix.py -u johndoe --ai openrouter
+
+# Recursive pivot — auto-scan aliases up to 4 hops deep
+python helix.py -u johndoe --pivot --pivot-depth 4
+
+# Permutations — scan johndoe1, john.doe, realjohndoe, etc.
+python helix.py -u johndoe --permutations
+
+# Everything, saved to custom dir, no browser
+python helix.py -u johndoe -e johndoe@gmail.com \
+  --wmn --sherlock --wayback --crt --paste \
+  --pivot --phash --breach --holehe \
+  --ai openrouter --format all --no-browser --output ~/Desktop/report
+
+# Check which AI providers are configured
+python helix.py --providers
+```
+
+---
+
+## 🤖 AI Verification
+
+Helix has a two-layer false-positive filter:
+
+**Layer 1 — Local heuristic verifier** (always on, zero cost)
+Scores every result across 8 signals. A single generic title (e.g. `"Pinterest"` instead of a username) instantly purges the result. WAF/Cloudflare pages scored separately at 80 points. Threshold: 60 for normal results, 85 for OG-validated high-confidence results.
+
+**Layer 2 — AI verifier** (`--ai`, optional)
+Sends uncertain results to an LLM with a strict system prompt. Three providers:
+
+| Provider | Flag | Cost | Setup |
+|---|---|---|---|
+| Anthropic Claude | `--ai claude` | Paid | `export ANTHROPIC_API_KEY=...` |
+| OpenRouter Llama 3.1 | `--ai openrouter` | **Free tier** | `export OPENROUTER_API_KEY=...` → [openrouter.ai](https://openrouter.ai) |
+| NVIDIA NIM Llama 3.1 | `--ai nvidia` | **Free tier** | `export NVIDIA_API_KEY=...` → [build.nvidia.com](https://build.nvidia.com) |
+
+---
+
+## 🏗 Architecture
+
+```
+helix/
+├── helix.py                         ← CLI entry point + orchestrator
+├── pyproject.toml                   ← pip installable (helix-osint)
+├── osint/
+│   ├── checker.py                   ← Async engine (aiohttp + optional curl_cffi)
+│   ├── platforms.py                 ← 70+ platform definitions with OG/API detection
+│   ├── verifier.py                  ← Local heuristic false-positive engine
+│   ├── graph.py                     ← D3.js relational graph generator
+│   ├── report.py                    ← JSON / CSV / TXT exporters
+│   ├── permutations.py              ← Username variation generator
+│   ├── pivot.py                     ← Concurrent BFS alias pivot engine
+│   ├── phash.py                     ← Perceptual avatar hash matcher
+│   └── modules/
+│       ├── wayback.py               ← Archive.org CDX API + archived HTML parser
+│       ├── github_deep.py           ← GitHub API deep recon + timezone inference
+│       ├── crt.py                   ← Certificate transparency (crt.sh)
+│       └── paste.py                 ← Gist + Pastebin intelligence
+│   └── adapters/
+│       ├── sherlock_adapter.py      ← Sherlock data.json loader (24h cached)
+│       ├── wmn_adapter.py           ← WhatsMyName loader
+│       ├── holehe_adapter.py        ← holehe email scanner wrapper
+│       ├── breach_adapter.py        ← XposedOrNot breach metadata
+│       └── ai_verifier.py           ← Multi-provider async AI verification
+└── results/                         ← Output (git-ignored)
+    └── username/
+        ├── username_graph.html      ← Interactive D3.js network graph
+        ├── username_TIMESTAMP.json  ← Full structured report
+        ├── username_TIMESTAMP.csv
+        └── username_TIMESTAMP.txt
+```
+
+---
+
+## 🔬 How False Positive Prevention Works
+
+Helix uses the right detection method per platform instead of naive HTTP 200 checks:
+
+| Platform | Method | Why |
+|---|---|---|
+| Reddit | `reddit.com/user/{u}/about.json` → `"is_employee"` field | JSON API; field only exists for valid users |
+| Bluesky | AT Protocol API | SPA — static HTML is useless |
+| Chess.com | `api.chess.com/pub/player/{u}` | Official public API |
+| Lichess | `lichess.org/api/user/{u}` | Official public API |
+| GitHub | `og:title` parsed + validated against known error strings | Server-side rendered, reliable |
+| Medium | `og:title` rejects homepage redirect string | Catches "Where good ideas find you" |
+| Twitter/X | `curl_cffi` TLS impersonation | Skipped gracefully without it |
+
+---
+
+## 📋 Output Formats
+
+| Format | Contents |
+|---|---|
+| `.html` | Standalone interactive D3.js graph — no server needed |
+| `.json` | Full structured report including intel bundle (wayback, GitHub deep, CRT, paste) |
+| `.csv` | Spreadsheet-friendly, all platforms |
+| `.txt` | Clean terminal-style summary |
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome. For major changes open an issue first.
+
+When adding a platform to `platforms.py`:
+- Prefer `og_meta` or API endpoints over `text_not_present`
+- Always test against a non-existent username first — if it returns `found=True`, your detection is wrong
+- Add `bio_extract: True` + `bio_patterns` if the platform renders bio text server-side
+
+---
+
+## ⚠️ Legal & Ethics
+
+Helix is built for **security research, bug bounty reconnaissance, and OSINT education**.
+All data sources used are publicly accessible. Always ensure you have proper authorization
+before running reconnaissance on any target. The author is not responsible for misuse.
+
+---
+
+## 📎 Related Projects
+
+- [esp32-iot-audit](https://github.com/thalha-a9/esp32-iot-audit) — ESP32 IoT security scanner
+- [esp-pentest-toolkit](https://github.com/thalha-a9/esp-pentest-toolkit) — Wireless ESP32/8266 pentest toolkit
+
+---
+
+<div align="center">
+
+Built by **Thalha Ahmed** · [@thalha-a9](https://github.com/thalha-a9)
+
+*If Helix helped you — drop a ⭐ and share it with your security community.*
+
+</div>