Страница документации

• https://brumbelow.github.io/layerleak/docs

Опубликованный сайт собирается из web/ на ветке main с помощью .github/workflows/pages.yml. Исходный код документации и симулированная демонстрация браузера находятся в этой директории.

Текущие возможности:

• Публичные образы из любого реестра, совместимого с OCI (Docker Hub, GHCR, Quay, GCR, MCR, Amazon ECR Public, собственные)
• Сканирование только для чтения
• Без проверки секретов
• Не требует зависимости от Docker daemon
• Сканирование с учётом манифеста и слоёв
• Сканирует финальную файловую систему и артефакты удалённых слоёв
• Сканирует метаданные конфигурации образа, переменные окружения, метки и историю
• Дедублицирует результаты по отпечатку секрета и сворачивает повторяющиеся идентичные фрагменты контекста для каждого манифеста
• Встроенные детекторы для 60+ типов секретов, плюс стандартные детекторы TruffleHog в качестве резервного слоя
• Подавляет результаты из путей test/fixture/spec/e2e/acceptance для снижения ложных срабатываний в образах для разработки

Установка

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

• Go 1.25.7+

Установка с помощью Go:

Каноническая цель установки — корень модуля. Чтобы явно зафиксировать релиз:

Замените v1.0.0 на опубликованный тег v1.x.y, который вам нужен. Убедитесь, что ваш GOBIN или GOPATH/bin находится в PATH.

Путь модуля — github.com/brumbelow/layerleak, поэтому go install @latest разрешается в самый высокий опубликованный тег v1.x.y. Релиз модуля v2.x.y потребовал бы изменения пути модуля на github.com/brumbelow/layerleak/v2. Установленные из модуля бинарники сообщают разрешённую версию модуля через layerleak --version; сборки из локальной копии сообщают версию, встроенную Go для этой копии, с понижением до dev, если версия модуля недоступна.

Сборка из исходного кода:

Запуск API с помощью контейнерного образа:

Контейнерный образ по умолчанию запускает API и устанавливает LAYERLEAK_API_ADDR=0.0.0.0:8080.

Необязательная конфигурация окружения:

Конфигурация результатов и базы данных:

Те же переменные и их значения по умолчанию находятся в .env.example, который является источником истины для значений по умолчанию.

Когда любой из лимитов MAX_* установлен в положительное значение, его превышение приводит к сбою сканирования с явной ошибкой, а не к молчаливому усечению работы.

Поведение результатов:

• Действенные результаты остаются в findings и формируют ненулевой статус выхода сканирования.
• Вероятные тестовые/примеры/демо-заполнители выводятся отдельно как подавленные примеры результатов и не учитываются в total_findings.
• Записи результатов включают disposition, disposition_reason и line_number для упрощения триажа и проверки ложных срабатываний.
• Если установленный операционный лимит превышен, layerleak всё равно записывает и отображает частичные результаты, полученные до сбоя, а затем завершается с кодом 1, так как сканирование неполное.

Постоянное хранение в Postgres

Layerleak поставляется с версионированными SQL-миграциями в migrations/. Миграции намеренно ручные. Сканер не создаёт и не обновляет схему автоматически. Layerleak требует PostgreSQL сервер >= 16.13 для работы API и сканера с поддержкой БД.

Примените миграции с помощью psql по порядку:

Или примените миграции с помощью команды-помощника в контейнере:

layerleak-migrate-up безопасно повторять, если миграции уже применены. Если он обнаруживает частичное состояние миграции, он завершается с ненулевым кодом и просит ручного вмешательства. Помощник также проверяет версию сервера >= 16.13 и проверяет, что встроенный postgresql-client-16 использует пакет Ubuntu PGDG 24.04 (.pgdg24.04+) версии >= 16.13-1.pgdg24.04+1.

Откат миграций в обратном порядке:

Операционные значения по умолчанию:

• Ожидается, что миграции будут аддитивными.
• Схема хранит текущее дедублицированное состояние с first_seen_at и last_seen_at, а также хранит историю сканирования в режиме "только добавление" в scan_runs.
• Сопоставления тегов обновляются для тегов, затронутых текущим сканированием.
• Результаты канонически дедублицируются по (manifest_digest, fingerprint), и повторяющиеся идентичные фрагменты контекста сворачиваются перед сохранением.
• История сканирования хранит скрытый снимок публичного JSON-результата, а не сырые значения или сырые фрагменты.

Примечание по безопасности секретов:

• По умолчанию Postgres хранит скрытые превью.
• Если LAYERLEAK_PERSIST_RAW_SECRETS=1, Postgres также хранит сырые значения результатов и сырые фрагменты.
• Снимок scan_runs.result_json остаётся скрытым.
• Используйте выделенную базу данных или схему для layerleak.
• Для самого безопасного пути удаления удалите выделенную базу данных или схему вместо попытки хирургического удаления отдельных строк.

Как начать

Показать справку CLI:

Запустить сканирование публичного OCI-образа в любом поддерживаемом реестре:

Каждое сканирование записывает JSON-файл с результатами в выходную директорию findings. Если LAYERLEAK_FINDINGS_DIR не установлена, выходная директория по умолчанию — findings/ в ближайшей родительской директории, содержащей go.mod (обычно корень репозитория), с понижением до текущей рабочей директории, если корень репозитория не найден.

Сохранённые файлы результатов содержат записи с redacted_value, скрытый context_snippet, точное местоположение источника, метаданные disposition и номер строки для каждого результата. Если LAYERLEAK_PERSIST_RAW_SECRETS=1, сохранённые файлы результатов также включают сырое value и raw_context_snippet. Если включено постоянное хранение в Postgres, сырые findings.value и finding_occurrences.raw_snippet остаются пустыми, если не установлен LAYERLEAK_PERSIST_RAW_SECRETS=1. Для multi-arch образов layerleak пропускает манифесты аттестации и происхождения, такие как application/vnd.in-toto+json, вместо того чтобы считать их неудачными сканированиями платформы.

Зачистки репозитория (sweeps):

• Передача имени репозитория без тега, например mongo, перечисляет все публичные теги в этом репозитории, разрешает каждый тег в дайджест, группирует дубликаты дайджестов и сканирует различные цели.
• layerleak выводит предупреждение в stderr перед началом зачистки, чтобы область действия была очевидна в логах CI и выводе автоматизации.
• Если вам нужен только один образ, передайте явный тег или дайджест, например mongo:latest или mongo@sha256:....

Синтаксис команд:

Флаги области для зачисток репозитория (каждый переопределяет соответствующую переменную окружения для одной команды):

HTTP API

Layerleak также включает минимальный JSON API в cmd/api. API использует Postgres и требует LAYERLEAK_DATABASE_URL; он не обслуживает данные из файлов результатов на диске.

Запустите его с помощью:

Или запустите контейнер API:

Текущие конечные точки:

• GET /health
• POST /api/v1/scans
• GET /api/v1/scans/{id}
• GET /api/v1/repositories
• GET /api/v1/repositories/{repository}/scans
• GET /api/v1/repositories/{repository}/findings
• GET /api/v1/findings/{id}

GET /health возвращает {"status":"ok"} и не требует настроенного хранилища или сканера. Он подходит для зондов готовности Kubernetes и целей healthcheck Docker Compose.

POST /api/v1/scans остаётся синхронным. Он принимает JSON-тело с reference и опциональным platform, и возвращает scan_run_id, если включено постоянное хранение в Postgres. Ответы API на сканирования используют ту же скрытую схему результата, что и вывод JSON CLI. GET /api/v1/scans/{id} возвращает сохранённые метаданные запуска плюс сохранённый скрытый снимок результата. Конечные точки репозитория и результатов также остаются скрытыми: они возвращают redacted_value и скрытый context_snippet, никогда не сырые значения секретов или сырые фрагменты из Postgres.

GET /api/v1/repositories/{repository}/scans и GET /api/v1/repositories/{repository}/findings принимают опциональный параметр запроса registry (например, ?registry=ghcr.io). Если он опущен, по умолчанию используется docker.io для обратной совместимости. Используйте его для получения сканирований репозиториев на GHCR, Quay, GCR, MCR, Amazon ECR Public или любом собственном реестре.

Конечные точки списков (/repositories, /repositories/{repository}/scans, /repositories/{repository}/findings) принимают ?limit= и ?offset= для пагинации. limit по умолчанию равен 50 и ограничен 200. /repositories/{repository}/findings также принимает ?disposition=actionable|suppressed|all; если параметр опущен, ответ включает только действенные результаты.

API не включает аутентификацию. Для организационных развёртываний держите его в частной сети и разместите перед ним собственный шлюз authn/authz или политику реверс-прокси.

Развёртывание через Docker Compose (Dockge / Komodo)

Этот репозиторий включает стек Compose в docker-compose.yml с сервисами db, migrate и api. Сервис db по умолчанию использует postgres:16.13-alpine. Если вы используете другой образ Postgres, поддерживайте версию сервера на уровне 16.13 или новее.

Установите переменные развёртывания (экспортируйте в оболочке или поместите в файл .env рядом с docker-compose.yml):

Проверьте отрендеренную конфигурацию Compose перед развёртыванием:

Запустите миграции один раз перед запуском API:

Запустите сервис API:

В Dockge или Komodo импортируйте тот же файл Compose и запустите сервис migrate один раз перед включением долго работающего сервиса api.

Лицензия

Выпущено под лицензией MIT — см. LICENSE.

Поддержать проект