• Contexte
• Options au niveau de l'organisation
• Options d'installation
  • Créer votre application GitHub
  • Créer votre dépôt de contrôle .allstar
  • Exécuter Allstar en tant qu'action GitHub
  • Exécuter Allstar en tant que démon de service
• Migration depuis l'application hébergée

Politiques et actions

• Actions
• Politiques

Avancé

• Définitions de configuration
• Exemples de configurations
• Exécuter votre propre instance d'Allstar

Contribuer

• Contribuer

Vue d'ensemble

Qu'est-ce qu'Allstar ?

Allstar est une application GitHub qui surveille en continu les organisations ou dépôts GitHub pour vérifier leur conformité aux 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, en 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 les politiques de sécurité à surveiller au niveau de l'organisation et du dépôt, ainsi que la manière de 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.

Nouveautés d'Allstar

Désactiver les problèmes indésirables

Si Allstar crée des problèmes que vous ne souhaitez pas, suivez ces instructions pour vous désengager.

Pour commencer

Contexte

Allstar est hautement configurable. Il existe trois principaux niveaux de contrôle :

• Niveau organisation : Les administrateurs d'organisation peuvent choisir d'activer Allstar sur :
  • tous les dépôts de l'organisation ;
  • la plupart des dépôts, à l'exception de certains qui sont désengagés ;
  • seulement quelques dépôts qui sont engagés.

Ces configurations sont effectuées dans le dépôt .allstar de l'organisation.

• Niveau dépôt : Les mainteneurs de dépôts dans une organisation qui utilise Allstar peuvent choisir d'engager ou de désengager leur dépôt des mesures d'application au niveau de l'organisation. Remarque : ces contrôles au niveau du dépôt ne sont fonctionnels que lorsque la « substitution au niveau du dépôt » est autorisée dans les paramètres de l'organisation. Ces configurations sont effectuées dans le répertoire .allstar du dépôt.

• Niveau politique : Les administrateurs ou mainteneurs peuvent choisir les politiques activées sur des dépôts spécifiques et les actions qu'Allstar entreprend lorsqu'une politique est violée. Ces configurations sont effectuées dans un fichier yaml de politique situé soit dans le dépôt .allstar de l'organisation (administrateurs), soit dans le répertoire .allstar du dépôt (mainteneurs).

Options au niveau de l'organisation

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'engagement et de désengagement.

• La stratégie d'engagement (Opt In) 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'engagement si vous souhaitez appliquer des politiques uniquement sur un petit nombre de vos dépôts totaux, ou si vous souhaitez essayer Allstar sur un seul dépôt avant de l'activer sur d'autres. Depuis la version v4.3, les globs sont pris en charge pour ajouter facilement plusieurs dépôts avec un nom similaire.

• La stratégie de désengagement (Opt Out) (recommandée) active Allstar sur tous les dépôts et vous permet de sélectionner manuellement les dépôts à désengager des mesures d'application d'Allstar. Vous pouvez également choisir de désengager 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ésengager seulement un petit nombre de dépôts ou un type spécifique (c'est-à-dire public ou privé) de dépôt. Depuis la version v4.3, les globs sont pris en charge pour ajouter facilement plusieurs dépôts avec un nom similaire.

Options d'installation

Allstar agit sur votre organisation en tant qu'application GitHub : vous créez l'application, et vous exécutez le processus qui s'authentifie en son nom. La configuration comporte donc deux étapes communes à chaque déploiement — créer l'application et créer le dépôt de contrôle — puis un choix sur la manière de l'exécuter :

L'Action est l'option la plus légère des deux et c'est par là que la plupart des organisations devraient commencer ; vous pouvez passer à un démon plus tard sans modifier aucune configuration de politique.

Créer votre application GitHub

Une application est une identité de type utilisateur avec un ensemble d'autorisations dans votre organisation. Allstar a besoin d'un accès en lecture à la plupart des paramètres et contenus de fichiers pour détecter la conformité, et d'un accès en écriture aux problèmes et aux vérifications pour créer des problèmes et prendre en charge l'action block.

Suivez les instructions de l'opérateur - Créer une application GitHub, et notez l'ID de l'application et la clé privée. Les deux modes d'exécution en ont besoin.

Créer votre dépôt de contrôle .allstar

Allstar lit sa configuration à partir d'un dépôt nommé .allstar dans votre organisation.

Le moyen le plus rapide d'en créer un est à partir de l'exemple :

1. Ouvrez le dépôt d'exemple et cliquez sur le bouton « Utiliser ce modèle »
2. Dans le champ Nom du dépôt, saisissez .allstar
3. Cliquez sur « Créer un dépôt à partir du modèle »

Cela active toutes les politiques Allstar actuelles sur tous les dépôts en utilisant la stratégie de désengagement, avec l'action issue. Vous pouvez modifier tout cela ultérieurement.

Pour un contrôle granulaire dès le départ — choisir la stratégie d'engagement ou de désengagement et rédiger vous-même les fichiers de politique individuels — suivez plutôt les instructions d'installation manuelle.

Exécuter Allstar en tant qu'action GitHub

Cette option exécute Allstar en tant que tâche planifiée à l'aide de GitHub Actions, il n'y a donc aucune infrastructure à gérer au-delà de GitHub lui-même.

Suivez les instructions d'installation de GitHub Actions pour configurer une Action récurrente dans votre dépôt .allstar, la durcir et surveiller ses résultats.

Exécuter Allstar en tant que démon de service

Cette option exécute Allstar en tant que processus persistant, qui détecte et résout les violations en continu plutôt que selon un calendrier.

Voir les instructions de l'opérateur pour exécuter le processus, gérer les secrets, le dimensionnement et les variables d'environnement disponibles.

Migration depuis l'application hébergée

Si votre organisation utilisait l'application hébergée par l'OpenSSF, votre configuration est reprise telle quelle. Le dépôt de contrôle .allstar, allstar.yaml et chaque fichier de politique continuent de fonctionner sans modification ; ce que vous remplacez est uniquement le processus qui les lit.

Pour migrer :

1. Créez votre propre application GitHub et installez-la sur votre organisation avec le même accès aux dépôts que l'application hébergée.
2. Conservez votre dépôt .allstar existant exactement tel quel.
3. Exécutez Allstar en tant qu'Action ou en tant que démon.
4. Désinstallez allstar-app de votre organisation, s'il apparaît encore sous Paramètres -> Applications GitHub.

Les problèmes précédemment créés par l'application hébergée restent dans vos dépôts. Votre propre instance identifie ses problèmes par le même libellé allstar (ou votre issueLabel configuré), elle les adoptera donc et les fermera à mesure que les violations seront résolues, plutôt que d'en créer des doublons.

Politiques et actions

Actions

Chaque politique peut être configurée avec une action qu'Allstar entreprendra lorsqu'il détectera qu'un dépôt n'est pas conforme.

• log : Il s'agit de l'action par défaut, et elle a en réalité lieu pour toutes les actions. Tous les résultats et détails d'exécution des politiques sont journalisés. Les journaux ne sont actuellement visibles que par l'opérateur de l'application ; des plans pour les exposer sont en 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 notifié avec un commentaire toutes les 24 heures sans mises à jour (non configurable par l'utilisateur actuellement). 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 traitée, 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 toute PR du dépôt pour empêcher sa fusion si la vérification échoue.
• email : Allstar enverrait un e-mail aux administrateurs du dépôt.
• rpc : Allstar enverrait un rpc à un système spécifique à l'organisation.

Configuration de l'action

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 le libellé allstar par défaut utilisé 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é.

Politiques

Comme pour la configuration d'activation de l'application Allstar, toutes les politiques sont activées et configurées avec un fichier yaml situé soit dans le dépôt .allstar de l'organisation, soit dans le répertoire .allstar du dépôt. Comme pour l'application, les politiques sont engagées par défaut ; également, l'action log par défaut ne produira pas de résultats visibles. Une manière simple d'activer toutes les politiques est de créer un fichier yaml pour chaque politique avec le contenu :```yaml optConfig: optOutStrategy: true action: issue

Exigences :

• L'application GitHub Allstar doit avoir la permission de dépôt Code scanning alerts définie sur Read & write (portée API : security_events). Cette permission ne fait pas partie de celles dont Allstar a besoin par ailleurs, ajoutez-la donc à votre application avant d'activer le téléversement SARIF.
• Le téléversement SARIF est non bloquant : si le téléversement échoue (par exemple en raison de permissions manquantes), le contrôle de politique se poursuit normalement.
• La détection de changements compare le SHA du commit HEAD du dépôt et ignore l'analyse et le téléversement lorsque le dépôt n'a pas été poussé depuis le dernier téléversement.

Le téléversement SARIF fonctionne avec les deux façons d'exécuter Allstar : en tant que daemon de service ou en tant qu'action GitHub.

GitHub Actions

Le fichier de configuration de cette politique est nommé 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 garantir qu'ils sont conformes aux règles (par exemple, exiger, interdire) définies dans la configuration au niveau de l'organisation pour la politique.

Administrateurs de dépôts

Le fichier de configuration de cette politique est nommé 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 facultativement si les utilisateurs sont autorisés à être administrateurs (par opposition aux équipes).

Politiques futures

• Garantir que dependabot est activé.
• Vérifier que les dépendances sont épinglées/gelées.

Exemple de dépôt de configuration

Consultez ce dépôt comme exemple d'utilisation de la configuration Allstar. En tant qu'administrateur de l'organisation, envisagez un README.md contenant des informations sur la façon dont Allstar est utilisé dans votre organisation.

Avancé

Définitions de configuration

• Configuration d'activation au niveau de l'organisation
• Configuration d'activation de remplacement de dépôt

Emplacement secondaire de la configuration au niveau de l'organisation

Par défaut, les fichiers de configuration au niveau de l'organisation, tels que le fichier allstar.yaml ci-dessus, sont attendus dans un dépôt .allstar. Si ce dépôt n'existe pas, le répertoire allstar du dépôt .github est utilisé comme emplacement secondaire. Pour clarifier, pour allstar.yaml :

Cela vaut également pour les fichiers de configuration au niveau de l'organisation des politiques individuelles, comme décrit ci-dessous.

Configurations de politique de dépôt dans le dépôt de l'organisation

Allstar recherchera également les configurations de politique au niveau du dépôt dans le dépôt .allstar de l'organisation, sous 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 :

Emplacement de la configuration de base et de fusion au niveau de l'organisation

Pour les fichiers de configuration Allstar et de politique au niveau de l'organisation, vous pouvez spécifier le champ baseConfig pour désigner un autre dépôt contenant la configuration Allstar de base. Cela s'explique le mieux par 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.

Cela utilisera toute la configuration de acme/.allstar comme configuration de base, puis appliquera toutes 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.

Contributing

Voir CONTRIBUTING.md