DockSec

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

Что такое DockSec?

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

Вместо того чтобы ошеломлять вас списком из 200+ CVE, DockSec:

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

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

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

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

DockSec следует конвейеру из пяти этапов:

Сканирование: запускает Trivy (уязвимости образов и ошибки конфигурации Dockerfile), Hadolint и Docker Scout локально в вашей среде.
Приоритизация: ранжирует каждую находку CVE по серьёзности в сочетании с EPSS — вероятностью эксплуатации, поэтому список упорядочен по тому, что исправлять в первую очередь, а не по тому, что было найдено первым.
Корреляция: обнаруживает цепочки эксплойтов, где отдельные находки объединяются в один путь атаки — база данных с учётными данными, доступная из интернет-сервиса, — это цепочка, а не две несвязанные находки. При наличии API-ключа ИИ-проход анализирует полный вывод сканирования, чтобы ранжировать, объяснить и расширить это.
Рекомендации: создаёт команды исправления для копирования и запуска, а также конкретные изменения Dockerfile или compose и указывает, сколько находок они устраняют.
Отчёт: экспортирует практические результаты в форматах HTML, PDF, JSON, CSV, Markdown, SARIF и CycloneDX SBOM.

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

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

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

Требование	Для чего нужно	Установка
Python 3.12+	Сам DockSec	python.org
Trivy	Все сканирования (обязательно)	`brew install trivy` или документация Trivy
Hadolint	Линтинг Dockerfile	`brew install hadolint` или документация Hadolint
Docker	Сканирование образов (`-i`)	документация Docker

Или позвольте 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

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

### 5. Или запустите образ контейнера (ничего устанавливать не нужно)

Опубликованный образ содержит закреплённые версии Trivy и Hadolint, так что
ничего не нужно устанавливать и ничего настраивать:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_DOCKERFILE=Dockerfile \
  -e INPUT_SCAN_ONLY=true \
  ghcr.io/owasp/docksec:latest

Публикуется для нескольких архитектур (amd64 и arm64) при каждом релизе. В CI указывайте конкретную версию (ghcr.io/owasp/docksec:2026.9.21) или минорную серию (ghcr.io/owasp/docksec:2026.9), а не latest. Каждый образ содержит аттестацию происхождения сборки:```bash gh attestation verify oci://ghcr.io/owasp/docksec:latest --repo OWASP/DockSec

Образ читает те же переменные `INPUT_*`, что и GitHub Action, поэтому здесь работает любой вход Action: `INPUT_IMAGE`, `INPUT_COMPOSE`, `INPUT_SEVERITY`, `INPUT_FAIL_ON`, `INPUT_FORMAT`, `INPUT_SARIF`, `INPUT_OUTPUT_DIR`. Записывайте отчёты куда-нибудь в примонтированный каталог, чтобы сохранить их после завершения контейнера:```bash
docker run --rm -v "$PWD:/github/workspace" \
  -e INPUT_COMPOSE=docker-compose.yml \
  -e INPUT_SCAN_ONLY=true \
  -e INPUT_FORMAT=json,html \
  -e INPUT_OUTPUT_DIR=/github/workspace/docksec-reports \
  ghcr.io/owasp/docksec:latest

6. Или используйте 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

# Write a Markdown report for posting directly into a pull request comment
docksec Dockerfile --scan-only --format markdown

# 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 --scan-only --compact-output         # shorter per-finding output
docksec Dockerfile --no-color                           # also honors NO_COLOR

# Apply the mechanical Dockerfile fixes (keeps a .bak, re-scans, shows the delta)
docksec Dockerfile --scan-only --fix --dry-run          # print the diff, change nothing
docksec Dockerfile --scan-only --fix

# Rank findings by severity alone, with no EPSS lookup and no network call
docksec Dockerfile --scan-only --no-epss

# Treat a scan that could not complete as a failure, not a pass
docksec Dockerfile --scan-only --fail-on high --incomplete-policy fail

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

Зафиксируйте .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`](https://github.com/owasp/docksec/blob/main/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`	-	ID правил, которые нужно полностью отключить

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

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

Комментарий # yaml-language-server: в первой строке обеспечивает автодополнение и встроенную валидацию в редакторах VS Code и JetBrains. Схема опубликована по адресу docs/docksec-config-schema.json и может быть перегенерирована с помощью docksec --print-config-schema.

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

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

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

Коды выхода

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

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

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

Незавершённые сканирования

Если сканер не может запуститься, результаты могут содержать пропущенные находки, а не быть действительно чистыми. DockSec сообщает об этом как о пробеле в обнаружении в блоке Coverage и в --json в разделе scan_info.completeness. Используйте --incomplete-policy fail, чтобы завершиться с кодом 3 в этом случае, чтобы CI не мог пройти на сканировании, которое не завершилось:```bash docksec Dockerfile --incomplete-policy fail

### Приоритет: что исправлять в первую очередь

Каждая находка CVE оценивается по [EPSS](https://www.first.org/epss/), который
оценивает вероятность её эксплуатации в течение следующих 30 дней. В сочетании
с уровнем серьёзности это даёт четыре уровня:

| Уровень | Значение |
|---|---|
| **Fix Now** | Критическая или высокая серьёзность, и входит в топ-10% CVE по вероятности эксплуатации |
| **Fix Soon** | Критическая или высокая серьёзность, но эксплуатация менее распространена |
| **Monitor** | Ниже серьёзность, но активно эксплуатируется |
| **Low Priority** | Ниже серьёзность, эксплуатация редка |

Это единственный сетевой вызов, который DockSec делает вне AI-прохода, и он
намеренно узок: **отправляются только идентификаторы CVE** — никаких имён образов,
содержимого файлов или путей. Оценки кэшируются на 24 часа. `--offline` и `--no-epss`
отключают его, а любая ошибка приводит к ранжированию только по серьёзности,
а не к сбою сканирования.

### Цепочки эксплуатации

Представление по каждому сервису сообщает о находках по одной. DockSec также
сообщает, где отдельные находки объединяются в единый путь атаки:```text
Exploit chains
  [HIGH] 'web' is internet-facing and can reach 'db' with a committed credential
      services: web, db
      combines: compose-plaintext-secret-env, compose-no-network-segmentation
      'web' accepts connections from outside the host and shares the default
      network with 'db'. 'db' is not exposed directly, but its credential is in
      the compose file, so compromising 'web' yields authenticated access to it.
      Neither service looks critical on its own.
      break it: Put 'db' on its own network that 'web' does not join, or move
      POSTGRES_PASSWORD to a Docker secret.

Обнаружение цепочек основано на правилах, поэтому оно работает с --scan-only, офлайн и без API-ключа, и возвращает один и тот же результат при каждом запуске. AI-проход ранжирует и расширяет его, а не является обязательным для него. Цепочки также отображаются в --json в разделе exploit_chains.

См. руководство по цепочкам эксплойтов для полного списка и справочник по правилам compose для каждого правила, которое они объединяют.

Команды исправления

Сканирования завершаются конкретными командами, а не списком идентификаторов, и простым утверждением о том, сколько находок они устраняют:```text Fix commands

apt-get install --only-upgrade -y libgnutls30=3.7.9-2+deb12u7 CRITICAL - 3.7.9-2+deb12u4 -> 3.7.9-2+deb12u7 (CVE-2026-33845 +6)

Dockerfile changes

[CRITICAL] Move the secret out of ENV; inject it at runtime (line 4)
[HIGH] Add a non-root USER before CMD/ENTRYPOINT (line 7)

Applying all of the above resolves 37 of 93 finding(s); 56 have no mechanical fix yet.

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

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

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

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

--format принимает список выходных файлов, разделённых запятыми:

Формат	Что вы получаете
`json`	Файл `.json` с метаданными сканирования, количеством уязвимостей по уровням серьёзности и полным списком уязвимостей (та же структура, что и у полезной нагрузки stdout `--json`, но записанная на диск).
`csv`	Таблица `.csv` с найденными проблемами (ID, уровень серьёзности, пакет, версия, заголовок и связанные поля).
`pdf`	Печатная PDF-сводка с информацией о сканировании, оценками и сведениями об уязвимостях.
`html`	Оформленный HTML-отчёт для просмотра результатов в браузере.
`markdown`	Отчёт `.md`, который отображается нативно в комментариях к pull request и сводках заданий CI. Опционально: не записывается, если не запрошен.

json, csv, pdf и html записываются по умолчанию; добавьте markdown явно, чтобы получить его.

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

О JSON в stdout и передаче в другие инструменты см. Машиночитаемый вывод выше. Для CI и GitHub Code Scanning используйте --sarif (см. следующий раздел); SARIF отделён от --format и всегда создаётся, когда запрошен.

Вывод 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**: Интерактивный, визуально чистый веб-отчёт: карточки серьёзности, рейтинг оценки, полная таблица уязвимостей с исправленными версиями и полные результаты AI.
- **pdf**: Портативный документ, готовый к презентации.
- **json**: Полные машиночитаемые данные сканирования (та же структура, что и вывод `--json` в stdout).
- **csv**: Готовая для электронных таблиц таблица отдельных уязвимостей.
- **markdown**: Лёгкий, удобочитаемый отчёт (сводка по серьёзности + таблица уязвимостей с исправленными версиями), который нативно отображается в комментариях к pull request и сводках заданий CI. Опционально: добавьте `markdown` в `--format`; по умолчанию он не записывается.

> Примечание о поведении 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 часа, переопределяется через
`DOCSEC_CACHE_TTL_HOURS`) и привязываются к дайджесту содержимого образа, поэтому пересобранный тег,
например повторно используемый `:latest`, всегда получает свежее сканирование. Используйте `--no-cache` (или
`DOCSEC_USE_CACHE=false`), чтобы обойти кэш для запуска.

### Загрузка образов, отсутствующих локально

Сканирование образа, отсутствующего локально, сначала загружает его. Стек compose
обычно указывает образы, которые машина никогда не загружала, и без этого каждый из
этих сервисов будет отмечен как неотсканированный.

Установите `DOCSEC_PULL_MISSING_IMAGES=false`, чтобы отключить это и вместо этого завершать с ошибкой, что
стоит делать при лимитированном соединении или на общем раннере. `--offline` никогда не загружает образы,
независимо от этой настройки.

---

## Навыки AI-ассистента (`install-skill`)

`docksec install-skill` записывает инструкции по использованию DockSec в общеизвестные контекстные
файлы популярных AI-ассистентов для программирования, чтобы ассистент, работающий в вашем репозитории, знал, как
вызывать 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, режим baseline/ratchet, аудируемые исключения, вывод JSON в stdout и GitHub Action в Marketplace.
Автономный режим: Полностью изолированное сканирование (--offline) с использованием локальной базы данных Trivy.
Навыки для ИИ-ассистентов: docksec install-skill обучает Claude Code, Cursor, Copilot и других запускать DockSec в вашем репозитории.

Сравнение DockSec

Возможность	DockSec	Trivy (отдельно)	Snyk Container	Aikido
Лицензия и стоимость	Бесплатно, открытый исходный код (MIT)	Бесплатно, открытый исходный код (Apache 2.0)	Коммерческий (ограниченный бесплатный тариф)	Коммерческий (ограниченный бесплатный тариф)
Управление	OWASP Lab Project, независимость от вендора	Открытый исходный код, поддерживается Aqua	Единственный вендор	Единственный вендор
Обнаружение CVE и ошибок конфигурации Dockerfile	Да	Да	Да	Да
Объяснение находок простым языком	Да (контекст и влияние, написанные ИИ)	Нет (необработанные данные CVE)	Частично (подсказки по серьёзности и исправлению)	Частично (ИИ-резюме в платформе)
Контекстное исправление Dockerfile	Да (конкретные перезаписи с объяснением)	Нет (только обнаружение)	Да (советы по обновлению базового образа, PR с исправлениями)	Да (ИИ AutoFix PR)
Сканирование Docker Compose (мультисервисное)	Да (проверки оркестрации и сканирование каждого сервиса)	Частично (сканирование конфигурации, без разветвления по сервисам)	Частично	Частично
Режим baseline / ratchet (сбой только на новых находках)	Да	Нет	Частично (политики платформы)	Частично (политики платформы)
Аудируемые исключения для каждой находки с причинами и сроком действия	Да	Частично (.trivyignore, причины не проверяются)	Частично (политики платформы)	Частично (политики платформы)
Вывод, нативный для CI (SARIF для GitHub Code Scanning)	Да	Да	Да	Да
Экспорт SBOM (CycloneDX)	Да (`--sbom`)	Да	Да	Да
Установка навыка для ИИ-ассистента (Claude Code, Cursor, Copilot)	Да (`install-skill`)	Нет	Нет	Нет
Полностью автономная работа / в изолированной среде	Да (локальная LLM через Ollama, режим только сканирования, без API-ключа)	Только сканирование (без слоя исправлений)	Нет (облачная платформа)	Нет (размещённая платформа)
Данные вашего образа остаются в вашей сети	Да	Да	Нет	Нет
Своя LLM / выбор модели	Да (OpenAI, Anthropic, Gemini или локальная Ollama)	Не применимо	Нет (проприетарный ИИ)	Нет (проприетарный ИИ)
Самостоятельный хостинг, без развёртывания платформы	Да	Да	Нет	Нет
Привязка к вендору	Отсутствует	Отсутствует	Да	Да
Оценка безопасности (0-100) и отчёты в нескольких форматах	Да	Частично (машинные форматы, без отчёта об исправлениях)	Частично (отчёты в дашборде)	Частично (отчёты в дашборде)

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

Автоматическое применение исправлений

--fix применяет механическую часть предложенных изменений Dockerfile, повторно сканирует и сообщает о разнице:```bash docksec Dockerfile --scan-only --fix --dry-run # print the diff, change nothing docksec Dockerfile --scan-only --fix # apply, keeping a .bak

```bash
# Установить зависимости
pip install -r requirements.txt

# Запустить сканирование
python3 cve_scan.py --target 192.168.1.0/24 --output results.json

# Просмотреть результаты
cat results.json | jq '.vulnerabilities[] | select(.severity=="CRITICAL")'

Параметры конфигурации

Параметр	Описание	По умолчанию
`--target`	Целевой диапазон IP или хост	Обязательно
`--ports`	Сканируемые порты	`1-65535`
`--timeout`	Тайм-аут соединения (секунды)	`5`
`--threads`	Количество параллельных потоков	`10`
`--output`	Путь к выходному файлу	`stdout`

Примеры использования

Базовое сканирование

python3 cve_scan.py --target example.com

Расширенное сканирование с пользовательскими портами

python3 cve_scan.py --target 10.0.0.0/24 --ports 22,80,443,8080 --threads 20

Экспорт результатов в формате CSV

python3 cve_scan.py --target 192.168.1.1 --output results.csv --format csv

Устранение неполадок

Ошибка подключения

Если вы получаете ошибки подключения, убедитесь, что:

Целевой хост доступен
Брандмауэр не блокирует исходящие соединения
У вас есть необходимые разрешения

Проблемы с производительностью

Для больших диапазонов сети уменьшите количество потоков:

python3 cve_scan.py --target 10.0.0.0/16 --threads 5

Лицензия

Этот проект лицензирован под MIT License — подробности см. в файле LICENSE.

Отказ от ответственности

Этот инструмент предназначен только для авторизованного тестирования на проникновение и оценки безопасности. Используйте его ответственно и только в системах, на которые у вас есть явное разрешение.```text Applied 4 change(s)

added --no-install-recommends on line(s) 2 [DS029]
converted ADD to COPY on line(s) 3 [DL3020]
replaced 'USER root' with 'USER appuser' on line 5 [DS002]
inserted a placeholder HEALTHCHECK before line 6 [DS026]

Original saved to Dockerfile.bak Dockerfile findings: 7 -> 2 (5 resolved)

Он намеренно консервативен. Он не будет выбирать версию базового образа, перемещать
секрет, преобразовывать `ADD`, который загружает URL или распаковывает архив, или редактировать
compose-файл — вместо этого они попадают в раздел «Needs review». Он также отказывается
редактировать файл с незакоммиченными изменениями, если не указан `--force`, поэтому git всегда
может отменить изменение.

## Документация

| Руководство | Что охватывает |
| --- | --- |
| [Руководство по оценке](https://github.com/owasp/docksec/blob/main/docs/evaluation-guide.md) | 15-минутная оценка, включая то, что DockSec *не* делает |
| [Цепочки эксплойтов](https://github.com/owasp/docksec/blob/main/docs/exploit-chains.md) | Межсервисные пути атак и их ограничения |
| [Справочник правил Compose](https://github.com/owasp/docksec/blob/main/docs/rules/README.md) | Все 17 правил: что каждое выявляет и когда его сохранение разумно |
| [Интеграция с CI](https://github.com/owasp/docksec/blob/main/docs/ci/README.md) | Jenkins, GitLab, Azure Pipelines, pre-commit |
| [Примеры](https://github.com/owasp/docksec/blob/main/examples/README.md) | Десять Dockerfile и compose-стеков с ожидаемыми находками |
| [Кейсы](https://github.com/owasp/docksec/blob/main/docs/case-studies/README.md) | Реальные сканирования официальных образов с цифрами |

## План развития

См. [ROADMAP.md](https://github.com/owasp/docksec/blob/main/ROADMAP.md), чтобы узнать, куда движется DockSec: сканирование реестров без
локального демона Docker, файл конфигурации политик на уровне репозитория, шаблоны для
Jenkins/GitLab/Azure DevOps, официальный контейнерный образ, сканирование Kubernetes и Helm и
многое другое. Отзывы и голоса по приоритетам приветствуются в
[issues](https://github.com/OWASP/DockSec/issues) и в
[OWASP Slack](https://owasp.slack.com/archives/C0APXGCUW7M).

---

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

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

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

Чтобы начать, ознакомьтесь с нашими [Руководящими принципами по участию](https://github.com/owasp/docksec/blob/main/CONTRIBUTING.md), [Кодексом поведения](https://github.com/owasp/docksec/blob/main/CODE_OF_CONDUCT.md) и [Руководством по спонсорству](https://github.com/owasp/docksec/blob/main/SPONSORSHIP.md).

---

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

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

- [Advait Patel](https://github.com/advaitpatel) — руководитель проекта
- [Arkadii Yakovets](https://github.com/arkid15r) — со-руководитель проекта

Найдите нас здесь:

- **Страница проекта OWASP**: [owasp.org/DockSec/](https://owasp.org/DockSec/)
- **OWASP Slack**: [#project-docksec](https://owasp.slack.com/archives/C0APXGCUW7M)
- **PyPI**: [pypi.org/project/docksec/](https://pypi.org/project/docksec/)
- **Issues**: [Сообщить об ошибке](https://github.com/OWASP/DockSec/issues)
- **Changelog**: [CHANGELOG.md](https://github.com/owasp/docksec/blob/main/CHANGELOG.md)

---

<div align="center">
  <strong>Если DockSec помогает вам, поставьте звезду репозиторию, чтобы помочь другим найти его.</strong><br>
  Создано <a href="https://github.com/advaitpatel">Advait Patel</a> и сообществом OWASP.
</div>

DockSec v2026.9.21

Категории