diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index f12dad2..86cbb8c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ name: Баг-репорт -description: Сообщить о проблеме в утилите, CI или документации +description: Сообщить о проблеме в инструменте, CI или документации title: "[Bug]: " labels: ["bug"] body: @@ -13,6 +13,8 @@ body: label: Где проблема options: - Container image optimizer (cio) + - SQL backup, restore and clone (sqlbrc) + - Новый инструмент или общая инфраструктура - CI / workflows - Документация validations: @@ -21,8 +23,8 @@ body: id: versions attributes: label: Версии - description: Коммит или тег, а также версии Go, Docker и Trivy - placeholder: "main @ a1b2c3d, Go 1.25.14, Docker 29.8.0, Trivy 0.74.0" + description: Коммит или тег, версия инструмента (`cio --version`, `sqlbrc --version`) и окружение + placeholder: "main @ a1b2c3d, cio 0.2.0, Go 1.25.14, Docker 29.8.0, Trivy 0.74.0" validations: required: true - type: textarea @@ -33,6 +35,11 @@ body: 1. go build -o bin/cio.exe ./cmd/cio 2. ./bin/cio.exe analyze postgres:15-alpine 3. ... + + Для sqlbrc: + 1. go build -o bin/sqlbrc.exe ./cmd/sqlbrc + 2. ./bin/sqlbrc.exe doctor --config deploy/config.example.yaml + 3. ... validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 5c1cfa2..a4c1a7a 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,7 +2,13 @@ blank_issues_enabled: false contact_links: - name: Правила разработки url: https://github.com/DevOps-spb-ru/DevOps-Engineer-Tools/blob/main/CONTRIBUTING.md - about: Как запускать проверки, оформлять коммиты и pull request + about: Как запускать проверки, оформлять коммиты и pull request, как добавить новый инструмент + - name: Политика безопасности + url: https://github.com/DevOps-spb-ru/DevOps-Engineer-Tools/blob/main/SECURITY.md + about: Поддерживаемые версии всех инструментов и порядок сообщения об уязвимостях - name: Документация Container image optimizer url: https://github.com/DevOps-spb-ru/DevOps-Engineer-Tools/tree/main/Container%20image%20optimizer about: Флаги CLI, правила анализа и ограничения утилиты cio + - name: Документация SQL backup, restore and clone + url: https://github.com/DevOps-spb-ru/DevOps-Engineer-Tools/tree/main/SQL%20backup%20restore%20clone + about: Команды, конфигурация, поставка и веб-интерфейс сервиса sqlbrc diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 06eddfb..e08ae74 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -9,7 +9,9 @@ body: label: Что улучшаем options: - Container image optimizer (cio) - - Новое правило анализа образа + - SQL backup, restore and clone (sqlbrc) + - Новый инструмент или общая инфраструктура + - Новое правило анализа образа (cio) - CI / workflows - Документация validations: diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fd1aa30..5f0378d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,8 @@ ## Что сделано - + ## Тип изменения @@ -14,14 +15,16 @@ ## Как проверено - + - [ ] `gofmt -l cmd internal` — пусто - [ ] `go vet ./...` - [ ] `go test ./... -count=1` - [ ] `golangci-lint run ./...` (или `.work/lint-docker.ps1`) -- [ ] Проверка на живом Docker (`.work/smoke-cio.ps1`) +- [ ] Проверка на живом окружении: `cio` — `.work/smoke-cio.ps1`; `sqlbrc` — `.work/smoke-container.ps1` или `.work/smoke-serve.ps1` - [ ] Обновлены `README.md` и `CHANGELOG.md` затронутого инструмента +- [ ] Если затронуты CI, зависимости или документы репозитория — обновлены матрицы workflow, `SECURITY.md`, `README.md` - [ ] При релизе: секция `CHANGELOG.md` совпадает с тегом `<инструмент>-vX.Y.Z` ## Влияние и риски diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b4614a..e2815ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,9 @@ # CHANGELOG Общего журнала в корне нет: у инструментов независимые версии и теги (`<инструмент>-vX.Y.Z`), -поэтому история изменений ведётся в каталоге каждого инструмента. +поэтому история изменений ведётся в каталоге каждого инструмента. Этот файл — указатель: строка +в таблице появляется, когда в репозитории добавляется новый инструмент (чеклист — в +[CONTRIBUTING.md](CONTRIBUTING.md)). | Инструмент | История изменений | | --- | --- | @@ -10,4 +12,5 @@ Формат разделов — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/), нумерация версий — [SemVer](https://semver.org/lang/ru/); правила версионирования и порядок релиза — в -[CONTRIBUTING.md](CONTRIBUTING.md), состав инструментов — в [README.md](README.md). +[CONTRIBUTING.md](CONTRIBUTING.md), состав инструментов — в [README.md](README.md), политика +безопасности для всех инструментов — в [SECURITY.md](SECURITY.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8117291..b2f8045 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,10 +22,11 @@ ## Локальная проверка перед пушем -Всё сразу (рекомендуется): +Всё сразу (рекомендуется) — скрипт затронутого инструмента: ```powershell -powershell -ExecutionPolicy Bypass -File .work/build-and-test.ps1 +powershell -ExecutionPolicy Bypass -File .work/build-and-test.ps1 # cio +powershell -ExecutionPolicy Bypass -File .work/build-and-test-sqlbrc.ps1 # sqlbrc ``` По шагам (в каталоге нужного инструмента: `cd "Container image optimizer"` или @@ -58,6 +59,9 @@ go build -trimpath -o bin/sqlbrc.exe ./cmd/sqlbrc # для sqlbrc (.exe — т отчёт по проверкам готовности сервера; код возврата 1 означает «есть ошибки», в том числе «на этой ОС проверить не удалось» (например, на Windows). +Полная проверка поставки `sqlbrc` в контейнере (нужны Docker и compose): `.work/smoke-container.ps1` — +образ собирается, запускается от непривилегированного пользователя и работает по `postgres.mode: tcp`. + ## Definition of Done 1. `gofmt` без замечаний, `go vet ./...` и `go test ./...` проходят. @@ -106,14 +110,15 @@ go build -trimpath -o bin/sqlbrc.exe ./cmd/sqlbrc # для sqlbrc (.exe — т | удаление или переименование флага, изменение формата JSON | в `0.x` — minor, начиная с `1.0.0` — major | Версия попадает в бинарь на этапе сборки (`-ldflags "-X main.version=..."`, см. `Makefile`), -поэтому `--version` печатает версию, коммит и дату сборки (у `sqlbrc` — тем же способом, цель -`version` в его `Makefile`), а образ `cio` получает те же значения -в метках `org.opencontainers.image.*`. +поэтому `--version` печатает версию, коммит и дату сборки — у обоих инструментов (цель `version` +в `Makefile`). Образ получает те же значения build-аргументами `--build-arg VERSION`, `REVISION` +и `DATE` (их передаёт `release-image.yml`), а `cio` — ещё и в метках `org.opencontainers.image.*`. +Значения в образе видны в `--version` внутри контейнера: без `DATE` там было бы «сборка unknown». ### Чеклист релиза 1. Убедиться, что CI на `main` зелёный: `Линт`, `Уязвимости зависимостей`, `Тесты` и `Сборка` - для нужного инструмента (для `cio` — ещё и `Docker-образ`). + для нужного инструмента, а если у него есть контейнерная поставка — ещё и `Docker-образ`. 2. В `CHANGELOG.md` инструмента (`Container image optimizer/CHANGELOG.md` или `SQL backup restore clone/CHANGELOG.md`) переименовать `## [Unreleased]` в `## [X.Y.Z] - ГГГГ-ММ-ДД` (например, `## [0.1.0] - 2026-10-01`), сразу добавить новый пустой `## [Unreleased]` @@ -153,7 +158,8 @@ go build -trimpath -o bin/sqlbrc.exe ./cmd/sqlbrc # для sqlbrc (.exe — т ```bash echo "$TOKEN" | docker login ghcr.io -u --password-stdin -docker build --build-arg VERSION=0.1.0 --build-arg REVISION="$(git rev-parse HEAD)" \ +docker build --build-arg VERSION=0.1.0 --build-arg REVISION="$(git rev-parse --short HEAD)" \ + --build-arg DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ -t ghcr.io/devops-spb-ru/cio:0.1.0 "Container image optimizer" docker push ghcr.io/devops-spb-ru/cio:0.1.0 ``` @@ -163,26 +169,37 @@ docker push ghcr.io/devops-spb-ru/cio:0.1.0 с репозиторием, после первого пуша зайдите в `Packages` → `Package settings` и выполните `Connect repository`. -Образ пока публикует только `cio`: поставка `sqlbrc` в контейнере запланирована на 0.2.0. +Образ публикуется у каждого инструмента, для которого есть поставка в контейнере: сейчас это +`ghcr.io/devops-spb-ru/cio` и `ghcr.io/devops-spb-ru/sqlbrc` (контейнерная поставка `sqlbrc` +появилась в 0.3.0). Инструмент без `Dockerfile` в релизном workflow образ не публикует. ## Как добавить новый инструмент 1. Создайте каталог с понятным именем и `README.md` внутри; образцы структуры — [`Container image optimizer`](Container%20image%20optimizer/README.md) и [`SQL backup restore clone`](SQL%20backup%20restore%20clone/README.md). -2. Добавьте сборочные файлы и тесты; сборочная команда и тесты должны быть воспроизводимы локально. -3. Заведите job в `.github/workflows/ci.yml` (линт/уязвимости/тесты/сборка) с `working-directory` - на новый каталог; отдельные job'ы — под образ, сканирование (`trivy-scan.yml`) и статический - анализ (`codeql.yml`, сейчас там собирается только `cio`). -4. Обновите таблицу инструментов в корневом `README.md`, заведите `CHANGELOG.md` в каталоге - инструмента (раздел `## [Unreleased]`) и строку про него в корневом `CHANGELOG.md`. +2. Добавьте сборочные файлы (`go.mod`, `Makefile`, при контейнерной поставке — `Dockerfile`) + и тесты; сборочная команда и тесты должны быть воспроизводимы локально. +3. Добавьте каталог в матрицы workflow: `ci.yml` (линт, зависимости, тесты, сборка; образ — + если он есть), `trivy-scan.yml` (образ и файловая система) и `codeql.yml` (анализ Go). + Путь к инструменту задаётся в `working-directory`, `context` и `go-version-file`. +4. Заведите релизные job'ы в `release.yml` по образцу существующих: тег `<инструмент>-vX.Y.Z`, + вызов `release-binaries.yml` (а для контейнерной поставки — ещё и `release-image.yml`) + с параметрами `tool`, `dir` и `tag_prefix`. +5. Обновите публичные документы: таблицу инструментов и требования в корневом `README.md`, + строку в корневом `CHANGELOG.md`, строку в `SECURITY.md` (поддерживаемые версии, область, + «вне области»), ссылку на README инструмента в `.github/ISSUE_TEMPLATE/config.yml` и варианты + инструмента в формах issue. +6. Заведите `CHANGELOG.md` в каталоге инструмента (раздел `## [Unreleased]`), добавьте модуль + Go, а при контейнерной поставке — и образы из `Dockerfile` в `.github/dependabot.yml`. ## Безопасность -- Порядок сообщения об уязвимостях и поддерживаемые версии — в [SECURITY.md](SECURITY.md); - приватный отчёт открывается во вкладке *Security* → *Report a vulnerability*. +- Порядок сообщения об уязвимостях, поддерживаемые версии и область ответственности описаны + сразу для всех инструментов — в [SECURITY.md](SECURITY.md); приватный отчёт открывается + во вкладке *Security* → *Report a vulnerability*. - Секреты, токены и пароли не коммитятся: ни в код, ни в конфиги, ни в документацию. - Сторонние экшены в workflows фиксируются по SHA; обновления предлагает Dependabot. - В отчётах утилиты секреты маскируются; если нашли обратное — это баг, заводите issue. -- Образ `cio` запускается без прав root, доступ к `docker.sock` выдаётся группой сокета - (`--group-add`, см. README инструмента). +- Образы запускаются без прав root (`cio`, `sqlbrc`). Доступ к `docker.sock` нужен только `cio`: + он выдаётся группой сокета (`--group-add`, см. README инструмента). diff --git a/README.md b/README.md index cefd016..7d69ce0 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,9 @@ make lint - Сообщения коммитов: `Add:` / `Update:` / `Fix:` + короткая суть изменения. - Definition of Done: `go vet ./...`, `go test ./...`, линт без замечаний, обновлённый `README`. -- Процессы (ветвление, PR, релизы) — в [CONTRIBUTING.md](CONTRIBUTING.md). +- Процессы (ветвление, PR, релизы, чеклист нового инструмента) — в [CONTRIBUTING.md](CONTRIBUTING.md). +- Политика безопасности общая для всех инструментов (поддерживаемые версии, область + ответственности, выпуск исправлений) — в [SECURITY.md](SECURITY.md). - Локальные правила для AI-ассистента лежат в `.clinerules/` — каталог намеренно исключён из Git (см. `.gitignore`), поэтому в репозитории его нет. @@ -71,6 +73,10 @@ GitHub Actions (`.github/workflows`): | `trivy-scan.yml` | уязвимости, секреты и конфигурацию образов обоих инструментов (`cio`, `sqlbrc`) и их файловой системы; находки CRITICAL/HIGH роняют прогон, отчёты уходят в GitHub Security | | `codeql.yml` | статический анализ Go-кода обоих модулей (`cio`, `sqlbrc`), отчёты — в GitHub Security | +Матрицы workflow перечисляют каталоги инструментов (`cio`, `sqlbrc`): новый инструмент попадает +в них по чеклисту из [CONTRIBUTING.md](CONTRIBUTING.md), поэтому набор проверок у всех +инструментов одинаковый. + В `.trivyignore` лежат исключения на уязвимости **встроенного в образ сканера** Trivy: каждое с указанием срока годности (`exp`), после которого «ворота» снова падают и список нужно перепроверить. Код `cio` и базовый образ проверяются без исключений. diff --git a/SECURITY.md b/SECURITY.md index f3dc8b1..94a58b0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,16 +1,26 @@ # Политика безопасности -Репозиторий содержит утилиту `cio` (Container image optimizer), её релизные бинари и образ -`ghcr.io/devops-spb-ru/cio`, а также workflows GitHub Actions. Ниже — как сообщить -об уязвимости и что считается предметом отчёта. +Репозиторий содержит набор утилит для DevOps-инженеров: инструмент живёт в своём каталоге, +имеет независимую версию (`<инструмент>-vX.Y.Z`) и, если для него есть поставка в контейнере, +свой образ в GitHub Packages. Сейчас это `cio` (Container image optimizer) и `sqlbrc` +(SQL backup, restore and clone); состав и версии — в [README.md](README.md). Политика ниже +распространяется на все инструменты репозитория, включая те, что появятся позже. Ниже — как +сообщить об уязвимости и что считается предметом отчёта. ## Поддерживаемые версии -| Версия | Поддержка | -| --- | --- | -| 0.2.x | исправления безопасности и обычные исправления | -| 0.1.x | только исправления уязвимостей | -| < 0.1 | не поддерживается | +| Инструмент | Версия | Поддержка | +| --- | --- | --- | +| `cio` | 0.2.x | исправления безопасности и обычные исправления | +| `cio` | 0.1.x | только исправления уязвимостей | +| `cio` | < 0.1 | не поддерживается | +| `sqlbrc` | 0.3.x | исправления безопасности и обычные исправления | +| `sqlbrc` | 0.2.x | только исправления уязвимостей | +| `sqlbrc` | < 0.2 | не поддерживается | + +Версии у инструментов независимые: поддерживаемая версия — это строка инструмента, а не номер, +общий для репозитория. Строка нового инструмента появляется в таблице вместе с его первым +релизом, а сведения о текущих версиях — в `README.md`. ## Как сообщить об уязвимости @@ -18,9 +28,13 @@ (). Так отчёт виден только мейнтейнерам. - Не создавайте публичный issue и не публикуйте эксплойт до выхода исправления. -- Приложите: версию (`cio --version`), способ запуска (бинарь или образ, флаги, - `docker`/`trivy` версии), команду воспроизведения и ожидаемое поведение. -- Секреты, пароли и содержимое чужих образов в отчёт не включайте: достаточно описания. +- Приложите: инструмент и версию (`cio --version` или `sqlbrc --version`), способ запуска + (бинарь из релиза, локальная сборка, контейнер, служба systemd), команду воспроизведения + и ожидаемое поведение. +- Что помогает для конкретного инструмента: для `cio` — версии Docker и Trivy либо команду + запуска контейнера; для `sqlbrc` — версию PostgreSQL, значение `postgres.mode` и вырезанный + до несекретных полей конфиг. +- Секреты, пароли, содержимое чужих образов и дампов баз в отчёт не включайте: достаточно описания. ## Что ожидать @@ -31,34 +45,58 @@ | Исправление или обходной путь | зависит от серьёзности: критичные уязвимости — внеочередным патчем | | Публичное раскрытие | после выпуска исправления; по запросу указываем автора отчёта | +Исправление выпускается для поддерживаемых версий затронутого инструмента (см. таблицу выше) +и публикуется отдельным релизом с тегом `<инструмент>-vX.Y.Z`: версии у инструментов +независимые, поэтому исправление в `sqlbrc` не требует релиза `cio` (и наоборот). + ## Область (что считается уязвимостью проекта) - `cio`: разбор аргументов, чтение образов через Docker Engine API, правила анализа, форматы отчётов (`table`, `json`), выход за пределы допустимых путей, коды возврата `--fail-on`. -- Утечка чувствительных данных: секреты из истории сборки образа, пароли и токены в отчёте, - запись отчёта с недостаточно строгими правами доступа. -- Релизные артефакты: бинари из GitHub Release, `SHA256SUMS`, образ - `ghcr.io/devops-spb-ru/cio` (включая метки и состав). +- `sqlbrc`: обход проверок «своя ли база» (`databases.pattern`, `pg.ValidateDBName`) и + `server.read_only`; сборка аргументов для `pg_dump`, `pg_restore`, `psql` и `pg_isready`; + очистка базы при восстановлении (`--clean --if-exists`); каталог бэкапов и политика хранения + (`storage.dir`, `store.Plan`); веб-интерфейс и API: аутентификация (bcrypt-хэши, сессии + в памяти, предел неудачных попыток входа), защита от подделки запросов, cookie сессии, + токены из `auth.token_file`, отказ выдавать API по cookie-сессии. +- Общее для инструментов: утечка чувствительных данных (секреты из истории сборки образа, + пароли и токены в отчёте, файлы, записанные с недостаточно строгими правами) и выход + за пределы каталогов, которые инструменту разрешены. +- Релизные артефакты любого инструмента: бинари из GitHub Release, `SHA256SUMS`, SBOM, + attestation сборки, образы `ghcr.io/devops-spb-ru/<инструмент>` (включая метки и состав). - Workflows репозитория: инъекция в `run`-блоки, не пиннутые экшены, избыточные права `GITHUB_TOKEN`, отравление кэша. ## Вне области -- Уязвимости в сторонних компонентах: Trivy, Docker Engine, дистрибутивные пакеты базовых - образов, сами сканируемые образы. Сообщайте в upstream; мы обновляем версии по своим - каналам (Dependabot, `.github/dependabot.yml`). -- Требование доступа к `docker.sock`: контейнер запускается с правами root, потому что сокет - демона принадлежит `root:root` с правами `0660`; это осознанный компромисс, описанный в - `Container image optimizer/README.md`. -- Находки в отчёте по чужому образу (уязвимости, секреты, ошибки сборки): это результат - анализа, а не уязвимость `cio`. +- Уязвимости в сторонних компонентах: Trivy, Docker Engine, PostgreSQL и утилиты `pg_*`, + дистрибутивные пакеты базовых образов, сами сканируемые образы и обслуживаемые базы. + Сообщайте в upstream; мы обновляем версии по своим каналам (Dependabot, + `.github/dependabot.yml`). +- Доступ к `docker.sock` у `cio`: образ работает под непривилегированным пользователем, + а доступ к сокету демона (root:root, 0660) выдаётся группой сокета (`--group-add`). Это + осознанный компромисс, описанный в `Container image optimizer/README.md`. +- Требование прав `pg_dump` и `pg_restore` у `sqlbrc`: сервис запускает только перечисленные + в sudoers утилиты от имени владельца кластера (`postgres.sudo_user`). Более широкие права + `sudo` на сервере — вопрос конфигурации сервера, а не уязвимость сервиса. +- Находки в отчёте по чужому образу или чужой базе (уязвимости, секреты, ошибки сборки): + это результат анализа, а не уязвимость инструмента. +- Развёртывание: доступность интерфейса в доверенной подсети, содержимое конфигов установки + и пароли стендов — настройки конкретной инсталляции, а не код репозитория. ## Как защищён проект -- Зависимости обновляются Dependabot (gomod, GitHub Actions, Docker), сторонние экшены - закреплены по SHA. -- Статический анализ: `golangci-lint` с набором `gosec`, CodeQL, `govulncheck`. -- Сканирование: Trivy (файловая система, Dockerfile, образ) в CI, отчёты — в GitHub Security. +- Зависимости обновляются Dependabot: модули Go каждого инструмента (`gomod` в его каталоге), + GitHub Actions, образы из `Dockerfile`. Сторонние экшены закреплены по SHA. +- Статический анализ по каждому модулю: `golangci-lint` с набором `gosec`, CodeQL и + `govulncheck` (достижимые уязвимости зависимостей). +- Сканирование: Trivy (файловая система, Dockerfile, образ каждого инструмента) в CI; находки + CRITICAL/HIGH роняют прогон, отчёты — в GitHub Security. - Секреты: проверка всей истории репозитория `gitleaks`; правило `secret-in-layer` ищет - секреты в истории сборки. В тестовых данных — только фиктивные значения. -- Релиз: SBOM и attestations рядом с бинарями и образом, публикуется только по тегу `cio-vX.Y.Z`. + секреты в истории сборки образа. В тестовых данных — только фиктивные значения. +- Релиз: SBOM и attestation сборки рядом с бинарями и образом, подпись образа cosign + в keyless-режиме; публикация — только по тегу `<инструмент>-vX.Y.Z`. +- Новый инструмент добавляется по чеклисту [CONTRIBUTING.md](CONTRIBUTING.md) («Как добавить + новый инструмент»): он получает собственные job'ы линта, проверки зависимостей, тестов + и сборки, строку в этой политике и запись в таблице инструментов `README.md`. Поэтому охват + политики не сужается с ростом числа инструментов.