ossf/allstarGitHub App pour définir et appliquer des politiques de sécurité
Allstar est une application GitHub qui surveille en continu les organisations ou dépôts GitHub pour s'assurer du respect des bonnes pratiques de sécurité. Si Allstar détecte une violation de politique de sécurité, il crée un problème pour alerter le propriétaire du dépôt ou de l'organisation. Pour certaines politiques de sécurité, Allstar peut également modifier automatiquement le paramètre du projet à l'origine de la violation, le rétablissant à l'état attendu.
L'objectif d'Allstar est de vous offrir un contrôle fin sur les fichiers et les paramètres qui affectent la sécurité de vos projets. Vous pouvez choisir quelles politiques de sécurité surveiller, à la fois au niveau de l'organisation et du dépôt, et comment gérer les violations de politique. Vous pouvez également développer ou contribuer à de nouvelles politiques.
Allstar est développé dans le cadre du projet OpenSSF Scorecard.
Si vous recevez des problèmes indésirables créés par Allstar, suivez ces instructions pour vous désinscrire.
Allstar est hautement configurable. Il existe trois niveaux principaux de contrôles :
Ces configurations sont effectuées dans le dépôt .allstar de l'organisation.
Niveau dépôt : Les responsables de dépôt dans une organisation qui utilise
Allstar peuvent choisir d'inscrire ou de désinscrire leur dépôt des
mesures de contrôle au niveau de l'organisation. Remarque : ces contrôles au niveau du dépôt ne sont fonctionnels que si la
"surcharge de dépôt" est autorisée dans les paramètres au niveau de l'organisation. Ces configurations sont
effectuées dans le répertoire .allstar du dépôt.
Niveau politique : Les administrateurs ou responsables peuvent choisir quelles politiques
sont activées sur des dépôts spécifiques et quelles actions Allstar entreprend lorsqu'une politique
est violée. Ces configurations sont effectuées dans un fichier yaml de politique, soit dans
le dépôt .allstar de l'organisation (administrateurs), soit dans le
répertoire .allstar du dépôt (responsables).
Avant d'installer Allstar au niveau de l'organisation, vous devez décider approximativement sur combien de dépôts vous souhaitez qu'Allstar s'exécute. Cela vous aidera à choisir entre les stratégies d'inscription et de désinscription.
La stratégie d'inscription vous permet d'ajouter manuellement les dépôts sur lesquels vous souhaitez qu'Allstar s'exécute. Si vous ne spécifiez aucun dépôt, Allstar ne s'exécutera pas malgré son installation. Choisissez la stratégie d'inscription si vous souhaitez appliquer des politiques uniquement sur un petit nombre de vos dépôts totaux, ou si vous voulez essayer Allstar sur un seul dépôt avant de l'activer sur davantage. Depuis la version v4.3, les globs sont pris en charge pour ajouter facilement plusieurs dépôts portant un nom similaire.
La stratégie de désinscription (recommandée) active Allstar sur tous les dépôts et vous permet de sélectionner manuellement les dépôts à désinscrire des mesures de contrôle d'Allstar. Vous pouvez également choisir de désinscrire tous les dépôts publics, ou tous les dépôts privés. Choisissez cette option si vous souhaitez exécuter Allstar sur tous les dépôts d'une organisation, ou si vous souhaitez désinscrire seulement un petit nombre de dépôts ou un type spécifique (c'est-à-dire public vs. privé) de dépôt. Depuis la version v4.3, les globs sont pris en charge pour ajouter facilement plusieurs dépôts portant un nom similaire.
Les options Installation rapide et Installation manuelle impliquent toutes deux l'installation de l'application Allstar dans votre organisation GitHub. L'application Allstar est gérée par OpenSSF et constitue un bon choix pour la plupart des dépôts open source. Vous pouvez consulter les autorisations demandées. L'application demande un accès en lecture à la plupart des paramètres et contenus de fichiers pour détecter la conformité de sécurité. Elle demande un accès en écriture aux problèmes et aux vérifications afin de pouvoir créer des problèmes et permettre l'action block.
Si vous ne souhaitez pas utiliser l'application Allstar gérée par OpenSSF, vous pouvez héberger Allstar vous-même, en créant votre propre application Allstar. Cela offre un contrôle direct de l'application, en échange de la nécessité de configurer, sécuriser, surveiller et maintenir l'application.
L'installation rapide ou manuelle est recommandée, sauf si vous avez des contraintes de sécurité ou de conformité spécifiques qui vous empêchent d'utiliser l'application Allstar gérée par OpenSSF.
Cette option d'installation activera Allstar en utilisant la stratégie de désinscription sur tous les dépôts de votre organisation. Toutes les politiques actuelles seront activées, et Allstar vous alertera des violations de politique en créant un problème. C'est le moyen le plus rapide et le plus simple de commencer à utiliser Allstar, et vous pouvez toujours modifier les configurations ultérieurement.
Effort : très facile
Étapes :
.allstarC'est tout ! Toutes les politiques actuelles d'Allstar sont maintenant activées sur tous vos dépôts. Allstar créera un problème si une politique est violée.
Pour modifier les configurations, voir les instructions d'installation manuelle.
Cette option d'installation vous guidera dans la création de fichiers de configuration selon la stratégie d'inscription ou de désinscription. Cette option offre un contrôle plus granulaire des configurations dès le départ.
Effort : modéré
Étapes :
N'hébergez Allstar vous-même que si vous le devez absolument ! L'application Allstar nécessite configuration, sécurisation et maintenance continue. Lorsqu'une nouvelle version d'Allstar est publiée, vous devrez mettre à niveau votre solution auto-hébergée.
Deux approches d'auto-hébergement sont décrites :
Cette option d'installation exécute Allstar en tant que tâche planifiée à l'aide de GitHub Actions.
Effort : élevé
Suivez les instructions d'installation pour GitHub Actions pour :
.allstar au niveau de l'organisation comme décrit dans
l'installation rapide ou
l'installation manuelle. (Ignorez les étapes pour installer
l'application Allstar gérée par OpenSSF dans votre organisation.).allstar pour exécuter Allstar en mode batch.Cette option d'installation exécute Allstar en tant que processus persistant.
Effort : très élevé
Voir les instructions pour l'opérateur pour plus d'informations, notamment la création d'une application Allstar, la gestion des secrets et les variables d'environnement disponibles.
Chaque politique peut être configurée avec une action qu'Allstar entreprendra lorsqu'il détecte qu'un dépôt n'est pas conforme.
log : Il s'agit de l'action par défaut, et elle a lieu en fait pour toutes
les actions. Tous les résultats et détails des exécutions de politiques sont enregistrés. Les journaux ne sont
actuellement visibles que pour l'opérateur de l'application, des plans pour les exposer sont en cours de discussion.issue : Cette action crée un problème GitHub. Un seul problème est créé par
politique, et le texte décrit les détails de la violation de politique. Si
le problème est déjà ouvert, il est relancé avec un commentaire toutes les 24 heures sans mise à jour
(actuellement non configurable par l'utilisateur). Si le résultat de la politique change, un nouveau commentaire
sera laissé sur le problème et lié dans le corps du problème. Une fois la violation
résolue, le problème sera automatiquement fermé par Allstar dans les 5 à 10 minutes.fix : Cette action est spécifique à la politique. La politique apportera les modifications aux
paramètres GitHub pour corriger la violation de politique. Toutes les politiques ne pourront pas
prendre en charge cela (voir ci-dessous).Actions proposées, mais pas encore implémentées. Les définitions seront ajoutées à l'avenir.
block : Allstar peut définir une vérification de statut
GitHub
et bloquer la fusion de toute PR dans le dépôt si la vérification échoue.email : Allstar enverrait un courriel au(x) administrateur(s) du dépôt.rpc : Allstar enverrait un rpc à un système spécifique à l'organisation.Deux paramètres sont disponibles pour configurer l'action issue :
issueLabel est disponible au niveau de l'organisation et du dépôt. Le définir
remplacera l'étiquette par défaut allstar utilisée par Allstar pour identifier ses
problèmes.
issueRepo est disponible au niveau de l'organisation. Le définir forcera tous
les problèmes créés dans l'organisation à être créés dans le dépôt spécifié.
Comme pour la configuration d'activation de l'application Allstar, toutes les politiques sont activées et
configurées avec un fichier yaml dans soit le dépôt .allstar de l'organisation,
soit le répertoire .allstar du dépôt. Comme pour l'application, les politiques sont en inscription
par défaut, et l'action par défaut log ne produira pas de résultats visibles. Un
moyen simple d'activer toutes les politiques est de créer un fichier yaml pour chaque politique avec
le contenu suivant :```yaml
optConfig:
optOutStrategy: true
action: issue
Les détails du fonctionnement de l'action `fix` pour chaque politique sont détaillés ci-dessous. Si omis ci-dessous, l'action `fix` n'est pas applicable.
### Protection de branche
Le fichier de configuration de cette politique est nommé `branch_protection.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).
La politique de protection de branche vérifie que les [paramètres de protection de branche](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) de GitHub sont configurés correctement selon la configuration spécifiée. Le texte de l'issue décrira quel paramètre est incorrect. Consultez la [documentation de GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) pour corriger les paramètres.
L'action `fix` modifiera les paramètres de protection de branche pour les rendre conformes à la configuration de la politique spécifiée.
### Artefacts binaires
Le fichier de configuration de cette politique est nommé `binary_artifacts.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).
Cette politique intègre la [vérification de scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Supprimez l'artefact binaire du dépôt pour atteindre la conformité. Comme les résultats de scorecard peuvent être verbeux, vous devrez peut-être exécuter [scorecard lui-même](https://github.com/ossf/scorecard) pour voir toutes les informations détaillées.
### CODEOWNERS
Le fichier de configuration de cette politique est nommé `codeowners.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).
Cette politique vérifie la présence d'un [`fichier CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) dans vos dépôts.
### Collaborateurs externes
Le fichier de configuration de cette politique est nommé `outside.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).
Cette politique vérifie si des [Collaborateurs externes](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) ont un accès administrateur (par défaut) ou push (optionnel) au dépôt. Seuls les membres de l'organisation devraient avoir cet accès, car autrement des membres non fiables peuvent modifier les paramètres de niveau administrateur et commettre du code malveillant.
### SECURITY.md
Le fichier de configuration de cette politique est nommé `security.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).
Cette politique vérifie que le dépôt possède un fichier de politique de sécurité dans `SECURITY.md` et qu'il n'est pas vide. L'issue créée contiendra un lien vers l'[onglet GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) qui vous aide à valider une politique de sécurité dans votre dépôt.
### Workflow dangereux
Le fichier de configuration de cette politique est nommé `dangerous_workflow.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).
Cette politique s'exécutera sur **toutes** les branches, voir la justification [ici](https://github.com/ossf/allstar/issues/569).
Cette politique vérifie les fichiers de configuration de workflow GitHub Actions (`.github/workflows`) pour tout motif correspondant à un comportement dangereux connu. Consultez la [documentation OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) pour plus d'informations sur cette vérification.
### Vérification générique Scorecard
Le fichier de configuration de cette politique est nommé `scorecard.yaml`, et les [définitions de configuration sont ici](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).
Cette politique exécute toute vérification scorecard listée dans la configuration `checks`. Toutes les vérifications exécutées doivent avoir un score égal ou supérieur au paramètre `threshold`. Veuillez consulter la [documentation OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md) pour plus d'informations sur chaque vérification.
#### Téléversement SARIF
La politique Scorecard peut éventuellement téléverser les résultats au format [SARIF](https://sarifweb.azurewebsites.net/) vers l'onglet **Security > Code Scanning** de chaque dépôt. Cela donne aux administrateurs de l'organisation une visibilité sur les résultats de Scorecard aux côtés d'autres outils de sécurité (CodeQL, Dependabot, etc.) sans nécessiter de configuration de workflow par dépôt.
Pour activer le téléversement SARIF, ajoutez le champ `upload` à votre `scorecard.yaml` :```yaml
optConfig:
optOutStrategy: true
action: issue
checks:
- Binary-Artifacts
- Signed-Releases
threshold: 8
upload:
sarif: true
Exigences :
security_events).
Les opérateurs auto-hébergés doivent ajouter cette permission à leur application GitHub. L'
application publique Allstar exploitée par OpenSSF n'inclut pas encore cette permission.Le téléchargement SARIF fonctionne avec les deux modes de déploiement auto-hébergés : exécuté en tant que démon de service ou en tant que GitHub Action.
Le fichier de configuration de cette politique s'appelle actions.yaml, et les définitions de configuration sont
ici.
Cette politique vérifie les fichiers de configuration des workflows GitHub Actions
(.github/workflows) (et les exécutions de workflows dans certains cas) dans chaque dépôt pour
s'assurer qu'ils sont conformes aux règles (par exemple, obliger, interdire) définies dans la
configuration au niveau de l'organisation pour la politique.
Le fichier de configuration de cette politique s'appelle admin.yaml, et les définitions de configuration sont
ici.
Cette politique vérifie que par défaut tous les dépôts doivent avoir un utilisateur ou un groupe assigné comme administrateur. Elle vous permet de configurer optionnellement si les utilisateurs sont autorisés à être administrateurs (par opposition aux équipes).
Voir ce dépôt comme un exemple de configuration Allstar utilisée. En tant qu'administrateur de l'organisation, envisagez un README.md avec quelques informations sur la façon dont Allstar est utilisé dans votre organisation.
Par défaut, les fichiers de configuration au niveau de l'organisation, tels que le fichier allstar.yaml
ci-dessus, sont censés se trouver dans un dépôt .allstar. Si ce dépôt n'existe pas,
alors le répertoire allstar du dépôt .github est utilisé comme emplacement secondaire.
Pour clarifier, pour allstar.yaml :
| Priorité | Dépôt | Chemin |
|---|---|---|
| Primaire | .allstar | allstar.yaml |
| Secondaire | .github | allstar/allstar.yaml |
Ceci est également vrai pour les fichiers de configuration au niveau de l'organisation pour les politiques individuelles, comme décrit ci-dessous.
Allstar recherchera également les configurations de politique au niveau du dépôt dans le
dépôt .allstar de l'organisation, dans le répertoire portant le même nom que le
dépôt. Cette configuration est utilisée indépendamment du fait que le "remplacement de dépôt"
soit désactivé.
Par exemple, Allstar recherchera la configuration de politique pour un dépôt donné
myapp dans l'ordre suivant :
Pour les fichiers de configuration de politique et Allstar au niveau de l'organisation, vous pouvez spécifier le champ
baseConfig pour spécifier un autre dépôt qui contient la configuration Allstar de
base. Cela s'explique mieux avec un exemple.
Supposons que vous ayez plusieurs organisations GitHub, mais que vous souhaitiez maintenir une
configuration Allstar unique. Votre organisation principale est "acme", et le dépôt
acme/.allstar contient allstar.yaml :```yaml
optConfig:
optOutStrategy: true
issueLabel: allstar-acme
issueFooter: Issue created by Acme security team.
Vous avez également une organisation satellite GitHub nommée « acme-sat ». Vous souhaitez réutiliser la configuration principale, mais appliquer quelques modifications supplémentaires en désactivant Allstar sur certains dépôts. Le dépôt `acme-sat/.allstar` contient `allstar.yaml` :```yaml
baseConfig: acme/.allstar
optConfig:
optOutRepos:
- acmesat-one
- acmesat-two
Cela utilisera toute la configuration de acme/.allstar comme configuration de base, mais appliquera ensuite les modifications du fichier actuel par‑dessus la configuration de base. La méthode utilisée est décrite comme un JSON Merge Patch. Le baseConfig doit être un <org>/<repository> GitHub.
Voir CONTRIBUTING.md
| Désinscription (Recommandée) optOutStrategy = true | Inscription optOutStrategy = false |
|---|
| Comportement par défaut | Tous les dépôts sont activés | Aucun dépôt n'est activé |
| Ajout manuel de dépôts | Ajouter manuellement des dépôts désactive Allstar sur ces dépôts | Ajouter manuellement des dépôts active Allstar sur ces dépôts |
| Configurations supplémentaires | optOutRepos : Allstar sera désactivé sur les dépôts listés optOutPrivateRepos : si vrai, Allstar sera désactivé sur tous les dépôts privés optOutPublicRepos : si vrai, Allstar sera désactivé sur tous les dépôts publics (optInRepos : ce paramètre sera ignoré) | optInRepos : Allstar sera activé sur les dépôts listés (optOutRepos : ce paramètre sera ignoré) |
| Surcharge de dépôt | Si vrai : Les dépôts peuvent se désinscrire des mesures de contrôle de leur organisation en utilisant
les paramètres de leur propre fichier de dépôt. Les paramètres d'inscription au niveau de l'organisation qui
s'appliquent à ce dépôt sont ignorés. Si faux : les dépôts ne peuvent pas se désinscrire des mesures de contrôle configurées au niveau de l'organisation. | Si vrai : Les dépôts peuvent s'inscrire aux mesures de contrôle de leur organisation même
s'ils ne sont pas configurés pour le dépôt au niveau de l'organisation. Les paramètres de désinscription
au niveau de l'organisation qui s'appliquent à ce dépôt sont ignorés. Si faux : Les dépôts ne peuvent pas s'inscrire aux mesures de contrôle si ce n'est pas configuré au niveau de l'organisation. |
| Dépôt | Chemin | Condition |
|---|
myapp | .allstar/branch_protection.yaml | Lorsque le « remplacement de dépôt » est autorisé. |
.allstar | myapp/branch_protection.yaml | Tout le temps. |
.allstar | branch_protection.yaml | Tout le temps. |
.github | allstar/myapp/branch_protection.yaml | Si le dépôt .allstar n'existe pas. |
.github | allstar/branch_protection.yaml | Si le dépôt .allstar n'existe pas. |