DockSec

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

Что такое DockSec?

DockSec — это лабораторный проект OWASP, который устраняет разрыв между сложными результатами сканирования безопасности и практичными исправлениями для разработчиков. Он объединяет отраслевые сканеры (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

---

## Файл конфигурации

Зафиксируйте `.docksec.yml` в корне вашего репозитория, и вся команда — а также
каждый CI-джоб — будет сканировать по одной и той же политике, вместо того чтобы каждый разработчик передавал свои собственные флаги.```yaml
# yaml-language-server: $schema=https://owasp.org/DockSec/docksec-config-schema.json
severity: CRITICAL,HIGH
fail_on: HIGH
formats: [json, html]
output_dir: ./security-reports

rules:
  disabled:
    - compose-missing-healthcheck

Каждый параметр необязателен; всё, что вы пропустите, берётся из переменной окружения, а затем из встроенного значения по умолчанию. Полный пример с комментариями приведён в examples/.docksec.yml.

Приоритет

Сначала — наивысший приоритет:``` CLI flag > environment variable > .docksec.yml > built-in default

Так что зафиксированный `severity: LOW` всё равно переопределяется параметром `--severity CRITICAL` в командной строке и переменной окружения `DOCKSEC_DEFAULT_SEVERITY`.

### Обнаружение

DockSec ищет `.docksec.yml` (или `.docksec.yaml`) в рабочем каталоге, а затем поднимается вверх до корня репозитория, поэтому сервис в подкаталоге монорепозитория наследует политику, зафиксированную на верхнем уровне. Поиск останавливается в каталоге, содержащем `.git`, поэтому файл извне репозитория никогда не подхватывается.

- `--config FILE` использует конкретный файл вместо поиска.
- `--no-config` игнорирует любой файл конфигурации для воспроизводимых запусков CI.

Действующий файл конфигурации отображается в баннере сканирования, поэтому всегда понятно, какая политика была применена.

### Настройки

| Настройка | Эквивалентный флаг | Примечания |
| --- | --- | --- |
| `severity` | `--severity` | Уровни серьёзности для сканирования образа |
| `fail_on` | `--fail-on` | Порог шлюза CI |
| `formats` | `--format` | Формат списка: `[json, html]` |
| `output_dir` | `--output-dir` | Каталог для отчётов |
| `provider` | `--provider` | `openai`, `anthropic`, `google`, `ollama` |
| `model` | `--model` | Название модели для провайдера |
| `offline` | `--offline` | Без сети; пропускает AI и Docker Scout |
| `skip_ai_scoring` | `--skip-ai-scoring` | Только локальная оценка |
| `no_redact` | `--no-redact` | Не маскировать секреты перед вызовом AI |
| `no_cache` | `--no-cache` | Обход кэша сканирования |
| `ignore_file` | `--ignore-file` | Путь к файлу исключений |
| `baseline` | `--baseline` | Путь к файлу базовой линии |
| `rules.disabled` | - | Идентификаторы правил для полного отключения |

Недопустимый файл конфигурации — неизвестный ключ, неверный уровень серьёзности — является жёсткой ошибкой, которая завершает работу с кодом `2`, а не предупреждением, поэтому сломанный файл политики никогда не приведёт к запуску сканирования по правилам, которые команда не фиксировала.

### Автодополнение в редакторе

Комментарий `# yaml-language-server:` в первой строке обеспечивает автодополнение и встроенную проверку в VS Code и редакторах JetBrains. Схема опубликована в [`docs/docksec-config-schema.json`](https://github.com/owasp/docksec/blob/main/docs/docksec-config-schema.json) и может быть перегенерирована с помощью `docksec --print-config-schema`.

### Отключение правил

`rules.disabled` полностью отключает проверку везде — она удаляется до оценки, отчётов, `--json` и шлюза `--fail-on`. Используйте это для проверок, которые не применимы к вашему окружению. Для отдельных находок, которые ваша команда уже рассмотрела и приняла, предпочтительнее использовать [файл исключений](#ignoring-findings-waivers), записи которого содержат причину и срок действия и поэтому остаются проверяемыми.

---

## Интеграция с 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, когда хотите принять текущее состояние как новую базовую линию.

Игнорирование находок (waivers)

--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**: Интерактивный, визуально чистый веб-отчёт: карточки серьёзности, оценка рейтинга, полная таблица уязвимостей с исправленными версиями и полные выводы ИИ.
- **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`) и привязываются к content digest образа, поэтому пересобранный тег, такой как повторно используемый `: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 с другими инструментами

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

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

См. ROADMAP.md о том, куда движется DockSec: сканирование реестров без локального 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