vuln-scanner

86のオープンソースセキュリティツールをオーケストレーションし、検出結果を集約・重複排除し、トリアージ、クラスタリング、および修復のためのオプションのOpenAI互換LLM分析レイヤーを実行し、概念実証スクリプトを生成し、プロフェッショナルなMarkdown、HTML、およびJSONレポートを作成する自動脆弱性評価プラットフォームです。すべて単一のBlackArch Linux Dockerイメージから動作します。

アーキテクチャ
ツール
ターゲットタイプのゲーティング
スキャンモード
認証付きスキャン
LLM分析
PoC生成と実行
プラグインシステム
レポート形式
クイックスタート
scanner.sh — Dockerラッパー
設定
環境変数
プロジェクト構造
新しいツールの追加
開発
DefectDojo統合

アーキテクチャ```

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 ↓ ScanResult[] → Assessment ↓ 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) ↓ ┌────────┬────────┬────────┐ │ .md │ .html │ .json │ (all formats written in parallel) └────────┴────────┴────────┘ ↓ DefectDojo (optional)

すべてのスキャンツールとPoCの実行は**BlackArch Linux**のDockerコンテナ内で行われます。ホストには何もインストールされません。

---

## ツール

カテゴリ別に整理された86のツール。各ツールはサポートするターゲットタイプを宣言しており、オーケストレーターは互換性のない組み合わせを自動的にスキップします。

### ネットワーク＆ポートスキャン
| ツール | 説明 |
|------|-------|
| `nmap` | サービス/バージョン検出を備えたフルポートスキャン |
| `rustscan` | 高速ポートスキャナー。nmapにフィードされる |
| `masscan` | 高速TCP/UDPスキャナー |
| `naabu` | サービス検出付きポートスキャナー |
| `netdiscover` | ARPベースのホスト発見 |

### Webアプリケーション
| ツール | 説明 |
|------|-------|
| `nuclei` | テンプレートベースの脆弱性スキャナー |
| `nikto` | Webサーバー設定ミススキャナー |
| `wapiti` | ブラックボックスWeb脆弱性スキャナー |
| `ffuf` | 高速Webファザー（ディレクトリ、パラメータ、ヘッダー） |
| `feroxbuster` | 再帰的なコンテンツ発見 |
| `gobuster` | URI/DNS/vhostブルートフォーサー |
| `wfuzz` | Webアプリケーションファザー |
| `dalfox` | パラメータ分析付きXSSスキャナー |
| `xsstrike` | 高度なXSS検出エンジン |
| `commix` | コマンドインジェクションの悪用ツール |
| `sqlmap` | 自動SQLインジェクションおよび乗っ取り |
| `nosqlmap` | NoSQLインジェクションスキャナー |
| `httpx` | HTTPプロービングとフィンガープリンティング |
| `whatweb` | Web技術フィンガープリンター |
| `wafw00f` | WAF検出とフィンガープリンティング |
| `wpscan` | WordPress脆弱性スキャナー |
| `acunetix` | Web脆弱性スキャナー（APIベース） |
| `arachni` | Webアプリケーションセキュリティスキャナー |
| `zap` | OWASP ZAP DASTスキャナー |
| `wapiti` | ブラックボックス脆弱性スキャナー |
| `drheader` | HTTPセキュリティヘッダーアナライザー |
| `humble` | HTTPヘッダーセキュリティチェッカー |
| `hakrawler` | URLとエンドポイントの高速Webクローラー |
| `katana` | 次世代Webクローリングフレームワーク |
| `gau` | 既知URLコレクター（AlienVault、WaybackMachine） |
| `jsluice` | JavaScriptのシークレットとURL抽出器 |
| `corscanner` | CORS設定ミススキャナー |
| `crlfuzz` | CRLFインジェクションスキャナー |
| `smuggler` | HTTPリクエストスマグリング検出器 |
| `linkfinder` | JavaScript/HTMLソース内のエンドポイント発見 |
| `cariddi` | シークレットとエンドポイント検出付きWebクローラー |

### API & GraphQL
| ツール | 説明 |
|------|-------|
| `kiterunner` | kiteファイルを使ったAPIルート発見 |
| `graphql_cop` | GraphQLセキュリティ監査ツール |
| `restler` | ステートフルREST APIファザー |
| `apifuzzer` | OpenAPI/Swaggerベースのファザー |
| `cherrybomb` | OpenAPI仕様セキュリティリンター |
| `arjun` | HTTPパラメータ発見 |
| `paramspider` | wayback/ソースからのパラメータマイニング |

### DNS & 偵察
| ツール | 説明 |
|------|-------|
| `amass` | サブドメイン列挙（パッシブ+アクティブ） |
| `subfinder` | 高速パッシブサブドメイン列挙 |
| `dnsx` | DNSリゾルバーおよびプローブツールキット |
| `dnsrecon` | DNS列挙とゾーン転送 |
| `fierce` | DNS偵察とホスト発見 |
| `theharvester` | OSINT：メール、名前、ホスト、サブドメイン |
| `puredns` | ワイルドカードフィルタリング付き高速サブドメインブルートフォーサー |
| `alterx` | サブドメイン順列エンジン |
| `waybackurls` | Wayback Machineからの履歴URL収集 |
| `httprobe` | 稼働中のHTTP/HTTPSホストプローバー |

### TLS / SSL
| ツール | 説明 |
|------|-------|
| `testssl` | TLS設定および暗号スイート監査 |
| `sslyze` | TLSスキャナー（暗号スイート、Heartbleed、ROBOT） |
| `sslscan` | SSL/TLSサービススキャナー |
| `tlsx` | 高速TLSプロービング |
| `tls_attacker` | TLSプロトコル攻撃ツール |
| `ssh_audit` | SSH設定およびアルゴリズム監査ツール |

### SMB & ネットワークサービス
| ツール | 説明 |
|------|-------|
| `smbmap` | SMB共有の列挙と権限 |
| `enum4linux` | SMB/NetBIOS列挙 |
| `crackmapexec` | Active DirectoryおよびSMBアセスメント |
| `openvas` | OpenVAS脆弱性スキャナー |

### SAST & コード解析
| ツール | 説明 |
|------|-------|
| `bandit` | Python SAST — 一般的なセキュリティアンチパターン |
| `semgrep` | コミュニティルール付きマルチ言語SAST |
| `gosec` | Goセキュリティチェッカー |
| `bearer` | プライバシーとセキュリティルール付きデータフローSAST |
| `horusec` | マルチ言語SASTエンジン |
| `brakeman` | Ruby on Rails SASTスキャナー |
| `flawfinder` | 一般的な欠陥を対象としたC/C++静的解析 |
| `dependency_check` | OWASP依存関係脆弱性スキャナー |
| `pip_audit` | Pythonパッケージ脆弱性チェッカー |

### ソフトウェア構成分析（SCA）
| ツール | 説明 |
|------|-------|
| `osv-scanner` | オープンソース脆弱性データベーススキャナー |
| `npm-audit` | Node.jsパッケージ脆弱性監査 |
| `govulncheck` | Goモジュール脆弱性チェッカー |

### シークレット検出
| ツール | 説明 |
|------|-------|
| `gitleaks` | Git履歴シークレットスキャナー |
| `trufflehog` | エントロピーに基づく深層シークレット検出器 |
| `secretfinder` | JSファイルとエンドポイント内のシークレット |
| `detect-secrets` | ベースライン方式のシークレットスキャナー |
| `noseyparker` | パターンルール付き高速シークレットスキャナー |

### IaC & 構成
| ツール | 説明 |
|------|-------|
| `checkov` | Terraform/K8s/Dockerfile IaCスキャナー |
| `tfsec` | Terraform静的解析 |
| `terrascan` | マルチクラウドIaCセキュリティスキャナー |
| `hadolint` | Dockerfileベストプラクティスリンター |

### クラウドインフラストラクチャ
| ツール | 説明 |
|------|-------|
| `prowler` | AWS/GCP/Azureセキュリティ態勢評価 |
| `kube-bench` | CIS Kubernetesベンチマークチェッカー |

### コンテナ＆サプライチェーン
| ツール | 説明 |
|------|-------|
| `trivy` | コンテナイメージ+ファイルシステム脆弱性スキャナー |
| `grype` | コンテナおよびパッケージ脆弱性マッチャー |

---

## ターゲットタイプのゲーティング

オーケストレーターは各ターゲットを1つ以上のタイプに分類し、そのタイプのサポートを宣言したツールのみを実行します。これにより、例えばWeb URLに対してSMBツールが実行されるといったノイズを排除できます。

| タイプ | 例 | 一致するツール |
|------|---------|-----------------|
| `HOST` | `example.com` | DNS、SSL、Web、SMBツール |
| `IP` | `10.0.0.1` | ネットワーク、ポート、SMBツール |
| `CIDR` | `10.0.0.0/24` | ネットワークスキャナー |
| `URL` | `https://app.example.com` | Web、API、SSLツール |
| `PATH` | `/src/myapp` | SAST、SCA、シークレット、IaCツール |
| `REPO` | `https://github.com/org/repo` | シークレット、SAST、SCAツール |
| `IMAGE` | `myapp:latest` | コンテナスキャナー |
| `CLOUD` | `aws:profile=prod`、`arn:aws:…` | クラウド態勢ツール（prowler、kube-bench、terrascan） |

分類は自動です。ターゲット文字列を渡すだけで、スキャナーがタイプを判別します。

認識されるクラウドターゲット形式:
- AWS ARN: `arn:aws:iam::123456789012:root`
- 名前付きプロファイルの省略形: `aws:profile=production`
- GCPプロジェクト: `projects/my-project-id`
- AzureサブスクリプションUUID: `00000000-0000-0000-0000-000000000000`

---

## スキャンモード

| モード | 説明 |
|------|-------------|
| `paranoid` | 最大限のステルス性 — パッシブプロービング、最小限のフットプリント |
| `passive` | アクティブな攻撃なし — 列挙とバナークラブのみ **(デフォルト)** |
| `active` | 標準の脆弱性チェックを有効化 |
| `aggressive` | フルスキャン：すべてのテンプレート、ブルートフォース、高速タイミング |

---

## 認証付きスキャン

認証情報は、該当するすべてのWebツール（nuclei、ffuf、feroxbuster、gobuster、nikto、sqlmap、dalfox、wpscan、wapiti、katana、hakrawler、arjun、wfuzz、corscanner、kiterunner、httpx）に転送されます。

### グローバル認証情報

ターゲットごとの上書きが存在しない限り、すべてのターゲットに適用されます。

**設定ファイル経由:**```toml
[scan.auth]
bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
username     = "admin"
password     = "secret"

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

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

環境変数経由 (グローバルのみ):```bash VS_AUTH_BEARER_TOKEN=eyJ... VS_AUTH_USERNAME=admin VS_AUTH_PASSWORD=secret

**CLI経由** (グローバルのみ):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

ターゲットごとの認証情報

異なる認証情報を必要とする複数のターゲットをスキャンする場合、[scan.auth.targets."<target>"] でターゲットごとの上書きを定義します。一致するエントリは、そのターゲットのグローバル設定を完全に置き換えます — マージは行われません。ターゲットごとの認証は設定ファイルのみで指定できます（環境変数とCLIフラグはグローバルデフォルトのみを設定します）。```toml [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"

[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"

[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"

**優先順位:** `per-target config > global config`

---

## LLM分析

APIキーが存在する場合、LLMレイヤーが自動的に有効になります。スキャン結果に対して4つのパスを実行します:

| パス | 名前 | 説明 |
|------|------|-------------|
| 1 | **トリアージ** | 各検出結果にCWE、信頼度、誤検知フラグ、悪用可能性の要約を割り当て、PoCを設計します |
| 2 | **PoC生成** | コンテナ内の既存ツールを使用して検出結果を確認する、自己完結型のPython/Bashスクリプトを作成します |
| 3 | **緩和策** | 具体的な短期的緩和策と恒久的な是正措置を生成し、必要に応じてPoCの証拠に基づいて判断します |
| 4 | **クラスタリング** | 根本原因ごとに検出結果をグループ化し、共通の是正措置を作成し、エグゼクティブサマリーを生成します |

### プロバイダー設定

LLMクライアントはOpenAI API互換です — OpenAI、Azure OpenAI、Ollama、vLLM、LM Studio、OpenRouter、その他互換性のあるエンドポイントで動作します。```toml
[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

Ollamaの例:```toml [llm] base_url = "http://localhost:11434/v1" api_key = "ollama" model = "llama3.2"

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

Feature matrix

各LLM機能は名前付きフィーチャーであり、グローバルに切り替え可能で、ツールまたはカテゴリごとに上書きできます。

グローバル機能設定:```toml [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

**機能の優先順位:** `tool override > category override > global`

### カスタムプロンプト

すべてのLLMプロンプトは上書き可能です:```toml
[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}

スコープフィルター```toml

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

---

## PoC 生成と実行

### 生成（常にホストに安全）

LLM は、発見事項ごとに自己完結型の Python および/または Bash スクリプトを作成します。スクリプトは BlackArch イメージに既に含まれているツール（`curl`、`sqlmap`、`nuclei`、`dalfox` など）を使用し、`<report>_assets/poc/` に書き込まれます。生成時はコードを一切実行せず、ファイルを書き込むだけです。```toml
[llm.poc]
languages        = ["python", "bash"]
only_severities  = ["critical", "high", "medium"]
max_pocs         = 20
allow_git_clone  = false   # permit cloning official exploit PoCs from GitHub

実行（コンテナのみ）

PoCの実行は、2つの独立したガードの背後に制御されています：

[llm.features] 内の execute_poc = true
VS_IN_CONTAINER=1 環境変数（Dockerイメージに組み込み済み）

いずれかのガードが欠けている場合、ランナーは静かに拒否するため、ホスト上では実行できません。実行前に、破壊的なパターン（rm -rf /、mkfs.、fork爆弾など）を含むスクリプトを静的拒否リストが排除します。```bash

Enable PoC execution inside the container

VS_LLM_FEATURE_EXECUTE_POC=true docker compose ... run --rm scanner ...

---

## プラグインシステム

`.py` ファイル（1つ以上の `AbstractTool` サブクラスを定義）を `./plugins/`（または `~/.vuln-scanner/plugins/`）に置くと、起動時に自動検出されます — コード変更は不要です。

**検出順序**（名前が衝突した場合は後方のエントリが優先）:
1. `./plugins/`（CWD からの相対）
2. `~/.vuln-scanner/plugins/`
3. `[plugins] dirs` または `--plugin-dir` で設定された追加ディレクトリ

**プラグイン例** (`plugins/my_scanner.py`):```python
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]:
        ...

設定:```toml [plugins] enabled = true dirs = ["/opt/company-scanners"]

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

ターゲットごとの動作

プラグインツールはグローバルに登録されますが、オーケストレーターのタイプゲーティングによって、各プラグインが実際にどのターゲットに対して実行されるかが制御されます。applicable_targets = frozenset({TargetType.URL}) を宣言したプラグインは、IP やファイルシステムパスに対しては決して実行されません。

タイプゲーティングを超えて、特定のターゲット文字列にのみプラグインを制限する場合（例：既知のステージングホストに対してのみ実行する場合）は、run() 内で ScanStatus.SKIPPED を返します。```python 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)

設定レベルでのターゲット別プラグインフィルターはありません — そのロジックはプラグイン自体に実装されます。

---

## レポート形式

3つの形式が並行して生成されます。任意の組み合わせを選択してください:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

またはCLI経由: --formats markdown html json

Markdown (`.md`)

業界標準のペンテスト慣行に従った専門的な構造化レポート:

エグゼクティブサマリー — 経営層向けの説明文
範囲と方法論 — ターゲット一覧、使用ツール、スキャン設定
深刻度評価ガイド — CVSSレンジ
調査結果概要 — リスク分布マトリクス + ターゲット別内訳
脆弱性クラスター — 根本原因別のグループ化 (LLM生成)
詳細調査結果 — 各所見: ID、深刻度、影響を受けるシステム、説明、ビジネス影響、アナリストメモ、緩和策、恒久的な是正、PoCリファレンス
付録A — スキャンエラー
付録B — PoCアセット索引

同じターゲットで同じ問題を報告した複数ツールの調査結果は、1つのエントリに重複排除され、寄与したすべてのツールが表示されます。

HTML (`.html`)

自己完結型の単一ファイルレポート（外部依存なし）で、以下を備えています:

ライト/ダークテーマの切り替え
深刻度別に色分けされた調査結果カード
折りたたみ可能なクラスターセクション
統計グリッドとエグゼクティブサマリーヒーロー

JSON (`.json`)

Assessment モデルの完全な構造化ダンプ — 調査結果、LLMエンリッチメント、クラスター、統計、PoCレコード。CI/CDパイプラインでの取り込みやダウンストリームツールに適しています。

Quick Start

poc.sh スクリプトは、DefectDojo、3つの脆弱なターゲット、そしてスキャナーを1つのコマンドで起動します。

前提条件: docker、docker compose プラグイン、curl、`python3````bash ./poc.sh

| ステップ | 操作 |
|------|--------|
| 1 | 前提条件をチェック |
| 2 | `.env`を読み込む（存在しない場合は`.env.example`からコピー） |
| 3 | DefectDojoスタックを起動 |
| 4 | DefectDojo APIの準備完了を待機 |
| 5 | 管理者認証情報でAPIトークンを取得 |
| 6 | 脆弱なターゲットコンテナを起動 |
| 7 | 各ターゲットに到達可能になるまで待機 |
| 8 | スキャナーのDockerイメージをビルド |
| 9 | スキャナーを実行し、レポートを生成してDefectDojoにプッシュ |
| 10 | URLと破棄手順を含むサマリーを表示 |

**LLM分析付き:**```bash
# Copy the example env and add your key
cp .env.example .env
# Edit .env: set OPENAI_API_KEY and VS_LLM_MODEL
./poc.sh

スキャンモードを上書き:```bash SCAN_MODE=active ./poc.sh

**分解:**```bash
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

脆弱なターゲット

ローカル (Docker — `poc.sh` で起動)

アプリ	URL	説明
OWASP Juice Shop	http://localhost:3000	OWASP Top 10 をカバーするモダンな Node.js アプリ

リモートラボ — pentest-ground.com

pentest-ground.com によって管理されている、一般公開された意図的に脆弱なシステム群です。セットアップは不要 — ツールと PoC 生成を検証するために直接スキャンできます。

---

## scanner.sh — Docker ラッパー

`scanner.sh` は、スキャナーを実行するための推奨される日常用インターフェースです。`docker compose run` をラップしているため、compose の起動コマンドを手動で入力する必要はありません。ターゲットとフラグを直接渡すだけです。```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

オプション

-- 以降は、ラッパー処理を介さずに、スキャナーのエントリーポイントへそのまま転送されます。

使用例```bash

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

### What it does automatically

- `.env` を読み込みます (存在しない場合は `.env.example` からコピーします)
- 設定が存在しない場合は `config.example.toml` を `config.toml` にコピーします
- 存在しない場合は `vuln_scanner_network` Dockerネットワークを作成します
- カスタム `--config` ファイルをコンテナ内の `/app/config.toml` にマウントします
- `--build` が指定された場合にイメージを再ビルドします

---

## 設定

注釈付きテンプレートをコピーしてください:```bash
cp config.example.toml config.toml

完全なリファレンス:```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 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

**設定マージの優先順位:** `CLI > env vars > config.toml > defaults`

---

## 環境変数

### コア

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `VS_TARGETS` | `--targets` | スペース区切りの対象リスト |
| `VS_MODE` | `--mode` | スキャンモード |
| `VS_TIMEOUT` | `--timeout` | ツールごとのタイムアウト（秒） |
| `VS_RATE_LIMIT` | `--rate-limit` | レート制限（リクエスト/秒） |
| `VS_MAX_CONCURRENT` | `--max-concurrent` | 並列ツールスロット |
| `VS_INCLUDE_TOOLS` | `--include-tools` | 名前でツールを許可リストに追加 |
| `VS_EXCLUDE_TOOLS` | `--exclude-tools` | 名前でツールを拒否リストに追加 |
| `VS_INCLUDE_CATEGORIES` | `--include-categories` | カテゴリの許可リスト |
| `VS_EXCLUDE_CATEGORIES` | `--exclude-categories` | カテゴリの拒否リスト |
| `VS_OUTPUT_DIR` | `--output-dir` | レポート出力ディレクトリ |

### レポート

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | レポート形式: `markdown html json` |

### LLM

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `OPENAI_API_KEY` | — | API キー（標準の環境変数、フォールバックとして使用） |
| `OPENAI_BASE_URL` | — | ベース URL のフォールバック（OpenAI 以外のエンドポイント用） |
| `VS_LLM_ENABLED` | `--no-llm` | `auto` \| `true` \| `false` |
| `VS_LLM_MODEL` | `--llm-model` | モデル名（有効時に必須） |
| `VS_LLM_TEMPERATURE` | — | サンプリング温度 |
| `VS_LLM_MAX_TOKENS` | — | 最大出力トークン数 |
| `VS_LLM_FEATURE_<NAME>` | `--llm-feature NAME=on` | グローバル機能の切り替え。例: `VS_LLM_FEATURE_GENERATE_POC=false` |
| `VS_LLM_FEATURE_EXECUTE_POC` | `--llm-poc-execute` | PoC 実行を有効にする（コンテナのみ） |

### 認証付きスキャン

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | ベアラートークン（`Authorization: Bearer …`） |
| `VS_AUTH_USERNAME` | `--auth-user` | HTTP Basic のユーザー名 |
| `VS_AUTH_PASSWORD` | `--auth-pass` | HTTP Basic のパスワード |
| `VS_AUTH_LOGIN_URL` | `--auth-login-url` | フォームベースのログイン URL |

Cookie と追加ヘッダーは、設定ファイルまたは `--auth-cookie` / `--auth-header` CLI フラグで設定する必要があります。

### プラグイン

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | プラグインの自動検出を有効/無効にする |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | 追加のプラグインディレクトリ（スペース区切り） |

### DefectDojo

| 変数 | CLI フラグ | 説明 |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | DefectDojo のベース URL |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | API トークン |
| `VS_DEFECTDOJO_PRODUCT` | — | プロダクト名 |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | エンゲージメント名 |

---

## プロジェクト構造```
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)

新しいツールの追加

単発用またはプライベートなツールの場合は、プラグインシステムを使用してください — コードを変更せずに .py ファイルを ./plugins/ に置くだけです。プロジェクトに同梱すべきツールの場合は、次の手順に従います。

vuln_scanner/tools/mytool.py を作成します:```python 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

2. これを `vuln_scanner/tools/__init__.py` に登録する:```python
from vuln_scanner.tools.mytool import MyTool

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

バイナリを Dockerfile に追加します:```dockerfile RUN pacman -Sy --noconfirm mytool

**ヒント:**
- stdout の代わりにファイルへ書き込むツールの場合、`build_command()` 内で `OUTPUT_FILE_SENTINEL` を使用し、`run()` をオーバーライドして `self._run_with_tempfile()` を呼び出します。
- `applicable_targets = frozenset(TargetType)`（デフォルト）を設定したツールは、すべてのターゲットタイプに対して実行されます。これは、本当に汎用的なツールにのみ使用してください。
- バイナリが見つからない → `ScanStatus.SKIPPED`（レポートから非表示）。ツールエラー → `ScanStatus.FAILED`（付録Aに表示）。

---

## 開発```bash
# 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 .

テストカテゴリ:

tests/test_config.py — 設定のマージと検証
tests/test_target_typing.py — classify_target() と applies_to()
tests/test_orchestrator_gating.py — モックツールによるタイプゲーティング
tests/test_llm.py — LLM機能、モック化されたクライアント、PoCランナーのコンテナガード
tests/test_reports.py — 3つのレポーターすべて（Markdown、HTML、JSON）
tests/test_nmap.py — nmap出力パーサー

安全規則: ホスト上で実際のスキャンツールを実行しないでください。すべてのツール実行は、分離されたターゲットコンテナに対してDockerコンテナ内で行われます。PocRunner はこれを強制します。PoCスクリプトを実行する前に VS_IN_CONTAINER=1 を確認し、Dockerイメージにはこの変数が組み込まれています。

DefectDojo統合

api_key と product_name が設定されている場合、検出結果は自動的にプッシュされます。

APIキーを取得する:

http://localhost:8080 でDefectDojoを開く
ログイン（デフォルト: admin / admin）
プロフィール → API v2キー に移動

手動プッシュ:```bash VS_DEFECTDOJO_API_KEY=your-key
VS_DEFECTDOJO_PRODUCT="My App"
uv run vuln-scanner --targets 192.168.1.1

`logs_analysis`	on	ツールの生の出力をLLMに供給する
`enrich`	on	CWE / 信頼度 / 誤検知 / 悪用可能性のトリアージ
`classify`	on	検出結果のタイプとリスクを分類する
`cluster`	on	根本原因ごとに検出結果をグループ化する
`mitigation`	on	緩和策と是正措置を生成する
`generate_poc`	on	レポート成果物としてPoCスクリプトを作成する
`execute_poc`	off	PoCをコンテナ内で実行する (要 `VS_IN_CONTAINER=1`)
`false_positive_filter`	on	レポートから可能性の高い誤検知を抑制する

DVWA	`https://pentest-ground.com:4280`	従来型 Web アプリ	CSRF, XSS, SQLi
DVGQL	`https://pentest-ground.com:5013`	GraphQL API	CMDi, XSS, SQLi
RestFlaw	`https://pentest-ground.com:9000`	REST API	SQLi, コードインジェクション, XXE
GuardianLeaks	`https://pentest-ground.com:81`	Web アプリ	XSS, SSRF, コードインジェクション
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

`-t`, `--targets HOST...`	1つ以上のスキャンターゲット（URL、IP、CIDR、パス、イメージ）
`-m`, `--mode MODE`	スキャンモード: `passive` \| `active` \| `aggressive` \| `paranoid`
`-c`, `--config FILE`	マウントする設定ファイル（デフォルト: `./config.toml`）
`-f`, `--formats FMT`	レポート形式（カンマ区切り）: `markdown,html,json`; 繰り返し指定可能
`--no-llm`	LLMエンリッチメントを無効化
`--llm-model MODEL`	LLMモデルの上書き（例: `gpt-4o`, `claude-sonnet-4-5`）
`--llm-min-severity SEV`	LLMで処理する最小の深刻度: `info\|low\|medium\|high\|critical`
`--include-tools TOOLS`	実行するツールのカンマ区切りリスト
`--exclude-tools TOOLS`	スキップするツールのカンマ区切りリスト
`-e`, `--env KEY=VALUE`	コンテナに追加の環境変数を渡す
`-b`, `--build`	実行前にDockerイメージを再ビルドする
`-n`, `--no-defectdojo`	DefectDojo連携をスキップ
`--shell`	スキャンする代わりにコンテナ内で対話型シェルを開く
`-h`, `--help`	ヘルプを表示

人気

vuln-scanner

vuln-scanner

目次

アーキテクチャ```

ターゲットごとの認証情報

Global fallback — used for any target without a specific entry

JWT for the main app

Cookie session for the admin panel

HTTP Basic for an internal API

Form login for a legacy app

Feature matrix

Per-tool override — disable PoC for bandit (SAST, no runtime target)

Per-category override — disable log analysis for noisy crawlers

スコープフィルター```toml

実行（コンテナのみ）

Enable PoC execution inside the container

ターゲットごとの動作

Markdown (.md)

HTML (.html)

JSON (.json)

Quick Start

脆弱なターゲット

ローカル (Docker — poc.sh で起動)

リモートラボ — pentest-ground.com

オプション

使用例```bash

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

Quick scan with explicit targets and mode

Use a custom config file

Enable LLM enrichment with a specific model

Run only specific tools

Rebuild the image first, then scan

Full manual passthrough to the scanner entrypoint

Open an interactive shell (all tools, volumes, and env available)

Authenticated scanning — forwarded to all applicable web tools

[scan.auth.cookies]

session = "abc123"

[scan.auth.headers]

X-API-Key = "secret"

dirs = ["/opt/company-scanners"]

── LLM Analysis ─────────────────────────────────────────────────────────────

extra_body = { top_k = 40 } # for Ollama/vLLM top_k support

Per-tool feature overrides (tool > category > global precedence)

新しいツールの追加

DefectDojo統合

Markdown (`.md`)

HTML (`.html`)

JSON (`.json`)

ローカル (Docker — `poc.sh` で起動)