vuln-scanner

An automated vulnerability assessment platform that orchestrates 210 open-source security tools, aggregates and deduplicates findings, optionally chains tools into a discovery data-flow graph, runs an optional OpenAI-compatible LLM analysis layer for triage, clustering, and remediation, generates proof-of-concept scripts, drives optional bug-bounty and pentester agents (Pydantic AI) to prove and PoC findings, and produces professional Markdown, HTML, JSON, and PDF reports — all from a single BlackArch Linux Docker image.

---

Table of Contents

1. Architecture
2. Tools
3. Target Type Gating
4. Scan Modes
5. Tool Chaining
6. Authenticated Scanning
7. LLM Analysis
8. PoC Generation and Execution
9. Agentic Testing
10. Plugin System
11. Report Formats
12. Quick Start
13. scanner.sh — Docker Wrapper
14. Configuration
15. Environment Variables
16. Project Structure
17. Adding a New Tool
18. Development
19. DefectDojo Integration

---

Architecture

config.toml / env vars / CLI args
             ↓
       AppConfig (pydantic, 3-layer merge: TOML < env < CLI)
             ↓
     Plugin loader — auto-discovers ./plugins/ + ~/.vuln-scanner/plugins/
             ↓
     ScanOrchestrator
      • classify_target() → TargetType
      • tool.applies_to(target) — skips mismatched pairs
      • asyncio + ThreadPoolExecutor — parallel (tool × target) tasks
      • AuthConfig forwarded to every applicable tool
      • optional chaining: produces/consumes assets in a wave/fixpoint loop
             ↓
      ScanResult[]  →  Assessment  (+ chain_edges / assets_by_type)
             ↓
    LLMAnalyzer (optional)
      • Pass 1: triage + PoC design  (threaded, per result)
      • Pass 2: PoC generation       (PocGenerator, host-safe)
      • Pass 3: mitigation           (evidence-informed)
      • Pass 4: clustering + exec summary
             ↓
      PocRunner (container-only, VS_IN_CONTAINER=1 guard)
             ↓
    AgentOrchestrator (optional, container-only, sequential)
      • bug-bounty / pentester agents (Pydantic AI)
      • drive tools with custom args + run sandboxed code
      • scope-guarded, denylisted, audited → Assessment.agent_reports
             ↓
    ┌────────┬────────┬────────┐
    │   .md  │  .html │  .json │   (all formats written in parallel)
    └────────┴────────┴────────┘
             ↓
        DefectDojo (optional)

All scanning tools, PoC execution, and agent actions run inside a BlackArch Linux Docker container — nothing is installed on the host.

---

Tools

210 tools organized by category. Each tool declares the target types it supports; the orchestrator skips incompatible pairings automatically.

Network & Port Scanning

Tool	Notes
nmap	Full port scan with service/version detection
rustscan	Fast port scanner, feeds into nmap
masscan	High-speed TCP/UDP scanner
naabu	Port scanner with service detection
netdiscover	ARP-based host discovery

Web Application

Tool	Notes
nuclei	Template-based vulnerability scanner
nikto	Web server misconfiguration scanner
wapiti	Black-box web vulnerability scanner
ffuf	Fast web fuzzer (dirs, params, headers)
feroxbuster	Content discovery with recursion
gobuster	URI/DNS/vhost brute-forcer
wfuzz	Web application fuzzer
dalfox	XSS scanner with parameter analysis
xsstrike	Advanced XSS detection engine
commix	Command injection exploiter
sqlmap	Automated SQL injection and takeover
nosqlmap	NoSQL injection scanner
httpx	HTTP probing and fingerprinting
whatweb	Web technology fingerprinter
wafw00f	WAF detection and fingerprinting
wpscan	WordPress vulnerability scanner
acunetix	Web vulnerability scanner (API-based)
arachni	Web application security scanner
zap	OWASP ZAP DAST scanner
wapiti	Black-box vulnerability scanner
drheader	HTTP security header analyser
humble	HTTP header security checker
hakrawler	Fast web crawler for URLs and endpoints
katana	Next-gen web crawling framework
gau	Known URL collector (AlienVault, WaybackMachine)
jsluice	JavaScript secrets and URL extractor
corscanner	CORS misconfiguration scanner
crlfuzz	CRLF injection scanner
smuggler	HTTP request smuggling detector
linkfinder	Endpoint discovery in JavaScript/HTML source
cariddi	Web crawler with secret and endpoint detection

API & GraphQL

Tool	Notes
kiterunner	API route discovery with kite files
graphql_cop	GraphQL security auditor
restler	Stateful REST API fuzzer
apifuzzer	OpenAPI/Swagger-based fuzzer
cherrybomb	OpenAPI spec security linter
arjun	HTTP parameter discovery
paramspider	Parameter mining from wayback/sources

DNS & Reconnaissance

Tool	Notes
amass	Subdomain enumeration (passive + active)
subfinder	Fast passive subdomain enumeration
dnsx	DNS resolver and probe toolkit
dnsrecon	DNS enumeration and zone transfer
fierce	DNS reconnaissance and host discovery
theharvester	OSINT: emails, names, hosts, subdomains
puredns	Fast subdomain brute-forcer with wildcard filtering
alterx	Subdomain permutation engine
waybackurls	Historical URL collection from Wayback Machine
httprobe	Live HTTP/HTTPS host prober

TLS / SSL

Tool	Notes
testssl	TLS configuration and cipher suite audit
sslyze	TLS scanner (cipher suites, Heartbleed, ROBOT)
sslscan	SSL/TLS service scanner
tlsx	Fast TLS probing
tls_attacker	TLS protocol attack tool
ssh_audit	SSH configuration and algorithm auditor

SMB & Network Services

Tool	Notes
smbmap	SMB share enumeration and permissions
enum4linux	SMB/NetBIOS enumeration
crackmapexec	Active Directory and SMB assessment
openvas	OpenVAS vulnerability scanner

SAST & Code Analysis

Tool	Notes
bandit	Python SAST — common security anti-patterns
semgrep	Multi-language SAST with community rules
gosec	Go security checker
bearer	Data-flow SAST with privacy and security rules
horusec	Multi-language SAST engine
brakeman	Ruby on Rails SAST scanner
flawfinder	C/C++ static analysis for common flaws
dependency_check	OWASP dependency vulnerability scanner
pip_audit	Python package vulnerability checker

Software Composition Analysis (SCA)

Tool	Notes
osv-scanner	Open Source Vulnerability database scanner
npm-audit	Node.js package vulnerability audit
govulncheck	Go module vulnerability checker

Secrets Detection

Tool	Notes
gitleaks	Git history secret scanner
trufflehog	Deep entropy-based secret finder
secretfinder	Secrets in JS files and endpoints
detect-secrets	Baseline-based secret scanner
noseyparker	High-speed secret scanner with pattern rules

IaC & Configuration

Tool	Notes
checkov	Terraform/K8s/Dockerfile IaC scanner
tfsec	Terraform static analysis
terrascan	Multi-cloud IaC security scanner
hadolint	Dockerfile best-practice linter