allstar
v4.2
Allstar — это приложение GitHub, которое постоянно контролирует организации или репозитории GitHub на предмет соблюдения передовых методов обеспечения безопасности. Если Allstar обнаруживает нарушение политики безопасности, это создает проблему, о которой необходимо предупредить владельца репозитория или организации. Для некоторых политик безопасности Allstar также может автоматически изменить настройку проекта, вызвавшую нарушение, вернув его в ожидаемое состояние.
Цель Allstar — предоставить вам точно настроенный контроль над файлами и настройками, влияющими на безопасность ваших проектов. Вы можете выбрать, какие политики безопасности отслеживать как на уровне организации, так и на уровне репозитория, а также как обрабатывать нарушения политик. Вы также можете разрабатывать или предлагать новые политики.
Allstar разработан как часть проекта OpenSSF Scorecard.
Если вы получаете нежелательные проблемы, созданные Allstar, следуйте этим инструкциям, чтобы отказаться.
Allstar имеет широкие возможности настройки. Существует три основных уровня контроля:
Эти конфигурации выполняются в репозитории .allstar организации.
Уровень репозитория. Специалисты по обслуживанию репозитория в организации, использующей Allstar, могут включить или отключить для своего репозитория меры контроля на уровне организации. Примечание. Эти элементы управления на уровне репозитория функциональны только в том случае, если в настройках уровня организации разрешено «переопределение репозитория». Эти конфигурации выполняются в каталоге .allstar репозитория.
Уровень политики: администраторы или специалисты по обслуживанию могут выбирать, какие политики активны для конкретных репозиториев и какие действия Allstar предпринимает в случае нарушения политики. Эти конфигурации выполняются в файле политики yaml либо в репозитории .allstar организации (администраторы), либо в каталоге .allstar репозитория (специалисты по обслуживанию).
Перед установкой Allstar на уровне организации вам следует примерно решить, на скольких репозиториях вы хотите, чтобы Allstar работал. Это поможет вам выбрать между стратегиями согласия и отказа.
Стратегия Opt In позволяет вам вручную добавлять репозитории, на которых вы хотите, чтобы Allstar работал. Если вы не укажете репозитории, Allstar не запустится, несмотря на установку. Выберите стратегию «Принять участие», если вы хотите применить политики только к небольшому количеству ваших репозиториев или хотите опробовать Allstar в одном репозитории, прежде чем включать его в других. Начиная с версии 4.3, поддерживаются globs, позволяющие легко добавлять несколько репозиториев с одинаковым именем.
Стратегия отказа (рекомендуется) включает Allstar во всех репозиториях и позволяет вручную выбирать репозитории для отказа от принудительного применения Allstar. Вы также можете отказаться от всех общедоступных или всех частных репозиториев. Выберите этот вариант, если вы хотите запускать Allstar во всех репозиториях в организации или хотите отказаться только от небольшого количества репозиториев или репозитория определенного типа (т. е. общедоступного или частного). Начиная с версии 4.3, поддерживаются globs, позволяющие легко добавлять несколько репозиториев с одинаковым именем.
| Отказаться (рекомендуется) optOutStrategy = правда | Включить optOutStrategy = ложь | |
|---|---|---|
| Поведение по умолчанию | Все репозитории включены | Репозитории не включены |
| Добавление репозиториев вручную | Добавление репозиториев вручную отключает Allstar в этих репозиториях. | Добавление репозиториев вручную позволяет использовать Allstar в этих репозиториях. |
| Дополнительные конфигурации | optOutRepos: Allstar будет отключен в перечисленных репозиториях. optOutPrivateRepos: если true, Allstar будет отключен во всех частных репозиториях. optOutPublicRepos: если true, Allstar будет отключен во всех публичных репозиториях. (optInRepos: этот параметр будет игнорироваться) | optInRepos: Allstar будет включен в перечисленных репозиториях. (optOutRepos: этот параметр будет игнорироваться) |
| Переопределение репо | Если это правда: репозитории могут отказаться от принудительного применения Allstar своей организации, используя настройки в своем собственном файле репо. Настройки согласия на уровне организации, применимые к этому репозиторию, игнорируются. Если false: репозитории не могут отказаться от принудительного применения Allstar, настроенного на уровне организации. | Если это правда: репозитории могут согласиться на принудительное применение Allstar своей организации, даже если они не настроены для репо на уровне организации. Настройки отказа на уровне организации, применимые к этому репозиторию, игнорируются. Если false: репозитории не могут принять меры Allstar, если они не настроены на уровне организации. |
Оба варианта установки: «Быстрый запуск» и «Ручная установка» предполагают установку приложения Allstar. Вы можете просмотреть запрошенные разрешения. Приложение запрашивает доступ для чтения к большинству настроек и содержимому файлов, чтобы определить соответствие требованиям безопасности. Он запрашивает доступ на запись к проблемам и проверяет, чтобы он мог создавать проблемы и разрешать действие block .
Этот вариант установки позволит Allstar использовать стратегию отказа во всех репозиториях вашей организации. Все текущие политики будут активированы, и Allstar предупредит вас о нарушениях политик, сообщив о проблеме. Это самый быстрый и простой способ начать использовать Allstar, и вы все равно сможете изменить любые конфигурации позже.
Усилие: очень легко
Шаги:
.allstarВот и все! Все текущие политики Allstar теперь включены во всех ваших репозиториях. Allstar создаст проблему, если политика будет нарушена.
Чтобы изменить какие-либо конфигурации, см. инструкции по установке вручную.
Этот вариант установки поможет вам создать файлы конфигурации в соответствии со стратегией согласия или отказа. Этот параметр обеспечивает более детальный контроль над конфигурациями с самого начала.
Усилие: умеренное
Шаги:
Для каждой политики можно настроить действие, которое Allstar предпримет, когда обнаружит, что репозиторий не соответствует требованиям.
log : это действие по умолчанию, которое фактически имеет место для всех действий. Все результаты и подробности выполнения политики протоколируются. Журналы в настоящее время видны только оператору приложения, планы по их раскрытию находятся в стадии обсуждения.issue : это действие создает проблему GitHub. Для каждой политики создается только одна проблема, и в тексте описываются подробности нарушения политики. Если проблема уже открыта, она отправляется с комментарием каждые 24 часа без обновлений (в настоящее время не настраивается пользователем). Если результат политики изменится, к проблеме будет оставлен новый комментарий, ссылка на который будет указана в тексте проблемы. Как только нарушение будет устранено, Allstar автоматически закроет проблему в течение 5–10 минут.fix : Это действие зависит от политики. Политика внесет изменения в настройки GitHub, чтобы исправить нарушение политики. Не все политики смогут это поддержать (см. ниже).Предложенные, но еще не реализованные действия. Определения будут добавлены в будущем.
block : Allstar может установить проверку статуса GitHub и заблокировать объединение любого PR в репозитории, если проверка не пройдена.email : Allstar отправит электронное письмо администратору(ам) репозитория.rpc : Allstar отправит RPC в некоторую систему, специфичную для организации.Для настройки действия по проблеме доступны две настройки:
issueLabel доступен на уровне организации и репозитория. Установка этого параметра приведет к переопределению метки allstar по умолчанию, используемой Allstar для выявления проблем.
issueRepo доступен на уровне организации. Установка этого параметра приведет к тому, что все проблемы, созданные в организации, будут создаваться в указанном репозитории.
Подобно конфигурации включения приложения Allstar, все политики включаются и настраиваются с помощью файла yaml либо в репозитории .allstar организации, либо в каталоге .allstar репозитория. Как и в случае с приложением, политики включены по умолчанию, а действие log по умолчанию не даст видимых результатов. Простой способ включить все политики — создать для каждой политики файл yaml с содержимым:
optConfig:
optOutStrategy: true
action: issue
Подробные сведения о том, как действие fix работает для каждой политики, подробно описаны ниже. Если опущено ниже, действие fix неприменимо.
Файл конфигурации этой политики называется branch_protection.yaml , а определения конфигурации находятся здесь.
Политика защиты ветвей проверяет, правильно ли настроены параметры защиты веток GitHub в соответствии с указанной конфигурацией. В тексте проблемы будет указано, какая настройка неверна. См. документацию GitHub для исправления настроек.
Действие fix изменит параметры защиты ветки, чтобы они соответствовали указанной конфигурации политики.
Файл конфигурации этой политики binary_artifacts.yaml , а определения конфигурации находятся здесь.
Эта политика включает проверку по системе показателей. Удалите двоичный артефакт из репозитория, чтобы обеспечить соответствие. Поскольку результаты системы показателей могут быть подробными, вам может потребоваться запустить саму систему показателей, чтобы просмотреть всю подробную информацию.
Файл конфигурации этой политики называется codeowners.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет наличие файла CODEOWNERS в ваших репозиториях.
Файл конфигурации этой политики называется outside.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет, есть ли у внешних соавторов доступ администратора (по умолчанию) или push-доступ (необязательно) к репозиторию. Только члены организации должны иметь этот доступ, поскольку в противном случае ненадежные участники могут изменить настройки уровня администратора и передать вредоносный код.
Файл конфигурации этой политики называется security.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет, что в репозитории есть файл политики безопасности в SECURITY.md и что он не пуст. Созданная задача будет иметь ссылку на вкладку GitHub, которая поможет вам зафиксировать политику безопасности в вашем репозитории.
Файл конфигурации этой политики называется dangerous_workflow.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет файлы конфигурации рабочего процесса GitHub Actions ( .github/workflows ) на наличие шаблонов, соответствующих известному опасному поведению. Дополнительную информацию об этой проверке см. в документации OpenSSF Scorecard.
Файл конфигурации этой политики называется scorecard.yaml , а определения конфигурации находятся здесь.
Эта политика запускает любую проверку системы показателей, указанную в конфигурации checks . Все выполняемые проверки должны иметь оценку, равную threshold значению или превышающую его. Дополнительную информацию о каждой проверке см. в документации OpenSSF Scorecard.
Файл конфигурации этой политики называется actions.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет файлы конфигурации рабочего процесса GitHub Actions ( .github/workflows ) (и рабочий процесс в некоторых случаях запускается) в каждом репозитории, чтобы убедиться, что они соответствуют правилам (например, требовать, запрещать), определенным в конфигурации уровня организации для политика.
Файл конфигурации этой политики называется admin.yaml , а определения конфигурации находятся здесь.
Эта политика проверяет, что по умолчанию все репозитории должны иметь пользователя или группу, назначенную администратором. Он позволяет вам дополнительно настроить, разрешено ли пользователям быть администраторами (в отличие от команд).
См. этот репозиторий как пример используемой конфигурации Allstar. Как администратор организации, рассмотрите файл README.md с некоторой информацией о том, как Allstar используется в вашей организации.
По умолчанию файлы конфигурации уровня организации, такие как файл allstar.yaml , указанный выше, должны находиться в репозитории .allstar . Если этот репозиторий не существует, то в качестве вторичного местоположения используется каталог allstar репозитория .github . Чтобы уточнить, для allstar.yaml :
| Приоритет | Репозиторий | Путь |
|---|---|---|
| Начальный | .allstar | allstar.yaml |
| Вторичный | .github | allstar/allstar.yaml |
Это также справедливо для файлов конфигурации на уровне организации для отдельных политик, как описано ниже.
Allstar также будет искать конфигурации политики уровня репозитория в репозитории .allstar организации в каталоге с тем же именем, что и репозиторий. Эта конфигурация используется независимо от того, отключено ли «переопределение репозитория».
Например, Allstar будет искать конфигурацию политики для данного репозитория myapp в следующем порядке:
| Репозиторий | Путь | Состояние |
|---|---|---|
myapp | .allstar/branch_protection.yaml | Когда разрешено «переопределение репо». |
.allstar | myapp/branch_protection.yaml | Все времена. |
.allstar | branch_protection.yaml | Все времена. |
.github | allstar/myapp/branch_protection.yaml | Если репозиторий .allstar не существует. |
.github | allstar/branch_protection.yaml | Если репозиторий .allstar не существует. |
Для файлов конфигурации Allstar и политики на уровне организации вы можете указать поле baseConfig , чтобы указать другой репозиторий, содержащий базовую конфигурацию Allstar. Лучше всего это объяснить на примере.
Предположим, у вас есть несколько организаций GitHub, но вы хотите поддерживать одну конфигурацию Allstar. Ваша основная организация — «acme», а репозиторий acme/.allstar содержит allstar.yaml :
optConfig :
optOutStrategy : true
issueLabel : allstar-acme
issueFooter : Issue created by Acme security team. У вас также есть сателлитная организация GitHub под названием «acme-sat». Вы хотите повторно использовать основную конфигурацию, но внести некоторые изменения поверх нее, отключив Allstar в определенных репозиториях. Репозиторий acme-sat/.allstar содержит allstar.yaml :
baseConfig : acme/.allstar
optConfig :
optOutRepos :
- acmesat-one
- acmesat-two При этом вся конфигурация из acme/.allstar будет использоваться в качестве базовой конфигурации, но затем все изменения в текущем файле будут применены поверх базовой конфигурации. Применяемый метод описан как JSON Merge Patch. baseConfig должен быть GitHub <org>/<repository> .
См. CONTRIBUTING.md
