ReconFrame — Unified Reconnaissance Framework

01 — Tools

12 Tools, One Interface

Every tool runs with its full power. ReconFrame is an orchestration layer — it coordinates them intelligently, not a watered-down wrapper.

live scan output — example.com

nmap

Network

Port scanning, service detection, OS fingerprinting. The backbone of every recon operation.

gobuster

Web

Directory and DNS brute-force enumeration. Finds hidden paths and subdomains fast.

nikto

Web

Web server misconfiguration and vulnerability scanner. Catches what manual testing misses.

sqlmap

Web

Automated SQL injection detection and exploitation. Runs only when web ports are open.

whois

OSINT

Domain registration and ownership lookup. Uncovers registrar, dates, and contact data.

subfinder

DNS

Passive subdomain enumeration from public sources. Fast and accurate surface mapping.

dnsenum

DNS

DNS zone transfer and brute-force enumeration. Exposes misconfigurations in DNS configs.

dnsrecon

DNS

DNS record enumeration and zone discovery. Maps the full DNS attack surface.

amass

DNS

In-depth attack surface mapping. The most thorough subdomain discovery engine available.

theHarvester

OSINT

Email, domain, IP, and hostname harvesting from public sources. OSINT at scale.

wafw00f

Web

Web Application Firewall fingerprinting. Know what's protecting the target before you attack.

sslyze

Network

SSL/TLS configuration and cipher analysis. Runs only when port 443 is open.

02 — Features

Built For Real Work

Every feature exists because running 12 tools manually wastes time. ReconFrame handles the coordination so you can focus on analysis.

🔍

Smart Target Validation

Detects IP vs domain automatically. Probes ports 80, 443, 8080 before running web tools. Skips sslyze if port 443 is closed. Every skip comes with a clear explanation.

⚡

Parallel Execution

ThreadPoolExecutor runs all tools simultaneously. Default 4 threads, configurable up to 100. A full scan that would take 40 minutes serially finishes in under 10.

📊

Live Progress Bar

Updates in-place — no terminal flooding. Shows percentage complete, current tool, and elapsed time. Stays clean and readable the entire scan.

🎨

Color-Coded Results

Green = open/success. Red = errors. Yellow = warnings. Cyan = headers. Results grouped by category: Open Ports, Directories, Subdomains, Vulnerabilities, SSL Issues, OSINT, WAF.

📄

Report Export

Save all results to a plain text file with -o. ANSI color codes stripped automatically for clean reading and sharing with clients or teammates.

🔊

Verbose Mode

-v shows the full raw output from every tool. Essential for deep analysis and debugging — see exactly what each tool found, nothing summarised away.

✅

Tool Availability Check

On startup, checks if each of the 12 tools is installed. For anything missing, shows the exact install command. No silent failures mid-scan.

🎬

Cinematic Startup

MSF-style matrix rain, glitch logo reveal, and module loading sequence. Skip it with --no-banner for pure speed. Because first impressions matter.

🧠

Zero Dependencies

Single Python file. Only standard library. No pip install, no virtual environment, no requirements.txt. Clone it, chmod +x, run it.

03 — Architecture

How It's Built

A single Python file with 10 distinct components. Each one has a clear responsibility. Nothing bleeds into anything else.

Color Management

ANSI Color Engine

All terminal colors defined as constants. Green, red, yellow, cyan, blue, magenta, white, gray. Every output goes through this layer — consistent coloring across the entire tool.

Box-Drawing Engine

Unicode Box Renderer

Custom functions: top(), bot(), mid(), row(), ruled(), center(). Uses Unicode box-drawing characters (╔ ╗ ╚ ╝ ║ ═ ╠ ╣) to build the professional terminal UI panels.

Config Manager

Persistent JSON Config

Stores user data in /etc/reconframe/config.json or ~/.reconframe.json. Tracks total scans performed. JSON format — human-readable, easy to inspect and modify.

Tool Registry

12-Tool Manifest

Each tool defined as an object: id, name, description, category, binary name, risk level, install hint. The registry is the single source of truth for tool metadata throughout the codebase.

ScanContext

Smart Validation Layer

Detects IP vs domain. Probes open ports before running web tools. Skips inappropriate tools with clear reasons. Handles the "enter domain for DNS tools" prompt when an IP is given.

Tool Runners

12 Dedicated Run Functions

run_nmap(), run_gobuster(), etc. Each one: checks if the binary is installed, builds the command, runs it with a timeout, returns status and output. Isolated — changing one never breaks another.

ScanEngine

Parallel Execution Core

ThreadPoolExecutor manages concurrent tool execution. Live progress bar updates in-place using cursor control sequences. Graceful Ctrl+C handling — kills all threads cleanly without leaving zombie processes.

Results Renderer

Output Grouping & Formatting

Groups findings by category: Open Ports, Directories, Subdomains, Vulnerabilities, SSL Issues, OSINT, WAF. Color-coded by severity. Verbose mode shows full raw output. File export strips ANSI codes.

User Interface

Checkbox-Style TUI

Main menu with options. Checkbox tool selection — pick exactly what runs. Target input with examples. Legal disclaimer before scan. All navigation via keyboard numbers and letters.

Startup Animation

Cinematic Intro Engine

Matrix-style green character rain. Glitch effect on the ReconFrame logo reveal. Module loading sequence with fake percentage bars. Skip entirely with --no-banner for zero overhead.

04 — Usage

Command Reference

install

$ git clone https://github.com/Jishnuec/reconframe.git
$ cd reconframe
$ chmod +x reconframe.py
$ ./reconframe.py

Command	Description
./reconframe.py	Interactive mode — full TUI menu
./reconframe.py -t example.com	Quick scan of a domain
./reconframe.py -t 192.168.1.1	Scan an IP address
./reconframe.py -t example.com -v	Verbose mode — shows full tool output
./reconframe.py -t example.com -o report.txt	Save results to file
./reconframe.py -t 10.0.0.1 --tools nmap,whois	Run specific tools only
./reconframe.py --list-tools	List all available tools
./reconframe.py --no-banner	Skip startup animation

smart validation in action

# IP given, DNS tools selected — prompts for domain
$ ./reconframe.py -t 192.168.1.100
  [?] IP detected. Enter domain for DNS tools (or Enter to skip): example.com

# No web ports — web tools automatically skipped
  [!] No web ports detected (80/443/8080 closed)
  [-] Skipping: gobuster, nikto, sqlmap, wafw00f

# Port 443 closed — sslyze automatically skipped
  [!] SSL scan only works on HTTPS ports
  [-] Skipping: sslyze

05 — Development Journey

How It Was Built

8 phases from initial concept to GitHub publication. Every phase solved a specific problem.

Phase 1

Initial Concept & Tool Selection

Identified the need for a unified reconnaissance tool. Researched common tools used in penetration testing. Selected 12 core tools covering network, web, DNS, and OSINT — enough to cover the full initial recon phase without overlap.

Phase 2

Core Architecture Design

Designed the box-drawing engine for professional terminal UI. Created the tool registry structure — each tool as a data object with id, binary, description, risk level. Implemented the base smart validation logic for IP vs domain detection.

Phase 3

Parallel Execution Engine

Built ThreadPoolExecutor-based parallel execution. The live progress bar required cursor control sequences (ANSI escape codes) to update in-place without terminal scrolling. Added rate limiting to avoid overwhelming targets with simultaneous connections.

Phase 4

Results Rendering System

Created grouping logic for different finding types — ports go to Open Ports, discovered paths to Directories, etc. Implemented color coding based on severity. Added verbose mode that shows full raw output per tool for deep analysis.

Phase 5

User Interface

Built the checkbox-style tool selection menu using Unicode box-drawing characters. Created main menu with options. Added legal disclaimer and target input with format examples. All keyboard-driven — no mouse required.

Phase 6

Cinematic Startup Animation

Designed the MSF-style startup: matrix rain using random printable characters, glitch effect on the ReconFrame logo (random character substitution with delay), module loading sequence with fake progress bars. Full animation skippable with --no-banner.

Phase 7

Testing & Bug Fixes

Tested on Kali Linux, Ubuntu, and Debian. Validated against live targets including example.com and scanme.nmap.org. Fixed 5 significant bugs: progress bar repeating, text truncation, DNS tools on IPs, web tools without open ports, and tool timeouts.

Phase 8

GitHub Publication

Created repository at github.com/Jishnuec/reconframe. Added MIT License. Wrote comprehensive README with installation instructions and usage examples. Pushed code with clean commit history.

06 — Problems Solved

5 Real Bugs Fixed

These weren't obvious issues — each one required understanding the underlying system before the fix made sense.

Progress Bar Repeating 12 Times

The header above the progress bar was redrawn inside the tool loop, causing it to print fresh 12 times instead of updating in-place.

Fix

Moved the header outside the loop. Used ANSI cursor movement sequences (\033[A) to move the cursor up and overwrite only the progress content — not the header.

Text Truncation in Columns

"version" appeared as "versio..." in the results table. Column widths were hardcoded too narrow, cutting off content in the UI boxes.

Fix

Calculated column widths dynamically based on terminal size using shutil.get_terminal_size(). Content now wraps cleanly at any width.

DNS Tools Failing on IP Targets

When an IP address was given as the target, DNS tools like subfinder and amass would fail — they require a domain name, not an IP.

Fix

Added IP detection with socket.inet_aton(). If IP detected and DNS tools selected, prompt for a domain. If no domain entered, skip all DNS tools with a clear message.

Web Tools Running Without Open Ports

gobuster, nikto, and sqlmap were running against targets with no web server — consuming time and producing useless output.

Fix

Added port probing with socket.connect_ex() before any web tool execution. If ports 80, 443, and 8080 are all closed, all web tools are skipped with a clear explanation.

Tool Timeouts Hanging the Scan

Slow or unresponsive targets caused individual tool processes to hang indefinitely, blocking progress on the entire scan.

Fix

Added timeout= parameter to subprocess.run() for every tool runner. Timeout exceeded produces a friendly "tool timed out" message and the scan continues with the next tool.