Options de configuration de flux de travail pour l’analyse du code

Modifiez votre fichier de flux de travail pour configurer la façon dont la configuration avancée analyse le code dans votre projet pour détecter les vulnérabilités et les erreurs.

Qui peut utiliser cette fonctionnalité ?

Utilisateurs avec accès en écriture if advanced setup is already enabled

Dans cet article

Remarque

Votre administrateur de site doit activer l’code scanning avant de pouvoir utiliser cette fonctionnalité. Si vous souhaitez utiliser GitHub Actions pour analyser votre code, l’administrateur de site doit également activer GitHub Actions et configurer l’infrastructure nécessaire. Pour plus d’informations, consultez « Configuration de l’analyse de code pour votre appliance ».

Remarque

Cet article décrit les fonctionnalités disponibles avec la version de l’action CodeQL et le pack CodeQL CLI associé inclus dans la mise en production initiale de cette version de GitHub Enterprise Server. Si votre entreprise utilise une version plus récente de l’action CodeQL, consultez la version GitHub Enterprise Cloud de cet article pour obtenir plus d’informations sur les dernières fonctionnalités. Pour plus d’informations sur l’utilisation de la dernière version, consultez Configuration de l’analyse de code pour votre appliance.

Prerequisites

Vous devez utiliser la configuration avancée pour code scanning et être capable de modifier le fichier de flux de travail dans lequel votre configuration est définie.

Les exemples fournis dans cet article concernent le Workflow d’analyse CodeQL fichier. Par défaut, ce fichier est défini à .github/workflows/codeql-analysis.yml.

Fréquence d’analyse

Vous pouvez configurer l’analyse du Workflow d’analyse CodeQL code selon une planification ou lorsque des événements spécifiques se produisent dans un référentiel.

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 lorsque les développeurs ne gèrent pas activement le référentiel.

Analyse sur poussée

Par défaut, l’événement Workflow d’analyse CodeQL utilise l’événement on:push pour déclencher une analyse de code sur chaque push vers la branche par défaut du référentiel et toutes les branches protégées. Pour code scanning être déclenché sur une branche spécifiée, le flux de travail doit exister dans cette branche. Pour plus d’informations, consultez « Syntaxe de flux de travail pour GitHub Actions ».

Si vous effectuez une analyse push, les résultats s’affichent sous l’onglet Security de votre référentiel. Pour plus d’informations, consultez « Évaluation 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 code scanning les alertes dans les pull requests, consultez Triage des alertes d’analyse du code dans les demandes de tirage (pull request).

Analyse des demandes de tirage

La valeur par défaut Workflow d’analyse CodeQL utilise l’événement pull_request pour déclencher une analyse de code sur les demandes d’extraction 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 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 CI/CD qui ne peut pas être configuré pour se déclencher sur les pull requests, vous pouvez toujours utiliser le on:push déclencheur, et code scanning mappe les résultats aux pull requests ouvertes sur la branche et ajoute les alertes en tant qu'annotations sur le pull request. 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 le configurer en spécifiant on:pull_request:paths-ignore ou on:pull_request:paths dans le code scanning flux de travail. 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'

Remarque

          `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](#specifying-directories-to-scan).

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 flux de travail pour GitHub Actions.

Analyse selon une planification

Si vous utilisez la valeur par défaut Workflow d’analyse CodeQL, le flux de travail analyse le code dans votre référentiel une fois par semaine, en plus des analyses déclenchées par des événements. Pour ajuster ce calendrier, modifiez la valeur cron pour l’événement on.schedule dans le flux de travail. Pour plus d’informations, consultez « Syntaxe de flux de travail pour GitHub Actions ».

Remarque

Cet événement déclenche l’exécution d’un flux de travail uniquement si le fichier de flux de travail existe sur la branche par défaut.

Exemple

L’exemple suivant montre un Workflow d’analyse CodeQL référentiel particulier 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

Système d’exploitation

Remarque

  • L’analyse du code Swift utilise des exécuteurs macOS par défaut.
  • Code scanning du code Swift n’est pas pris en charge pour les exécuteurs qui font partie d’un ARC Actions Runner Controller, car les exécuteurs ARC utilisent uniquement Linux et Swift nécessite des exécuteurs macOS. Toutefois, vous pouvez avoir un mélange d’exécuteurs ARC et d’exécuteurs macOS auto-hébergés. Pour plus d’informations, consultez « Actions Runner Controller ».

Si votre code nécessite une compilation d’un système d’exploitation spécifique, vous pouvez configurer le système d’exploitation dans votre Workflow d’analyse CodeQL. Modifiez la valeur de jobs.analyze.runs-on pour spécifier le système d'exploitation de l'ordinateur qui exécute votre code scanning action. Vous spécifiez le système d’exploitation à l’aide d’une étiquette appropriée comme deuxième élément d’un tableau à deux éléments, après self-hosted.

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

          CodeQL
          code scanning prend en charge les dernières versions d’Ubuntu, Windows et macOS. Les valeurs classiques de ce paramètre sont donc : `ubuntu-latest`, `windows-latest` et `macos-latest`. Pour plus d’informations, consultez « [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) » et « [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners) ».

          Vous devez vous assurer que Git se trouve dans la variable PATH sur vos exécuteurs auto-hébergés. Pour plus d’informations, consultez « [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) » et « [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners) ».

Pour obtenir les spécifications recommandées (RAM, cœurs d’UC et disque) pour l’exécution CodeQL d’une analyse auto-hébergées, consultez Ressources matérielles recommandées pour l’exécution de CodeQL.

          CodeQL emplacement de la base de données

En règle générale, vous n’avez pas besoin de vous soucier de l’emplacement Workflow d’analyse CodeQLCodeQL des bases de données, car les étapes ultérieures recherchent automatiquement les bases de données créées par les étapes précédentes. Toutefois, si vous écrivez une étape de flux de travail personnalisée qui nécessite que la CodeQL base de données se trouve dans un emplacement de disque spécifique, par exemple pour charger la base de données en tant qu’artefact de flux de travail, vous pouvez spécifier cet emplacement à l’aide du db-location paramètre sous l’action init .

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

Le Workflow d’analyse CodeQL s'attendra à ce que le chemin fourni dans db-location soit accessible en écriture, et à ce qu'il n'existe pas ou soit 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 GitHubdes exécuteurs hébergés, qui obtiennent une nouvelle instance et un système de fichiers propre chaque fois qu’ils s’exécutent. Pour plus d’informations, consultez « Exécuteurs hébergés par GitHub ».

Si ce paramètre n’est pas utilisé, il Workflow d’analyse CodeQL crée des bases de données dans un emplacement temporaire de son propre choix. Actuellement, la valeur par défaut est ${{ github.runner_temp }}/codeql_databases.

Langues à analyser

          CodeQL
          code scanning prend en charge le code écrit dans les langues suivantes :
  • C/C++
  • C#
  • Go
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Rust (préversion publique)
  • Workflows rapides

Remarque

  • Utilisez java-kotlin pour analyser le code écrit en Java, Kotlin ou les deux.
  • Utilisez javascript-typescript 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.

          CodeQL utilise les identificateurs de langue suivants :
LangageIdentificateurIdentificateurs alternatifs facultatifs (le cas échéant)
C/C++c-cppc ou cpp
C#csharp
Gogo
Java/Kotlinjava-kotlinjava ou kotlin
JavaScript/TypeScriptjavascript-typescriptjavascript ou typescript
Pythonpython
Rubyruby
Rust (préversion publique)rust
Swiftswift

Remarque

Si vous spécifiez l'un des identificateurs alternatifs, cela équivaut à l'utilisation de l'identificateur de langue standard. Par exemple, la spécification javascript au lieu de javascript-typescript n’exclut pas l’analyse du code TypeScript. Vous pouvez également utiliser un fichier de configuration personnalisé pour exclure des fichiers de l’analyse à l’aide du paramètre paths-ignore. Pour plus d’informations, consultez Utilisation d’un fichier de configuration personnalisé et Spécification des répertoires à analyser.

Ces identificateurs de langage peuvent être utilisés comme arguments pour l’entrée languages de l’action init. Nous recommandons de ne fournir qu’un seul langage comme argument :

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

Le fichier par défaut Workflow d’analyse CodeQL créé après la configuration avancée de l’installation pour l’analyse du code avec CodeQL définit une matrice contenant une propriété nommée language qui répertorie les langues de votre référentiel qui seront analysées. Cette matrice a été automatiquement préremplie avec les langages pris en charge détectés dans votre référentiel. L’utilisation de la language matrice permet CodeQL d’exécuter chaque analyse de langage en parallèle et de personnaliser l’analyse pour chaque langue. Dans une analyse individuelle, le nom du langage de la matrice est fourni à l’action init comme argument pour l’entrée languages. Nous recommandons que tous les flux de travail adoptent cette configuration. Pour plus d’informations sur les matrices, consultez Exécution de variantes de tâches dans un workflow.

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

Si votre flux de travail utilise la language matrice, CodeQL il analyse uniquement les langues de la matrice. Pour changer les langages que vous souhaitez analyser, modifiez la configuration de la matrice. Vous pouvez supprimer un langage pour empêcher son analyse. 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. Vous pouvez également ajouter une langue qui n’était pas présente dans le référentiel lors code scanning de la configuration. Par exemple, si le référentiel contenait initialement uniquement JavaScript lors code scanning de la configuration et que vous avez ajouté ultérieurement du code Python, vous devez ajouter python à la matrice.

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

Pour les langages compilés, la matrice peut également être utilisée pour configurer le mode de génération à utiliser pour l’analyse en modifiant la valeur de la propriété build-mode. Pour plus d’informations sur les modes de génération, consultez Analyse CodeQL pour les langages compilés.

Si votre flux de travail ne fournit pas d’argument à l’entrée languages de l’action init , CodeQL il est configuré pour exécuter des analyses séquentiellement. Dans ce cas, CodeQL détecte et tente automatiquement d’analyser toutes les langues prises en charge dans le référentiel. Selon la taille du référentiel et le nombre de langues, cela peut prendre beaucoup de temps. Si l’analyse d’un langage échoue dans ce mode, l’analyse de tous les langages échoue. Par conséquent, nous ne recommandons pas cette configuration.

Remarque

Lors de l’analyse séquentielle des langues, le mode de génération par défaut de chaque langage sera utilisé. Sinon, si vous fournissez une étape autobuild explicite, toutes les langues prenant en charge le mode autobuild l’utiliseront, tandis que les autres continueront d’utiliser leur mode par défaut. Si une configuration du mode de génération plus complexe que celle-ci est nécessaire, vous devrez configurer une matrice.

Gravité des alertes pour les échecs de vérification

Vous pouvez utiliser des ensembles de règles pour empêcher la fusion des demandes de tirage (pull request) lorsque l’une des conditions suivantes est remplie :

  • Un outil requis détecte une alerte code scanning dont la gravité est spécifiée dans l’ensemble de règles.
  • L’analyse d’un outil requis est toujours en cours.
  • Un outil requis n’est pas configuré pour le référentiel.

Pour plus d’informations, consultez « Définir la protection contre la fusion d’analyse du code ». Pour plus d’informations générales sur les ensembles de règles, consultez À propos des ensembles de règles.

Catégorie d’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@v4
      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 category paramètre dans votre flux de travail, GitHub génère un nom de catégorie pour vous, en fonction du nom du fichier de flux de travail qui déclenche l’action, le nom de l’action et 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.

          CodeQL packs de modèles

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

Remarque

Les packs de modèles CodeQL sont actuellement en préversion publique et peuvent faire l’objet de modifications. Les packs de modèles sont pris en charge pour l’analyse C/C++, C#, Java/Kotlin, Python, et Ruby.

L’éditeur de modèle CodeQL de l’extension CodeQL pour Visual Studio Code prend en charge les dépendances de modélisation pour C#, Java/Kotlin, Python et Ruby.

Utilisation de CodeQL paquets de modèles

Pour ajouter un ou plusieurs packs de modèles publiés CodeQL, spécifiez-les à l’intérieur de l’entrée with: packs: dans la section uses: github/codeql-action/init@v4 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 « Utiliser GITHUB_TOKEN pour l’authentification dans les flux de travail » et « Utilisation de secrets dans GitHub Actions ».

YAML
- uses: github/codeql-action/init@v4
  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 sont exécutées pour Java, ainsi que les requêtes d’une version supérieure ou égale à 7.8.9 et inférieures à 7.9.0 du 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.

Requêtes non par défaut

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.

Conseil

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 fichiers de configuration personnalisés 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 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](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/).

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

Utilisation des packs de requêtes

Pour ajouter un ou plusieurs CodeQL packs de requêtes, ajoutez une with: packs: entrée dans la uses: github/codeql-action/init@v4 section 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 « Utiliser GITHUB_TOKEN pour l’authentification dans les flux de travail » et « Utilisation de secrets dans GitHub Actions ».

Remarque

Pour les flux de travail qui génèrent des CodeQL bases de données pour plusieurs langues, vous devez plutôt spécifier les CodeQL packs de requêtes dans un fichier de configuration. Pour plus d’informations, consultez Spécification des packs de CodeQL requêtes ci-dessous.

Dans l’exemple ci-dessous, scope correspond au compte d’organisation ou personnel qui a publié le package. Lorsque le flux de travail s'exécute, les quatre CodeQL packs de requêtes sont téléchargés depuis GitHub et les requêtes par défaut ou la suite de requêtes 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@v4
  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 éventuellement devenir trop ancienne pour être utilisée efficacement par le moteur par défaut CodeQL 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 Informations de référence sur les packs de requêtes CodeQL.

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

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

YAML
- uses: github/codeql-action/init@v4
  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 pour token doivent être générées par l'instance GitHub à partir de laquelle vous téléchargez, avec la permission read:packages.

Notez le | après le nom de la propriété registries. Cela est important, car GitHub Actions les entrées ne peuvent accepter que des chaînes. L’utilisation de | convertit le texte suivant en chaîne, qui sera analysé ultérieurement par l’action github/codeql-action/init@v4.

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@v4 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@v4
  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ê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é.

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 voulez exécuter l’ensemble combiné de packs ou requêtes supplémentaires, préfixez la valeur des packs ou queries dans le workflow avec le symbole +. Pour plus d’informations, consultez les fichiers de configuration personnalisés.

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

Fichiers de configuration personnalisés

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 les requêtes spécifiques et spécifier les répertoires à analyser au cours de 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@v4
  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@v4
  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 CodeQL packs de requêtes 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 disposez d’un flux de travail qui génère plusieurs CodeQL bases de données, vous pouvez spécifier les CodeQL packs de requêtes à 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

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

Remarque

Les modèles de menace se trouvent actuellement en préversion publique et peuvent être amenés à changer. Pendant la préversion publique, les modèles de risque ne sont pris en charge que par l’analyse pour Java/Kotlin et C#.

Le modèle de risque par défaut inclut les sources distantes de données non fiables. Vous pouvez étendre le CodeQL modèle de menace pour inclure des sources locales de données non approuvées (par exemple : arguments de ligne de commande, variables d’environnement, systèmes de fichiers et bases de données) en spécifiant threat-models: local dans un fichier de configuration personnalisé. Si vous étendez le modèle de risques, celui par défaut sera également utilisé.

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 Requêtes non par défaut 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 sous l’onglet Security . 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.

Conseil

  • 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

Lorsque les bases de code sont analysées sans générer le code, vous pouvez restreindre code scanning les fichiers dans des répertoires spécifiques en ajoutant un paths tableau au fichier de configuration. Vous pouvez également exclure les fichiers de répertoires spécifiques de l’analyse en ajoutant un tableau paths-ignore. Vous pouvez utiliser cette option lorsque vous exécutez les CodeQL actions sur un langage interprété (Python, Ruby et JavaScript/TypeScript) ou lorsque vous analysez un langage compilé sans générer le code (actuellement pris en charge pour C# et Java).

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

Remarque

  • Les mots clés paths et paths-ignore, utilisés dans le contexte de code scanning fichier de configuration, à ne pas être confondus avec ces mêmes mots-clés lorsqu'ils sont utilisés pour on.<push|pull_request>.paths dans un flux de travail. 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 flux de travail 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 l’analyse où le code est généré, si vous souhaitez limiter code scanning des répertoires spécifiques dans votre projet, vous devez spécifier les étapes de génération appropriées dans le flux de travail. 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 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 pour une utilisation, consultez Requêtes non par défaut.

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

Détails de la configuration

Si vous préférez spécifier des détails de configuration supplémentaires dans le fichier de flux de travail, 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 les fichiers de configuration personnalisés ci-dessus.

Exemple de configuration

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

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      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.

Conseil

Vous pouvez partager une configuration entre plusieurs référentiels à l’aide de GitHub Actions variables. L’un des avantages de cette approche est que vous pouvez mettre à jour la configuration dans un emplacement unique sans modifier le fichier de workflow.

Dans l’exemple suivant, vars.CODEQL_CONF est une GitHub Actions variable. Sa valeur peut être le contenu de n’importe quel fichier de configuration valide. Pour plus d’informations, consultez « Stocker des informations dans des variables ».

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

Langues compilées

Pour les langages compilés, vous pouvez décider de la façon dont l’action CodeQL crée une base de données à des fins d’analyse CodeQL . Pour obtenir des informations sur les options de build disponibles, consultez Analyse CodeQL pour les langages compilés.

Chargement de données

          GitHub peut afficher des 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 « [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github) ».