Владельцы кода
и безопасность

§1CODEOWNERS: кто отвечает за контракт

Файл .github/CODEOWNERS сопоставляет пути в репозитории с людьми или группами. Тот, кто указан владельцем, автоматически получает запрос на просмотр изменения, если правки затронули его файлы.

# В учебном репозитории владелец один. В команде вместо имени пишут группу
# ревьюеров API, например @org/api-reviewers.

*                        @MaximBytecamp

# Публичный контракт и правила его проверки
/openapi/                @MaximBytecamp
/.spectral.yaml          @MaximBytecamp
/docs/API_STYLE_GUIDE.md @MaximBytecamp
/docs/VERSIONING.md      @MaximBytecamp
/docs/adr/               @MaximBytecamp

В связке с защитой ветки из главы 6.4 это даёт нужное свойство: изменение файла описания нельзя объединить без одобрения владельца контракта — это запрет на уровне настроек, а не договорённость.

§2Как читается файл

§3Что назначают владельцу API

В перечень путей включены файлы, изменение которых меняет обещания клиентам или правила их проверки.

Обратите внимание на вторую строку. Файл с правилами линтера охраняется наравне с описанием: смягчив правило, можно провести изменение, которое до этого не проходило.

§4SECURITY.md: как сообщить об уязвимости

Второй файл отвечает на вопрос внешнего исследователя: куда сообщать о найденной уязвимости.

## Поддерживаемые версии

| Версия | Поддерживается |
|---|---|
| 1.1.x | да |
| 1.0.x | нет, обновитесь до 1.1 |

## Сообщить об уязвимости

Не публикуйте уязвимость в issue. Используйте приватное сообщение об уязвимости
на GitHub или напишите API Team: api-team@example.edu.

Укажите, насколько сможете:
- операцию и версию API;
- шаги воспроизведения;
- X-Request-Id из ответа;
- чем уязвимость опасна.

Мы ответим в течение трёх рабочих дней.

§5Почему не через обычный issue

Issue публичен с первой секунды. Сообщение об уязвимости в нём становится доступным всем, в том числе до выпуска исправления.

Чтобы путь не выбирался наугад, в проекте настроен файл .github/ISSUE_TEMPLATE/config.yml: он убирает возможность создать issue без формы и добавляет в список ссылку на приватное сообщение об уязвимости. Нашедший уязвимость видит нужный вариант сразу, до создания issue.

§6Что не должно утекать через API

Часть требований безопасности относится не к репозиторию, а к самим ответам сервиса. Ниже собрано то, что разбиралось в предыдущих модулях.

Все шесть пунктов проверяются тестами или настройкой, и все шесть входят в контракт, а не выносятся в отдельную работу по безопасности.

§7Dependabot: обновление зависимостей

Третий файл — .github/dependabot.yml. Он еженедельно проверяет версии библиотек и действий сборки и сам открывает изменения с обновлениями.

version: 2
updates:
  - package-ecosystem: pip
    directory: "/"
    schedule:
      interval: weekly

  - package-ecosystem: github-actions
    directory: "/"
    schedule:
      interval: weekly
    groups:
      actions:
        patterns: ["*"]

Это связано с требованием из главы 6.4: версии всех инструментов закреплены, чтобы сборка не ломалась сама по себе. Закреплённая версия со временем устаревает, в том числе по части безопасности. Dependabot снимает это противоречие: версии остаются закреплёнными, а их обновление приходит отдельным изменением, которое проходит все проверки контракта.

Настройка groups для действий собирает их обновления в одно изменение вместо пяти — иначе мелкие правки приходят по нескольку в неделю и их перестают разбирать.

§8Как делают другие

Сравнив три файла в учебном проекте с их же вариантами у Kubernetes, Azure и OpenAPI Initiative, можно заметить: чем крупнее проект, тем подробнее файлы, но состав разделов у них одинаковый. Поэтому их и берут за образец.