ActiveRecon

A Python-based reconnaissance CLI tool for authorized security assessments, lab environments, and security learning.

ActiveRecon combines Nmap scanning, HTTP and TLS analysis, DNS checks, web endpoint discovery, Markdown reports, JSON schema output, and interesting signal generation into a structured recon workflow.

---

Quick Start

Run a web-focused recon workflow and save timestamped Markdown and JSON reports under reports/:

activerecon --target 127.0.0.1 --scan-profile web --output juice-shop

Check your local setup without scanning anything:

activerecon --doctor

---

Responsible Use

Important: Only scan systems that you own or have explicit written permission to assess.

ActiveRecon is an active reconnaissance tool. It may generate network traffic that can be detected by monitoring systems.

Do not use ActiveRecon against systems, networks, bug bounty targets, or production environments without clear authorization and defined scope.

---

Overview

ActiveRecon helps organize early-stage reconnaissance into a repeatable command-line workflow.

Instead of manually running separate commands and collecting notes from different tools, ActiveRecon can:

• run predefined Nmap scan profiles
• check local setup with a no-scan --doctor command
• identify open, closed, and filtered port results
• detect HTTP services from open Nmap ports, including common web and development ports
• collect HTTP status, final URLs, redirects, page titles, headers, missing security headers, and technology hints
• collect TLS certificate metadata for HTTPS services
• query A, MX, and TXT DNS records, while skipping noisy DNS lookups for IP address targets
• run endpoint discovery automatically from the web scan profile
• generate timestamped Markdown and JSON reports under reports/
• highlight interesting signals for follow-up review

This project is intended for learning, lab use, portfolio development, and authorized testing.

---

Features

Reconnaissance Workflow

ActiveRecon currently supports:

Area	Capability
Nmap	Scan profiles, executable discovery, XML parsing, timeout and error results
HTTP	Status, title, final URL, redirects, headers, missing headers, tech hints
TLS	TLS version, cipher, subject, issuer, and certificate validity dates
DNS	Separate A, MX, and TXT lookups, with clean IP-target skip behavior
Web	Endpoint discovery from HTML, headers, JavaScript, robots.txt, and probes
Reporting	Timestamped Markdown and JSON schema 1.1 reports
Safety	Responsible-use notice, scope guard, dry-run mode, doctor checks
Analysis	Low-noise interesting signals for follow-up review

---

Scan Profiles

Scan profiles are configured in:

activerecon/modules/config/config.yaml

Current profiles:

Profile	Purpose
fast	Quick scan using top ports
web	Web workflow for HTTP/HTTPS and common development ports
standard	More detailed TCP scan with service and default script detection
full	Full TCP port scan with service and default script detection
udp	UDP scan using top UDP ports and script timeout

The web profile is a workflow preset. It runs the web-focused Nmap profile, HTTP analysis, TLS analysis where applicable, endpoint discovery, interesting signal generation, and Markdown plus JSON reporting.

---

Example Usage

Run a quick scan:

activerecon --target example.com --scan-profile fast

Run a web-focused scan:

activerecon --target 127.0.0.1 --scan-profile web --output juice-shop

Generate only JSON output:

activerecon --target example.com --scan-profile web --output example-web --output-format json

Preview planned report paths without scanning:

activerecon --target example.com --scan-profile fast --dry-run

Run a full TCP scan:

activerecon --target 127.0.0.1 --scan-profile full --output localhost-full

Check local setup without scanning:

activerecon --doctor

Use a scope file:

activerecon --target app.example.com --scope scope.txt --scan-profile standard

---

Example Report Output

ActiveRecon generates timestamped reports under reports/ by default:

reports/example.com_20260617_090807.md
reports/example.com_20260617_090807.json

Generated Markdown reports include sections such as:

# Active Recon Report

## Summary
## Scan Information
## Port Scan Results
## HTTP Analysis
## Endpoint Discovery
## TLS Analysis
## DNS Analysis
## Interesting Signals

Markdown reports also include:

• a scan context note for local, private, Docker, virtualization, or lab targets
• open ports shown before other port states
• endpoint discovery grouped into API-like endpoints, frontend routes, well-known/probed paths, and static assets
• static asset summaries instead of long asset lists
• cautious wording such as "follow-up recommended" instead of confirmed vulnerability language

Example interesting signals:

INFO   [http]       HTTP service detected on port 3000
LOW    [http]       Missing Content-Security-Policy header
INFO   [cors]       Wildcard CORS header observed
INFO   [endpoint]   API-like endpoint discovered; follow-up recommended
INFO   [endpoint]   Interesting path found in response header X-Recruiting
INFO   [technology] X-Powered-By header exposed

---

Installation

Prerequisites

ActiveRecon requires:

• Python 3.6 or later
• Nmap

Install Nmap on Debian/Ubuntu-based systems:

sudo apt-get update
sudo apt-get install nmap

On Windows, install Nmap from the official installer and make sure nmap.exe is available in PATH.

ActiveRecon also attempts to resolve Nmap from common Windows install paths.

The --doctor command checks Python, Nmap availability, the resolved Nmap path, config loading, and whether the reports directory is writable.

---

Install from GitHub

git clone https://github.com/CamiloCod3/ActiveRecon.git
cd ActiveRecon
pip install .

For local development:

pip install -e .

---

Usage

activerecon --target <IP_OR_DOMAIN> --scan-profile <PROFILE> [--output <OUTPUT_FILE>] [--output-format md|json|both] [--verbose|--quiet]
activerecon --doctor

Arguments

Argument	Description
--target	Target IP address or domain name
--doctor	Check Python, Nmap, config loading, and report directory write access without scanning
--scan-profile	Nmap scan profile to use
--output	Optional report name or path
--output-format	md, json, or both. Defaults to both
--scope	Optional file with allowed domains, IPs, or CIDR ranges
--dry-run	Validate arguments and planned outputs without scanning
--verbose	Show detailed internal logs
--quiet	Suppress the normal summary and show only errors plus report paths

---

Config

Common config values live in:

activerecon/modules/config/config.yaml

Example:

http_timeout: 5
nmap_timeout: 300

# Optional override if Nmap is installed outside PATH.
# nmap_executable: "C:\\Program Files\\Nmap\\nmap.exe"

scan_profiles:
  fast: "-Pn -n -sT --top-ports 100 -T4"
  web: "-Pn -n -sT -p 80,443,3000,5000,8000,8080,8443,9000,9443 -sV -T3"
  standard: "-Pn -n -sT -sV -sC -T3"
  full: "-Pn -n -sT -p- -sV -sC -T4"
  udp: "-Pn -n -sU --top-ports 100 -sC --script-timeout 5m"

web_recon:
  enabled_profiles:
    - web
  endpoint_probe_limit: 50
  fetch_javascript: true
  same_origin_only: true
  well_known_paths:
    - /robots.txt
    - /sitemap.xml
    - /.well-known/security.txt
    - /api
    - /rest
    - /ftp
    - /admin
    - /login
    - /debug
    - /swagger
    - /api-docs

---

Scope Guard

Use --scope to require the target to match an allowed domain, IP address, or CIDR range before any scan runs.

Example scope.txt:

example.com
192.0.2.0/24

Subdomains are allowed when the parent domain is listed.

For example:

example.com

allows:

app.example.com

---

JSON Schema

The JSON report uses schema version 1.1 and keeps existing result keys for backwards compatibility.

{
  "schema_version": "1.1",
  "generated_at": "2026-06-17T09:08:07Z",
  "target": "example.com",
  "metadata": {
    "tool": "ActiveRecon",
    "scan_profile": "web",
    "authorized_use_notice": true
  },
  "summary": {
    "host_status": "up",
    "total_ports_listed": 5,
    "open_ports": 3,
    "http_services": 1,
    "tls_results": 0,
    "dns_records": 1,
    "interesting_signals": 4,
    "endpoint_count": 6
  },
  "results": {}
}

Top-level metadata may include:

Field	Meaning
tool	Tool name, currently ActiveRecon
scan_profile	Selected scan profile when available
scan_context	Local/private/lab context note when applicable
authorized_use_notice	Always true to mark authorized-use expectations

The results object contains the same major sections used by the Markdown report, including:

Nmap Scan
HTTP Analysis
Endpoint Discovery
TLS Analysis
DNS Analysis
Attention
Interesting Signals

Markdown reports use the heading Interesting Signals. JSON output keeps results["Attention"] for backwards compatibility. New JSON consumers should prefer results["Interesting Signals"].

When the web profile is used, results["Endpoint Discovery"] keeps the original flat endpoints list and also adds machine-readable summary and category fields.

Endpoint discovery categories currently include:

api_like
frontend_routes
static_assets
well_known
header_discovered
realtime_services

The JSON endpoint_count counts unique endpoint paths from the flat endpoint list.

---

Project Structure

ActiveRecon/
|-- activerecon/
|   |-- main.py
|   `-- modules/
|       |-- config/
|       |   `-- config.yaml
|       |-- config_loader.py
|       |-- dns_analysis.py
|       |-- doctor.py
|       |-- endpoint_discovery.py
|       |-- http_enum.py
|       |-- json_report.py
|       |-- nmap_scan.py
|       |-- report_generator.py
|       |-- risk_analysis.py
|       |-- scope_guard.py
|       `-- tls_analysis.py
|-- reports/
|-- tests/
|-- .github/workflows/
|-- MANIFEST.in
|-- setup.py
`-- README.md

---

Skills Demonstrated

This project demonstrates practical skills in:

• Python CLI development
• Linux-based security tooling
• Nmap automation
• XML parsing
• DNS analysis
• HTTP service enumeration
• TLS metadata collection
• JSON and Markdown report generation
• modular Python project structure
• security-focused scripting
• authorized reconnaissance methodology

---

Roadmap

Possible future improvements include:

• multi-target scanning
• screenshot support for HTTP services
• optional SARIF or CSV export
• richer TLS and certificate risk checks
• modern Python packaging with pyproject.toml

---

Disclaimer

This project is for educational purposes, lab environments, and authorized security assessments only.

The author is not responsible for misuse of this tool.

---

License

This project is licensed under the MIT License.