Metadata-Version: 2.4
Name: bladerecon
Version: 0.2.1
Summary: BladeRecon - Fast, lightweight reconnaissance framework for attack surface discovery, bug bounty hunting, and web security assessments.
Author-email: Mohamed Kotb <ma7660@fayoum.edu.eg>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohamedxk9tb/BladeRecon
Project-URL: Repository, https://github.com/mohamedxk9tb/BladeRecon
Project-URL: Issues, https://github.com/mohamedxk9tb/BladeRecon/issues
Project-URL: Changelog, https://github.com/mohamedxk9tb/BladeRecon/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/mohamedxk9tb/BladeRecon#documentation
Project-URL: Security, https://github.com/mohamedxk9tb/BladeRecon/blob/main/SECURITY.md
Keywords: bug-bounty,reconnaissance,attack-surface,web-security,pentesting,security-research,osint,nuclei,subdomain-enumeration,endpoint-discovery
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx[http2]>=0.24.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: playwright>=1.35.0
Requires-Dist: beautifulsoup4>=4.12.0
Dynamic: license-file

# BladeRecon

![BladeRecon banner](https://raw.githubusercontent.com/mohamedxk9tb/BladeRecon/main/assets/banner.png)

![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![Version](https://img.shields.io/badge/version-0.2.1-cyan)
![CLI](https://img.shields.io/badge/interface-Rich%20CLI-0f766e)
![Reports](https://img.shields.io/badge/reports-HTML%20%2B%20Markdown-4b5563)
![License](https://img.shields.io/badge/license-MIT-green)

BladeRecon is a lightweight reconnaissance framework for bug bounty, web pentesting, and reporting-focused attack-surface discovery. It keeps the workflow terminal-native and modular while producing clean TXT, JSON, JSONL, Markdown, and HTML outputs.

Developer: [Mohamed Kotb](https://github.com/mohamedxk9tb)

## Project Overview

BladeRecon helps you move from a target domain to a readable reconnaissance report:

```text
subdomains -> probe -> js -> endpoints -> secrets -> parameters -> intelligence -> advanced -> screenshots -> nuclei -> report
```

It is designed to be:

- Lightweight and Windows-friendly
- Beginner friendly without hiding operational details
- Useful for bug bounty and small pentest workflows that need safe defaults
- Easy to inspect manually, automate from files, and hand over as reports

It is not intended to replace Amass, distributed recon stacks, or enterprise scanners.

Use BladeRecon only on assets you own or are authorized to test. Public issue
reports and shared artifacts should be sanitized before posting.


### CLI Preview

![BladeRecon CLI preview](https://raw.githubusercontent.com/mohamedxk9tb/BladeRecon/main/assets/cli-preview.png)

The CLI preview demonstrates the terminal-first workflow: branded startup,
module status output, dependency checks, and scan summaries. This matters
because BladeRecon is designed for researchers who need to understand what is
running, what was skipped, and where artifacts were written.

Data policy: sanitized `example.com` target, no fake findings, no sensitive data.

### Report Preview

![BladeRecon report preview](https://raw.githubusercontent.com/mohamedxk9tb/BladeRecon/main/assets/report-preview.png)

The report preview demonstrates the dark offline report, including a decision
dashboard, start-here investigation queue, campaign test plans, supporting
evidence, findings status, and performance analytics. This matters because
BladeRecon's output is meant to help researchers prioritize follow-up work, not
just count discovered artifacts.

Data policy: sanitized sample data with zero fake findings.

## Features

| Area | Capability |
| --- | --- |
| Subdomains | Passive sources, source attribution, cache, optional lightweight DNS expansion |
| Probe | Alive hosts, status codes, redirects, titles, content length, server/CDN/WAF hints |
| JavaScript | Finds external JavaScript assets from alive hosts and can reuse historical JS when live HTML is blocked |
| Endpoints | Extracts endpoint candidates from downloaded and historical JavaScript |
| Secrets | Informational secret pattern detection with confidence and risk labels |
| Parameters | Historical URL sources plus local fallback URL inventory and wordlist candidates |
| Screenshots | Optional Playwright screenshots with duplicate/placeholder filtering |
| Intelligence | Technology, infrastructure, cloud asset, risk, and template-selection context |
| Advanced Recon | Historical URLs, historical JS, low-noise content discovery, security-header assets, and explainable asset prioritization |
| Nuclei | Optional Nuclei wrapper with safe, balanced, aggressive, intelligence-guided profiles, ROI gating, and a lightweight baseline safety net when justified |
| Reports | Dark-theme offline HTML and Markdown reports with an executive dashboard, a single Where Should I Start queue, campaign test plans, separated research/risk scoring, section search, exports, and performance analytics |
| Safety | Safety profiles, request ceilings, per-host concurrency, rate limits, and Nuclei timeout reporting |
| Utilities | Doctor, repair, cache management, resume state, and install helper |

## Supported Modules

| Command | Description | Main Outputs |
| --- | --- | --- |
| `subdomain` | Discover subdomains from multiple sources | `subdomains.txt`, `subdomains.json`, `subdomains.jsonl` |
| `probe` | Probe alive hosts | `alive.txt`, `probe.json`, `probe.jsonl` |
| `js` | Discover JavaScript assets | `js_files.txt`, `js_files.json` |
| `endpoints` | Extract endpoints from JavaScript | `endpoints.txt`, `endpoints.json` |
| `secrets` | Detect exposed JavaScript secret patterns | `secrets.txt`, `secrets.json` |
| `param` | Discover URL parameters | `parameters.txt`, `parameters.json`, `parameters.jsonl` |
| `intelligence` | Generate recon intelligence from existing artifacts | `intelligence/*.json`, `technology/technology.json` |
| `advanced` | Generate advanced recon intelligence from existing artifacts | `historical/`, `historical_js/`, `content_discovery/`, `asset_priority.json` |
| `screenshot` | Capture screenshots from alive hosts | PNG files, `failed_screenshots.txt` |
| `nuclei` | Run Nuclei templates | `results.json`, `results.jsonl`, `results.md` |
| `report` | Generate Markdown and HTML reports | `report.md`, `report.html` |
| `full` | Run the standard workflow | All module outputs |

## Installation

See [INSTALL](INSTALL.md) for complete Windows, Python, Go, Nuclei, Playwright, Docker, and verification instructions.

Recommended install:

```bash
pipx install bladerecon
bladerecon doctor
```

Alternative install:

```bash
python -m pip install bladerecon
bladerecon doctor
```

Development install from source:

```bash
git clone https://github.com/mohamedxk9tb/BladeRecon.git
cd BladeRecon
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install .
bladerecon doctor
```

Optional external tools:

```bash
bladerecon install-deps
python -m playwright install chromium
```

BladeRecon installs Nuclei from the v3 release line when using `install-deps`.

## Quick Examples

Start here on a fresh install:

```bash
bladerecon doctor
bladerecon full example.com --profile safe
bladerecon report example.com
```

`bladerecon scan example.com --profile safe` is also accepted as a first-user
alias for `bladerecon full`.

```bash
bladerecon --help
bladerecon doctor
bladerecon subdomain hackerone.com
bladerecon probe hackerone.com
bladerecon js hackerone.com
bladerecon endpoints hackerone.com
bladerecon secrets hackerone.com
bladerecon param hackerone.com
bladerecon intelligence hackerone.com
bladerecon advanced hackerone.com --profile safe
bladerecon report hackerone.com
```

Full workflow:

```bash
bladerecon full hackerone.com
bladerecon full hackerone.com --profile safe
bladerecon report hackerone.com
```

Resume and cache:

```bash
bladerecon resume hackerone.com
bladerecon cache info
bladerecon cache clear
```

Docker:

```bash
docker build -t bladerecon .
docker run --rm bladerecon doctor
docker run --rm -v "%cd%\results:/app/results" bladerecon full hackerone.com
```

## Command Reference

| Command | Example | Expected Output |
| --- | --- | --- |
| `subdomain` | `bladerecon subdomain hackerone.com` | `results/hackerone.com/subdomains/` |
| `probe` | `bladerecon probe hackerone.com` | `results/hackerone.com/probe/` |
| `js` | `bladerecon js hackerone.com` | `results/hackerone.com/js/` |
| `endpoints` | `bladerecon endpoints hackerone.com` | `results/hackerone.com/endpoints/` |
| `param` | `bladerecon param hackerone.com` | `results/hackerone.com/parameters/` or skipped state |
| `intelligence` | `bladerecon intelligence hackerone.com` | `results/hackerone.com/intelligence/` and `results/hackerone.com/technology/` |
| `advanced` | `bladerecon advanced hackerone.com --profile safe` | Historical, content-discovery, header-asset, and priority artifacts |
| `secrets` | `bladerecon secrets hackerone.com` | `results/hackerone.com/secrets/` |
| `screenshot` | `bladerecon screenshot hackerone.com` | `results/hackerone.com/screenshots/` or skipped state |
| `nuclei` | `bladerecon nuclei hackerone.com --profile balanced` | `results/hackerone.com/nuclei/` or skipped state |
| `report` | `bladerecon report hackerone.com` | Latest isolated full-run report, or legacy `results/hackerone.com/reports/` |
| `full` | `bladerecon full hackerone.com --profile safe` | New isolated run under `results/hackerone.com/runs/<timestamp-profile-id>/` |
| `doctor` | `bladerecon doctor` | Runtime dependency table |
| `resume` | `bladerecon resume hackerone.com` | Resumes unfinished full workflow modules |
| `cache info` | `bladerecon cache info` | Cache size, sources, and age |
| `cache clear` | `bladerecon cache clear` | Safe cache cleanup summary |
| `--version` | `bladerecon --version` | Version, build date, Python, platform |
| `install-deps` | `bladerecon install-deps` | External dependency installation helper |

## Doctor Command

Run doctor before the first real scan:

```bash
bladerecon doctor
```

Doctor checks:

- Go availability
- Nuclei availability
- Playwright package
- Chromium browser availability
- Results directory write permission

Optional dependencies can be missing. BladeRecon will skip the related modules and continue the workflow.

## Scan Safety Profiles

BladeRecon defaults to `balanced`. Use `safe` for bug bounty programs or shared infrastructure, and `aggressive` only when you explicitly want higher active-request volume.

| Profile | Intended Use | Active Safeguards |
| --- | --- | --- |
| `safe` | Bug bounty and conservative validation | Low concurrency, low RPS, tighter request ceilings, one request per host for HTTP/browser modules |
| `balanced` | Default day-to-day recon | Moderate concurrency, capped JS/screenshots/Nuclei targets, per-host limits |
| `aggressive` | Explicit opt-in speed | Higher ceilings and concurrency while still retaining rate limits |

Profiles control request pressure and ceilings, not a guaranteed wall-clock
ordering. A `safe` scan can take longer than `aggressive` when lower
concurrency, one-request-per-host browser work, retries, or target-side delays
dominate runtime. Reports show full scan duration and per-module timings so the
slow path is visible.

Examples:

```bash
bladerecon probe hackerone.com --profile safe
bladerecon js hackerone.com --profile safe
bladerecon screenshot hackerone.com --profile safe
bladerecon nuclei hackerone.com --profile safe
bladerecon full hackerone.com --profile safe
```

The active profile is written to the run marker, `scan_state.json`, module metadata, and the HTML report. `bladerecon resume <target>` resumes the latest isolated run and preserves that run's stored profile.

Smart Nuclei keeps technology-guided tag selection, but it is no longer the
only coverage layer. When tags are selected automatically, BladeRecon may run
a lightweight tag-free baseline pass for `critical,high` severities, but only
for uncovered high-confidence or validated opportunity hosts. When no tags,
validated attack surface, or high-confidence opportunities exist, the ROI gate
skips baseline-only Nuclei instead of spending runtime on low-value templates.
If the ROI gate justifies a baseline-only run, BladeRecon scopes the target list
to the validated or high-confidence opportunity hosts first instead of scanning
every alive host. Reports and `nuclei/metadata.json` show
`coverage_strategy`, `roi_decision`, `target_scope`, `baseline_reason`,
`baseline_skip_reason`, `baseline_roi`, `baseline_targets`, and the
`baseline_scan` status.
Explicit `--templates` paths can point to a single Nuclei template file or a
directory of custom templates; they do not need the official template repository
layout.

## Output Structure

Full scans are isolated by run. Each `bladerecon full <target>` creates a new
folder under `results/<target>/runs/`, and `results/<target>/latest_run.json`
points to the most recent valid run. `bladerecon report <target>` reads that
latest valid run; if no isolated run exists, it falls back to the legacy flat
`results/<target>/` layout used by individual module commands.

```text
results/
`-- example.com/
    |-- latest_run.json
    `-- runs/
        `-- 20260611T121505Z-safe-ea0a5419/
            |-- .bladerecon_run.json
            |-- scan_state.json
            |-- subdomains/
            |   |-- subdomains.txt
            |   |-- subdomains.json
            |   `-- subdomains.jsonl
            |-- probe/
            |   |-- alive.txt
            |   |-- metadata.json
            |   |-- probe.json
            |   `-- probe.jsonl
            |-- js/
            |   |-- js_files.txt
            |   |-- metadata.json
            |   |-- js_files.json
            |   `-- files/
            |-- endpoints/
            |   |-- endpoints.txt
            |   |-- endpoints.json
            |   `-- metadata.json
            |-- secrets/
            |   |-- secrets.txt
            |   `-- secrets.json
            |-- parameters/
            |   |-- parameters.txt
            |   |-- parameters.json
            |   |-- parameters.jsonl
            |   `-- parameters_from_urls.txt
            |-- technology/
            |   |-- technology.txt
            |   `-- technology.json
            |-- intelligence/
            |   |-- attack_surface.json
            |   |-- cloud_assets.json
            |   |-- historical_dns.json
            |   |-- infrastructure.json
            |   |-- infrastructure_assets.json
            |   |-- risk_score.json
            |   `-- template_intelligence.json
            |-- historical/
            |   |-- urls.txt
            |   |-- urls.json
            |   |-- parameters.txt
            |   |-- endpoints.txt
            |   |-- endpoints.json
            |   `-- metadata.json
            |-- historical_js/
            |   |-- js_urls.txt
            |   |-- js_urls.json
            |   |-- endpoints.txt
            |   |-- endpoints.json
            |   |-- parameters.txt
            |   `-- metadata.json
            |-- content_discovery/
            |   |-- interesting_paths.txt
            |   |-- interesting_paths.json
            |   `-- metadata.json
            |-- historical_diff.json
            |-- security_headers_assets.json
            |-- asset_priority.json
            |-- advanced_metadata.json
            |-- screenshots/
            |-- nuclei/
            |   |-- metadata.json
            |   |-- results.json
            |   |-- results.jsonl
            |   `-- results.md
            |-- reports/
            |   |-- report.html
            |   `-- report.md
            `-- logs/
                |-- scan.log
                |-- errors.log
                `-- scan_meta.json
```

## Screenshots

Screenshots are optional and require Playwright Chromium:

```bash
python -m playwright install chromium
bladerecon screenshot hackerone.com
```

If Chromium is missing, BladeRecon displays a skip reason and continues.
Screenshot metadata includes average capture time, slow targets, timeout
targets, and per-target timings so slow browser captures are visible instead of
hidden inside total runtime.

## Signal Quality

Endpoint discovery suppresses third-party API URLs found inside in-scope
JavaScript unless the endpoint host is in scope. Historical JS endpoint
artifacts are merged into the same endpoint output so blocked live pages can
still contribute attack-surface evidence.

Advanced recon metadata includes source-level ROI for historical URL sources,
including selected URLs, opportunity candidates, source duration, and
signal-to-noise ratios. Use this to decide whether a source is worth its runtime
on future scans.

## Roadmap

### Current Release Candidate (v0.2.1)

- Finalize release consistency across CLI, reports, metadata, and scan state
- Validate real-world scans across Safe, Balanced, and Aggressive profiles
- Continue improving detection quality while keeping runtime efficient
- Expand regression coverage using real production-inspired scenarios
- Keep optional dependencies graceful, transparent, and well documented
- Gather community feedback before the first stable release

### Future Development (v0.3.0)

- Improve Opportunity Intelligence and evidence correlation
- Smarter target prioritization based on recon confidence
- Additional report intelligence without increasing noise
- Performance optimizations for very large scopes
- Better observability, diagnostics, and debugging information
- Continued UX improvements for researchers and bug bounty hunters

## Documentation

- [INSTALL](INSTALL.md)
- [QUICKSTART](QUICKSTART.md)
- [TROUBLESHOOTING](TROUBLESHOOTING.md)
- [CHANGELOG](CHANGELOG.md)
- [CONTRIBUTING](CONTRIBUTING.md)
- [SECURITY](SECURITY.md)
- [SUPPORT](SUPPORT.md)

## License

MIT
