WebRekon

CTF Web Reconnaissance & Learning Assistant

WebRekon wraps existing reconnaissance tools in a clear terminal workflow. It helps CTF players collect web reconnaissance evidence, understand notable results, keep notes, and create a Markdown write-up without performing exploitation.

Authorized use

Use WebRekon only against CTF platforms, local labs, systems you own, or targets for which you have explicit permission. The operator must confirm authorization before scanning begins.

Features

• Target validation and authorization confirmation
• Nmap port and service discovery
• HTTP response and header analysis
• robots.txt parsing
• ffuf directory discovery with Gobuster fallback
• Static HTML/source inspection without JavaScript execution
• Deterministic web intelligence and safe manual-investigation guidance
• Technology fingerprinting with optional WhatWeb support
• Passive sensitive-path, API, authentication, cookie, and SSRF indicator analysis
• Structured findings, safe learning guidance, player notes, and Markdown reports

WebRekon is a terminal-based Linux CLI tool. It automates repetitive reconnaissance, organizes the evidence it collects, and explains what the results mean. It does not exploit targets or execute JavaScript.

Project structure

WebRekon/
├── webrekon/                    # Application package
│   ├── analyzers/            # web intelligence, source, API, technology, and findings
│   ├── cli/                  # Rich terminal interface and menus
│   ├── core/                 # Models, workflow, validation, runners
│   ├── intelligence/         # Deterministic guidance and optional AI adapter
│   ├── reporting/            # Markdown report generation
│   ├── scanners/             # Nmap, HTTP, and content discovery wrappers
│   └── utils/                # Logging and configuration helpers
├── config/
│   └── settings.yaml         # Runtime settings
├── reports/                  # Generated reports (created at runtime)
├── tests/                    # Test suite
├── northstar-site/            # Separate local Flask/Docker test target
│   ├── app.py                 # Harmless Northstar Systems web application
│   ├── docker-compose.yml     # Loopback-only 127.0.0.1:8080 service
│   ├── Dockerfile             # Container build definition
│   ├── templates/             # Website pages
│   └── static/                # Website styling
├── main.py                   # Application entry point
├── requirements.txt          # Runtime dependencies
├── requirements-dev.txt      # Development dependencies
└── LICENSE

Installation

Install via pipx (recommended):

pipx install webrekon
webrekon

Or for development from source:

git clone https://github.com/thehusnain/WebRekon.git
cd WebRekon
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

WebReKon uses nmap, curl,whatweb and optionally ffuf or gobuster. Install them through your Kali/Debian package manager and configure a valid wordlist in config/settings.yaml.

The included northstar-site/ project is separate from WebReKon itself. It is a small fictional technology-company website for authorized local testing. It contains harmless source comments, robots.txt references, hidden pages, forms, and fictional status information so the CLI can be demonstrated without contacting an external system.

Run

python3 main.py

Set a target, confirm authorization, then choose Run Full WebRekon Workflow from the Recon Menu. Generated reports are saved in reports/.

Linux CLI workflow

Run WebRekon from a Linux terminal, preferably inside the project virtual environment:

source .venv/bin/activate
python3 main.py

The CLI validates the URL, asks for authorization, checks reachability, checks available tools, runs the enabled reconnaissance stages, presents findings and guidance, and can save a timestamped Markdown report. Press Ctrl+C to cancel safely or choose Q to exit.

Local Northstar test target

Northstar Systems is an included, separate Flask application for local demonstrations. Its website does not identify itself as a test target. The README inside northstar-site/ documents its routes and controlled purpose.

Requirements: Docker Engine and Docker Compose.

Start it from the WebRekon repository:

docker compose -f northstar-site/docker-compose.yml up --build -d
curl http://127.0.0.1:8080/health

The service is bound only to 127.0.0.1:8080; it is not published to the LAN or Internet. Use the local URL http://127.0.0.1:8080 as the authorized WebRekon target. Stop it when finished:

docker compose -f northstar-site/docker-compose.yml down

Northstar includes public pages such as /, /about, /services, /contact, /login, /portal, /health, /robots.txt, and /sitemap.xml. Controlled hidden pages include /archive/, /admin/, and /internal-status/. The forms return harmless responses and do not store submitted credentials or personal information. Do not use this target outside the local authorized environment.

Testing WebRekon

python3 -m compileall .
python3 -m pytest -q

The test suite covers validation, models, HTTP parsing, Nmap parsing, tool detection, subprocess handling, and error behavior. The Northstar application is deliberately tested separately from WebRekon's unit suite.

Configuration

config/settings.yaml contains discovery wordlists, extensions, timeouts, passive sensitive paths, output paths, and optional AI settings. WebRekon continues normally when AI is unavailable.

Scope

WebRekon is a reconnaissance and learning assistant. It does not exploit targets, execute JavaScript, submit payloads, modify cookies, brute force credentials, or access internal services. Findings are clues for manual investigation only.

License

MIT — see LICENSE.