reconaut

A modular reconnaissance orchestration framework for authorized penetration testing. One command runs a full recon pipeline — passive OSINT → DNS → live hosts → ports & services → TLS → web fingerprinting → content discovery → screenshots → (opt-in) vulnerability templates — then renders the results as JSON, Markdown and HTML reports.

⚠️ Authorized use only. reconaut is built for authorized security testing and education. Scanning systems you do not own or lack explicit, written permission to test may be illegal. You alone are responsible for staying within your engagement's authorized scope.

---

Why reconaut

Mature recon frameworks already exist (reconFTW, Osmedeus, BBOT). reconaut is not trying to out-feature them — it's a clean, well-engineered take on the same problem that demonstrates the reconnaissance methodology and solid software design:

• 🧩 Modular & extensible — every recon step is a self-registering Module; every external tool is a uniform Adapter. Adding a tool is one small file.
• 🐍 Works out of the box — a pure-Python native layer (crt.sh, RDAP/WHOIS, DNS, HTTP probing, TLS inspection, TCP scan, Wayback) means reconaut does useful recon with zero external binaries, even on a bare Windows box.
• ⬆️ Graceful upgrade — when a better tool is installed (e.g. nmap, httpx, sslscan), the matching adapter automatically supersedes its native fallback. Nothing crashes when a tool is missing; reconaut check-tools tells you what to install.
• ⚡ Async orchestration — phases run in order, modules within a phase run concurrently, and data flows from one phase to the next (subdomains → resolution → live hosts → ports → TLS …).
• 🔒 Safe by default — passive by default; active phases require an explicit --active flag and an authorization confirmation.
• ✅ Engineered like production code — fully type-checked (mypy --strict), linted/formatted (ruff), unit-tested (pytest), CI on GitHub Actions, and shipped as a Docker image.

Architecture

flowchart LR
    T["Target<br/>domain · IP · URL"] --> P["Passive OSINT"]
    P --> D["DNS"]
    D --> HD["Live hosts"]
    HD --> PS["Ports & services"]
    PS --> TL["TLS / SSL"]
    TL --> WF["Web fingerprint"]
    WF --> CD["Content discovery"]
    CD --> SC["Screenshots"]
    SC --> VL["Vuln templates"]
    VL --> R["Reports<br/>JSON · MD · HTML"]

Loading

Layered design — the engine talks to modules; modules use a pure-Python native layer or thin adapters around external tools:

flowchart TD
    CLI["CLI · Typer + Rich"] --> ENG["Engine<br/>async orchestrator"]
    ENG --> MOD["Modules<br/>one per recon step"]
    MOD --> NAT["Native layer<br/>pure Python, no binary"]
    MOD --> ADP["Adapters<br/>wrap external tools"]
    ADP --> EXT["nmap · httpx · subfinder<br/>sslscan · nuclei · gobuster · …"]
    ENG --> REP["Reporters<br/>JSON · Markdown · HTML"]

Loading

More detail in docs/architecture.md.

Demo

$ reconaut scan scanme.nmap.org --active -p full

  _ __ ___  ___ ___  _ __   __ _ _   _  / /_
 | '__/ _ \/ __/ _ \| '_ \ / _` | | | || __|
 | | |  __/ (_| (_) | | | | (_| | |_| || |_
 |_|  \___|\___\___/|_| |_|\__,_|\__,_| \__|
        reconaut · modular reconnaissance orchestration framework

▶ Passive OSINT (3 modules)
▶ DNS enumeration (2 modules)
▶ Live-host discovery (1 module)
▶ Port & service scan (1 module)   45.33.32.156: 2/198 ports open
▶ TLS / SSL analysis (1 module)
▶ Web fingerprinting (1 module)

           Scan summary
 Target         scanme.nmap.org
 Subdomains     2     Hosts        2
 Web assets     1     URLs         83
 Findings       1     Modules run  9
 Duration       24.9s

Reports written: output/scanme.nmap.org_.../reconaut-report.{json,md,html}

📄 Sample reports from that run (committed in the repo): Markdown (renders on GitHub) · HTML (open in a browser) · JSON

Installation

Docker (recommended — bundles every external tool)

docker build -t reconaut .
docker run --rm -v "$PWD/output:/app/output" reconaut scan example.com

The multi-stage image ships nmap, subfinder, httpx, sslscan, nuclei, gobuster, naabu, amass, gau and more, so every module is available with no host setup.

Python (native core, runs anywhere — Windows/macOS/Linux)

pipx install .            # or: pip install .
reconaut --help

The native (pure-Python) modules work immediately. Install external tools to unlock the adapters — run reconaut check-tools to see what's present and how to get the rest.

Usage

reconaut scan example.com                 # passive scan (default), profile "standard"
reconaut scan example.com -p passive      # OSINT + DNS only, no contact with the target
reconaut scan example.com --active -p full   # full active pipeline (asks for authorization)
reconaut scan 192.0.2.10 --active -p full -f json -f html

reconaut check-tools     # which external tools are installed
reconaut list-modules    # recon modules in this build
reconaut list-profiles   # built-in scan profiles

Profile	Phases	Active?
passive	OSINT + DNS	never contacts the target
standard (default)	OSINT, DNS, live hosts, TLS, web fingerprint	active parts need --active
web	standard + content discovery, no port scan (ideal for web apps)	active parts need --active
full	everything except vuln templates	active parts need --active
full-vuln	everything incl. nuclei	active parts need --active

Global flags go before the command (e.g. reconaut -v --no-banner scan …). See docs/usage.md for the full reference and the YAML config format.

Tools orchestrated

Phase	Native (built-in)	External tool adapters
Passive OSINT	crt.sh, RDAP/WHOIS, Wayback	subfinder, amass, gau
DNS	records + resolution (dnspython)	—
Live hosts	HTTP probe	httpx
Ports & services	async TCP connect scan	nmap, naabu
TLS / SSL	certificate + protocol (cryptography)	sslscan
Web fingerprint	security headers	(httpx tech-detect)
Content discovery	—	gobuster
Vuln templates	—	nuclei

reconaut check-tools lists the full catalogue (22 tools) with install hints.

Safety & ethics

• Passive by default. Active phases (port scan, content discovery, vuln templates, …) only run with --active, and an interactive prompt asks you to confirm authorization (--yes to skip it in automation).
• Identifiable. Native HTTP requests send a reconaut/… User-Agent.
• No surprises. Missing tools degrade gracefully to native modules — they never crash a run.

Development

pip install -e ".[dev]"
ruff check . && ruff format --check .   # lint + format
mypy src                                 # strict type checking
pytest -q                                # unit tests (parsers, config, engine — offline)
pre-commit install                       # optional: run ruff on every commit

CI (GitHub Actions) runs lint, types and tests on Python 3.11 & 3.12, and builds the Docker image.

What this project demonstrates

A compact but real codebase showing: a plugin/registry architecture, asyncio orchestration with bounded concurrency, strict typing with pydantic v2 models end-to-end, defensive parsing of third-party tool output (tested against fixtures), graceful degradation, multi-format reporting with Jinja2, a multi-stage Dockerfile, GitHub Actions CI — and a deliberate, documented stance on authorization and ethics.

License

MIT © Thomas NOYON (@Making6). For authorized security testing and educational use only.