Personnalisation de votre configuration avancée pour l’analyse de code

À propos de la configuration de l’code scanning

Vous pouvez exécuter l’code scanning sur GitHub Enterprise Server, en utilisant GitHub Actions ou à partir de votre système d’intégration continue (CI). Pour plus d’informations, consultez « Écriture de workflows » ou « Utilisation de l'analyse du code avec votre système CI existant ».

Avec la configuration avancée pour code scanning vous pouvez personnaliser un flux de travail code scanning pour un contrôle plus précis de votre configuration. Pour plus d’informations, consultez « Configuration de la configuration par défaut pour l’analyse du code ».

L’analyse CodeQL n’est qu’un seul type d’code scanning que vous pouvez effectuer dans GitHub. GitHub Marketplace sur GitHub.com contient d’autres workflows d’code scanning que vous pouvez utiliser. 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.

1. Dans votre dépôt, accédez au fichier de workflow que vous souhaitez modifier.
2. En haut à droite de la vue des fichiers, pour ouvrir l’éditeur de workflow, cliquez sur .
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).

Pour plus d’informations sur la modification de fichiers de workflow, consultez « Écriture de workflows ».

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. L’événement pull_request n’est pas déclenché si la demande de tirage a été ouverte à partir d’une duplication (fork) privée

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 « Analyse sur poussée ».

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'

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

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

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.

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

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. Vous spécifiez le 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]

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

Vous devez vous assurer que Git se trouve dans la variable PATH de vos exécuteurs auto-hébergés. 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, 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.

- uses: github/codeql-action/init@v3
  with:
    db-location: '${{ github.runner_temp }}/my_location'

- uses: github/codeql-action/init@v3
  with:
    db-location: '${{ github.runner_temp }}/my_location'

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 « Utilisation 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. La valeur par défaut est actuellement ${{ github.runner_temp }}/codeql_databases.

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
• Swift

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

CodeQL utilise les identificateurs de langue suivants :

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 « Exécution de variantes de tâches dans un workflow ».

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-typescript', 'python']

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', '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@v3
  with:
    languages: c-cpp, csharp, python

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

Définir les gravités d’alerte qui provoquent un échec de vérification d’une demande de tirage

Lorsque vous activez code scanning sur les demandes de tirage (pull request), la vérification échoue uniquement si une ou plusieurs alertes de gravité error, ou de gravité de sécurité critical ou high sont détectées. La vérification réussit si des alertes avec une gravité ou une gravité de sécurité inférieure sont détectées. Pour les codebases importants, il peut être souhaitable que la vérification code scanning échoue si des alertes sont détectées, de sorte que l’alerte doit être corrigée ou ignorée avant la fusion des modifications du code. Pour plus d’informations sur les niveaux de gravité, consultez « À propos des niveaux de gravité d’alerte et de gravité de sécurité ».

Vous pouvez modifier les niveaux d’alerte de gravité et de gravité de sécurité qui provoquent un échec de la vérification. Pour plus d’informations, consultez « Modification de la configuration d’installation par défaut ».

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@v3
      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"

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v3
      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 Server 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-typescript, os: linux} produisent la catégorie .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/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.

Extension de la couverture de CodeQL avec des packs de modèles CodeQL

Si votre codebase dépend d'une bibliothèque ou d'un cadre qui n'est pas reconnu par les requêtes standard dans CodeQL, vous pouvez étendre la couverture de CodeQL dans votre flux de travail code scanning en spécifiant des packs de modèles CodeQL publiés. Pour plus d'informations sur la création de vos propres packs de modèles, consultez « Création et utilisation de packs CodeQL ».

Pour ajouter un ou plusieurs packs de modèles CodeQL publiés, indiquez-les dans l'entrée with: packs: de la section uses: github/codeql-action/init@v3 du flux de travail. 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 « Utilisation de secrets dans GitHub Actions ».

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

Dans cet exemple, les requêtes par défaut seront exécutées pour Java, ainsi que les requêtes d'une version supérieure ou égale au 7.8.9 et inférieure au 7.9.0 de pack de requêtes my-company/my-java-queries. Les dépendances modélisées dans la dernière version du pack de modèles my-repo/my-java-model-pack seront disponibles à la fois pour les requêtes par défaut et pour celles en my-company/my-java-queries.

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 exécuter des requêtes supplémentaires si elles font partie d’un pack CodeQL publié sur le Container registry GitHub ou d’un pack CodeQL 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 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.

Utilisation des packs de requêtes

Pour ajouter un ou plusieurs packs de requêtes CodeQL, ajoutez une entrée with: packs: dans la section uses: github/codeql-action/init@v3 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 « Utilisation de secrets dans GitHub Actions ».

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 Server 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@v3
  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

- uses: github/codeql-action/init@v3
  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@v3. Cette entrée accepte une liste de propriétés url, packageset token, comme indiqué ci-dessous.

- uses: github/codeql-action/init@v3
  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 }}

    

- uses: github/codeql-action/init@v3
  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@v3.

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

- uses: github/codeql-action/init@v3
  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 }}

- uses: github/codeql-action/init@v3
  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.

Pour plus d’informations, consultez « Suites de requêtes CodeQL ».

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

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.

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@v3
  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

- uses: github/codeql-action/init@v3
  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@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

- uses: github/codeql-action/init@v3
  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@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

- uses: github/codeql-action/init@v3
  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

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

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

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

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

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

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

Lorsque des codebases sont analysées sans générer de code, vous pouvez restreindre code scanning aux fichiers dans des annuaires spécifiques en ajoutant un tableau paths au fichier de configuration. Vous pouvez également exclure les fichiers d’annuaires spécifiques de l’analyse en ajoutant un tableau paths-ignore. Vous pouvez utiliser cette option lorsque vous exécutez les actions CodeQL sur un langage interprété (Python, Ruby et JavaScript/TypeScript).

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

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

Pour les analyses dans lesquelles le code est généré, si vous souhaitez limiter l’code scanning à des annuaires 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 « Analyse du code 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 CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/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 CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Spécification des détails de configuration à l’aide de l’entrée config

Si vous préférez spécifier des détails de configuration supplémentaires dans le fichier de workflow, vous pouvez utiliser l’entrée config de la commande init de l’action CodeQL. La valeur de cette entrée doit être une chaîne YAML qui suit le format de fichier de configuration documenté dans « Utilisation d’un fichier de configuration personnalisé » ci-dessus.

Exemple de configuration

Cette étape d’un fichier de workflow GitHub Actions utilise une entrée config pour désactiver les requêtes par défaut, ajouter la suite de requêtes security-extended et exclure les requêtes étiquetées avec cwe-020.

- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

Vous pouvez utiliser la même approche pour spécifier toutes les options de configuration valides dans le fichier de workflow.

- uses: github/codeql-action/init@v3
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

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

Pour les langages compilés, l’action CodeQL génère la codebase pour créer une base de données CodeQL à des fins d’analyse. Par défaut, CodeQL utilise des étapes autobuild pour identifier la méthode de génération la plus probable pour la codebase. En cas d’échec de autobuild ou si vous souhaitez analyser un ensemble différent de fichiers source générés par le processus autobuild, vous devez supprimez ou commentez l’étape de génération automatique dans le workflow. Supprimez ensuite les marques de commentaire de l’étape run et spécifiez manuellement le processus de génération à utiliser. Pour C/C++, C#, Go, Java, et Swift, CodeQL va analyser 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 « Analyse du code 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 ».