Все инструменты сканирования и выполнение PoC запускаются внутри Docker-контейнера **BlackArch Linux** — на хосте ничего не устанавливается.

---

## Инструменты

86 инструментов, сгруппированных по категориям. Каждый инструмент объявляет типы целей, которые он поддерживает; оркестратор автоматически пропускает несовместимые пары.

### Сетевое и портовое сканирование
| Инструмент | Примечания |
|------|-------|
| `nmap` | Полное сканирование портов с определением сервисов/версий |
| `rustscan` | Быстрый сканер портов, передаёт результаты в nmap |
| `masscan` | Высокоскоростной TCP/UDP сканер |
| `naabu` | Сканер портов с определением сервисов |
| `netdiscover` | Обнаружение хостов на основе ARP |

### Веб-приложения
| Инструмент | Примечания |
|------|-------|
| `nuclei` | Сканер уязвимостей на основе шаблонов |
| `nikto` | Сканер ошибок конфигурации веб-сервера |
| `wapiti` | Сканер уязвимостей веб-приложений методом чёрного ящика |
| `ffuf` | Быстрый веб-фаззер (каталоги, параметры, заголовки) |
| `feroxbuster` | Обнаружение контента с рекурсией |
| `gobuster` | Брутфорсер URI/DNS/vhost |
| `wfuzz` | Фаззер веб-приложений |
| `dalfox` | XSS-сканер с анализом параметров |
| `xsstrike` | Продвинутый движок обнаружения XSS |
| `commix` | Эксплуатация внедрения команд |
| `sqlmap` | Автоматизированное внедрение SQL-инъекций и захват БД |
| `nosqlmap` | Сканер NoSQL-инъекций |
| `httpx` | HTTP-пробинг и снятие отпечатков (fingerprinting) |
| `whatweb` | Определитель веб-технологий |
| `wafw00f` | Обнаружение и идентификация WAF |
| `wpscan` | Сканер уязвимостей WordPress |
| `acunetix` | Сканер уязвимостей веб-приложений (на основе API) |
| `arachni` | Сканер безопасности веб-приложений |
| `zap` | DAST-сканер OWASP ZAP |
| `wapiti` | Сканер уязвимостей методом чёрного ящика |
| `drheader` | Анализатор HTTP security-заголовков |
| `humble` | Проверка безопасности HTTP-заголовков |
| `hakrawler` | Быстрый веб-краулер для URL и эндпоинтов |
| `katana` | Фреймворк веб-краулинга нового поколения |
| `gau` | Сборщик известных URL (AlienVault, WaybackMachine) |
| `jsluice` | Извлечение секретов и URL из JavaScript |
| `corscanner` | Сканер ошибок конфигурации CORS |
| `crlfuzz` | Сканер CRLF-инъекций |
| `smuggler` | Детектор HTTP-смагглинга (контрабанды запросов) |
| `linkfinder` | Обнаружение эндпоинтов в исходном коде JavaScript/HTML |
| `cariddi` | Веб-краулер с обнаружением секретов и эндпоинтов |

### API и GraphQL
| Инструмент | Примечания |
|------|-------|
| `kiterunner` | Обнаружение маршрутов API с файлами kite |
| `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: email-адреса, имена, хосты, поддомены |
| `puredns` | Быстрый брутфорсер поддоменов с фильтрацией wildcard |
| `alterx` | Движок перестановок поддоменов |
| `waybackurls` | Сбор исторических URL из Wayback Machine |
| `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` | SAST для Python — типичные анти-паттерны безопасности |
| `semgrep` | Многоязычный SAST с правилами сообщества |
| `gosec` | Проверка безопасности Go |
| `bearer` | SAST с анализом потоков данных и правилами приватности и безопасности |
| `horusec` | Многоязычный SAST-движок |
| `brakeman` | SAST-сканер для Ruby on Rails |
| `flawfinder` | Статический анализ C/C++ на типичные ошибки |
| `dependency_check` | Сканер уязвимостей зависимостей OWASP |
| `pip_audit` | Проверка уязвимостей Python-пакетов |

### Анализ состава ПО (SCA)
| Инструмент | Примечания |
|------|-------|
| `osv-scanner` | Сканер базы уязвимостей открытого ПО (Open Source Vulnerability database) |
| `npm-audit` | Аудит уязвимостей Node.js-пакетов |
| `govulncheck` | Проверка уязвимостей Go-модулей |

### Обнаружение секретов
| Инструмент | Примечания |
|------|-------|
| `gitleaks` | Сканер секретов в истории Git |
| `trufflehog` | Глубокий поиск секретов на основе энтропии |
| `secretfinder` | Секреты в JS-файлах и эндпоинтах |
| `detect-secrets` | Сканер секретов на основе базовой линии (baseline) |
| `noseyparker` | Высокоскоростной сканер секретов с правилами на основе паттернов |

### IaC и конфигурация
| Инструмент | Примечания |
|------|-------|
| `checkov` | Сканер IaC для Terraform/K8s/Dockerfile |
| `tfsec` | Статический анализ Terraform |
| `terrascan` | Мультиоблачный сканер безопасности IaC |
| `hadolint` | Линтер Dockerfile по лучшим практикам |

### Облачная инфраструктура
| Инструмент | Примечания |
|------|-------|
| `prowler` | Оценка уровня безопасности AWS/GCP/Azure |
| `kube-bench` | Проверка CIS Kubernetes Benchmark |

### Контейнеры и цепочка поставок
| Инструмент | Примечания |
|------|-------|
| `trivy` | Сканер уязвимостей образов контейнеров + файловых систем |
| `grype` | Сопоставитель уязвимостей контейнеров и пакетов |

---

## Фильтрация по типу цели

Оркестратор классифицирует каждую цель по одному или нескольким типам и запускает только те инструменты, которые заявляют поддержку соответствующего типа. Это исключает шум, например, от SMB-инструментов, запускаемых против веб-URL.

| Тип | Пример | Подходящие инструменты |
|------|---------|-----------------|
| `HOST` | `example.com` | DNS, SSL, веб и SMB-инструменты |
| `IP` | `10.0.0.1` | Сетевые, портовые и SMB-инструменты |
| `CIDR` | `10.0.0.0/24` | Сетевые сканеры |
| `URL` | `https://app.example.com` | Веб, 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`
- UUID подписки Azure: `00000000-0000-0000-0000-000000000000`

---

## Режимы сканирования

| Режим | Описание |
|------|-------------|
| `paranoid` | Максимальная скрытность — пассивный пробинг, минимальный след |
| `passive` | Без активных атак — только перечисление и сбор баннеров **(по умолчанию)** |
| `active` | Стандартные проверки уязвимостей включены |
| `aggressive` | Полное сканирование: все шаблоны, брутфорс, быстрый тайминг |

---

## Аутентифицированное сканирование

Учётные данные передаются во все применимые веб-инструменты (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"

**Через CLI** (только глобально):```bash
vuln-scanner --targets https://app.example.com \
  --auth-bearer eyJ... \
  --auth-cookie session=abc123 \
  --auth-header X-API-Key=secret

**Resolution:** `per-target config > global config`

---

## LLM-анализ

Когда присутствует API-ключ, слой LLM активируется автоматически. Он выполняет четыре прохода по результатам сканирования:

| Проход | Название | Что делает |
|------|------|-------------|
| 1 | **Триаж** | Назначает CWE, уровень уверенности, флаг ложного срабатывания, сводку по эксплуатируемости и разрабатывает PoC для каждой находки |
| 2 | **Генерация PoC** | Пишет автономные Python/Bash-скрипты, которые подтверждают находку с помощью инструментов, уже имеющихся в контейнере |
| 3 | **Смягчение** | Предлагает конкретные краткосрочные меры смягчения и постоянные исправления, при необходимости с учётом данных PoC |
| 4 | **Кластеризация** | Группирует находки по первопричине, формирует общие исправления и создаёт итоговую сводку |

### Конфигурация провайдера

Клиент LLM совместим с OpenAI API — работает с OpenAI, Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter и любым другим совместимым endpoint.```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

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

**Приоритет функций:** `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}

---

## Генерация и выполнение 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

---

## Система плагинов

Поместите `.py`-файл, определяющий один или несколько подклассов `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]:
        ...

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

Фильтра плагинов по целям на уровне конфигурации нет — эта логика относится к самому плагину.

---

## Форматы отчетов

Три формата генерируются параллельно. Выберите любую комбинацию:```toml
[report]
formats    = ["markdown", "html", "json"]
output_dir = "./reports"

| Step | Action |
|------|--------|
| 1 | Проверяет предварительные требования |
| 2 | Загружает `.env` (копирует из `.env.example`, если отсутствует) |
| 3 | Запускает стек DefectDojo |
| 4 | Ожидает готовности API DefectDojo |
| 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
docker compose down -v
docker compose -f docker-compose.target.yaml down -v

---

## scanner.sh — Docker-обёртка

`scanner.sh` — рекомендуемый повседневный интерфейс для запуска сканера. Он оборачивает `docker compose run`, так что вам не нужно вводить команду compose вручную — просто передавайте цели и флаги напрямую.```bash
./scanner.sh [OPTIONS] [-- SCANNER_ARGS...]

### Что делает автоматически

- Загружает `.env` (копирует из `.env.example`, если отсутствует)
- Копирует `config.example.toml` → `config.toml`, если конфигурация не существует
- Создаёт Docker-сеть `vuln_scanner_network`, если она отсутствует
- Монтирует пользовательский файл `--config` в контейнер по пути `/app/config.toml`
- Пересобирает образ при передаче `--build`

---

## Конфигурация

Скопируйте аннотированный шаблон:```bash
cp config.example.toml config.toml

**Приоритет слияния конфигурации:** `CLI > env vars > config.toml > defaults`

---

## Переменные окружения

### Основные

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `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` | Каталог вывода отчётов |

### Отчёты

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_FORMATS` | `--formats` | Форматы отчётов: `markdown html json` |

### LLM

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `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 (только в контейнере) |

### Аутентифицированное сканирование

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_AUTH_BEARER_TOKEN` | `--auth-bearer` | 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 входа на основе формы |

Cookies и дополнительные заголовки должны быть заданы через файл конфигурации или флаги CLI `--auth-cookie` / `--auth-header`.

### Плагины

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_PLUGINS_ENABLED` | `--no-plugins` | Включить/отключить автоматическое обнаружение плагинов |
| `VS_PLUGINS_DIRS` | `--plugin-dir` | Дополнительные каталоги плагинов (через пробел) |

### DefectDojo

| Variable | CLI flag | Description |
|----------|----------|-------------|
| `VS_DEFECTDOJO_URL` | `--defectdojo-url` | Базовый URL DefectDojo |
| `VS_DEFECTDOJO_API_KEY` | `--defectdojo-api-key` | API-токен |
| `VS_DEFECTDOJO_PRODUCT` | — | Название продукта |
| `VS_DEFECTDOJO_ENGAGEMENT` | — | Название 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)

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,
}

**Советы:**
- Для инструментов, которые пишут в файл вместо stdout, используйте `OUTPUT_FILE_SENTINEL` в `build_command()` и переопределите `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 .