Metadata-Version: 2.4
Name: webrekon
Version: 1.0.0
Summary: CTF Web Reconnaissance & Learning Assistant
Author: Husnain
License: MIT
Project-URL: homepage, https://github.com/thehusnain/WebRekon
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.0
Requires-Dist: PyYAML>=6.0.1
Dynamic: license-file

# 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

```text
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):

```bash
pipx install webrekon
webrekon
```

Or for development from source:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
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](LICENSE).
