DockSec

ИИ-сканер безопасности Docker, который объясняет уязвимости простым языком

Что такое DockSec?

DockSec — это проект OWASP Lab, который устраняет разрыв между сложными результатами сканирования безопасности и практичными исправлениями для разработчиков. Он объединяет отраслевые сканеры (Trivy, Hadolint, Docker Scout) с ИИ для обеспечения контекстно-зависимого анализа безопасности.

Вместо того чтобы перегружать вас списком из более чем 200 CVE, DockSec:

• Расставляет приоритеты среди того, что действительно влияет на вашу конкретную конфигурацию контейнера.
• Объясняет уязвимости простым языком, а не только техническим жаргоном.
• Предлагает конкретные исправления для вашего Dockerfile.
• Создаёт профессиональные интерактивные отчёты по безопасности для вашей команды.

Всё сканирование выполняется локально; единственное, что покидает вашу машину, — это содержимое файлов (с удалёнными секретами), отправляемое выбранному вами ИИ-провайдеру. При использовании локальной модели или режима только сканирования ничего не покидает устройство. См. Поток данных и конфиденциальность.

Как это работает

Рабочий процесс DockSec: от сканирования до практических рекомендаций

DockSec использует конвейер из четырёх этапов:

1. Сканирование: запускает Trivy, Hadolint и Docker Scout локально в вашей среде.
2. Анализ: ИИ сопоставляет результаты всех сканеров для устранения шума и оценки реального влияния.
3. Рекомендации: генерирует понятные объяснения и конкретные шаги по устранению.
4. Отчёт: экспортирует практические результаты в HTML, PDF, JSON, CSV, SARIF и CycloneDX SBOM.

Начало работы

1. Предварительные требования

DockSec управляет локальными сканерами, поэтому ему требуются:

Или позвольте DockSec установить Trivy и Hadolint за вас:```bash python -m docksec.setup_external_tools

### 2. Установка DockSec```bash
# Full install with AI analysis support (recommended)
pip install "docksec[ai]"

# Or the slim, scan-only core (no LLM dependencies, no API key needed)
pip install docksec

3. Запустите первое сканирование

Для локального сканирования API-ключ не требуется:```bash docksec Dockerfile --scan-only

Каждое сканирование завершается сводкой результатов: таблицей серьёзности, оценкой безопасности от 0 до 100 с рейтингом, блоком действий «Quick take», сгенерированными отчётами (по умолчанию сохраняются в `~/.docksec/results/`) и рекомендуемой следующей командой.

### 4. Включение AI-анализа

AI-анализ объясняет найденные проблемы и предлагает исправления. Выберите провайдера, задайте его API-ключ и выполните:```bash
# OpenAI (default provider)
export OPENAI_API_KEY="sk-..."
docksec Dockerfile

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
docksec Dockerfile --ai-only --provider anthropic --model claude-sonnet-5

# Google Gemini
export GOOGLE_API_KEY="..."
docksec Dockerfile --ai-only --provider google

# Ollama (fully local, no API key, data never leaves your machine)
docksec Dockerfile --ai-only --provider ollama --model llama3.1

У каждого провайдера есть разумная модель по умолчанию (OpenAI: gpt-4o, Anthropic: claude-haiku-4-5, Google: gemini-1.5-pro, Ollama: llama3.1), так что --model является необязательным. Чтобы не повторять флаги, задайте переменные окружения (или поместите их в файл .env в каталоге, из которого вы запускаете - DockSec загружает его автоматически):```bash export LLM_PROVIDER=anthropic export LLM_MODEL=claude-sonnet-5 docksec Dockerfile

Прежде чем какой-либо контент будет отправлен ИИ-провайдеру, значения, похожие на секреты (пароли, токены,
ключи API, блоки приватных ключей), маскируются автоматически. См.
[Поток данных и конфиденциальность](#data-flow-and-privacy).

### 5. Или используйте GitHub Action```yaml
- name: Run DockSec AI Scanner
  uses: OWASP/[email protected]
  with:
    dockerfile: 'Dockerfile'
    openai_api_key: ${{ secrets.OPENAI_API_KEY }}

Основные команды```bash

Scan Dockerfile + Docker image (AI + scanners)

docksec Dockerfile -i myapp:latest

Scan a Docker Compose file and all its services

docksec --compose docker-compose.yml

Scan only a Docker image

docksec --image-only -i myapp:latest

Fast local scan, no AI, no API key

docksec Dockerfile --scan-only

Choose which severity levels the image scan reports (default: CRITICAL,HIGH)

docksec -i myapp:latest --image-only --severity CRITICAL,HIGH,MEDIUM

Fail the build (exit 1) if any finding is HIGH or above

docksec -i myapp:latest --image-only --fail-on high

Write only the report formats you want, to a directory of your choice

docksec Dockerfile --scan-only --format json,html --output-dir ./reports

Print results as JSON to stdout for scripts and CI pipelines

docksec -i myapp:latest --image-only --json

Write a SARIF report for GitHub Code Scanning

docksec Dockerfile --scan-only --sarif

Write a CycloneDX SBOM of an image for supply-chain tooling

docksec --image-only -i myapp:latest --sbom

Fully offline scan: local Trivy DB, no network, no AI

docksec --image-only -i myapp:latest --offline

Save today's findings as a baseline, then only gate on new findings later

docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

Suppress triaged findings with an auditable ignore file

docksec -i myapp:latest --image-only --ignore-file .docksec-ignore.yml

Force a fresh scan, bypassing the results cache

docksec -i myapp:latest --image-only --no-cache

Install AI-assistant skill files (Claude Code, Cursor, Copilot, and more)

docksec install-skill

Output control

docksec Dockerfile --scan-only --quiet # warnings, errors, summary only docksec Dockerfile --scan-only --verbose # INFO-level diagnostics on stderr docksec Dockerfile --scan-only --verbose --log-file logs/docksec.log docksec Dockerfile --no-color # also honors NO_COLOR

---

## Интеграция CI/CD

### Коды выхода

DockSec использует понятные для CI коды выхода, чтобы сборки и оболочки могли реагировать на результаты:

| Код | Значение |
|---|---|
| `0` | Успех, нет находок на уровне `--fail-on` или выше |
| `1` | Есть находки на уровне порога `--fail-on` или выше |
| `2` | Ошибка использования или аргументов |
| `3` | Ошибка инструмента или выполнения (сбой сканирования, образ не найден, отсутствуют инструменты) |

`--fail-on` действует как шлюз на основе структурированных находок (уязвимости образов и ошибки конфигурации compose). Когда `--fail-on` ниже запрошенного `--severity`, уровень серьёзности сканирования автоматически расширяется, чтобы шлюз мог учитывать эти находки.

### Машиночитаемый вывод

`--json` выводит один JSON-объект в stdout (информация о сканировании, уязвимости, количество серьёзностей и любые AI-находки) вместо человекочитаемой сводки, что позволяет передавать его напрямую в другие инструменты:```bash
docksec -i myapp:latest --image-only --json | jq '.severity_counts'

При использовании только --json файлы отчётов не записываются; комбинируйте его с --format, чтобы записывать файлы и выводить JSON в том же запуске. В режиме --json все человекочитаемые сообщения выводятся в stderr, поэтому stdout содержит только JSON-нагрузку.

Вывод SARIF для GitHub Code Scanning

--sarif записывает отчёт SARIF 2.1.0 вместе с другими форматами отчётов. Загрузите его с помощью стандартного действия github/codeql-action/upload-sarif, чтобы увидеть находки, аннотированные непосредственно в pull request’ах и на вкладке Security:```yaml

• name: Run DockSec uses: OWASP/[email protected] with: dockerfile: 'Dockerfile' sarif: 'true'

• name: Upload SARIF to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: ~/.docksec/results

> `if: always()` важен: без него шаг загрузки пропускается всякий раз, когда
> `--fail-on` заставляет DockSec завершиться с ненулевым кодом, и результаты теряются именно тогда,
> когда они нужнее всего.

### Базовый уровень / режим храповика

`--baseline FILE` позволяет применить `--fail-on` в существующем проекте без стены
уже имеющихся находок, блокирующих каждую сборку. Выполните команду один раз с `--update-baseline`, чтобы создать снимок
текущих находок, затем закоммитьте файл базовой линии; после этого `--fail-on` будет срабатывать только на
находки, которых ещё нет в базовой линии:```bash
# Snapshot current findings (does not gate)
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --update-baseline

# Later runs only fail on NEW findings above the threshold
docksec -i myapp:latest --image-only --baseline .docksec-baseline.json --fail-on high

Находки сопоставляются по идентификатору уязвимости, цели и имени пакета, поэтому базовая линия остаётся действительной, пока несвязанные находки появляются и исчезают. Повторно запустите с --update-baseline, когда захотите принять текущее состояние в качестве новой базовой линии.

Игнорирование находок (исключения)

--ignore-file FILE подавляет отдельные находки, которые команда рассмотрела и приняла. В отличие от базовой линии (мгновенного снимка), файл игнорирования — это явный, проверяемый список, где каждая запись содержит причину и необязательный срок действия. Если в текущем каталоге есть файл .docksec-ignore.yml, он будет подхвачен автоматически.```yaml

.docksec-ignore.yml

ignores:

• id: CVE-2023-45853 # Trivy vulnerability ID or DockSec rule ID reason: "zlib CVE; code path not reachable, vendor fix pending" expires: 2026-12-31 # optional; entry stops applying after this date
• id: compose-missing-healthcheck reason: "healthchecks are handled by the orchestrator"

Подавленные находки удаляются до подсчёта очков, формирования отчётов, вывода `--json` и проверки `--fail-on`. Просроченные записи перестают применяться автоматически (с предупреждением), а записи без причины помечаются, чтобы исключения оставались проверяемыми. Коммитьте файл в систему контроля версий, чтобы подавления проходили ревью, как и любые другие изменения.

---

## Отчёты

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

По умолчанию каждое сканирование создаёт четыре файла отчётов; используйте `--format`, чтобы выбрать подмножество:

- **html**: интерактивный, визуально понятный веб-отчёт: карточки серьёзности, рейтинг оценки, полная таблица уязвимостей с исправленными версиями и полные выводы AI.
- **pdf**: переносимый документ, готовый к презентации.
- **json**: полные машиночитаемые данные сканирования (та же структура, что и вывод `--json` в stdout).
- **csv**: таблица отдельных уязвимостей, готовая для работы в табличных редакторах.

> Примечание о поведении CSV: при нулевом количестве уязвимостей DockSec всё равно записывает CSV только с заголовками (названия колонок, без строк), чтобы автоматизация ниже по конвейеру никогда не ломалась из-за отсутствующего или пустого файла. Это сделано намеренно.

### CycloneDX SBOM

`--sbom` создаёт спецификацию программного обеспечения CycloneDX (`<image>.cdx.json`) для сканируемого образа, перечисляя каждый компонент пакета, а также известные уязвимости. BOM создаётся нативным экспортёром Trivy (поэтому она соответствует спецификации), а DockSec добавляет себя в метаданные инструмента. Передавайте её в Dependency-Track, граф зависимостей GitHub или любой другой потребитель SBOM:```bash
docksec --image-only -i myapp:latest --sbom

--sbom требует один образ (-i), поэтому для запусков compose он пропускается. Как и --sarif, он не зависит от --format.

Поток данных и конфиденциальность

DockSec спроектирован так, чтобы вы всегда знали, что покидает ваш компьютер:

• Сканирование полностью локальное. Trivy, Hadolint и оценка безопасности выполняются на вашем компьютере. DockSec никогда никуда не загружает содержимое образов.
• AI-анализ отправляет только просканированный файл. Когда выполняется этап AI, содержимое Dockerfile или compose-файла (а также краткая сводка по количеству уязвимостей для оценки) отправляется настроенному вами LLM-провайдеру. Больше ничего не передаётся.
• Секреты маскируются до отправки. Похожие на секреты значения (пароли, токены, ключи API, блоки приватных ключей) в файле маскируются перед отправкой содержимого AI-провайдеру. Имена ключей остаются видимыми, чтобы скомпрометированные учётные данные по-прежнему помечались. Используйте --no-redact, чтобы отказаться от маскировки.
• Полностью локальный AI поддерживается. Используйте --provider ollama, чтобы оставить AI-анализ на своём собственном оборудовании, или --scan-only / --offline, чтобы пропустить AI полностью.
• Никакой телеметрии. DockSec не собирает данные об использовании и ничего не отправляет на внешние серверы.

Офлайн-режим

--offline запускает сканирование без доступа к сети. Используется база данных уязвимостей Trivy, уже находящаяся на диске (без обновления БД), а AI-анализ и расширенное сканирование Docker Scout пропускаются — оба требуют сети. Это самый простой способ сканирования в изолированной или строго ограниченной среде:```bash docksec --image-only -i myapp:latest --offline

Убедитесь, что база данных Trivy была загружена хотя бы один раз (любое предыдущее онлайн-сканирование делает это), прежде чем полагаться на `--offline`.

### Кэш результатов сканирования

Результаты сканирования образов кэшируются (по умолчанию: 24 часа; переопределяется через `DOCKSEC_CACHE_TTL_HOURS`) и индексируются по дайджесту содержимого образа, поэтому пересобранный тег, например повторно используемый `:latest`, всегда получает свежее сканирование. Используйте `--no-cache` (или `DOCKSEC_USE_CACHE=false`), чтобы обойти кэш для запуска.

---

## Навыки для ИИ-ассистентов (`install-skill`)

`docksec install-skill` записывает инструкции по использованию DockSec в стандартные контекстные файлы популярных ИИ-ассистентов для программирования, чтобы ассистент, работающий в вашем репозитории, знал, как вызывать DockSec:```bash
docksec install-skill

Это создаёт или обновляет:

• .claude/commands/docksec.md (слэш-команда Claude Code /docksec)
• .cursor/rules/docksec.mdc (Cursor)
• AGENTS.md (Codex CLI), GEMINI.md (Gemini CLI)
• .github/copilot-instructions.md (GitHub Copilot)

Файлы представляют собой обычный текст, который можно просмотреть и закоммитить; ничего не выполняется. Повторный запуск команды обновляет раздел DockSec на месте, а не дублирует его.

Возможности

• Умный анализ: ИИ объясняет, что означают уязвимости для вашего конкретного окружения.
• Поддержка нескольких LLM: OpenAI, Anthropic Claude, Google Gemini или локальные модели через Ollama.
• Конфиденциальность прежде всего: секретные значения маскируются до того, как какой-либо контент достигнет ИИ-провайдера; сканирование полностью локальное, телеметрия отсутствует.
• Сканирование Docker Compose: обнаружение ошибок конфигурации на уровне оркестрации и сканирование всех сервисов в compose-файле.
• Глубокая интеграция: объединяет Trivy (уязвимости), Hadolint (линтинг) и Docker Scout.
• Оценка безопасности: оценка от 0 до 100 с рейтингом для отслеживания вашего уровня безопасности с течением времени.
• Богатые форматы: HTML (интерактивный), PDF, JSON, CSV, SARIF и CycloneDX SBOM.
• Готовность к CI/CD: коды выхода --fail-on, режим базовой линии/храповика, аудируемые исключения, вывод JSON в stdout и GitHub Action в Marketplace.
• Офлайн-режим: сканирование в полностью изолированной среде (--offline) с использованием локальной базы данных Trivy.
• Навыки для ИИ-ассистентов: docksec install-skill обучает Claude Code, Cursor, Copilot и другие инструменты запуску DockSec в вашем репозитории.

Сравнение с другими инструментами

DockSec — единственный из этих инструментов, который сочетает контекстное исправление Dockerfile с полностью открытым исходным кодом, управлением OWASP и локально запускаемой архитектурой. Snyk и Aikido предлагают полноценное исправление с помощью ИИ, но только как коммерческие облачные платформы, которые отправляют ваши данные в свой сервис. Trivy имеет открытый исходный код и работает локально, но останавливается на этапе обнаружения и не помогает ничего исправить. DockSec заполняет этот пробел для разработчиков и для команд в регулируемых или изолированных средах, которым нужны и рекомендации по исправлению, и полный контроль над своими данными, без затрат.

Дорожная карта

О том, куда движется DockSec, читайте в ROADMAP.md: сканирование реестров без локального демона Docker, файл конфигурации политик на уровне репозитория, шаблоны Jenkins/GitLab/Azure DevOps, официальный контейнерный образ, сканирование Kubernetes и Helm и многое другое. Отзывы и голосование по приоритетам приветствуются в issues и в OWASP Slack.

Участие в разработке

DockSec процветает благодаря вкладу сообщества. Разработчик ли вы, дизайнер или энтузиаст безопасности — есть множество способов поучаствовать:

• Вклад в код: исправление ошибок или добавление новых функций.
• Документация: улучшение руководств или создание обучающих материалов.
• Сообщение об ошибках: выявление и отправка отчётов об ошибках.
• Обратная связь: поделитесь своим опытом и предложениями.

Для начала ознакомьтесь с нашими Руководством по участию, Кодексом поведения и Руководством по спонсорству.

Лидеры и сообщество

DockSec возглавляет целеустремлённая команда, стремящаяся сделать безопасность контейнеров доступной:

• Advait Patel — лидер проекта
• Arkadii Yakovets — со-лидер проекта

Где нас найти:

• Страница проекта OWASP: owasp.org/DockSec/
• OWASP Slack: #project-docksec
• PyPI: pypi.org/project/docksec/
• Issues: Сообщить об ошибке
• Журнал изменений: CHANGELOG.md