Allstar

Обзор

• Что такое Allstar?

Что нового в Allstar

• whats-new.md

Отключение нежелательных задач (Issues)

• Помогите! Allstar создаёт задачи, а я этого не хочу!

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

• Предыстория
• Настройки на уровне организации
• Варианты установки
  • Использование публичного приложения Allstar
    • Быстрая установка
    • Ручная установка
  • Самостоятельный хостинг Allstar
    • Запуск Allstar как GitHub Action
    • Запуск Allstar как службы-демона

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

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

Расширенные возможности

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

Участие

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

Обзор

Что такое Allstar?

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

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

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

Что нового в Allstar

Отключение нежелательных задач (Issues)

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

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

Предыстория

Allstar обладает широкими возможностями настройки. Существует три основных уровня управления:

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

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

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

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

Настройки на уровне организации

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

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

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

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

Как быстрая установка, так и ручная установка предполагают установку приложения Allstar в вашу организацию GitHub. Приложение Allstar управляется OpenSSF и является хорошим выбором для большинства репозиториев с открытым исходным кодом. Вы можете просмотреть запрашиваемые разрешения. Приложение запрашивает доступ на чтение к большинству настроек и содержимому файлов для обнаружения соответствия требованиям безопасности. Оно запрашивает доступ на запись к задачам (issues) и проверкам (checks), чтобы иметь возможность создавать задачи и разрешать действие block.

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

Использование приложения Allstar

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

Быстрая установка

Этот вариант установки включает Allstar по стратегии исключения для всех репозиториев в вашей организации. Все текущие политики будут включены, и Allstar будет уведомлять вас о нарушениях политик, создавая задачу (issue). Это самый быстрый и простой способ начать работу с Allstar, и вы впоследствии сможете изменить любые настройки.

Требуемые усилия: очень низкие

Шаги:

1. Установите приложение Allstar
   1. Откройте страницу установки и нажмите Configure
   2. Если у вас несколько организаций, выберите ту, в которую хотите установить Allstar
   3. Выберите «All Repositories» (Все репозитории) в разделе Repository Access, даже если вы планируете отключить Allstar на некоторых репозиториях позже
2. Создайте форк образцового репозитория
   1. Откройте образцовый репозиторий и нажмите кнопку «Use this template» (Использовать этот шаблон)
   2. В поле Repository Name (Имя репозитория) введите .allstar
   3. Нажмите «Create repository from template» (Создать репозиторий из шаблона)

Вот и всё! Все текущие политики Allstar теперь включены для всех ваших репозиториев. Allstar создаст задачу, если политика будет нарушена.

Чтобы изменить какие-либо настройки, следуйте инструкциям по ручной установке.

Ручная установка

Этот вариант установки проведёт вас через процесс создания файлов конфигурации в соответствии со стратегией включения или исключения. Этот вариант обеспечивает более детальный контроль над конфигурациями с самого начала.

Требуемые усилия: средние

Шаги:

1. Установите приложение Allstar (выберите «All Repositories» в разделе Repository Access, даже если вы не планируете использовать Allstar на всех репозиториях)
2. Следуйте инструкциям по ручной установке, чтобы создать файлы конфигурации Allstar на уровне организации или репозитория, а также отдельные файлы политик.

Самостоятельный хостинг Allstar

Размещайте Allstar самостоятельно только в случае крайней необходимости! Приложение Allstar требует настройки, обеспечения безопасности и постоянного обслуживания. При выходе новой версии Allstar вам нужно будет обновлять ваше самостоятельно размещённое решение.

Описываются два подхода к самостоятельному хостингу:

• Запуск Allstar как GitHub Action — этот вариант относительно лёгкий и использует GitHub Actions для выполнения проверок Allstar.
• Запуск Allstar как службы-демона — этот вариант обеспечивает наибольший уровень контроля и предполагает, что вы можете запускать постоянный сервис на надёжном сервере или оркестраторе контейнеров.

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

Этот вариант установки запускает Allstar как запланированное задание с помощью GitHub Actions.

Требуемые усилия: высокие

Следуйте инструкциям по установке GitHub Action, чтобы:

1. Создать новое приложение GitHub для использования Allstar.
2. Создать контрольный репозиторий .allstar на уровне организации, как описано в быстрой установке или ручной установке. (Пропустите шаги по установке управляемого OpenSSF приложения Allstar в вашу организацию.)
3. Настроить повторяющийся GitHub Action в .allstar для запуска Allstar в пакетном режиме.
4. Отслеживать активность заданий и результаты.

Запуск Allstar как службы-демона

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

Требуемые усилия: очень высокие

См. Инструкции для оператора для получения дополнительной информации, включая создание приложения Allstar, управление секретами и доступные переменные окружения.

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

Действия

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

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

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

• block: Allstar может установить GitHub Status Check и заблокировать слияние любого 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

Конфигурационный файл этой политики называется `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

Конфигурационный файл этой политики называется `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 Collaborators

Конфигурационный файл этой политики называется `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) доступ уровня администратора (по умолчанию) или push (опционально) к репозиторию. Только участники организации должны иметь такой доступ, иначе ненадёжные участники могут изменять настройки уровня администратора и вносить вредоносный код.

### 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

Конфигурационный файл этой политики называется `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) для получения дополнительной информации об этой проверке.

### Generic Scorecard Check

Конфигурационный файл этой политики называется `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 Upload

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

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

Требования:

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

Загрузка SARIF работает как в режиме самостоятельного развёртывания: в виде работающего служебного демона или 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>.

Вклад