Skip to main content

Personnalisation de l’analyse du code

Vous pouvez personnaliser la manière dont GitHub analyse le code de votre projet à la recherche de vulnérabilités et d’erreurs.

Who can use this feature

People with write permissions to a repository can customize code scanning for the repository.

Code scanning est disponible pour tous les dépôts publics sur GitHub.com. Pour utiliser code scanning dans un dépôt privé appartenant à une organisation, vous devez avoir une licence pour GitHub Advanced Security. Pour plus d’informations, consultez « À propos de GitHub Advanced Security ».

À propos de la configuration de l’code scanning

Vous pouvez exécuter l’code scanning sur GitHub Enterprise Cloud, en utilisant GitHub Actions ou à partir de votre système d’intégration continue (CI). Pour plus d’informations, consultez « À propos de GitHub Actions » ou « À propos de l’code scanning CodeQL dans votre système CI ».

La configuration par défaut et la configuration avancée de l’code scanning s’exécutent sur GitHub Actions. La configuration par défaut détecte automatiquement la meilleure configuration d’code scanning pour votre référentiel, tandis que la configuration avancée vous permet de personnaliser un workflow d’code scanning. Pour plus d’informations, consultez « Configuration de l’code scanning pour un référentiel ». Cet article décrit l’utilisation de la configuration avancée pour l’code scanning.

Avec la configuration avancée, vous pouvez modifier des workflows tels que le CodeQL analysis workflow de GitHub pour spécifier la fréquence des analyses, les langages ou les répertoires à analyser, et ce que l’code scanning doit rechercher dans votre code. Vous devrez peut-être également modifier le workflow si vous utilisez un ensemble spécifique de commandes pour compiler votre code.

L’analyse CodeQL n’est qu’un seul type d’code scanning que vous pouvez effectuer dans GitHub. GitHub Marketplace contient d’autres workflows d’code scanning que vous pouvez utiliser. Vous trouverez une sélection de ceux-ci dans la page « Démarrer avec l’code scanning », à laquelle vous pouvez accéder à partir de l’onglet Sécurité . Les exemples spécifiques fournis dans cet article concernent le fichier du CodeQL analysis workflow.

Modification d’un workflow d’code scanning

GitHub enregistre les fichiers de workflow dans le répertoire .github/workflows de votre dépôt. Vous pouvez trouver un flux de travail que vous avez ajouté en recherchant son nom de fichier. Par exemple, par défaut, le fichier de workflow pour l’code scanning CodeQL est appelé codeql-analysis.yml.

  1. Dans votre dépôt, accédez au fichier de workflow que vous souhaitez modifier.
  2. Dans le coin supérieur droit de l’affichage des fichiers, pour ouvrir l’éditeur de workflow, cliquez sur . Bouton Modifier le fichier de workflow
  3. Après avoir modifié le fichier, cliquez sur Démarrer la validation et complétez le formulaire « Valider les modifications ». Vous pouvez valider directement dans la branche active ou créer une branche et démarrer une demande de tirage (pull request). Commiter la mise à jour dans le workflow codeql.yml

Pour plus d’informations sur la modification des fichiers de workflow, consultez « Découvrir GitHub Actions ».

Configuration de la fréquence

Vous pouvez configurer le CodeQL analysis workflow pour analyser le code selon une planification ou quand des événements spécifiques se produisent dans un dépôt.

L’analyse du code quand un utilisateur pousse (push) une modification et chaque fois qu’une demande de tirage est créée empêche les développeurs d’introduire de nouvelles vulnérabilités et erreurs dans le code. L’analyse du code selon une planification vous informe des dernières vulnérabilités et erreurs que GitHub, les chercheurs en sécurité et la communauté découvrent, même quand des développeurs ne gèrent pas activement le dépôt.

Analyse sur poussée

Par défaut, le CodeQL analysis workflow utilise l’événement on.push pour déclencher une analyse du code à chaque poussée vers la branche par défaut du dépôt et toutes les branches protégées. Pour que l’code scanning soit déclenchée sur une branche spécifiée, le workflow doit exister dans cette branche. Pour plus d’informations, consultez « Syntaxe de workflow pour GitHub Actions ».

Si vous effectuez une analyse sur poussée, les résultats s’affichent sous l’onglet Sécurité de votre dépôt. Pour plus d’informations, consultez « Gestion des alertes d’analyse du code pour votre dépôt ».

Par ailleurs, quand une analyse on:push retourne des résultats pouvant être mappés à une demande de tirage ouverte, ces alertes s’affichent automatiquement sur la demande de tirage au même endroit que les autres alertes de demande de tirage. Les alertes sont identifiées en comparant l’analyse existante de la tête de la branche à l’analyse de la branche cible. Pour plus d’informations les alertes d’code scanning dans les demandes de tirage, consultez « Triage des alertes d’code scanning dans les demandes de tirage ».

Analyse des demandes de tirage

Le CodeQL analysis workflow par défaut utilise l’événement pull_request pour déclencher une analyse de code sur les demandes de tirage ciblées sur la branche par défaut. Si une demande de tirage provient d’une duplication privée, l’événement pull_request n’est déclenché que si vous avez sélectionné l’option « Exécuter des workflows à partir de demandes de tirage de duplication » dans les paramètres du dépôt. Pour plus d’informations, consultez « Gestion des paramètres GitHub Actions pour un dépôt ».

Pour plus d’informations sur l’événement pull_request, consultez « Événements qui déclenchent des workflows ».

Si vous analysez des demandes de tirage, les résultats s’affichent sous forme d’alertes dans une vérification des demandes de tirage. Pour plus d’informations, consultez « Triage des alertes d’analyse du code dans les demandes de tirage ».

L’utilisation du déclencheur pull_request, configuré pour analyser le commit de fusion de la demande de tirage au lieu du commit de tête, produit des résultats plus efficaces et plus exacts que l’analyse de la tête de la branche pour chaque poussée. Toutefois, si vous utilisez un système d’intégration continue et de livraison continue (CI/CD) qui ne peut pas être configuré pour se déclencher sur des demandes de tirage, vous pouvez toujours utiliser le déclencheur on:push et l’code scanning mappera les résultats aux demandes de tirage ouvertes sur la branche et ajoutera les alertes en tant qu’annotations à la demande de tirage. Pour plus d’informations, consultez « Analyse sur poussée ».

Définition des gravités entraînant l’échec de la vérification des demandes de tirage (pull request)

Par défaut, seules les alertes ayant le niveau de gravité Error ou de sécurité Critical ou High entraînent un échec de la vérification de la requête de tirage, et une vérification aboutit toujours avec des alertes de gravité inférieure. Vous pouvez modifier les niveaux de gravité des alertes et de gravité de la sécurité qui entraînent l’échec de la vérification des demandes de tirage dans les paramètres de votre référentiel. Pour plus d’informations sur les niveaux de gravité, consultez « À propos des alertes d’analyse du code ».

  1. Dans , accédez à la page principale du dépôt. 1. Sous le nom de votre dépôt, cliquez sur Paramètres. Bouton Paramètres du dépôt

  2. Dans la section « Sécurité » de la barre latérale, cliquez sur Sécurité et analyse du code.

  3. Sous « Analyse du code », à droite de « Vérifier l’échec », utilisez le menu déroulant pour sélectionner le niveau de gravité qui doit provoquer l’échec de la vérification d’une demande de tirage. Vérifier le paramètre d’échec

Prévention des analyses inutiles des demandes de tirage

Vous souhaiterez peut-être éviter qu’une analyse du code ne soit déclenchée sur des demandes de tirage spécifiques ciblées sur la branche par défaut, quels que soient les fichiers qui ont été modifiés. Vous pouvez configurer cela en spécifiant on:pull_request:paths-ignore ou on:pull_request:paths dans le workflow d’code scanning. Par exemple, si les seules modifications apportées à une demande de tirage concernent des fichiers portant l’extension .md ou .txt, vous pouvez utiliser le tableau paths-ignore suivant.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

Remarques

  • on:pull_request:paths-ignore et on:pull_request:paths définissent les conditions qui déterminent si les actions du workflow s’exécutent sur une demande de tirage. Ils ne déterminent pas les fichiers qui sont analysés quand les actions sont exécutées. Quand une demande de tirage contient des fichiers qui ne sont pas mis en correspondance par on:pull_request:paths-ignore ou on:pull_request:paths, le workflow exécute les actions et analyse tous les fichiers modifiés dans la demande de tirage, y compris ceux mis en correspondance par on:pull_request:paths-ignore ou on:pull_request:paths, sauf si les fichiers ont été exclus. Pour plus d’informations sur l’exclusion de fichiers de l’analyse, consultez « Spécification des répertoires à analyser ».
  • Pour les fichiers de workflow d’code scanning CodeQL, n’utilisez pas les mots clés paths-ignore ou paths avec l’événement on:push, car cela risque de provoquer des analyses manquantes. Pour obtenir des résultats précis, l’code scanning CodeQL doit pouvoir comparer les nouvelles modifications à l’analyse du commit précédent.

Pour plus d’informations sur l’utilisation de on:pull_request:paths-ignore et on:pull_request:paths pour déterminer quand un workflow s’exécute pour une demande de tirage, consultez « Syntaxe de workflow pour GitHub Actions ».

Analyse selon une planification

Si vous utilisez le CodeQL analysis workflow par défaut, celui-ci analyse le code dans votre dépôt une fois par semaine, en plus des analyses déclenchées par les événements. Pour ajuster cette planification, modifiez la valeur cron dans le flux de travail. Pour plus d’informations, consultez « Syntaxe de workflow pour GitHub Actions ».

Remarque : GitHub exécute uniquement des travaux planifiés qui se trouvent dans des workflows sur la branche par défaut. La modification de la planification dans un workflow sur une autre branche n’a aucun effet tant que vous n’avez pas fusionné la branche dans la branche par défaut.

Exemple

L’exemple suivant montre un CodeQL analysis workflow pour un dépôt donné qui a une branche par défaut appelée main et une branche protégée appelée protected.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

Ce flux de travail analyse les éléments suivants :

  • Chaque envoi (push) vers la branche par défaut et la branche protégée
  • Chaque demande de tirage (pull request) sur la branche par défaut
  • La branche par défaut tous les lundis à 14:20 UTC

Spécification d’un système d’exploitation

Si la compilation de votre code nécessite un système d’exploitation spécifique, vous pouvez configurer ce dernier dans votre CodeQL analysis workflow. Modifiez la valeur de jobs.analyze.runs-on pour spécifier le système d’exploitation de la machine qui exécute vos actions d’code scanning.

jobs:
  analyze:
    name: Analyze
    runs-on: [ubuntu-latest]

Si vous choisissez d’utiliser un exécuteur auto-hébergé pour l’analyse du code, vous pouvez spécifier un système d’exploitation en utilisant une étiquette appropriée comme second élément d’un tableau à deux éléments, après self-hosted.

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

L’code scanning CodeQL prend en charge les dernières versions d’Ubuntu, de Windows et de macOS. Les valeurs classiques de ce paramètre sont donc : ubuntu-latest, windows-latest et macos-latest. Pour plus d’informations, consultez « Choix de l’exécuteur pour un travail » et « Utilisation d’étiquettes avec des exécuteurs auto-hébergés ».

Si vous utilisez un exécuteur auto-hébergé, vous devez vous assurer que Git se trouve dans la variable PATH. Pour plus d’informations, consultez « À propos des exécuteurs auto-hébergés » et « Ajout d’exécuteurs auto-hébergés ».

Pour obtenir les spécifications recommandées (RAM, cœurs de processeur et disque) pour l’exécution de l’analyse CodeQL sur des machines auto-hébergées, consultez « Ressources matérielles recommandées pour l’exécution de CodeQL ».

Spécification de l’emplacement des bases de données CodeQL

En général, vous n’avez pas besoin de vous soucier de l’endroit où le CodeQL analysis workflow place les bases de données CodeQL, car les bases de données créées sont automatiquement trouvées au cours des étapes ultérieures. Toutefois, si vous écrivez une étape de workflow personnalisée qui nécessite que la base de données CodeQL se trouve dans un emplacement de disque spécifique, par exemple pour charger la base de données en tant qu’artefact de workflow, vous pouvez spécifier cet emplacement avec le paramètre db-location sous l’action init.

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

Le CodeQL analysis workflow s’attend à ce que le chemin fourni dans db-location soit accessible en écriture et qu’il n’existe pas ou qu’il s’agisse d’un répertoire vide. Lors de l’utilisation de ce paramètre dans un travail en cours d’exécution sur un exécuteur auto-hébergé ou avec un conteneur Docker, il incombe à l’utilisateur de s’assurer que le répertoire choisi est effacé entre les exécutions ou que les bases de données sont supprimées une fois qu’elles ne sont plus nécessaires. Cela n’est pas nécessaire pour les travaux s’exécutant sur les exécuteurs hébergés par GitHub, qui obtiennent une nouvelle instance et un système de fichiers propre chaque fois qu’ils s’exécutent. Pour plus d’informations, consultez « À propos des exécuteurs hébergés par GitHub ».

Si ce paramètre n’est pas utilisé, le CodeQL analysis workflow crée les bases de données dans un emplacement temporaire de son choix.

Changement des langages qui sont analysés

L’code scanning CodeQL détecte automatiquement le code écrit dans les langages pris en charge.

  • C/C++
  • C#
  • Go
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby

Remarque :

  • L’analyse CodeQL pour Kotlin est actuellement en version bêta. Durant la version bêta, l’analyse de Kotlin est moins complète que l’analyse CodeQL des autres langages.
  • Utilisez java pour analyser le code écrit en Java, Kotlin ou les deux.
  • Utilisez javascript pour analyser le code écrit en JavaScript, TypeScript ou les deux.

Pour plus d’informations, consultez la documentation disponible sur le site web de CodeQL : « Langages et frameworks pris en charge ».

Le fichier du CodeQL analysis workflow par défaut contient une matrice appelée language qui répertorie les langages de votre dépôt qui sont analysés. CodeQL remplit automatiquement cette matrice quand vous ajoutez l’code scanning à un dépôt. L’utilisation de la matrice language optimise CodeQL pour exécuter chaque analyse en parallèle. Nous recommandons que tous les flux de travail adoptent cette configuration en raison des avantages en matière de performances de la parallélisation des builds. Pour plus d’informations sur les matrices, consultez « Utilisation d’une matrice pour vos travaux ».

Si votre référentiel contient du code dans plusieurs des langages pris en charge, vous pouvez choisir les langages que vous souhaitez analyser. Il existe plusieurs raisons pour lesquelles vous pouvez souhaiter empêcher l’analyse d’un langage. Par exemple, le projet peut avoir des dépendances dans un langage autre que celui du corps principal de votre code, et vous préférerez peut-être ne pas voir les alertes pour ces dépendances.

Si votre workflow utilise la matrice language, CodeQL est codé en dur pour analyser uniquement les langages de la matrice. Pour modifier les langages que vous souhaitez analyser, modifiez la valeur de la variable de la matrice. Vous pouvez supprimer un langage pour empêcher son analyse ou vous pouvez ajouter un langage qui n’était pas présent dans le référentiel lors de la configuration de l’code scanning. Par exemple, si le référentiel ne contenait initialement que du code JavaScript quand l’code scanning a été configurée et que vous avez ajouté ultérieurement du code Python, vous devrez ajouter python à la matrice.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

Si votre workflow ne contient pas de matrice appelée language, CodeQL est configuré pour exécuter l’analyse de manière séquentielle. Si vous ne spécifiez pas de langages dans le workflow, CodeQL détecte automatiquement et tente d’analyser les langages pris en charge dans le dépôt. Si vous souhaitez choisir les langages à analyser, sans utiliser de matrice, vous pouvez utiliser le paramètre languages sous l’action init.

- uses: github/codeql-action/init@v2
  with:
    languages: cpp, csharp, python

Analyse des dépendances Python

Pour les exécuteurs hébergés par GitHub qui utilisent Linux uniquement, le CodeQL analysis workflow essaie d’installer automatiquement les dépendances Python afin d’obtenir plus de résultats pour l’analyse CodeQL. Vous pouvez contrôler ce comportement en spécifiant le paramètre setup-python-dependencies de l’action appelée par l’étape « Initialiser CodeQL ». Par défaut, ce paramètre a la valeur true :

  • Si le dépôt contient du code écrit en Python, l’étape « Initialiser CodeQL » installe les dépendances nécessaires sur l’exécuteur hébergé par GitHub. Si l’installation automatique réussit, l’action définit également la variable d’environnement CODEQL_PYTHON sur le fichier exécutable Python qui inclut les dépendances.

  • Si le dépôt n’a pas de dépendances Python ou que les dépendances sont spécifiées de manière inattendue, vous recevez un avertissement et l’action se poursuit avec les travaux restants. L’action peut s’exécuter correctement même en cas de problèmes d’interprétation des dépendances, mais les résultats peuvent être incomplets.

Vous pouvez également installer manuellement les dépendances Python sur n’importe quel système d’exploitation. Vous devez ajouter setup-python-dependencies et le définir sur false ainsi que définir CODEQL_PYTHON sur l’exécutable Python qui inclut les dépendances, comme indiqué dans cet extrait de workflow :

jobs:
  CodeQL-Build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ];
          then pip install -r requirements.txt;
          fi
          # Set the `CODEQL-PYTHON` environment variable to the Python executable
          # that includes the dependencies
          echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: python
          # Override the default behavior so that the action doesn't attempt
          # to auto-install Python dependencies
          setup-python-dependencies: false

Configuration d’une catégorie pour l’analyse

Utilisez category pour distinguer plusieurs analyses pour le même outil et le même commit, mais effectuées dans différents langages ou différentes parties du code. La catégorie que vous spécifiez dans votre workflow est incluse dans le fichier de résultats SARIF.

Ce paramètre est particulièrement utile si vous utilisez des monodépôts et que vous avez plusieurs fichiers SARIF pour différents composants du monodépôt.

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

Si vous ne spécifiez pas de paramètre category dans votre workflow, GitHub Enterprise Cloud génère un nom de catégorie pour vous, en fonction du nom du fichier de workflow déclenchant l’action, du nom de l’action et de toutes les variables de matrice. Par exemple :

  • Le workflow .github/workflows/codeql-analysis.yml et l’action analyze produisent la catégorie .github/workflows/codeql.yml:analyze.
  • Le workflow .github/workflows/codeql-analysis.yml, l’action analyze et les variables de matrice {language: javascript, os: linux} produisent la catégorie .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux.

La valeur category apparaît en tant que propriété <run>.automationDetails.id dans SARIF v2.1.0. Pour plus d’informations, consultez « Prise en charge de SARIF pour l’code scanning ».

La catégorie que vous spécifiez ne remplace pas les détails de l’objet runAutomationDetails dans le fichier SARIF, le cas échéant.

Exécution de requêtes supplémentaires

Quand vous utilisez CodeQL pour analyser du code, le moteur d’analyse de CodeQL génère une base de données à partir du code et exécute des requêtes sur celle-ci. L’analyse CodeQL utilise un ensemble de requêtes par défaut, mais vous pouvez spécifier d’autres requêtes à exécuter en plus des requêtes par défaut.

Vous pouvez aussi spécifier les requêtes à exclure de l’analyse ou à inclure dans l’analyse. L’utilisation d’un fichier de configuration personnalisé est alors nécessaire. Pour plus d’informations, consultez « Utilisation d’un fichier de configuration personnalisé » et « Exclusion de requêtes spécifiques de l’analyse » ci-dessous.

Vous pouvez exécuter des requêtes supplémentaires si elles font partie d’un pack CodeQL (bêta) publié sur le Container registry GitHub ou d’un pack QL stocké dans un dépôt. Pour plus d’informations, consultez « À propos de l’code scanning avec CodeQL ».

Les options disponibles pour spécifier les requêtes supplémentaires à exécuter sont les suivantes :

  • packs pour installer un ou plusieurs packs de requêtes CodeQL (bêta), et exécuter les requêtes ou la suite de requêtes par défaut de ces packs.
  • queries pour spécifier un seul fichier .ql, un répertoire contenant plusieurs fichiers .ql, un fichier de définition de suite de requêtes .qls ou une combinaison de ces possibilités. Pour plus d’informations sur les définitions de suites de requêtes, consultez « Création de suites de requêtes CodeQL ».

Vous pouvez utiliser à la fois packs et queries dans le même workflow.

Nous vous déconseillons de référencer les suites de requêtes directement à partir du dépôt github/codeql, par exemple github/codeql/cpp/ql/src@main. Ces requêtes doivent être recompilées et peuvent ne pas être compatibles avec la version de CodeQL actuellement active sur GitHub Actions, ce qui peut entraîner des erreurs lors de l’analyse.

Utilisation de packs de requêtes CodeQL

Remarque : La fonctionnalité de gestion des packages CodeQL ainsi que les packs CodeQL sont en version bêta et peuvent être amenés à changer.

Pour ajouter un ou plusieurs packs de requêtes CodeQL (bêta), ajoutez une entrée with: packs: dans la section uses: github/codeql-action/init@v2 du workflow. Dans packs, vous spécifiez un ou plusieurs packages à utiliser et, éventuellement, la version à télécharger. Si vous ne spécifiez pas de version, la version la plus récente est téléchargée. Si vous voulez utiliser des packages qui ne sont pas disponibles publiquement, vous avez besoin de définir la variable d’environnement GITHUB_TOKEN sur une secret qui a accès aux packages. Pour plus d’informations, consultez « Authentification dans un workflow » et « Secrets chiffrés ».

Remarque : Pour les workflows qui génèrent des bases de données CodeQL pour plusieurs langages, vous devez à la place spécifier les packs de requêtes CodeQL dans un fichier de configuration. Pour plus d’informations, consultez « Spécification de packs de requêtes CodeQL » ci-dessous.

Dans l’exemple ci-dessous, scope correspond au compte d’organisation ou personnel qui a publié le package. Quand le workflow s’exécute, les quatre packs de requêtes CodeQL sont téléchargés à partir de GitHub Enterprise Cloud et la suite de requêtes ou les requêtes par défaut pour chaque pack s’exécutent :

  • La dernière version de pack1 est téléchargée et toutes les requêtes par défaut sont exécutées.
  • La version 1.2.3 de pack2 est téléchargée et toutes les requêtes par défaut sont exécutées.
  • La dernière version de pack3 qui est compatible avec la version 3.2.1 est téléchargée et toutes les requêtes sont exécutées.
  • La version 4.5.6 de pack4 est téléchargée et seules les requêtes trouvées dans path/to/queries sont exécutées.
- uses: github/codeql-action/init@v2
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Téléchargement des packs CodeQL à partir de GitHub Enterprise Server

Si votre workflow utilise des packs publiés sur une installation de GitHub Enterprise Server, vous devez indiquer à votre workflow où les trouver. Pour ce faire, utilisez l’entrée registries de l’action github/codeql-action/init@v2. Cette entrée accepte une liste de propriétés url, packageset token, comme indiqué ci-dessous.

- uses: github/codeql-action/init@v2
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

    

Comme les modèles de package dans la liste des registres sont examinés dans l’ordre, vous devez généralement placer les modèles de package les plus spécifiques en premier. Les valeurs de token doivent être un personal access token (classic) généré par l’instance GitHub à partir de laquelle vous faites le téléchargement avec l’autorisation read:packages.

Notez le | après le nom de la propriété registries. C’est un détail important, car les entrées GitHub Actions peuvent uniquement accepter des chaînes. L’utilisation de | convertit le texte suivant en chaîne, analysée ensuite par l’action github/codeql-action/init@v2.

Utilisation des requêtes dans des packs QL

Pour ajouter une ou plusieurs requêtes, ajoutez une entrée with: queries: dans la section uses: github/codeql-action/init@v2 du workflow. Si les requêtes se trouvent dans un dépôt privé, utilisez le paramètre external-repository-token pour spécifier un jeton doté de l’accès nécessaire pour extraire le dépôt privé.

- uses: github/codeql-action/init@v2
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Vous pouvez également spécifier des suites de requêtes dans la valeur de queries. Les suites de requêtes sont des collections de requêtes, généralement regroupées par objectif ou langage.

Les suites de requêtes suivantes sont intégrées à CodeQL code scanning et sont disponibles pour utilisation.

Suite de requêtesDescription
security-extendedRequêtes issues de la suite par défaut, plus requêtes de gravité et de précision moindres
security-and-qualityRequêtes de security-extended, plus requêtes de maintenabilité et de fiabilité.

Lorsque vous spécifiez une suite de requêtes, le moteur d’analyse CodeQL exécute l’ensemble par défaut de requêtes, ainsi que toutes les requêtes supplémentaires définies dans la suite de requêtes supplémentaire. Les suites de requêtes security-extended et security-and-quality pour JavaScript contiennent des requêtes expérimentales. Pour plus d’informations, consultez « À propos des alertes code scanning ».

Utilisation de fichiers de configuration personnalisés

Si vous utilisez aussi un fichier de configuration pour des paramètres personnalisés, tous les packs ou requêtes supplémentaires spécifiés dans votre workflow sont utilisés à la place de ceux spécifiés dans le fichier de configuration. Si vous souhaitez exécuter l’ensemble combiné de packs ourequêtes supplémentaires, préfixez la valeur de packs ou queries dans le workflow avec le symbole +. Pour plus d’informations, consultez « Utilisation d’un fichier de configuration personnalisé ».

Dans l’exemple suivant, le symbole + garantit que les packs et requêtes supplémentaires spécifiés sont utilisés ensemble avec tous ceux spécifiés dans le fichier de configuration référencé.

- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

Utilisation d’un fichier de configuration personnalisé

Un fichier de configuration personnalisé est une autre façon de spécifier des packs et des requêtes supplémentaires à exécuter. Vous pouvez également utiliser le fichier pour désactiver les requêtes par défaut, exclure ou inclure des requêtes spécifiques, et spécifier les répertoires à analyser pendant l’analyse.

Dans le fichier de workflow, utilisez le paramètre config-file de l’action init pour spécifier le chemin d’accès au fichier de configuration que vous souhaitez utiliser. Cet exemple charge le fichier de configuration ./.github/codeql/codeql-config.yml.

- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml

Le fichier de configuration peut être situé dans le référentiel que vous analysez ou dans un référentiel externe. L’utilisation d’un référentiel externe vous permet de spécifier des options de configuration pour plusieurs référentiels à un même emplacement. Quand vous référencez un fichier de configuration situé dans un dépôt externe, vous pouvez utiliser la syntaxe OWNER/REPOSITORY/FILENAME@BRANCH . Par exemple : octo-org/shared/codeql-config.yml@main.

Si le fichier de configuration se trouve dans un référentiel privé externe, utilisez le paramètre external-repository-token de l’action init pour spécifier un jeton qui a accès au référentiel privé.

- uses: github/codeql-action/init@v2
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Les paramètres dans le fichier de configuration sont écrits au format YAML.

Spécification de packs de requêtes CodeQL

Remarque : La fonctionnalité de gestion des packages CodeQL ainsi que les packs CodeQL sont en version bêta et peuvent être amenés à changer.

Vous spécifiez des packs de requêtes CodeQL dans un tableau. Notez que le format est différent du format utilisé par le fichier de workflow.

packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

Le format complet pour spécifier un pack de requêtes est scope/name[@version][:path]. version et path sont facultatifs. version est la plage de versions de semver. Si le paramètre est absent, la dernière version est utilisée. Pour plus d’informations sur les plages semver, consultez la Documentation de semver sur npm.

Si vous avez un workflow qui génère plusieurs bases de données CodeQL, vous pouvez spécifier les packs de requêtes CodeQL à exécuter dans un fichier de configuration personnalisé à l’aide d’une carte imbriquée de packs.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Spécification de requêtes supplémentaires

Vous spécifiez des requêtes supplémentaires dans un tableau queries. Chaque élément du tableau contient un paramètre uses avec une valeur qui identifie un fichier de requête unique, un répertoire contenant des fichiers de requête ou un fichier de définition de suite de requêtes.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Si vous le souhaitez, vous pouvez attribuer un nom à chaque élément de tableau, comme indiqué dans les exemples de fichiers de configuration ci-dessous. Pour plus d’informations sur les requêtes supplémentaires, consultez « Exécution de requêtes supplémentaires » ci-dessus.

Désactivation des requêtes par défaut

Si vous souhaitez uniquement exécuter des requêtes personnalisées, vous pouvez désactiver les requêtes de sécurité par défaut à l’aide de disable-default-queries: true.

Exclusion de requêtes spécifiques de l’analyse

Vous pouvez ajouter les filtres exclude et include à votre fichier de configuration personnalisé afin de spécifier les requêtes que vous souhaitez exclure ou inclure dans l’analyse.

Cela est utile si vous souhaitez exclure, par exemple :

  • Des requêtes spécifiques des suites par défaut (security, security-extended et security-and-quality).
  • Des requêtes spécifiques dont les résultats ne vous intéressent pas.
  • Toutes les requêtes qui génèrent des avertissements et des recommandations.

Vous pouvez utiliser des filtres exclude similaires à ceux du fichier de configuration ci-dessous pour exclure les requêtes que vous souhaitez supprimer de l’analyse par défaut. Dans l’exemple de fichier de configuration ci-dessous, les deux requêtes js/redundant-assignment et js/useless-assignment-to-local sont exclues de l’analyse.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Pour rechercher l’ID d’une requête, vous pouvez cliquer sur l’alerte dans la liste des alertes affichée sous l’onglet Sécurité. La page des détails de l’alerte s’ouvre alors. Le champ Rule ID contient l’ID de requête. Pour plus d’informations sur la page des détails de l’alerte, consultez « À propos des alertes d’code scanning ».

Conseils :

  • L’ordre des filtres est important. La première instruction de filtre qui apparaît après les instructions relatives aux requêtes et les packs de requêtes détermine si les requêtes sont incluses ou exclues par défaut.
  • Les instructions suivantes sont exécutées dans l’ordre et les instructions qui apparaissent plus tard dans le fichier sont prioritaires sur les instructions précédentes.

Vous trouverez un autre exemple illustrant l’utilisation de ces filtres dans la section « Exemples de fichiers de configuration ».

Pour plus d’informations sur l’utilisation des filtres exclude et include dans votre fichier de configuration personnalisé, consultez « Création de suites de requêtes CodeQL ». Pour plus d’informations sur les métadonnées de requête sur lesquelles vous pouvez définir un filtre, consultez « Métadonnées des requêtes CodeQL ».

Spécification des répertoires à analyser

Pour les langages interprétés que CodeQL prend en charge (Python et JavaScript/TypeScript), vous pouvez limiter l’code scanning aux fichiers de répertoires spécifiques en ajoutant un tableau paths au fichier de configuration. Vous pouvez exclure les fichiers de répertoires spécifiques de l’analyse en ajoutant un tableau paths-ignore.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Remarque :

  • Les mots clés paths et paths-ignore, utilisés dans le contexte du fichier de configuration de l’code scanning, ne doivent pas être confondus avec les mêmes mots clés quand ils sont utilisés pour on.<push|pull_request>.paths dans un workflow. Lorsqu’ils sont utilisés pour modifier on.<push|pull_request> dans un workflow, ils déterminent si les actions sont exécutées lorsqu’un utilisateur modifie le code dans les répertoires spécifiés. Pour plus d’informations, consultez « Syntaxe de workflow pour GitHub Actions ».
  • Les caractères de motif de filtre ?, +, [, ] et ! ne sont pas pris en charge et seront pris en compte littéralement.
  •           Les caractères `**` ne peuvent être qu’au début ou à la fin d’une ligne, ou placés entre barres obliques, et vous ne pouvez pas mélanger `**` et autres caractères. Par exemple, `foo/**`, `**/foo` et `foo/**/bar` sont des syntaxes autorisées, mais `**foo` ne l'est pas. Toutefois, vous pouvez utiliser des étoiles uniques avec d’autres caractères, comme indiqué dans l’exemple. Vous devez utiliser des guillemets pour tout ce qui contient un caractère `*`.
    

Pour les langages compilés, si vous souhaitez limiter l’code scanning à des répertoires spécifiques dans votre projet, vous devez spécifier les étapes de génération appropriées dans le workflow. Les commandes que vous devez utiliser pour exclure un répertoire de la génération dépendent de votre système de génération. Pour plus d’informations, consultez « Configuration du workflow CodeQL pour les langages compilés ».

Vous pouvez analyser rapidement de petites parties d’un référentiel lorsque vous modifiez du code dans des répertoires spécifiques. Vous devez à la fois exclure des répertoires dans vos étapes de génération et utiliser les mots clés paths-ignore et paths pour on.<push|pull_request> dans votre workflow.

Exemples de fichiers de configuration

Ce fichier config ajoute la suite de requêtes security-and-quality à la liste des requêtes exécutées par CodeQL au moment de l’analyse de votre code. Pour plus d’informations sur les suites de requêtes disponibles, consultez « Exécution de requêtes supplémentaires ».

name: "My CodeQL config"

queries:
  - uses: security-and-quality

Le fichier config suivant désactive les requêtes par défaut et spécifie un ensemble de requêtes personnalisées à exécuter à la place. Il configure également CodeQL pour analyser les fichiers du répertoire src (par rapport à la racine), à l’exception du répertoire src/node_modules et des fichiers dont le nom finit par .test.js. Les fichiers présents dans src/node_modules et les fichiers dont le nom finit par .test.js sont donc exclus de l’analyse.

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src 
paths-ignore: 
  - src/node_modules
  - '**/*.test.js'

Le fichier de configuration suivant exécute uniquement les requêtes qui génèrent des alertes dont le niveau de gravité est Erreur. La configuration sélectionne d’abord toutes les requêtes par défaut, toutes les requêtes dans ./my-queries et la suite par défaut dans codeql/java-queries, puis elle exclut toutes les requêtes qui génèrent des avertissements ou des recommandations.

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Configuration de l’code scanning pour les langages compilés

Pour les langages compilés pris en charge, vous pouvez utiliser l’action autobuild dans le CodeQL analysis workflow pour générer votre code. Cela vous évite d’avoir à spécifier des commandes de build explicites pour C/C++, C#, Go, Kotlin et Java. Pour ces langages, CodeQL analyse les fichiers sources générés dans votre dépôt. Pour ces langages, vous pouvez désactiver autobuild et utiliser à la place des commandes de build personnalisées afin d’analyser uniquement les fichiers générés par ces commandes personnalisées.

Si autobuild échoue, ou si vous voulez analyser un ensemble de fichiers sources différents de ceux générés par le processus autobuild, vous devez supprimer l’étape autobuild du workflow et ajouter manuellement les étapes de génération. Pour les projets C/C++, C#, Go, Kotlin, et Java, CodeQL analyse le code source généré par vos étapes de génération spécifiées. Pour plus d’informations sur la configuration de l’code scanning CodeQL pour les langages compilés, consultez « Configuration du workflow CodeQL pour les langages compilés ».

Chargement de données d’code scanning sur GitHub

GitHub peut afficher les données d’analyse du code générées en externe par un outil tiers. Vous pouvez charger les données d’analyse du code avec l’action upload-sarif. Pour plus d’informations, consultez « Chargement d’un fichier SARIF sur GitHub ».