Personnaliser votre workflow d’analyse du code avec CodeQL : Partie 1

  • 10 minutes

Les workflows d’analyse du code qui utilisent CodeQL offrent différentes options de configuration ajustables pour mieux répondre aux besoins de votre organisation.

Quand vous utilisez CodeQL pour analyser du code, le moteur d’analyse CodeQL génère une base de données à partir du code pour exécuter 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 (bêta) publié dans le registre de conteneurs GitHub ou un pack QL stocké dans un référentiel.

Il existe deux options pour spécifier les requêtes à exécuter avec l’analyse du code CodeQL :

  • Utilisation de votre workflow d’analyse du code
  • Utilisation d’un fichier de configuration personnalisé

Dans cette unité, vous allez découvrir comment modifier un fichier de workflow pour référencer des requêtes supplémentaires, comment utiliser des requêtes provenant de packs de requêtes, et comment combiner des requêtes provenant d’un fichier de workflow et d’un fichier de configuration personnalisé.

Spécifier des requêtes supplémentaires dans un fichier de workflow

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 pour ces packs.
  • queries pour spécifier un fichier .ql unique, un répertoire contenant plusieurs fichiers .ql, un fichier de définition de suite de requêtes .qls ou une combinaison.

Vous pouvez utiliser à la fois des packs et des requêtes dans le même workflow.

Nous vous déconseillons de référencer directement des suites de requêtes à partir du dépôt github/codeql, comme github/codeql/cpp/ql/src@main. Ces requêtes risquent de ne pas être compilées avec la même version de CodeQL que celle des autres requêtes, ce qui peut entraîner des erreurs lors de l’analyse.

Utiliser des packs de requêtes CodeQL

Remarque

La fonctionnalité de gestion des packages CodeQL, y compris les packs CodeQL, est actuellement en version bêta et est susceptible d’être modifiée.

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@v1 du workflow. Dans les packs, vous spécifiez un ou plusieurs packages à utiliser et éventuellement quelle 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 devez définir la variable d’environnement GITHUB_TOKEN sur un secret qui a accès aux packages.

Dans l’exemple suivant, l’étendue correspond au compte d’organisation ou personnel qui a publié le package. Quand le workflow s’exécute, les trois packs de requêtes CodeQL sont téléchargés depuis de GitHub, et les requêtes ou la suite de requêtes par défaut de chaque pack s’exécutent. Dans l’exemple suivant, chacun des packs de la liste est téléchargé en fonction de leurs spécifications :

  • La dernière version de l’application 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 compatible pack3 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

Remarque

Pour les workflows qui génèrent des bases de données CodeQL pour plusieurs langages, vous devez plutôt spécifier les packs de requêtes CodeQL dans un fichier de configuration.

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

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

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

Les suites de requêtes suivantes sont intégrées à l’analyse du code CodeQL et peuvent être utilisées :

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.

Quand vous spécifiez une suite de requêtes, le moteur d’analyse CodeQL exécute automatiquement les requêtes contenues dans la suite, en plus de l’ensemble de requêtes par défaut.

Combiner des requêtes issues d’un fichier de workflow et d’un fichier de configuration personnalisé

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 de requêtes supplémentaires, préfixez la valeur des packs ou queries dans le workflow avec le symbole +.

Dans l’exemple suivant, le symbole + garantit que les packs et requêtes supplémentaires spécifiés sont utilisés en plus que 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