scanforge

module

v0.3.0 Latest Latest Go to latest Published: Aug 8, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/MikeRoss27/scanforge

Links

Open Source Insights

README ¶

ScanForge

ScanForge is a command-line tool (CLI) written in Go, designed to securely and structurally orchestrate your penetration testing and reconnaissance (recon) workflows.

Thanks to its artifact-driven architecture, ScanForge chains well-known security tools while enforcing extremely strict scope validation rules to prevent any unauthorized scanning.

📚 Documentation

Usage guide: installation, configuration, commands and examples.
Scope management: implicit modes, files, exclusions and CI.
Architecture: DAG, artifacts, central filtering and outputs.
Contribution guide: repository structure, style and validations.

Français : Documentation en français · 中文：中文文档

🚀 Key Features

Artifact-driven pipeline: Modules communicate through artifacts in an ordered way (e.g. subfinder output automatically feeds dnsx and httpx), with parallel execution per DAG wave.
Strict scope validation: Explicit scope via file, or confirmed implicit scope (exact by default, domain on request), then filtering of every artifact.
Proxy integration (Caido / Burp Suite): --proxy routes HTTP traffic of the relevant modules through your interception proxy for manual triage/replay.
Authenticated scanning: -H/--header (repeatable) injects headers/cookies (session, bearer token) into every HTTP request issued.
JavaScript secrets scanner: the jssecrets module fetches crawled .js files and detects exposed API keys/tokens/creds, public cloud buckets, internal hosts, emails, sensitive API endpoints and accessible source maps.
Fully configurable Nuclei: severity, tags, rate-limit, custom templates and template updates via dedicated flags.
Parallelized Nmap: bounded worker pool (--nmap-concurrency) instead of sequential host-by-host scans.
Real-time progress: spinner per active module during the scan (visible by default, not only in --verbose), colored tables for plan/doctor, and a summary panel at the end of the run.
Dry-Run mode: Preview the commands that will be launched and the generated files before making any network request.
Diagnostic tool (Doctor): Instantly check whether your local dependencies are installed and configured for the selected profile.
Consolidated reports: Automatically generates a unified risk model in report.json and report.md formats.

🛠️ Supported Tools

ScanForge centralizes and orchestrates 12 external security tools, plus one native module:

subfinder (Subdomain discovery)
dnsx (Active DNS resolution)
httpx (HTTP probing and technology detection)
naabu (Ultra-fast port scanner)
nmap (Accurate port scanning and service detection, run in parallel)
whatweb (Web technology fingerprinting)
wafw00f (Web Application Firewall detection)
katana (Web resource crawling)
ffuf (Directory and file fuzzing)
nuclei (Template-based vulnerability scanner)
gau (Passive collection of historical URLs)
tlsx (TLS certificate and protocol enrichment)
jssecrets (native, no external binary) — analyzes JS crawled by katana to detect secrets, cloud buckets, internal hosts, emails and exposed source maps

httpx, nuclei, katana, ffuf, whatweb, wafw00f, subfinder, gau and jssecrets support --proxy and -H/--header to route traffic through Caido/Burp and scan in authenticated mode.

📦 Simple Installation (Hassle-Free)

Like mainstream tools (nuclei, subfinder...), ScanForge is distributed as prebuilt binaries via GitHub Releases: no compilation, no Go required.

Option 1: One-liner (Recommended)

Linux / macOS / Git-Bash:

curl -fsSL https://raw.githubusercontent.com/MikeRoss27/scanforge/main/install.sh | bash

The script detects your OS/architecture, downloads the latest version, verifies its SHA-256 checksum and installs it in ~/.local/bin.

Windows (PowerShell):

Invoke-Expression (Invoke-RestMethod https://raw.githubusercontent.com/MikeRoss27/scanforge/main/install.ps1)

The installer places the binary in %LOCALAPPDATA%\Programs\scanforge and automatically adds the directory to the user PATH.

Specific version or custom directory:

curl -fsSL https://raw.githubusercontent.com/MikeRoss27/scanforge/main/install.sh | bash -s -- --version v0.1.0 --dir /usr/local/bin

Option 2: Full installation (binary + scan tools)

ScanForge orchestrates external tools (nmap, nuclei, subfinder, httpx, ...). To install them automatically on top of ScanForge (requires Go):

curl -fsSL https://raw.githubusercontent.com/MikeRoss27/scanforge/main/install.sh | bash -s -- --full

From a clone of the repository, the local scripts do the same:

chmod +x install.sh && ./install.sh --full   # Linux / macOS
.\install.ps1 -Full                           # Windows (PowerShell)

Option 3: Docker (Zero local installation)

If you don't want to install Go or the other tools on your host system, use Docker. Everything is pre-configured in the image!

# With docker-compose
docker-compose run scanforge run target.com --profile web

# Manually with Docker
docker build -t scanforge .
docker run -v $(pwd):/workspace scanforge run target.com --profile web

🚦 Quick Start Guide

1. Initialize the project

Generate the default configuration files in your current directory:

scanforge init

This creates:

scanforge.yaml: Lets you configure tool paths and modify/define profiles.
scope.txt: Optional template to keep a reusable perimeter. You can delete it; ScanForge will then propose a minimal implicit scope to confirm.

2. Validate the environment

Check that all tools required for your scan profile are installed and accessible:

scanforge doctor --profile web

3. Launch a Scan

Without an applicable scope file, ScanForge derives a minimal scope from the target, displays it and asks for explicit confirmation before creating the run:

scanforge run example.com --profile web

To include the domain and its subdomains, add rules or exclude some:

scanforge run example.com --scope-mode domain \
  --scope-add api.other.test --exclude admin.example.com

--scope file.txt remains authoritative and is never silently replaced if it rejects the target. To avoid any ambiguity, it does not combine with --scope-mode, --scope-add or --exclude. An explicit or configured file requires no additional confirmation. For an implicit scope in CI or without a TTY, inspect scanforge plan first, then confirm the intent with --confirm-scope.

To test without sending any request:

scanforge run example.com --profile web --dry-run --confirm-scope

With an implicit scope, dry-run also requires confirmation: it performs no network requests, but formalizes the authorized perimeter.

Preview the validated pipeline before creating a run:

scanforge plan example.com --preset deep

The scanforge scan command is a more direct alias of scanforge run:

scanforge scan example.com --preset safe

🕵️ Proxy, authentication and Nuclei settings

For real-world penetration testing, route traffic through Caido (or Burp Suite) and inject an authenticated session:

scanforge run app.example.com --profile web \
  --proxy http://127.0.0.1:8080 \
  -H "Cookie: session=..." \
  --nuclei-tags cve,exposure --nuclei-severity critical,high \
  --nuclei-update-templates \
  --nuclei-include-custom \
  --ffuf-wordlist /usr/share/wordlists/dirb/big.txt \
  --nmap-concurrency 6

--proxy: HTTP/SOCKS proxy for the modules that speak HTTP.
-H/--header (repeatable): raw header "Name: Value" added to every request.
--nuclei-severity, --nuclei-exclude-severity, --nuclei-tags, --nuclei-exclude-tags, --nuclei-rate-limit, --nuclei-templates, --nuclei-update-templates: fine-grained control of the vulnerability scanner.
--nuclei-headless: enable nuclei headless mode (browser-based templates).
--nuclei-include-custom: also run the ScanForge templates bundled in templates/ (actuator, swagger, CORS misconfiguration, Go debug endpoints, WordPress debug log); located via SCANFORGE_TEMPLATES_DIR, ./templates or next to the binary.
--ffuf-wordlist, --ffuf-filter-codes: override the ffuf wordlist (default /usr/share/wordlists/dirb/common.txt) and filter out status codes.
--nmap-concurrency: number of simultaneous nmap scans (default 4); lower it to stay discreet on a sensitive engagement.

📊 Built-in Profiles and Presets

Name	Modules	Usage
`safe`	subfinder, dnsx, httpx, tlsx	Light exposure check.
`recon`	safe + gau	Inventory enriched with historical URLs.
`passive`	subfinder, dnsx, httpx	Minimal historical pipeline.
`ports`	subfinder, dnsx, naabu, nmap	Open ports then service validation.
`web`	subfinder, dnsx, httpx, whatweb, wafw00f, katana, jssecrets, attacksurface, techcve, httpcheck, payloadgen, nuclei	Application analysis: attack-surface consolidation, JS secrets, tech-to-CVE correlation, header checks and payload generation.
`vuln`	subfinder, dnsx, httpx, tlsx, attacksurface, techcve, nuclei	Targeted vulnerability detection (tech-to-CVE + templates).
`deep`	All modules (+ jssecrets)	Full and noisy pipeline.
`full`	All modules (+ jssecrets)	Full profile, history-compatible.

Use --preset safe or --profile safe interchangeably. Before any active profile, always review its DAG with scanforge plan.

📂 Final Report Structure

At the end of each scan, a timestamped folder is created under ./runs/. In addition to the raw logs of each tool, ScanForge generates:

report.json: Structured model of assets, ports, technologies and vulnerabilities.
report.md: Readable synthetic report.
00_meta/manifest.json: Run status, modules, artifacts and scope metadata.
00_meta/commands.log: External commands prepared or executed.
00_meta/effective-scope.txt: Canonical copy of the scope actually applied, with its source and mode recorded in the manifest.
00_meta/scope-rejections.jsonl: Out-of-scope values rejected, when any.
06_vulns/js-secrets.jsonl: Secrets, cloud buckets, internal hosts, emails and source maps detected in crawled JS (module jssecrets).
06_vulns/cve-findings.jsonl: Vulnerable versions correlated from fingerprints (module techcve).
06_vulns/http-checks.jsonl: Missing security headers and cookie flags (module httpcheck).
04_surface/attack-surface.txt: Consolidated candidate URLs for scanning (module attacksurface).
04_payloads/: Generated wordlists for api paths, endpoints, parameters and per-technology endpoints (module payloadgen).

ScanForge must only be used on assets for which you have explicit authorization.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
scanforge command Command scanforge is the CLI entry point.	Command scanforge is the CLI entry point.
internal
app Package app wires configuration, scope validation, orchestration and reporting together behind the CLI commands.	Package app wires configuration, scope validation, orchestration and reporting together behind the CLI commands.
ascii Package ascii renders the ScanForge ASCII banner shown at startup.	Package ascii renders the ScanForge ASCII banner shown at startup.
auth Package auth manages authenticated header injection for scan modules.	Package auth manages authenticated header injection for scan modules.
cli Package cli defines the cobra command tree for scanforge.	Package cli defines the cobra command tree for scanforge.
config Package config loads scanforge.yaml and resolves tool paths and profiles.	Package config loads scanforge.yaml and resolves tool paths and profiles.
doctor Package doctor validates that the tools required by a profile are installed and reachable.	Package doctor validates that the tools required by a profile are installed and reachable.
initcmd Package initcmd scaffolds the default scanforge.yaml and scope.txt files.	Package initcmd scaffolds the default scanforge.yaml and scope.txt files.
modules Package modules defines the scanner integration contract (Module, artifacts, run context) and the registry used to resolve them.	Package modules defines the scanner integration contract (Module, artifacts, run context) and the registry used to resolve them.
modules/attacksurface Package attacksurface consolidates every discovered URL (alive hosts, crawled pages, fuzzed paths, JS-discovered endpoints) into a single de-duplicated attack surface list that downstream vulnerability scanners consume, so detection is not limited to the homepage of each host.	Package attacksurface consolidates every discovered URL (alive hosts, crawled pages, fuzzed paths, JS-discovered endpoints) into a single de-duplicated attack surface list that downstream vulnerability scanners consume, so detection is not limited to the homepage of each host.
modules/dnsx Package dnsx wraps the dnsx DNS resolution tool.	Package dnsx wraps the dnsx DNS resolution tool.
modules/ffuf Package ffuf wraps the ffuf directory and file fuzzing tool.	Package ffuf wraps the ffuf directory and file fuzzing tool.
modules/gau Package gau wraps the gau passive URL collection tool.	Package gau wraps the gau passive URL collection tool.
modules/httpcheck Package httpcheck performs lightweight HTTP security header checks on the discovered attack surface and reports hardening gaps (missing CSP, HSTS, clickjacking protections, unsafe cookies) as low/info findings.	Package httpcheck performs lightweight HTTP security header checks on the discovered attack surface and reports hardening gaps (missing CSP, HSTS, clickjacking protections, unsafe cookies) as low/info findings.
modules/httpx Package httpx wraps the httpx HTTP probing and technology detection tool.	Package httpx wraps the httpx HTTP probing and technology detection tool.
modules/jssecrets Package jssecrets scans crawled JavaScript for exposed secrets, cloud buckets, internal hosts, emails and source maps.	Package jssecrets scans crawled JavaScript for exposed secrets, cloud buckets, internal hosts, emails and source maps.
modules/jsverify Package jsverify replays the PoC payloads attached to jssecrets AST findings in a real headless browser, injecting them through the attack sources the sink classes rely on (URL parameters, URL fragment, window postMessage) and reporting whether the payload actually reached the sink or executed JavaScript on the page.	Package jsverify replays the PoC payloads attached to jssecrets AST findings in a real headless browser, injecting them through the attack sources the sink classes rely on (URL parameters, URL fragment, window postMessage) and reporting whether the payload actually reached the sink or executed JavaScript on the page.
modules/katana Package katana wraps the katana web crawler.	Package katana wraps the katana web crawler.
modules/naabu Package naabu wraps the naabu fast port scanner.	Package naabu wraps the naabu fast port scanner.
modules/nmap Package nmap wraps the nmap port scanner, running hosts in parallel with a bounded worker pool.	Package nmap wraps the nmap port scanner, running hosts in parallel with a bounded worker pool.
modules/nuclei Package nuclei wraps the nuclei vulnerability scanner.	Package nuclei wraps the nuclei vulnerability scanner.
modules/payloadgen Package payloadgen derives contextual fuzzing payloads from the scan's own findings: API endpoints discovered in JavaScript, parameters harvested from historical URLs, and technology-specific endpoints.	Package payloadgen derives contextual fuzzing payloads from the scan's own findings: API endpoints discovered in JavaScript, parameters harvested from historical URLs, and technology-specific endpoints.
modules/subfinder Package subfinder wraps the subfinder subdomain discovery tool.	Package subfinder wraps the subfinder subdomain discovery tool.
modules/techcve Package techcve correlates technologies fingerprinted by httpx and whatweb with a bundled dataset of version-specific CVEs, so known-vulnerable software versions are flagged even when no nuclei template covers them.	Package techcve correlates technologies fingerprinted by httpx and whatweb with a bundled dataset of version-specific CVEs, so known-vulnerable software versions are flagged even when no nuclei template covers them.
modules/tlsx Package tlsx wraps the tlsx TLS/certificate enrichment tool.	Package tlsx wraps the tlsx TLS/certificate enrichment tool.
modules/wafw00f Package wafw00f wraps the wafw00f WAF detection tool.	Package wafw00f wraps the wafw00f WAF detection tool.
modules/whatweb Package whatweb wraps the whatweb technology fingerprinting tool.	Package whatweb wraps the whatweb technology fingerprinting tool.
orchestrator Package orchestrator executes scan modules in dependency order using an artifact-driven DAG, running independent modules in parallel waves while enforcing scope filtering on produced artifacts.	Package orchestrator executes scan modules in dependency order using an artifact-driven DAG, running independent modules in parallel waves while enforcing scope filtering on produced artifacts.
profile Package profile resolves named scan profiles and presets to module lists.	Package profile resolves named scan profiles and presets to module lists.
report Package report consolidates raw tool outputs into a unified risk model and renders report.json and report.md.	Package report consolidates raw tool outputs into a unified risk model and renders report.json and report.md.
runner Package runner abstracts command execution so scans can run for real or in dry-run mode without sending any network traffic.	Package runner abstracts command execution so scans can run for real or in dry-run mode without sending any network traffic.
scope Package scope models canonical scan scopes, exclusions and the filtering applied to every produced artifact.	Package scope models canonical scan scopes, exclusions and the filtering applied to every produced artifact.
storage Package storage manages run directories, manifests and artifact layout.	Package storage manages run directories, manifests and artifact layout.
tui Package tui renders the live scan progress view with Bubble Tea.	Package tui renders the live scan progress view with Bubble Tea.
ui Package ui centralizes ScanForge's terminal styling (colors, tagged log lines, headers, panels, tables, progress bars, gradients) on top of lipgloss so every command shares one look instead of ad hoc formatting per call site.	Package ui centralizes ScanForge's terminal styling (colors, tagged log lines, headers, panels, tables, progress bars, gradients) on top of lipgloss so every command shares one look instead of ad hoc formatting per call site.
version Package version carries the build-time version metadata injected via ldflags during release builds.	Package version carries the build-time version metadata injected via ldflags during release builds.