DockSec

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

Что такое DockSec?

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

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

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

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

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

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

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

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

У каждого провайдера есть разумная модель по умолчанию (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

Общие команды```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

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

Приоритет

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

С --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

Находки сопоставляются по идентификатору уязвимости, цели и имени пакета, поэтому базовая линия остаётся действительной, когда появляются и исчезают несвязанные находки. Повторно запускайте с --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"

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

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

• .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