[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

[scan.auth.cookies]
session = "abc123"

[scan.auth.headers]
X-API-Key = "my-api-key"

VS_AUTH_BEARER_TOKEN=eyJ...
VS_AUTH_USERNAME=admin
VS_AUTH_PASSWORD=secret

vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

[scan.auth]
# Global fallback — used for any target without a specific entry
bearer_token = "default-token"

# JWT for the main app
[scan.auth.targets."https://app.example.com"]
bearer_token = "app-specific-jwt"

# Cookie session for the admin panel
[scan.auth.targets."https://admin.example.com"]
[scan.auth.targets."https://admin.example.com".cookies]
session   = "s%3Aabc123"
csrftoken = "xyz789"

# HTTP Basic for an internal API
[scan.auth.targets."10.0.0.50"]
username = "apiuser"
password = "s3cret"

# Form login for a legacy app
[scan.auth.targets."https://legacy.example.com"]
login_url = "https://legacy.example.com/login"
username  = "admin"
password  = "password123"
[scan.auth.targets."https://legacy.example.com".login_data]
_token = "csrf-value-here"

[llm]
enabled   = "auto"          # "auto" | true | false  (auto = on when api_key present)
api_key   = ""              # or set OPENAI_API_KEY env var
base_url  = ""              # leave empty for OpenAI; set for Ollama/vLLM/etc.
model     = "gpt-4o"        # REQUIRED when LLM is active — no default

# Sampling parameters (all OpenAI-compatible)
temperature = 0.2
top_p       = 0.95
max_tokens  = 4096
# top_k and other non-standard params go in extra_body:
# [llm.extra_body]
# top_k = 40

[llm]
base_url = "http://localhost:11434/v1"
api_key  = "ollama"
model    = "llama3.2"

[llm]
base_url = "http://localhost:8000/v1"
api_key  = "token-abc123"
model    = "meta-llama/Meta-Llama-3-8B-Instruct"

[llm.features]
generate_poc = true
execute_poc  = false   # enable only inside Docker

# Per-tool override — disable PoC for bandit (SAST, no runtime target)
[llm.features.tool.bandit]
generate_poc = false

# Per-category override — disable log analysis for noisy crawlers
[llm.features.category.web]
logs_analysis = false

[llm.prompts]
enrich_system    = "You are a senior penetration tester..."
mitigation_user  = "Write remediation steps for: {title}..."
# Available placeholders: {title} {severity} {description} {cwe}
#   {exploitability} {tool} {target} {cves} {raw_output}

[llm]
include_tools      = []          # empty = all tools
exclude_tools      = ["hakrawler", "gau"]
include_categories = []
exclude_categories = ["dns"]

[llm.poc]
languages        = ["python", "bash"]
only_severities  = ["critical", "high", "medium"]
max_pocs         = 20
allow_git_clone  = false   # permit cloning official exploit PoCs from GitHub

# Enable PoC execution inside the container
VS_LLM_FEATURE_EXECUTE_POC=true docker compose ... run --rm scanner ...

from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, ScanStatus, TargetType
from vuln_scanner.tools.models import Finding, ScanInput, ScanResult

class MyScannerTool(AbstractTool):
    name: str = "my-scanner"
    category: str = "web"
    # Only runs against URL targets — skipped automatically for IPs, paths, etc.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["my-scanner", "--target", target, "--json"]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        ...

[plugins]
enabled = true
dirs    = ["/opt/company-scanners"]

vuln-scanner --plugin-dir /opt/company-scanners --targets https://app.example.com

def run(self, target: str, scan_input: ScanInput) -> ScanResult:
    if "staging" not in target:
        return ScanResult(tool=self.name, target=target, status=ScanStatus.SKIPPED)
    return super().run(target, scan_input)

[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

./poc.sh

# Copy the example env and add your key
cp .env.example .env
# Edit .env: set OPENAI_API_KEY and VS_LLM_MODEL
./poc.sh

SCAN_MODE=active ./poc.sh

docker compose down -v
docker compose -f docker-compose.target.yaml down -v

vuln-scanner --targets \
  https://pentest-ground.com:4280 \
  https://pentest-ground.com:5013 \
  https://pentest-ground.com:9000 \
  https://pentest-ground.com:81 \
  --mode active

./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

# Scan using ./config.toml (targets and mode come from the config)
./scanner.sh

# Quick scan with explicit targets and mode
./scanner.sh -t https://app.example.com 192.168.1.0/24 -m active

# Use a custom config file
./scanner.sh -c /path/to/prod.toml

# Enable LLM enrichment with a specific model
./scanner.sh -t https://app.example.com --llm-model gpt-4o

# Run only specific tools
./scanner.sh -t https://app.example.com --include-tools nuclei,dalfox,ffuf

# Rebuild the image first, then scan
./scanner.sh --build -t https://app.example.com -m active

# Full manual passthrough to the scanner entrypoint
./scanner.sh -- --targets https://t.example.com --mode aggressive --formats markdown html json

# Open an interactive shell (all tools, volumes, and env available)
./scanner.sh --shell
./scanner.sh --build --shell

cp config.example.toml config.toml

[scan]
targets    = ["192.168.1.1", "https://app.example.com", "/src/myapp"]
mode       = "passive"   # paranoid | passive | active | aggressive
timeout    = 300         # per-tool timeout in seconds
rate_limit = null        # requests/sec; null = no limit

# Authenticated scanning — forwarded to all applicable web tools
[scan.auth]
bearer_token = ""        # Authorization: Bearer <token>
username     = ""        # HTTP Basic username
password     = ""        # HTTP Basic password
login_url    = ""        # Form-based login URL
# [scan.auth.cookies]
# session = "abc123"
# [scan.auth.headers]
# X-API-Key = "secret"

[tools]
exclude = ["nikto"]      # skip specific tools by name

[categories]
include = ["web", "ssl"] # limit to these categories; empty = all

[plugins]
enabled = true
# dirs = ["/opt/company-scanners"]

[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

[defectdojo]
url             = "http://localhost:8080"
api_key         = ""
product_name    = "My Product"
engagement_name = "Automated Scan"

# ── LLM Analysis ─────────────────────────────────────────────────────────────

[llm]
enabled     = "auto"     # "auto" | true | false
api_key     = ""         # or OPENAI_API_KEY env var
base_url    = ""         # leave empty for OpenAI
model       = ""         # required when active, e.g. "gpt-4o" or "llama3.2"
temperature = 0.2
top_p       = 0.95
max_tokens  = 4096
# extra_body = { top_k = 40 }   # for Ollama/vLLM top_k support

exclude_tools      = []
exclude_categories = []

[llm.features]
logs_analysis      = true
enrich             = true
classify           = true
cluster            = true
mitigation         = true
generate_poc       = true
execute_poc        = false  # container-only; set VS_LLM_FEATURE_EXECUTE_POC=true
false_positive_filter = true

# Per-tool feature overrides (tool > category > global precedence)
[llm.features.tool.bandit]
generate_poc = false

[llm.features.category.dns]
logs_analysis = false

[llm.poc]
languages       = ["python", "bash"]
only_severities = ["critical", "high", "medium"]
max_pocs        = 20
allow_git_clone = false

vuln_scanner/
├── config/
│   ├── models.py        # AppConfig, AppLLMConfig, PluginsConfig (pydantic)
│   └── loader.py        # 3-layer merge: TOML + env (VS_*) + CLI
│
├── tools/
│   ├── enums.py         # Severity, Confidence, ScanStatus, ScanMode, TargetType
│   ├── models.py        # Finding, ScanInput, ScanResult, AuthConfig (pydantic)
│   ├── target.py        # classify_target() — maps target string to TargetType set
│   ├── abstract.py      # AbstractTool ABC + subprocess execution helpers
│   ├── __init__.py      # TOOL_REGISTRY (86 tools)
│   └── <tool>.py        # One file per tool (86 total)
│
├── llm/
│   ├── models.py        # LLMConfig, LLMFeatures, PocConfig (pydantic)
│   ├── features.py      # resolve_features() — tool > category > global merge
│   ├── client.py        # LLMClient — thin openai SDK wrapper
│   ├── analyzer.py      # LLMAnalyzer — 4-pass analysis pipeline
│   └── prompts.py       # Default prompt templates (all overridable)
│
├── poc/
│   ├── models.py        # Poc, PocVerdict
│   ├── generator.py     # PocGenerator — writes scripts, never executes (host-safe)
│   └── runner.py        # PocRunner — executes scripts (VS_IN_CONTAINER guard)
│
├── reports/
│   ├── base.py          # AbstractReporter
│   ├── markdown.py      # Professional structured Markdown report
│   ├── html.py          # Self-contained HTML with light/dark theme
│   └── json_reporter.py # Full Assessment JSON dump
│
├── defectdojo/
│   └── client.py        # DefectDojoClient — push findings via REST API
│
├── plugins.py           # Plugin auto-discovery (./plugins/, ~/.vuln-scanner/plugins/)
├── model.py             # Assessment, Cluster, AssessmentStats
└── orchestrator.py      # ScanOrchestrator — type-gated, async concurrent execution

plugins/                 # Drop .py plugin files here (auto-discovered at startup)
main.py                  # Entry point
config.example.toml      # Fully documented configuration template
.env.example             # Environment variable reference
Dockerfile               # BlackArch-based image; bakes VS_IN_CONTAINER=1
docker-compose.yaml                # DefectDojo stack
docker-compose.scanner.yaml        # Scanner service
docker-compose.target.yaml        # Vulnerable test targets (Juice Shop, WebGoat)
scanner.sh                        # Convenience wrapper — runs the scanner via docker compose
poc.sh                            # End-to-end quick-start script (DefectDojo + targets + scanner)

from vuln_scanner.tools.abstract import AbstractTool
from vuln_scanner.tools.enums import Severity, TargetType
from vuln_scanner.tools.models import Finding, ScanInput

class MyTool(AbstractTool):
    name: str = "mytool"
    category: str = "web"
    # Declare which target types this tool supports.
    # The orchestrator skips mismatched (tool, target) pairs automatically.
    applicable_targets: frozenset[TargetType] = frozenset({TargetType.URL, TargetType.HOST})

    def build_command(self, target: str, scan_input: ScanInput) -> list[str]:
        return ["mytool", "--target", target]

    def parse_output(self, raw: str, target: str) -> list[Finding]:
        findings = []
        for line in raw.splitlines():
            if "VULN" in line:
                findings.append(Finding(
                    title="Example finding",
                    severity=Severity.HIGH,
                    description=line,
                    tool=self.name,
                    target=target,
                ))
        return findings

from vuln_scanner.tools.mytool import MyTool

TOOL_REGISTRY: dict[str, type[AbstractTool]] = {
    ...
    "mytool": MyTool,
}

RUN pacman -Sy --noconfirm mytool

# Install with dev dependencies
uv sync

# Run tests (host-safe only — no real tool execution)
uv run pytest tests/ -v

# Lint
uv run ruff check .
uv run ruff format .

VS_DEFECTDOJO_API_KEY=your-key \
VS_DEFECTDOJO_PRODUCT="My App" \
uv run vuln-scanner --targets 192.168.1.1