Personnalisation de l’analyse du code

À 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 « Découvrir GitHub Actions » ou « À propos de l’analyse du code CodeQL dans votre système d’intégration continue ».

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 dépôt, tandis que la configuration avancée vous permet de personnaliser un workflow d’code scanning. Pour plus d’informations, consultez « Configuration de l’analyse du code pour un référentiel ». Cet article décrit l’utilisation de la configuration avancée de l’code scanning.

Avec la configuration avancée, vous pouvez modifier des workflows tels que le Workflow d’analyse CodeQL 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 Workflow d’analyse CodeQL.

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.

Dans votre dépôt, accédez au fichier de workflow que vous souhaitez modifier.
Dans le coin supérieur droit de l’affichage des fichiers, pour ouvrir l’éditeur de workflow, cliquez sur .
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).

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

Configuration de la fréquence

Vous pouvez configurer le Workflow d’analyse CodeQL 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 Workflow d’analyse CodeQL 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 « Workflow syntax for 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 référentiel ».

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 sur les alertes d’code scanning dans les demandes de tirage, consultez « Triage des alertes d’analyse du code dans les demandes de tirage (pull request) ».

Analyse des demandes de tirage

Le Workflow d’analyse CodeQL 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 de GitHub Actions pour un dépôt ».

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

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 (pull request) ».

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 « Personnalisation de l’analyse du code ».

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 ».

Dans GitHub.com, accédez à la page principale du dépôt. 1. Sous le nom de votre dépôt, cliquez sur Paramètres. Si vous ne voyez pas l’onglet « Paramètres », sélectionnez le menu déroulant et cliquez sur Paramètres.
Dans la section « Sécurité » de la barre latérale, cliquez sur Sécurité et analyse du code.
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.

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.

YAML

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 la façon d’exclure des fichiers de l’analyse, consultez « Spécification des répertoires à analyser ».

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 « Workflow syntax for GitHub Actions ».

Analyse selon une planification

Si vous utilisez le Workflow d’analyse CodeQL 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 « Workflow syntax for 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 Workflow d’analyse CodeQL 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.

YAML

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 Workflow d’analyse CodeQL. 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.

YAML

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.

YAML

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 découvrir 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 Workflow d’analyse CodeQL 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.

YAML

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

Le Workflow d’analyse CodeQL 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 Workflow d’analyse CodeQL 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

Remarques:

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 Workflow d’analyse CodeQL 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.

YAML

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.

YAML

- 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 Workflow d’analyse CodeQL 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 :

YAML

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.

YAML

    - 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’analyse du code ».

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’analyse du code 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 par jeton automatique » 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.

YAML

- 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

Remarque : Si vous spécifiez une version particulière d’un pack de requêtes à utiliser, sachez que la version que vous spécifiez peut finir par devenir trop ancienne pour être utilisée efficacement par le moteur CodeQL par défaut utilisé par l’action CodeQL. Pour garantir des performances optimales, si vous avez besoin de spécifier des versions de pack de requêtes exactes, envisagez de vérifier régulièrement si la version épinglée du pack de requêtes a besoin d’être incrémentée.

Pour plus d’informations sur la compatibilité des packs, consultez « Publication et utilisation de packs CodeQL ».

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.

YAML

- 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é.

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.

YAML

- uses: github/codeql-action/init@v2
  with:
    # Comma-separated list of queries / packs / suites to run. 
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

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

Suite de requêtes	Description
`security-extended`	Requêtes issues de la suite par défaut, plus requêtes de gravité et de précision moindres
`security-and-quality`	Requêtes de `security-extended`, plus requêtes de maintenabilité et de fiabilité.

Chacune de ces suites de requêtes contient un sous-ensemble différent des requêtes incluses dans le pack de requêtes CodeQL intégré pour ce langage. Les suites de requêtes sont générées automatiquement à l’aide des métadonnées de chaque requête. Pour plus d’informations, consultez « Métadonnées pour les requêtes CodeQL ».

Vous pouvez identifier les suites de requêtes dans lesquelles une requête est incluse en parcourant la documentation d’aide sur les requêtes CodeQL. Pour chaque requête, toutes les suites dans laquelle elle est incluse s’affichent en haut de la page avec les métadonnées de requête. Par exemple : Écriture de fichier arbitraire lors de l’extraction de zip (« Zip Slip ») et Falsification de requête côté client.

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 d’analyse du code ».

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é.

YAML

- 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.

YAML

- 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é.

YAML

- 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.

YAML

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.

YAML

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.

YAML

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.

YAML

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. 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’analyse du code ».

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, Ruby et JavaScript/TypeScript), vous pouvez limiter 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.

YAML

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 « Workflow syntax for 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 Workflow d’analyse CodeQL 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 ».

Personnalisation de l’analyse du code

Dans cet article

À propos de la configuration de l’code scanning

Modification d’un workflow d’code scanning

Configuration de la fréquence

Analyse sur poussée

Analyse des demandes de tirage

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

Prévention des analyses inutiles des demandes de tirage

Analyse selon une planification

Exemple

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

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

Changement des langages qui sont analysés

Analyse des dépendances Python

Configuration d’une catégorie pour l’analyse

Exécution de requêtes supplémentaires

Utilisation de packs de requêtes CodeQL

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

Utilisation des requêtes dans des packs QL

Utilisation de fichiers de configuration personnalisés

Utilisation d’un fichier de configuration personnalisé

Spécification de packs de requêtes CodeQL

Spécification de requêtes supplémentaires

Désactivation des requêtes par défaut

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

Spécification des répertoires à analyser

Exemples de fichiers de configuration

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

Chargement de données d’code scanning sur GitHub