Autorisations minimales pour le workflow et chaque tâche

GITHUB_TOKEN permet à GitHub Actions de s’authentifier pour effectuer des opérations dans un dépôt. La clé permissions configure ses droits pour l’ensemble du workflow ou pour des tâches individuelles, afin que chacune ne reçoive que les capacités nécessaires.

Pour commencer, GitHub recommande de définir l’autorisation par défaut de GITHUB_TOKEN sur la lecture du contenu du dépôt, puis de l’élargir lorsqu’une tâche précise en a besoin. Si un workflow ne fait que consulter des fichiers, il n’a pas besoin de droits d’écriture par commodité.

Les autorisations doivent correspondre à l’opération : créer une issue nécessite issues: write ; d’autres tâches peuvent nécessiter des droits différents. Vous pouvez définir une base au niveau du workflow et ajuster les autorisations de la tâche qui effectue l’opération. N’élargissez pas les droits de toutes les tâches pour répondre à un besoin localisé.

Les actions peuvent aussi accéder au jeton par le contexte github.token, même s’il ne leur est pas transmis comme entrée. Limitez donc les autorisations et examinez les actions exécutées dans chaque tâche. Ne pas transmettre explicitement secrets.GITHUB_TOKEN ne prouve pas qu’une action n’a pas accès au jeton.

Exemple de workflow en lecture seule

Le modèle suivant se déclenche lorsque des changements sont poussés vers main et accorde un accès en lecture au contenu du dépôt. Avant de l’utiliser, remplacez actions/checkout@<SHA_COMPLET_VÉRIFIÉ> par un SHA complet réel et vérifié ; le marqueur n’est pas une référence exécutable.

Modèle adaptable : remplacez le marqueur par un SHA complet vérifié avant d’enregistrer et d’exécuter le workflow.

name: Vérifier les changements

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verifier:
    runs-on: ubuntu-latest
    steps:
      - name: Récupérer le code
        uses: actions/checkout@<SHA_COMPLET_VÉRIFIÉ>

      - name: Exécuter les vérifications
        run: ./scripts/check.sh

Épingler une action à un SHA complet réduit le risque qu’une étiquette change de cible, mais ne prouve pas que le code est sûr. Vérifiez que le SHA appartient au dépôt attendu et examinez le code des actions utilisées. GitHub présente les fichiers de verrouillage des dépendances comme une protection plus robuste que le seul épinglage des SHA.

Adaptez les autorisations au travail réel. Si vous n’avez pas besoin de consulter le dépôt, vérifiez si contents: read est nécessaire. Si vous ajoutez une opération d’écriture, identifiez l’autorisation requise et accordez-la à la tâche concernée, au lieu d’élargir les droits de tout le workflow.

Accorder l’écriture uniquement à la tâche concernée

Pour créer une issue avec GitHub CLI, une tâche a besoin de l’autorisation issues: write. L’exemple documenté par GitHub configure ce droit pour la tâche et fournit le jeton à l’outil au moyen de la variable d’environnement GH_TOKEN.

name: Créer une issue

on:
  workflow_dispatch:

jobs:
  creer-issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Créer une issue avec GitHub CLI
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh issue create --title "Tâche automatisée" --body "Examiner le résultat du workflow."

N’inscrivez pas de secrets directement dans les fichiers du workflow et ne les affichez pas dans les journaux. GitHub avertit que le masquage automatique n’est pas garanti pour les valeurs transformées. Si un identifiant apparaît sans protection dans un journal, supprimez le journal concerné et faites tourner l’identifiant.

Si GITHUB_TOKEN ne fournit pas les autorisations nécessaires, GitHub documente des solutions de remplacement : un jeton d’installation de GitHub App ou un jeton d’accès personnel stocké comme secret. Appliquez le principe du moindre privilège et limitez les personnes pouvant accéder à ces identifiants.

Pull requests externes et tâches privilégiées

Le contenu d’une pull request externe doit être traité comme une entrée non fiable : son auteur peut contrôler le code, les scripts et les dépendances exécutés pendant les tests. GitHub Security Lab indique que, par défaut, l’événement pull_request bloque les droits d’écriture et l’accès aux secrets du dépôt cible pour les demandes provenant de forks.

pull_request_target s’exécute dans le contexte du dépôt cible et peut disposer de droits d’écriture ainsi que d’un accès aux secrets. Le risque apparaît lorsque ce contexte privilégié est associé à la récupération et à l’exécution de code externe : les scripts, tests et installations de paquets contrôlés par l’auteur de la PR peuvent exécuter du code dans l’environnement du workflow.

N’exécutez pas de code non fiable dans une tâche privilégiée. pull_request_target peut convenir à des tâches limitées, comme l’ajout d’étiquettes ou de commentaires, à condition que le workflow n’exécute pas de code contrôlé par la pull request. Un checkout explicite ne prouve pas à lui seul qu’une exploitation a eu lieu : le contenu peut aussi être traité comme une donnée passive, mais il ne doit pas contrôler les processus de compilation, de test ou d’installation.

Pour tester du code externe, utilisez un workflow non privilégié avec pull_request. Si vous devez ensuite publier un résultat avec des droits d’écriture, vous pouvez séparer les tests de cette tâche au moyen de workflow_run. Les artefacts issus de la pull request restent des données non fiables : le workflow privilégié peut lire les informations nécessaires, mais ne doit pas exécuter les binaires ni les scripts provenant de ces artefacts.

Examinez également les pull requests déjà ouvertes lorsque vous avez modifié un workflow vulnérable. GitHub Security Lab avertit qu’une demande en attente peut continuer à utiliser la version du workflow en vigueur au moment de son ouverture ; il peut être nécessaire de la fermer ou de la mettre à jour de façon contrôlée.

Pull requests externos y tareas privilegiadas El contenido de un pull request externo debe tratarse como entrada no confiable: quien lo presenta puede controlar código, scripts y d...
Illustration éditoriale de BytePreview

Entrées, actions et secrets

Les données d’une pull request peuvent parvenir au shell par les expressions du workflow. Pour réduire le risque d’injection, GitHub recommande de placer la valeur externe dans une variable d’environnement intermédiaire et d’utiliser cette variable dans le script, plutôt que d’interpoler directement la donnée dans la commande.

Les actions tierces doivent elles aussi être examinées. Les tâches peuvent partager des informations ou des ressources, et une action compromise peut affecter le jeton et les secrets auxquels elle a accès. Examinez le code de chaque action et vérifiez qu’elle n’envoie pas de secrets vers des destinations inattendues et ne les écrit pas dans les journaux.

Pour les workflows qui accèdent à des services cloud compatibles, GitHub recommande d’envisager l’authentification OIDC plutôt que de stocker des identifiants de longue durée sous forme de secrets. Si une tâche a besoin des secrets d’un environnement, vous pouvez définir des réviseurs obligatoires afin que l’accès dépende d’une approbation.

Limitez les secrets disponibles à ceux qui sont indispensables et auditez leur utilisation. Le masquage des journaux est utile, mais ne remplace pas la séparation entre code fiable et non fiable ; faites tourner les identifiants s’ils sont exposés.

Liste de contrôle pour un workflow existant

Commencez par identifier l’événement qui déclenche chaque tâche, puis suivez la chaîne jusqu’aux autorisations, aux actions, aux secrets et aux données d’entrée. Ne recherchez pas uniquement secrets.GITHUB_TOKEN : une action peut accéder au jeton par github.token.

  • La tâche peut-elle fonctionner en lecture plutôt qu’en écriture ?
  • Le droit d’écriture est-il limité à la tâche qui effectue l’opération ?
  • Un workflow privilégié traite-t-il du code ou des artefacts provenant d’une pull request externe ?
  • Les actions sont-elles épinglées à des SHA complets vérifiés et leur code est-il examiné ?
  • Les valeurs externes atteignent-elles le shell par des variables d’environnement intermédiaires ?
  • Les secrets sont-ils indispensables et leur présence dans les journaux est-elle évitée ?

Dans les dépôts publics, accordez une attention particulière aux exécuteurs autohébergés. GitHub avertit que du code non fiable peut les compromettre de façon persistante. À l’inverse, GitHub décrit ses exécuteurs hébergés comme des machines virtuelles éphémères et propres ; cette description ne constitue pas une garantie pour les exécuteurs autohébergés et ne supprime pas la nécessité de limiter les autorisations et les secrets.

Comme règle opérationnelle, combinez lecture par défaut, écriture selon les besoins et isolation du code externe. Après avoir testé un workflow, examinez les journaux pour vérifier que les informations sensibles n’ont pas été exposées et faites tourner tout identifiant compromis.