ReconHound

1. Introduction

ReconHound is an External Attack Surface Management (EASM) and Threat Intelligence engine built for analysts, Red Teams, and researchers. It automates reconnaissance and unifies the results in a real-time graphical interface.

What is "EASM & Threat Intelligence Engine"?

External Attack Surface Management (EASM) is the process of discovering, monitoring, and evaluating internet-exposed assets to identify attack vectors before adversaries do. ReconHound acts as an engine that enriches this data with threat intelligence, actively validates findings, and qualifies real-world exploitation risk. It transforms terabytes of raw, noisy internet telemetry into prioritized, actionable intelligence, enabling security teams to focus on what truly matters.

2. Architecture & Correlation Pipeline

The ReconHound engine executes an asynchronous 5-stage pipeline designed to transform raw OSINT and active scans into a high-fidelity relational graph model:

Relational Topology Hierarchy (Host-Centric & Target-Driven)

The structured data synthesized into the Graph organizes nodes through an agile, **Host-Centric** attack chain architecture:

Target Query Root (Anchor with Full DNS Inventory: all_domains & all_subdomains)
  ├── CONTAINS_TARGET ──► Target Hosts / IPs (with metadata badge 🌐 N FQDNs)
  │     └── EXPOSES ──► Services / Ports (Local 1:N Instances per Host)
  │           └── HAS_VULN ──► CVEs (Global Deduplicated N:M Entities)
  │                 ├── ENRICHED_WITH ──► FIRST EPSS + CISA KEV
  │                 └── WEAPONIZED_BY ──► ExploitDB + GitHub PoCs
  └── CONTAINS_TARGET ──► Explicit FQDN Targets (Scan Targets Marked On-Demand)
        └── RESOLVES_TO ──► Resolved Hosts / IPs

Recursive Retroactive Discovery Engine & Incremental Fusion (Smart Upsert)

The core technological differentiator of ReconHound compared to static asset discovery scanners is its Autonomous Recursive Surface Expansion Cycle. Rather than confining analysis to initial query blocks (such as a single ASN, Org name, or CIDR range), the engine launches a multi-tier heuristic correlation chain in real time:

Target Query (e.g. org:'ACME Corp')
  │
  ├─► [1. Primary Recon] ───────► Host Profiling + TLS / HTTP Banners
  │                                     │
  │                                     ▼ Heuristic Domain Extraction
  ├─► [2. Cascading Enumeration] ─► crt.sh + Reverse WHOIS (Domains & Subdomains)
  │                                     │
  │                                     ▼ Concurrent DNS Resolution (A/AAAA)
  ├─► [3. Network Expansion] ───► Discovery of New Satellite IP Infrastructure
  │                                     │
  │                                     ▼ Retroactive Passive Profiling
  └─► [4. Incremental Fusion] ──► SQLite Smart Upsert: Preserved History + Merged Provenance

3. Installation Guide (Quickstart)

ReconHound runs natively across Linux, macOS, and Windows (via WSL2).

Step 1: Clone and Install Dependencies

# Clone repository
git clone https://github.com/ls4ss/ReconHound.git
cd ReconHound

# Run the automated installer, bootstrap dependencies,
# configure capabilities, and set up your secure Dashboard Admin credentials.
reconx config setup

Step 2: Active Scan Binaries (Masscan & Nuclei)

The reconx config setup routine automatically verifies and configures raw socket network capabilities (setcap) and templates. To manually install the binaries:

# Installation (Debian / Ubuntu / Kali Linux)
sudo apt update && sudo apt install -y masscan

# Grant non-root Linux capabilities for WebUI execution:
sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip $(which masscan)

# Installation (Nuclei via Go or pre-built binary):
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip $(which masscan)

Step 3: Local Exploit Database (ExploitDB)

The local exploit database cache is initialized automatically during setup. To update it on demand:

reconx config update

4. Configuration & API Keys

ReconHound includes free out-of-the-box fallbacks (crt.sh, HackerTarget, FIRST EPSS, CISA KEV, and GitHub PoC API). To unlock deeper network range profiling, configure your API keys in .env:

The .env file is automatically created from .env.example during setup. Configure your keys as needed:

# ==============================================================================
# ReconHound - External Attack Surface Management & Threat Intelligence Engine
# Copy this file to .env and insert your API keys as needed.
# ==============================================================================

# [Required for Shodan Queries, Subnets, DNS & Banner Reconnaissance]
SHODAN_API_KEY=

# [Required for V3: AlienVault OTX Threat Actors & Malware extraction]
ALIENVAULT_API_KEY=

# [Required for V3: SecurityTrails Subdomain & Passive IP Enumeration]
SECURITYTRAILS_API_KEY=

# [Optional: Censys Platform API v3 Personal Access Token & Org ID]
CENSYS_PAT_TOKEN=
CENSYS_ORG_ID=

# [Optional: Censys Legacy API ID & Secret]
CENSYS_API_ID=
CENSYS_API_SECRET=

# [Optional: NVD API Key for Accelerated CVSS & CWE Enrichment]
NVD_API_KEY=

# [Optional: WhoisFreaks API Key for Structured Reverse WHOIS Domain Mapping]
WHOISFREAKS_API_KEY=

# [Optional: GitHub Personal Access Token for Public Exploit & PoC Hunting]
GITHUB_TOKEN=

Diagnostics & Automated Pre-requisite Configuration

Verify environment health, Python dependencies, operational folders, permissions, and live API endpoints:

# Display complete diagnostics table for system and APIs
reconx config check

# Automatically diagnose and configure missing prerequisites
reconx config setup

5. ReconExec

The command-line interface is driven by Typer and styled with Rich, providing clean formatting, asynchronous progress indicators, and high-visibility risk tables.

Usage: reconexec [OPTIONS] COMMAND [ARGS]...                                   
                                                                                
╭─ Global Recon Scans ─────────────────────────────────────────────────────────╮
│ all         Execute passive attack surface mapping using ALL modules.        │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Targeted Recon Modules ─────────────────────────────────────────────────────╮
│ shodan      Execute passive scan using the 'Shodan' module.                  │
│ censys      Execute passive scan using the 'Censys' module.                  │
│ crtsh       Execute passive scan using the 'crt.sh' module.                  │
│ whois       Execute passive scan using the 'Reverse WHOIS' module.           │
│ sectrails   Execute passive scan using the 'SecurityTrails' module.          │
│ axfr        Execute passive scan using the 'Zone Transfer' module.           │
│ otx         Execute passive scan using the 'AlienVault OTX' module.          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Utility & Intelligence ─────────────────────────────────────────────────────╮
│ intel       Execute advanced threat intelligence lookups.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ System & Configuration ─────────────────────────────────────────────────────╮
│ version     Show ReconExec version and maintainer information.               │
│ config      Manage configuration, setup, and system updates                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Target Scan Modes

Recon Modules & Flags

SQLite EASM Persistence

# Scan domain and persist into ./data/dbs/company.sqlite
reconx all company.com --create-db company

# Scan subnet and persist into ./data/dbs/datacenter.sqlite
reconx all 198.51.100.0/24 --create-db datacenter

Executive Reports & Export

# 1. Executive Markdown Report
reconx all company.com -o markdown -f executive_report.md

# 2. Standalone Styled HTML Report (Print & PDF Ready)
reconx all company.com -o html -f easm_report.html

# 3. Structured JSON for SIEM/SOAR integration
reconx all company.com -o json -f attack_surface.json

# 4. Tabular CSV for Spreadsheet Analysis
reconx all company.com -o csv -f vulnerabilities.csv

# 5. Batch export of all formats into a directory
reconx all company.com -o all -d ./exports/company/

6. ReconHound Dashboard

ReconHound provides an interactive graph visualization experience inspired by SpecterOps BloodHound, powered by FastAPI and Cytoscape.js.

⠀⠀⠀⠀⡀⠀⠀⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⣷⠀⠀⢰⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⣿⣧⠀⣼⣿⣇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢸⣿⣿⡆⠘⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⣸⣿⣿⣿⡄⠙⠛⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⣿⣿⣿⣿⣷⡀⣿⣿⣿⣿⠿⠿⢿⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀   RECONHOUND DAEMON
⠀⠀⢰⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣄⡀⢻⣿⣿⣿⠟⢿⣿⠛⣦⡀⢻⣿⡇⠀   ==================================
⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠛⣶⡞⠻⣶⠛⢻⡄⠹⠀⠀   [✓] Attack Surface Dashboard UI
⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣿⣷⣾⣿⣶⣿⣿⠆⠀⠀   [✓] Threat Tracking Engine
⠀⢠⣿⣿⣿⡄⢹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣏⣉⣉⣉⣉⣉⣉⣉⣉⣉⡉⠀⠀⠀   Usage: reconexec hound start
⠀⢸⣿⣿⣿⣷⡀⠻⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠿⠃⠀⠀⠀
⠀⣿⣿⣿⣿⣿⣷⣶⣶⣶⣶⣶⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

Daemon Server Commands

Graph-First UX & Floating Lead Management

ReconHound adopts a Graph-First interaction model. Instead of relying on cluttered sidebars, you manage your passive attack surface directly from the canvas itself.

• Target Root Persistence: The central node (target_root) acts as your scope anchor. Even if you deselect all leads or click "Collapse All", this node remains visible on the canvas.
• Cinematic Auto-Centering: If the target_root becomes the only visible node, the camera will smoothly glide and zoom into it automatically.
• Floating Leads Modal (Context Menu): Right-click the target_root node and select "Explore Leads..." to open an interactive, translucent modal directly in the center of the graph featuring a real-time search bar. From here, you can seamlessly search, filter, and select passive IPs, Domains, and Subdomains to expand the visual tree. (You can quickly dismiss it by clicking anywhere on the canvas or pressing ESC).
• Intelligent Auto-Select: If your initial scan discovers a very small footprint (50 leads or less), the engine will preemptively select and render them all upon your first dashboard load, avoiding unnecessary manual clicks.
• Canvas HUD Search: The search bar is now embedded directly as a floating HUD in the top-left of the canvas, maximizing tactical screen real estate.
• Clean Canvas (BloodHound-style): The graph starts completely clean, showing only the root node. Expanding assets no longer forces target updates in the database, promoting a fluid, passive exploration.
• CLI Command reconx hound restart: Enables seamless, instant restart of the WebGUI backend without dropping dependencies during development.

Graph-First UX & Floating Lead Management

ReconHound adopts a Graph-First interaction model. Instead of relying on cluttered sidebars, you manage your passive attack surface directly from the canvas itself.

• Target Root Persistence: The central node (target_root) acts as your scope anchor. Even if you deselect all leads or click "Collapse All", this node remains visible on the canvas.
• Cinematic Auto-Centering: If the target_root becomes the only visible node, the camera will smoothly glide and zoom into it automatically.
• Floating Leads Modal (Context Menu): Right-click the target_root node and select "Explore Leads..." to open an interactive, translucent modal directly in the center of the graph featuring a real-time search bar. From here, you can seamlessly search, filter, and select passive IPs, Domains, and Subdomains to expand the visual tree. (You can quickly dismiss it by clicking anywhere on the canvas or pressing ESC).
• Intelligent Auto-Select: If your initial scan discovers a very small footprint (50 leads or less), the engine will preemptively select and render them all upon your first dashboard load, avoiding unnecessary manual clicks.
• Canvas HUD Search: The search bar is now embedded directly as a floating HUD in the top-left of the canvas, maximizing tactical screen real estate.

Graph Topology & Semantic Visual Guide

Edge Semantics & Relational Topology

Directed relationship edges represent resolution, exposure, and threat ancestry in the attack surface graph:

Interface Highlights & Active Engine

ReconHound's interface is designed to be highly intuitive (similar to BloodHound), allowing you to navigate, filter, and attack targets with just a few clicks.

• Interactive Navigation: Left-click any node to open the Asset Inspector (technical details, geolocation, vulnerabilities), and right-click to open the Context Menu (target marking, collapse/uncollapse, and quick actions).
• Smart Target Management (WAF/CDN Bypass): When setting a Domain/Subdomain (FQDN) as a target, ReconHound preserves the Server Name Indication (SNI) to bypass WAFs and Cloudflare. For IP targets, the engine handles dynamic connection reconciliation.
• Smart Scanning (Masscan & Nuclei): Designed for stealth and operational efficiency. Masscan skips already verified active ports, and Nuclei strictly attacks "Confirmed Active" ports, reducing network noise to zero. Both engines perform graceful database state saves if cancelled.
• Strict Attack Path Filtering: Using the sidebar filters (like CISA KEV or Critical CVSS), the graph prunes the entire network to isolate only direct attack chains (Root ──► IP ──► Port ──► CVE), hiding all harmless visual noise.

7. Threat Intelligence & 3D EASM Risk Matrix

The traditional vulnerability prioritization model based purely on static CVSS scores is obsolete. In a real External Attack Surface Management (EASM) scenario, a purely theoretical CVSS 9.8 vulnerability on an inactive host or with no known exploit represents less immediate operational risk than a CVSS 7.5 flaw on an exposed port actively weaponized by ransomware operators.

To eliminate the noise of thousands of irrelevant alerts and guide security teams directly to imminent threats, ReconExec and ReconHound implement the Three-Dimensional EASM Risk Matrix.

The 3 Fundamental Dimensions

The 3 Pillars of Dimension 3 (Real-World Threat)

Dimension 3 does not require 100% coincidence across all feeds to prevent dangerous blind spots. It is triggered if the finding matches any of the following pillars:

Practical Comparative Scenario

Consider two vulnerabilities discovered by the pipeline on an organization's attack surface: