Allstar

[!IMPORTANT] Размещаемое OpenSSF приложение Allstar GitHub App было выведено из эксплуатации. Сам Allstar, подпроект OpenSSF Scorecard, продолжает поддерживаться — теперь вы должны запускать его самостоятельно, либо как GitHub Action, либо как фоновый сервис.

Подробнее см. ossf/allstar#881.

Если ваша организация полагалась на размещаемое приложение, см. Миграция с размещаемого приложения.

Обзор

• Что такое Allstar?

Что нового в Allstar

• whats-new.md

Отключение нежелательных проблем

• Помогите! Allstar создаёт проблемы, которые мне не нужны!

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

• Предыстория
• Параметры уровня организации
• Варианты установки
  • Создайте свой GitHub App
  • Создайте свой контрольный репозиторий .allstar
  • Запуск Allstar как GitHub Action
  • Запуск Allstar как фонового сервиса
• Миграция с размещаемого приложения

Политики и действия

• Действия
• Политики

Дополнительно

• Определения конфигурации
• Примеры конфигураций
• Запуск собственного экземпляра Allstar

Участие

• Внесение вклада

Обзор

Что такое Allstar?

Allstar — это GitHub App, который непрерывно отслеживает организации или репозитории GitHub на предмет соблюдения лучших практик безопасности. Если Allstar обнаруживает нарушение политики безопасности, он создаёт проблему, чтобы уведомить владельца репозитория или организации. Для некоторых политик безопасности Allstar также может автоматически изменять настройку проекта, которая вызвала нарушение, возвращая её в ожидаемое состояние.

Цель Allstar — дать вам тонко настроенный контроль над файлами и настройками, которые влияют на безопасность ваших проектов. Вы можете выбирать, какие политики безопасности отслеживать как на уровне организации, так и на уровне репозитория, и как обрабатывать нарушения политик. Вы также можете разрабатывать или вносить вклад в новые политики.

Allstar разрабатывается как часть проекта OpenSSF Scorecard.

Что нового в Allstar

Отключение нежелательных проблем

Если Allstar создаёт проблемы, которые вам не нужны, следуйте этим инструкциям, чтобы отказаться от участия.

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

Предыстория

Allstar очень гибок в настройке. Существует три основных уровня управления:

• Уровень организации: Администраторы организации могут выбрать, включить ли Allstar:
  • для всех репозиториев в организации;
  • для большинства репозиториев, кроме некоторых, которые отказались от участия;
  • только для нескольких репозиториев, которые согласились на участие.

Эти конфигурации выполняются в репозитории .allstar организации.

• Уровень репозитория: Сопровождающие репозитория в организации, использующей Allstar, могут выбрать, согласиться ли на применение политик уровня организации в своём репозитории или отказаться от них. Примечание: эти элементы управления уровня репозитория работают только тогда, когда "переопределение репозитория" разрешено в настройках уровня организации. Эти конфигурации выполняются в каталоге .allstar репозитория.

• Уровень политики: Администраторы или сопровождающие могут выбирать, какие политики включены для конкретных репозиториев и какие действия Allstar предпринимает при нарушении политики. Эти конфигурации выполняются в yaml-файле политики либо в репозитории .allstar организации (администраторы), либо в каталоге .allstar репозитория (сопровождающие).

Параметры уровня организации

Перед установкой Allstar на уровне организации вам следует примерно решить, на скольких репозиториях вы хотите, чтобы Allstar работал. Это поможет вам выбрать между стратегиями Opt-In и Opt-Out.

• Стратегия Opt In позволяет вам вручную добавлять репозитории, на которых вы хотите, чтобы Allstar работал. Если вы не укажете ни одного репозитория, Allstar не будет работать, несмотря на установку. Выбирайте стратегию Opt In, если хотите применять политики только к небольшому числу ваших общих репозиториев или хотите опробовать Allstar на одном репозитории, прежде чем включать его на большем количестве. Начиная с версии v4.3, поддерживаются glob-шаблоны для простого добавления нескольких репозиториев со схожими именами.

• Стратегия Opt Out (рекомендуется) включает Allstar для всех репозиториев и позволяет вам вручную выбирать репозитории для отказа от применения политик Allstar. Вы также можете отказаться от всех публичных репозиториев или всех приватных репозиториев. Выбирайте этот вариант, если хотите запустить Allstar на всех репозиториях в организации или хотите отказаться только от небольшого числа репозиториев или от репозиториев определённого типа (например, публичных или приватных). Начиная с версии v4.3, поддерживаются glob-шаблоны для простого добавления нескольких репозиториев со схожими именами.

Варианты установки

Allstar действует в вашей организации как GitHub App: вы создаёте приложение и запускаете процесс, который аутентифицируется от его имени. Таким образом, настройка состоит из двух шагов, общих для любого развёртывания — создание приложения и создание контрольного репозитория — а затем выбор способа его запуска:

Action — это вариант с меньшими накладными расходами из двух, и с него большинству организаций следует начинать; позже вы можете перейти на демон без изменения какой-либо конфигурации политик.

Создайте свой GitHub App

Приложение — это личность, подобная пользователю, с набором разрешений в вашей организации. Allstar требует доступ на чтение к большинству настроек и содержимому файлов для обнаружения соответствия, а также доступ на запись к проблемам и проверкам для создания проблем и поддержки действия block.

Следуйте Инструкциям для оператора — Создание GitHub App и запишите идентификатор приложения и закрытый ключ. Оба режима запуска нуждаются в них.

Создайте свой контрольный репозиторий .allstar

Allstar читает свою конфигурацию из репозитория с именем .allstar в вашей организации.

Самый быстрый способ создать его — из образца:

1. Откройте образец репозитория и нажмите кнопку «Use this template»
2. В поле «Repository Name» введите .allstar
3. Нажмите «Create repository from template»

Это включает все текущие политики Allstar для всех репозиториев, используя стратегию Opt Out, с действием issue. Вы можете изменить всё это позже.

Для детального контроля с самого начала — выбора стратегии Opt In или Opt Out и самостоятельного написания отдельных файлов политик — вместо этого следуйте инструкциям по ручной установке.

Запуск Allstar как GitHub Action

Этот вариант запускает Allstar как запланированное задание с использованием GitHub Actions, поэтому не требуется управлять инфраструктурой, кроме самого GitHub.

Следуйте инструкциям по установке GitHub Actions, чтобы настроить повторяющееся действие в вашем репозитории .allstar, защитить его и отслеживать его результаты.

Запуск Allstar как фонового сервиса

Этот вариант запускает Allstar как постоянный процесс, который обнаруживает и устраняет нарушения непрерывно, а не по расписанию.

См. Инструкции для оператора по запуску процесса, управлению секретами, масштабированию и доступным переменным окружения.

Миграция с размещаемого приложения

Если ваша организация использовала размещаемое OpenSSF приложение, ваша конфигурация переносится как есть. Контрольный репозиторий .allstar, allstar.yaml и каждый файл политики продолжат работать без изменений; вы заменяете только процесс, который их читает.

Для миграции:

1. Создайте свой собственный GitHub App и установите его в свою организацию с тем же доступом к репозиториям, который был у размещаемого приложения.
2. Оставьте свой существующий репозиторий .allstar точно как есть.
3. Запустите Allstar как Action или как демон.
4. Удалите allstar-app из своей организации, если он всё ещё отображается в разделе Settings -> GitHub Apps.

Проблемы, ранее созданные размещаемым приложением, остаются в ваших репозиториях. Ваш собственный экземпляр идентифицирует свои проблемы по той же метке allstar (или вашей настроенной issueLabel), поэтому он примет их и закроет по мере устранения нарушений, а не будет создавать дубликаты.

Политики и действия

Действия

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

• log: Это действие по умолчанию, и оно фактически выполняется для всех действий. Все результаты и детали выполнения политик регистрируются. Журналы в настоящее время видны только оператору приложения; планы по их раскрытию обсуждаются.
• issue: Это действие создаёт проблему GitHub. Создаётся только одна проблема на политику, и текст описывает детали нарушения политики. Если проблема уже открыта, она получает комментарий каждые 24 часа без обновлений (в настоящее время не настраивается пользователем). Если результат политики изменится, новый комментарий будет оставлен в проблеме и связан в теле проблемы. Как только нарушение будет устранено, проблема будет автоматически закрыта Allstar в течение 5–10 минут.
• fix: Это действие специфично для политики. Политика внесёт изменения в настройки GitHub для исправления нарушения политики. Не все политики смогут поддерживать это (см. ниже).

Предлагаемые, но ещё не реализованные действия. Определения будут добавлены в будущем.

• block: Allstar может установить проверку статуса GitHub и блокировать слияние любого PR в репозитории, если проверка не пройдена.
• email: Allstar отправит электронное письмо администратору(ам) репозитория.
• rpc: Allstar отправит rpc в какую-либо специфичную для организации систему.

Конфигурация действия

Доступны два параметра для настройки действия issue:

• issueLabel доступен на уровне организации и репозитория. Его установка переопределит метку allstar по умолчанию, используемую Allstar для идентификации своих проблем.

• issueRepo доступен на уровне организации. Его установка приведёт к тому, что все проблемы, создаваемые в организации, будут создаваться в указанном репозитории.

Политики

Аналогично конфигурации включения приложения Allstar, все политики включаются и настраиваются с помощью yaml-файла либо в репозитории .allstar организации, либо в каталоге .allstar репозитория. Как и в случае с приложением, политики по умолчанию являются opt-in, также действие по умолчанию log не даёт видимых результатов. Простой способ включить все политики — создать yaml-файл для каждой политики со следующим содержимым:```yaml optConfig: optOutStrategy: true action: issue

Детали того, как действие `fix` работает для каждой политики, описаны ниже. Если ниже это не указано, действие `fix` неприменимо.

### Защита веток

Файл конфигурации этой политики называется `branch_protection.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).

Политика защиты веток проверяет, что [настройки защиты веток](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) GitHub настроены правильно в соответствии с указанной конфигурацией. В тексте issue будет описано, какой параметр настроен неверно. См. [документацию GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) для исправления настроек.

Действие `fix` изменит настройки защиты веток, чтобы они соответствовали указанной конфигурации политики.

### Бинарные артефакты

Файл конфигурации этой политики называется `binary_artifacts.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).

Эта политика включает [проверку из
scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Удалите
бинарный артефакт из репозитория для достижения соответствия. Так как результаты
scorecard могут быть подробными, вам может потребоваться запустить [сам
scorecard](https://github.com/ossf/scorecard), чтобы увидеть всю детальную информацию.

### CODEOWNERS

Файл конфигурации этой политики называется `codeowners.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).

Эта политика проверяет наличие [файла `CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) в ваших репозиториях.

### Внешние соавторы

Файл конфигурации этой политики называется `outside.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).

Эта политика проверяет, имеют ли [внешние
соавторы](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) доступ к репозиторию с правами администратора (по умолчанию) или на отправку изменений (опционально). Только участники организации должны иметь такой доступ, так как в противном случае недоверенные участники могут изменять настройки уровня администратора и коммитить вредоносный код.

### SECURITY.md

Файл конфигурации этой политики называется `security.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).

Эта политика проверяет, что в репозитории есть файл политики безопасности в
`SECURITY.md` и что он не пуст. В созданном issue будет ссылка на
[вкладку GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository),
которая поможет вам добавить политику безопасности в ваш репозиторий.

### Опасный рабочий процесс

Файл конфигурации этой политики называется `dangerous_workflow.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).

Эта политика будет применяться ко **всем** веткам, обоснование см. [здесь](https://github.com/ossf/allstar/issues/569).

Эта политика проверяет файлы конфигурации рабочих процессов GitHub Actions
(`.github/workflows`) на наличие любых шаблонов, соответствующих известному опасному
поведению. См. [документацию OpenSSF
Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)
для получения дополнительной информации об этой проверке.

### Общая проверка Scorecard

Файл конфигурации этой политики называется `scorecard.yaml`, а [определения конфигурации находятся
здесь](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).

Эта политика запускает любую проверку scorecard, указанную в конфигурации `checks`. Все
запускаемые проверки должны иметь оценку, равную или превышающую параметр `threshold`. Пожалуйста, обратитесь к
[документации OpenSSF
Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md)
для получения дополнительной информации о каждой проверке.

#### Загрузка SARIF

Политика Scorecard может опционально загружать результаты в формате
[SARIF](https://sarifweb.azurewebsites.net/) на вкладку **Security > Code Scanning** каждого репозитория. Это дает администраторам организации
видимость результатов Scorecard наряду с другими инструментами безопасности (CodeQL,
Dependabot и т. д.) без необходимости настройки рабочего процесса для каждого репозитория.

Чтобы включить загрузку SARIF, добавьте поле `upload` в ваш `scorecard.yaml`:```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

Требования:

• GitHub App Allstar должен иметь разрешение на Code scanning alerts для репозитория, установленное в Read & write (область API: security_events). Это не входит в число разрешений, которые Allstar в остальном требует, поэтому добавьте его в своё приложение перед включением загрузки SARIF.
• Загрузка SARIF не блокирует выполнение: если загрузка не удалась (например, из-за отсутствующих разрешений), проверка политики продолжается в обычном режиме.
• Сравнение изменений сопоставляет SHA коммита HEAD репозитория и пропускает сканирование и загрузку, если в репозиторий не было push-запросов с момента последней загрузки.

Загрузка SARIF работает с обоими способами запуска Allstar: как служебный демон или как GitHub Action.

GitHub Actions

Файл конфигурации этой политики называется actions.yaml, а определения конфигурации находятся здесь.

Эта политика проверяет файлы конфигурации рабочих процессов GitHub Actions (.github/workflows) (а в некоторых случаях и запуски рабочих процессов) в каждом репозитории, чтобы убедиться, что они соответствуют правилам (например, требовать, запрещать), определённым в конфигурации политики на уровне организации.

Администраторы репозитория

Файл конфигурации этой политики называется admin.yaml, а определения конфигурации находятся здесь.

Эта политика проверяет, что по умолчанию во всех репозиториях пользователь или группа назначены администратором. Она позволяет дополнительно настроить, разрешено ли пользователям быть администраторами (в отличие от команд).

Будущие политики

• Обеспечить включение dependabot.
• Проверить, что зависимости закреплены/зафиксированы.

Пример репозитория конфигурации

См. этот репозиторий как пример использования конфигурации Allstar. Как администратор организации, рассмотрите README.md с некоторой информацией о том, как Allstar используется в вашей организации.

Дополнительно

Определения конфигурации

• Конфигурация включения на уровне организации
• Конфигурация включения переопределения репозитория

Вторичное расположение конфигурации на уровне организации

По умолчанию файлы конфигурации уровня организации, такие как allstar.yaml выше, должны находиться в репозитории .allstar. Если этот репозиторий не существует, то каталог allstar репозитория .github используется как вторичное расположение. Для уточнения, для allstar.yaml:

Это также относится к файлам конфигурации уровня организации для отдельных политик, как описано ниже.

Конфигурации политик репозитория в репозитории организации

Allstar также будет искать конфигурации политик уровня репозитория в репозитории .allstar организации, в каталоге с тем же именем, что и репозиторий. Эта конфигурация используется независимо от того, отключено ли «переопределение репозитория».

Например, Allstar будет искать конфигурацию политики для данного репозитория myapp в следующем порядке:

Расположение базовой и объединённой конфигурации на уровне организации

Для файлов конфигурации Allstar и политик на уровне организации вы можете указать поле baseConfig, чтобы задать другой репозиторий, содержащий базовую конфигурацию Allstar. Это лучше всего объяснить на примере.

Предположим, у вас несколько организаций GitHub, но вы хотите поддерживать единую конфигурацию Allstar. Ваша основная организация — «acme», и репозиторий acme/.allstar содержит allstar.yaml:```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

Вы также имеете спутниковую организацию на GitHub под названием «acme-sat». Вы хотите
переиспользовать основную конфигурацию, но применить некоторые изменения поверх, отключив Allstar на
определённых репозиториях. Репозиторий `acme-sat/.allstar` содержит
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

Это будет использовать всю конфигурацию из acme/.allstar в качестве базовой конфигурации, но затем применит любые изменения из текущего файла поверх базовой конфигурации. Метод, которым это применяется, описан как JSON Merge Patch. Поле baseConfig должно быть GitHub-репозиторием в формате <org>/<repository>.

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

См. CONTRIBUTING.md