ReconScript

ReconScript is a read-only reconnaissance toolkit. It collects metadata from approved targets, consolidates the findings into human-readable reports, and keeps each action auditable for regulated environments. The project ships with both a Flask web interface and a command-line client so assessments can run in whichever workflow is most convenient.

Key Features

• Safety-first design: All gathering routines are scoped to passive network inspection so the tool can be reviewed and approved for tightly controlled engagements.
• Multiple execution paths: Start the Flask dashboard, use the CLI, or run the Docker image to match local policy requirements.
• Structured reporting: Export HTML, Markdown, JSON, or PDF artefacts, each tagged with metadata for downstream review.
• Operational guardrails: Environment variables, consent manifests, and placeholder keys highlight what must be configured before running against production targets.

Safe Default Reconnaissance Profile

ReconScript now ships with a conservative, non-intrusive recon profile that limits every network touchpoint. The ReconProfile dataclass describes the caps in effect (TCP port counts, concurrency, DNS behaviour, HTTP enumeration depth) and is surfaced in every report under metadata.profile. The defaults explicitly disable exploitation, credentialed checks, and aggressive crawling.

• Passive DNS: WHOIS summaries, certificate transparency notes, and hostname resolutions without issuing active probes beyond a single record sweep.
• Active probing: one pass of rate-limited DNS queries, a single UDP sweep, and a TCP SYN scan capped to a curated port list.
• HTTP coverage: GET/HEAD requests and small wordlist enumeration only for low/medium evidence levels, with strict per-request rate limiting.
• Reporting: every finding includes timestamps, the exact pseudo-command executed, and a 400-character evidence snippet.

You can create custom profiles from the CLI or web UI by instantiating ReconProfile and passing it to run_recon(). This allows regulated environments to tighten or loosen bounds while keeping safe defaults intact.

Project Layout

The repository follows a conventional Python structure with documentation and automation assets kept alongside the source code. A more detailed component map lives in docs/DEPENDENCY_OVERVIEW.md.

ReconScript
├── reconscript/        → Application package (Flask views, scanners, exporters)
├── templates/          → HTML and Markdown templates used by the web UI
├── scripts/            → Utility scripts for keys, manifests, and environment setup
├── tests/              → Pytest suites covering CLI and UI behaviours
├── docs/               → Additional guides, references, and architecture notes
└── results/            → Generated reports (ignored by Git)

Installation

ReconScript targets Python 3.9 through 3.13 on Linux, macOS, and Windows. The commands below create an isolated environment, install dependencies, and verify the installation.

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\\Scripts\\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

For contributors, install the optional tooling as well:

python -m pip install -r requirements-dev.txt

Quick Start

Launch the Web UI

Before starting the Flask UI, generate deployment-specific secrets and point the application at them:

export FLASK_SECRET_KEY="$(openssl rand -hex 32)"
export ADMIN_USER=security-admin
export ADMIN_PASSWORD='replace-with-strong-passphrase'
export CONSENT_PUBLIC_KEY_PATH=/secure/path/consent_ed25519.pub
export REPORT_SIGNING_KEY_PATH=/secure/path/report_ed25519.priv
python start.py

The launcher checks dependencies, loads environment variables from .env if present, and starts the Flask server on http://127.0.0.1:5000. Use start.sh, start.bat, or start.ps1 for platform-specific wrappers.

Run a CLI Scan

python -m reconscript --target 203.0.113.10 --ports 80 443 --format html

Outputs are timestamped under results/<scan-id>/ and include hashes to support tamper review.

Docker Usage

A Docker Compose definition is provided for isolated demonstrations:

docker compose up --build

Mount the results/ directory when running containers so generated artefacts persist outside the container lifecycle. Override the required secrets via environment variables or secrets managers at runtime.

Observability

ReconScript exposes Prometheus-compatible metrics at /metrics and a readiness probe at /healthz. Scrape the metrics endpoint to monitor scan durations, completion counts, and open-port histograms.

Validation and Quality Checks

The project includes automation scripts and workflows to keep contributions consistent:

python -m pip install -r requirements-dev.txt
black --check .
ruff check .
bandit -r reconscript
pip-audit --requirement requirements.txt
pytest

Continuous integration is handled by .github/workflows/ci-matrix.yml, which caches Python dependencies, runs Ruff, Black, and pytest on Python 3.9 and 3.11, and uploads coverage artefacts for inspection.

Troubleshooting

• Missing system packages: PDF export requires additional system libraries; review docs/HELP.md before enabling that pathway.
• Permissions errors: Ensure write access to the results/ directory; it stores generated artefacts and logs.
• Environment variables: Copy .env.example to .env to configure default targets, API keys, or Flask secrets in a local-only context.
• Docker networking: When running inside Docker, provide the SCAN_TARGET environment variable to avoid host-only lookups.

Support and Contributions

Bug reports and feature ideas are welcome via GitHub issues. Follow the guidelines in CONTRIBUTING.md and run the validation commands listed above before opening a pull request.

License and Credits

ReconScript is released under the MIT License. See the LICENSE file for full terms.

Author: Daniel Madden