vuln-scanner - Vulnerability Assessment Scanner with Report Gener

项目说明

An automated 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, dri 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. En
16. Project Structure
17. Adding a New Tool
18. De
19. DefectDojo Integration

---

Architecture

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/ 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 scanner |
| nikto | Web ser scanner |
| wapiti | Black-box web 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 | Ad 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 scanner |
| acunetix | Web scanner (API-based) |
| arachni | Web application security scanner |
| zap | OWASP ZAP DAST scanner |
| wapiti | Black-box 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 | Ja secrets and URL extractor |
| corscanner | CORS misconfiguration scanner |
| crlfuzz | CRLF injection scanner |
| smuggler | HTTP request smuggling detector |
| linkfinder | Endpoint discovery in Ja/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 passi enumeration |
| dnsx | DNS resolver and probe toolkit |
| dnsrecon | DNS enumeration and zone transfer |
| fierce | DNS reconnaissance and host discovery |
| thehar | 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 | Acti and SMB assessment |
| openvas | Open 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 scanner |
| pip_audit | Python package checker |

Software Composition Analysis (SCA)

| Tool | Notes |
|------|-------|
| os | Open Source database scanner |
| npm-audit | Node.js package audit |
| go | Go module 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 |

Cloud Infrastructure

| Tool | Notes |
|------|-------|
| prowler | AWS/GCP/Azure security posture assessment |
| kube-bench | CIS Kubernetes Benchmark checker |

Container & Supply Chain

| Tool | Notes |
|------|-------|
| trivy | Container image + filesystem scanner |
| grype | Container and package matcher |

---

Target Type Gating

The orchestrator classifies each target into one or more types and only runs tools that declare support for that type. This eliminates noise from e.g. SMB tools running against web URLs.

| Type | Example | Tools that match |
|------|---------|-----------------|
| HOST | example.com | DNS, SSL, web, SMB tools |
| IP | 10.0.0.1 | Network, port, SMB tools |
| CIDR | 10.0.0.0/24 | Network scanners |
| URL | | Web, API, SSL tools |
| PATH | /src/myapp | SAST, SCA, secrets, IaC tools |
| REPO | | Secrets, SAST, SCA tools |
| IMAGE | myapp:latest | Container scanners |
| CLOUD | aws:profile=prod, arn:aws:… | Cloud posture tools (prowler, kube-bench, terrascan) |

Classification is automatic — just pass the target string; the scanner figures out the type.

Cloud target formats recognised:

AWS ARN: arn:aws:iam::2:root

Named profile shorthand: aws:profile=production

GCP project: projects/my-project-id

Azure subscription UUID: 00000000-0000-0000-0000-000000000000

---

Scan Modes

| Mode | Description |
|------|-------------|
| paranoid | Maximum stealth — passi, minimal footprint |
| passive | No acti — enumeration and banner grabbing only (default) |
| active | Standard checks enabled |
| aggressive | Full scan: all templates, brute-force, fast timing |

---

Tool Chaining

By default the orchestrator runs a flat tool × target matrix. Enable
[chaining] to turn it into a live data-flow graph instead: tools that
*produce* assets (subdomains, li, open ports, URLs, params, tech
fingerprints…) feed tools that *consume* those asset types in later waves.

Wave 0 runs tools with no dependencies against the CLI targets.

Each subsequent wave is triggered by the assets discovered so far, up to

max_depth, until a fixpoint (no new work) is reached.

An asset_predicate gates routing so, e.g., wpscan only fires on a tech

asset whose fingerprint contains wordpress, and TLS tools only on TLS ports.

Passi modes only propagate passi types; budgets cap how

many assets of each type carry forward.

The discovery graph is surfaced in every report as a Discovery Chain section
— assets found per type, wa, and the chain edges
(source_tool → asset → triggered_tool) — and in JSON as chain_edges,
stats.assets_by_type, and stats.wa.

---

Authenticated Scanning

Credentials are forwarded to all applicable web tools (nuclei, ffuf, feroxbuster, gobuster, nikto, sqlmap, dalfox, wpscan, wapiti, katana, hakrawler, arjun, wfuzz, corscanner, kiterunner, httpx).

Global credentials

Applied to every target unless a per-target o exists.

:

(global only):

Via CLI (global only):

Per-target credentials

When scanning multiple targets that require different credentials, define per-target o under [scan.auth.targets."<target>"]. A matching entry replaces the global config for that target entirely — there is no merge. Per-target auth is config-file only (env vars and CLI flags only set the global default).

Resolution: per-target config > global config

---

LLM Analysis

When an API key is present, the LLM layer activates automatically. It performs two passes over the scan results:

| Pass | Name | What it does |
|------|------|-------------|
| 1 | Enrich & triage | Assigns CWE, confidence, false-positive flag, exploitability summary, mitigation, remediation, and a PoC plan for each finding in a single call |
| 2 | Clustering | Groups findings by root cause, writes shared remediations, and produces an executi |

PoC generation and execution are a separate optional phase (see [llm.features] generate_poc / execute_poc), and post-PoC mitigation re-enrichment runs only when confirmed PoCs are produced.

Provider configuration

The LLM client is OpenAI-API-compatible — works with OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter, and any other compatible endpoint.

Ollama example:

vLLM example:

Feature matrix

Each LLM capability is a named feature, toggleable globally and o per tool or per category.

| Feature | Default | Description |
|---------|:-------:|-------------|
| logs_analysis | on | Feed tool's raw output to the LLM |
| enrich | on | CWE / confidence / false-positive / exploitability triage |
| classify | on | Classify finding type and risk |
| cluster | on | Group findings by root cause |
| mitigation | on | Generate mitigation and remediation |
| generate_poc | on | Write PoC scripts as report assets |
| execute_poc | off | Run PoCs in-container *(requires =1)* |
| false_positi | on | Suppress likely false positives from the report |

Global feature config:

Feature precedence: tool o > category o > global

Custom prompts

All LLM prompts are o:

Scope filters

---

PoC Generation and Execution

Generation (always host-safe)

The LLM writes self-contained Python and/or Bash scripts per finding. Scripts use tools already in the BlackArch image (curl, sqlmap, nuclei, dalfox, etc.) and are written to <report>_assets/poc/. Generation ne code — it only writes files.

Execution (container-only)

PoC execution is gated behind two independent guards:

1. execute_poc = true in [llm.features]
2. =1 en (baked into the Docker image)

The runner refuses silently if either guard is missing, so it cannot execute on the host. A static denylist rejects scripts containing destructi (rm -rf /, mkfs., fork bombs, etc.) before execution.

---

Agentic Testing (bug-bounty & pentester)

After tool execution and the static LLM analysis pass, an optional **agentic
layer** (built on Pydantic AI) can drive the existing tools with custom
arguments and run sandboxed code to prove or exploit findings. It is
container-only and off by default.

Two profiles, same machinery / different permissions and prompt:

| Profile | Goal | Exploitation |
| --- | --- | --- |
| bug_bounty | Prove a bug exists (non-destructive) | Never — e only |
| pentester | Produce a working PoC | Dry-run by default; live exec opt-in |

Agents run strictly one at a time (no parallelism) so they ne on
a target. Each agent has its own tunable prompt, model, timeout, and ceilings;
when a wall-clock deadline or tool-call/token ceiling is hit, the agent is asked
for a final summary — a report is always produced.

Safety model (enforced in code, not just the prompt)

Container gate — nothing runs unless =1.

Scope enforcement — every host an agent touches (in run_tool args, in

run_code source, in OOB payloads) is against [scope] + the scan
allowlist. Out-of-scope actions are refused.

Sandbox — run_code runs under POSIX rlimits (CPU, memory, process count,

file size) so a runaway or fork bomb cannot take down the host.

Denylist — destructi patterns (rm -rf /, mkfs, fork

bombs, reverse shells, credential-file access…) are rejected before execution.

Audit trail — every action is appended to run_dir/agent_logs/<agent>.jsonl.

— a bug's PoC is independently re-run before it is marked

.

Secret scrubbing — API keys, tokens, and private keys are redacted from

agent output before it reaches any report or submission.

Configuration

Li for a pentester requires all of: allow_exploitation =
true, require_approval = false, scan mode active/aggressive, and the
container gate. Absent any of these it emits an ordered exploit plan instead
of firing it.

Agent tools a to the model: list_tools, run_tool, run_code,
oob_get_callback / oob_check (interactsh OAST for blind bugs), sa,
record_poc.

Results appear in an Agent Operations report section and, for bug-bounty
findings, as ready-to-submit files under run_dir/agent_submissions/.

En: , ENT.

---

Plugin System

Drop a .py file defining one or more AbstractTool subclasses into ./plugins/ (or ~/./plugins/) and they are auto-discovered at startup — no code changes needed.

Discovery order (later entries o on name collision):
1. ./plugins/ (relative to CWD)
2. ~/./plugins/
3. Extra dirs configured via [plugins] dirs or --plugin-dir

Example plugin (plugins/my_scanner.py):

Config:

CLI:

Per-target behaviour

Plugin tools are registered globally but the orchestrator's type-gating controls which targets each plugin actually runs against. A plugin declaring applicable_targets = frozenset({TargetType.URL}) will never fire against an IP or a filesystem path.

To restrict a plugin to specific target strings beyond type-gating (e.g., only run against a known staging host), return ScanStatus.SKIPPED inside run():

There is no config-le plugin filter — that logic belongs in the plugin itself.

---

Report Formats

Four formats are generated in parallel. Select any combination:

Or via CLI: --formats markdown html json pdf

Markdown (.md)

Professional structured report following industry pentest con:

1. Executi — prose for management
2. Scope and Methodology — target list, tools used, scan config
3. Se Rating Guide — C
4. Findings O — risk distribution matrix + per-target breakdown
5. Clusters — root-cause groupings (LLM-generated)
6. Detailed Findings — per finding: ID, se, affected system, description, business impact, analyst note, mitigation, permanent remediation, PoC references
7. Discovery Chain — assets discovered per type, wa, and chain edges (source_tool → asset → triggered_tool) — present when [chaining] is enabled
8. Agent Operations — per-agent summary, proven bugs, PoC artifacts, dry-run exploit plans, and audit-log paths — present when the agentic layer ran
9. Appendix A — scan errors
10. Appendix B — PoC asset index

Findings from multiple tools reporting the same issue on the same target are deduplicated into a single entry showing all contributing tools.

HTML (.html)

Self-contained single-file report (no external dependencies) with:

Light/dark theme toggle

Se finding cards

Collapsible cluster sections

Stats grid and executi hero

Discovery Chain and Agent Operations sections (when applicable)

JSON (.json)

Full structured dump of the Assessment model — findings, LLM enrichment, clusters, stats, PoC records, chain_edges / stats.assets_by_type, and agent_reports. Suitable for CI/CD pipeline ingestion and downstream tooling.

PDF (.pdf)

Print-ready report (reportlab) with cover page, executi, stats, clusters, and detailed findings.

---

Quick Start

The poc.sh script starts DefectDojo, three targets, and the scanner in one command.

Prerequisites: docker, docker compose plugin, curl, python3

| Step | Action |
|------|--------|
| 1 | Checks prerequisites |
| 2 | Loads .env (copies from .en if missing) |
| 3 | Starts DefectDojo stack |
| 4 | Waits for DefectDojo API to be ready |
| 5 | Obtains API token credentials |
| 6 | Starts target containers |
| 7 | Waits for each target to be reachable |
| 8 | Builds the scanner Docker image |
| 9 | Runs the scanner, generates reports, pushes to DefectDojo |
| 10 | Prints summary with URLs and teardown instructions |

With LLM analysis:

O scan mode:

Teardown:

---

Targets

Local (Docker — started by poc.sh)

| App | URL | Description |
|-----|-----|-------------|
| OWASP Juice Shop | | Modern Node.js app co OWASP Top 10 |
| WebGoat | | Ja intentionally insecure app |

Remote Lab — pentest-ground.com

Publicly a, intentionally- systems maintained by pentest-ground.com. No setup required — scan directly to tools and PoC generation.

| System | URL | Type | Classes |
|--------|-----|------|----------------------|
| DVWA | | Classic Web App | CSRF, XSS, SQLi |
| DVGQL | | GraphQL API | CMDi, XSS, SQLi |
| RestFlaw | | REST API | SQLi, Code Injection, XXE |
| GuardianLeaks | | Web App | XSS, SSRF, Code Injection |

---

scanner.sh — Docker Wrapper

scanner.sh is the recommended day-to-day interface for running the scanner. It wraps docker compose run so you never need to type the compose in manually — just pass targets and flags directly.

Options

| Flag | Description |
|------|-------------|
| -t, --targets HOST... | One or more scan targets (URL, IP, CIDR, path, image) |
| -m, --mode MODE | Scan mode: passive \| active \| aggressive \| paranoid |
| -c, --config FILE | Config file to mount (default: ./config.toml) |
| -f, --formats FMT | Report formats, comma-separated: markdown,html,json; repeatable |
| --no-llm | Disable LLM enrichment |
| --llm-model MODEL | LLM model o (e.g. gpt-4o, claude-sonnet-4-5) |
| --llm-min-se SEV | Minimum se for LLM: info\|low\|medium\|high\|critical |
| --include-tools TOOLS | Comma-separated list of tools to run |
| --exclude-tools TOOLS | Comma-separated list of tools to skip |
| -e, --env KEY=VALUE | Pass an extra en to the container |
| -b, --build | Rebuild the Docker image before running |
| -n, --no-defectdojo | Skip DefectDojo integration |
| --shell | Open an interacti inside the container instead of scanning |
| -h, --help | Show help |

E after -- is forwarded to the scanner entrypoint, bypassing all wrapper logic.

Examples

What it does automatically

Loads .env (copies from .en if missing)

Copies config.example.toml → config.toml if no config exists

Creates the Docker network if not present

Mounts a custom --config file into the container at /app/config.toml

Rebuilds the image when --build is passed

---

Configuration

Copy the annotated template:

Full reference:

Config merge precedence: CLI > env vars > config.toml > defaults

---

En

Core

| | CLI flag | Description |
|----------|----------|-------------|
| | --targets | Space-separated target list |
| | --mode | Scan mode |
| | --timeout | Per-tool timeout (seconds) |
| | --rate-limit | Rate limit (req/s) |
| | --max-concurrent | Parallel tool slots |
| | --include-tools | Whitelist tools by name |
| | --exclude-tools | Blacklist tools by name |
| | --include-categories | Whitelist categories |
| | --exclude-categories | Blacklist categories |
| | --output-dir | Report output directory |

Reports

| | CLI flag | Description |
|----------|----------|-------------|
| | --formats | Report formats: markdown html json |

LLM

| | CLI flag | Description |
|----------|----------|-------------|
| OPENAI_API_KEY | — | API key (standard env var, used as fallback) |
| OPENAI_BASE_URL | — | Base URL fallback (for non-OpenAI endpoints) |
| | --no-llm | auto \| true \| false |
| | --llm-model | Model name (required when active) |
| | — | Sampling temperature |
| | — | Max output tokens |
| | — | Log a one-line summary of each LLM response li true) |
| <NAME> | --llm-feature NAME=on | Global feature toggle, e.g. POC=false |
| OC | --llm-poc-execute | Enable PoC execution (container-only) |

Agents

| | CLI flag | Description |
|----------|----------|-------------|
| | — | Enable the agentic layer (also requires =1) |
| ENT | — | Toggle per-host scope (default on) |

Per-agent settings (profiles, prompts, timeouts, sandbox, submissions) are set
under [agents] in the config file — see Agentic Testing.

Authenticated Scanning

| | CLI flag | Description |
|----------|----------|-------------|
| | --auth-bearer | Bearer token (Authorization: Bearer …) |
| | --auth-user | HTTP Basic username |
| | --auth-pass | HTTP Basic password |
| | --auth-login-url | Form-based login URL |

Cookies and extra headers must be set file or --auth-cookie / --auth-header CLI flags.

Plugins

| | CLI flag | Description |
|----------|----------|-------------|
| | --no-plugins | Enable/disable plugin auto-discovery |
| | --plugin-dir | Extra plugin directories (space-separated) |

DefectDojo

| | CLI flag | Description |
|----------|----------|-------------|
| | --defectdojo-url | DefectDojo base URL |
| | --defectdojo-api-key | API token |
| | — | Product name |
| | — | Engagement name |

---

Project Structure

---

Adding a New Tool

For one-off or private tools, use the Plugin System — drop a .py file into ./plugins/ with no code changes. For tools that should ship with the project:

1. Create /tools/mytool.py:

2. Register it in /tools/__init__.py:

3. Add the binary to Dockerfile:

Tips:

For tools that write to a file instead of stdout, use OUTPUT_FILE_SENTINEL in build_command() and o run() to call self._run_with_tempfile().

Tools with applicable_targets = frozenset(TargetType) (the default) run against all target types — use this only for genuinely uni tools.

Binary not found → ScanStatus.SKIPPED (hidden from report). Tool error → ScanStatus.FAILED (shown in Appendix A).

---

De

Test categories:

tests/test_config.py — config merge and

tests/test_target_typing.py — classify_target() and applies_to()

tests/test_orchestrator_gating.py — type-gating with mock tools

tests/test_llm.py — LLM features, mocked client, PoC runner container guard

tests/test_reports.py — all three reporters (Markdown, HTML, JSON)

tests/test_nmap.py — nmap output parser

Safety rule: never run real scanning tools on the host. All tool execution happens inside the Docker container against the isolated target containers. The PocRunner enforces this — it checks =1 before executing any PoC script, and the Docker image bakes this in.

---

DefectDojo Integration

Findings are pushed automatically when api_key and product_name are configured.

Get your API key:
1. Open DefectDojo at
2. Log in (default: admin / admin)
3. Go to Profile → API v2 Key

Manual push:

项目信息

开发语言：Python

Star 数：12

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Vulnerability Assessment Scanner with Report Generation展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。