diff --git a/README.md b/README.md index 3d564ea..dee14d7 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,21 @@ [![Go](https://img.shields.io/badge/Go-1.24.2+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg?style=for-the-badge)](LICENSE) [![CodeQL](https://img.shields.io/github/actions/workflow/status/TMHSDigital/subenum/codeql.yml?label=CodeQL&style=for-the-badge)](https://github.com/TMHSDigital/subenum/actions/workflows/codeql.yml) -[![Go Report Card](https://goreportcard.com/badge/github.com/TMHSDigital/subenum?style=for-the-badge&v=0.5.0)](https://goreportcard.com/report/github.com/TMHSDigital/subenum) +[![Go Report Card](https://goreportcard.com/badge/github.com/TMHSDigital/subenum?style=for-the-badge&v=0.5.1)](https://goreportcard.com/report/github.com/TMHSDigital/subenum) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](./docs/CONTRIBUTING.md) +[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey?style=for-the-badge)](#installation)
-[Quick Start](#installation)  |  [Configuration](#configuration)  |  [Usage](#usage)  |  [Architecture](#system-architecture)  |  [Changelog](./CHANGELOG.md) +**Fast concurrent subdomain enumeration, written in Go.** Point it at a domain and a wordlist; it brute-forces DNS across a worker pool and prints the subdomains that resolve. Built for pentesters, bug-bounty hunters, and operators doing authorized reconnaissance of their own infrastructure. + +
+ +subenum interactive TUI + +
+ +[Quick Start](#quick-start)  |  [Configuration](#configuration)  |  [Usage](#usage)  |  [Architecture](#system-architecture)  |  [Changelog](./CHANGELOG.md) @@ -28,6 +38,33 @@
+## Quick Start + +```bash +git clone https://github.com/TMHSDigital/subenum.git +cd subenum +go build -buildvcs=false -o subenum +./subenum -w examples/sample_wordlist.txt example.com +``` + +No network required to try it out. Simulation mode generates synthetic results with zero DNS queries: + +```bash +./subenum -simulate -hit-rate 20 -w examples/sample_wordlist.txt example.com +``` + +Or launch the interactive terminal UI with no flags: + +```bash +./subenum -tui +``` + +
+ +--- + +
+ ## Feature Matrix | Module | Description | @@ -38,7 +75,7 @@ | Graceful Shutdown | Trap SIGINT/SIGTERM, drain in-flight workers, flush partial results | | Input Validation | RFC-compliant domain syntax and strict `ip:port` format enforcement | | Wordlist Dedup | Deduplicate wordlist entries in a single pass before scanning begins | -| Simulation Mode | Generate synthetic DNS results at a configurable hit rate — zero network I/O | +| Simulation Mode | Generate synthetic DNS results at a configurable hit rate, with zero network I/O | | Output Pipeline | Resolved domains to stdout (pipe-clean); progress and diagnostics to stderr | | Interactive TUI | Form-based config and live-scrolling results via `-tui`; session values persisted | @@ -134,7 +171,7 @@ docker compose run subenum make build # compile binary make test # run test suite with race detector make lint # run golangci-lint -make simulate # safe run — no DNS queries +make simulate # safe run - no DNS queries make tui # launch interactive TUI make docker-build # build Docker image make help # list all targets @@ -154,25 +191,25 @@ make help # list all targets | Flag | Default | Description | | :--- | :---: | :--- | -| `-w ` | — | Wordlist file, one prefix per line **(required)** | +| `-w ` | n/a | Wordlist file, one prefix per line **(required)** | | `-t ` | `100` | Concurrent worker goroutines | | `-timeout ` | `1000` | Per-query DNS timeout in milliseconds | | `-dns-server ` | `8.8.8.8:53` | DNS server address (validated on startup) | | `-attempts ` | `1` | DNS resolution attempts per subdomain (1 = no retry) | | `-force` | `false` | Continue scanning even if wildcard DNS is detected | -| `-o ` | — | Write results to file in addition to stdout | +| `-o ` | n/a | Write results to file in addition to stdout | | `-v` | `false` | Verbose output: IPs, timings, per-query detail (stderr) | | `-progress` | `true` | Live progress line on stderr | | `-simulate` | `false` | Simulation mode: no real DNS queries | -| `-hit-rate ` | `15` | Simulated resolution rate, percent (1–100) | +| `-hit-rate ` | `15` | Simulated resolution rate, percent (1-100) | | `-tui` | `false` | Launch the interactive Terminal UI | -| `-version` | — | Print version and exit | -| `-retries ` | — | **Deprecated** — alias for `-attempts`, prints a warning | +| `-version` | n/a | Print version and exit | +| `-retries ` | n/a | **Deprecated** - alias for `-attempts`, prints a warning |
> [!NOTE] -> Wildcard DNS is detected automatically before scanning begins. If the target resolves wildcard records, the tool exits with a warning — all subdomains would match, making results meaningless. Pass `-force` to override. +> Wildcard DNS is detected automatically before scanning begins. If the target resolves wildcard records, the tool exits with a warning, since all subdomains would match, making results meaningless. Pass `-force` to override. > [!CAUTION] > Simulation mode (`-simulate`) generates synthetic results and performs zero network I/O. Do not confuse simulated output with real DNS data. @@ -209,7 +246,7 @@ subenum -w [flags] ./subenum -w wordlist.txt -attempts 3 -timeout 2000 example.com ``` -**Pipe-friendly — only resolved subdomains on stdout** +**Pipe-friendly - only resolved subdomains on stdout** ```bash ./subenum -w wordlist.txt example.com | cut -d' ' -f2 | your-takeover-scanner ``` @@ -219,7 +256,7 @@ subenum -w [flags] ./subenum -w wordlist.txt -force example.com ``` -**Simulation — zero network I/O** +**Simulation - zero network I/O** ```bash ./subenum -simulate -hit-rate 20 -w examples/sample_wordlist.txt example.com ``` @@ -236,15 +273,7 @@ Press `Ctrl+C` at any time to abort. In-flight queries drain and partial results ./subenum -tui ``` -No flags required. Fill in the form and press `ctrl+r` to start scanning. Last-used values are saved to `~/.config/subenum/last.json` and restored on next launch. - -
- -
- -![subenum TUI — Configure Scan](docs/assets/tui-form.png) - -
+No flags required. Fill in the form and press `ctrl+r` to start scanning. Last-used values are saved to `~/.config/subenum/last.json` and restored on next launch. The interface is shown at the top of this README.
@@ -257,7 +286,7 @@ No flags required. Fill in the form and press `ctrl+r` to start scanning. Last-u | `space` | Toggle Simulate / Force | | `ctrl+r` | Start scan | | `ctrl+c` | Abort scan (scan view) / quit (form) | -| `r` | New scan — restores last-used values | +| `r` | New scan - restores last-used values | | `q` | Quit after scan completes | diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 1f8a1bd..ded9d76 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -329,7 +329,7 @@ Docker Contributing
- Download v0.5.0 + Download v0.5.1
@@ -343,9 +343,9 @@
build release - go + go license - go report + go report
Download latest release