Personnaliser votre workflow d’analyse du code avec CodeQL - Partie 2

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

Dans cette unité, nous allons examiner comment référencer des requêtes supplémentaires dans un fichier de configuration personnalisé.

Requêtes supplémentaires dans 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 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.

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

Le fichier de configuration peut se trouver dans le dépôt que vous analysez ou dans un dépôt 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. Lorsque vous référencez un fichier de configuration situé dans un référentiel 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 }}

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

Spécifier les packs de requêtes CodeQL dans les fichiers de configuration personnalisés

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.

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:
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 une gamme de versions semver. S’il est manquant, la dernière version est utilisée.

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

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

Spécifier des requêtes supplémentaires dans une configuration personnalisée

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

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

Si vous le souhaitez, vous pouvez attribuer un nom à chaque élément du tableau, comme indiqué dans l’exemple de fichier de configuration ci-dessous :

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'

Désactiver les 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. Vous devez aussi utiliser cet indicateur si vous essayez de construire une suite de requêtes personnalisée qui exclut une règle particulière. Cela évite que toutes les requêtes s’exécutent à deux reprises.

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

Vous pouvez ajouter des 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, comme :

Des requêtes spécifiques des suites par défaut (security, security-extended et security-and-quality).
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 les filtres exclude similaires à ceux de la configuration dans le fichier suivant afin d’exclure des requêtes que vous souhaitez retirer de l’analyse par défaut. Dans l’exemple d’un fichier de configuration qui suit, les requêtes de type js/redundant-assignment et js/useless-assignment-to-local sont exclues de l’analyse.

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

Pour trouver l’ID d’une requête, vous pouvez cliquer sur l’alerte dans la liste d’alertes de l’onglet Sécurité. Cela ouvre la page des détails de l’alerte. Le champ ID de règle contient l’ID de la requête.

Gardez ceci en tête lorsque vous travaillez avec le filtre excludes :

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.

Spécifier les répertoires à analyser

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

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

Remarque

Les mots clés paths et paths-ignore utilisés dans le contexte du fichier de configuration d’analyse du code ne doivent pas être confondus avec les mêmes mots clés lorsqu’ils sont utilisés dans un flux de travail on.<push|pull_request>.paths. Quand ils sont utilisés pour modifier on.<push|pull_request> dans un workflow, ils déterminent si les actions sont exécutées quand un utilisateur modifie le code dans les répertoires spécifiés.
Les caractères de modèle 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 ce n’est pas le cas de **foo. Cependant, vous pouvez utiliser des étoiles simples avec d'autres caractères, comme indiqué dans l'exemple. Vous devez mettre entre guillemets tout ce qui contient un caractère *.

Pour les langages compilés, si vous souhaitez limiter l’analyse du code à 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.

Vous pouvez rapidement analyser certaines petites parties de code d’un monorepo 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.

Commentaires

Cette page a-t-elle été utile ?