Skip to main content

Cette version de GitHub Enterprise a été abandonnée le 2023-01-18. Aucune publication de correctifs n’est effectuée, même pour les problèmes de sécurité critiques. Pour de meilleures performances, une sécurité améliorée et de nouvelles fonctionnalités, effectuez une mise à niveau vers la dernière version de GitHub Enterprise. Pour obtenir de l’aide sur la mise à niveau, contactez le support GitHub Enterprise.

Exécution de l’exécuteur CodeQL dans votre système CI

Vous pouvez utiliser le CodeQL runner pour effectuer l’code scanning CodeQL dans un système d’intégration continue tiers.

Code scanning est disponible pour les dépôts appartenant à l’organisation dans GitHub Enterprise Server. Cette fonctionnalité nécessite une licence pour GitHub Advanced Security. Pour plus d’informations, consultez « À propos de GitHub Advanced Security ».

Remarque : L’CodeQL runner est en cours de dépréciation. Sur GitHub Enterprise Server 3.0 et les versions ultérieures, vous pouvez installer CodeQL CLI version 2.6.3 pour remplacer l’CodeQL runner.

Pour plus d’informations, consultez les informations relatives à la dépréciation de l’exécuteur CodeQL. Pour plus d’informations sur la migration vers l’CodeQL CLI, consultez « Migration de l’exécuteur CodeQL vers l’interface CLI CodeQL ».

Remarque : Votre administrateur de site doit activer l’code scanning pour your GitHub Enterprise Server instance afin que vous puissiez utiliser cette fonctionnalité. Pour plus d’informations, consultez « Configuration de code scanning pour votre appliance ».

À propos de l’CodeQL runner

L’CodeQL runner est un outil qui vous permet d’exécuter l’code scanning sur le code que vous traitez dans un système d’intégration continue (CI) tiers. Code scanning est une fonctionnalité que vous utilisez pour analyser le code dans un dépôt GitHub afin de détecter d’éventuelles vulnérabilités de sécurité et erreurs de codage. Tous les problèmes identifiés par l’analyse sont affichés dans GitHub Enterprise Server. Pour plus d’informations, consultez « À propos de l’code scanning avec CodeQL ».

Dans de nombreux cas, il est plus facile de configurer l’code scanning CodeQL en utilisant l’CodeQL CLI directement dans votre système CI.

Vous pouvez également utiliser GitHub Actions pour exécuter l’code scanning dans GitHub Enterprise Server. Pour des informations supplémentaires, consultez « Configuration de code scanning pour un référentiel ».

L’CodeQL runner est un outil en ligne de commande qui exécute l’analyse CodeQL lors de l’extraction d’un dépôt GitHub. Vous ajoutez l’exécuteur à votre système tiers, puis appelez l’exécuteur pour analyser le code et charger les résultats sur GitHub Enterprise Server. Ces résultats sont affichés sous la forme d’alertes d’code scanning dans le dépôt.

Remarque :

  • L’CodeQL runner est disponible pour les clients disposant d’une licence Advanced Security.

Téléchargement de l’CodeQL runner

Vous pouvez télécharger l’CodeQL runner à partir de https://NOM HÔTE/github/codeql-action/releases. Sur certains systèmes d’exploitation, vous devrez peut-être changer les autorisations pour le fichier téléchargé avant de pouvoir l’exécuter.

Sur Linux :

chmod +x codeql-runner-linux

Sur macOS :

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

Sur Windows, le fichier codeql-runner-win.exe ne nécessite généralement aucune modification des autorisations.

Ajout de l’CodeQL runner à votre système CI

Une fois que vous avez téléchargé l’CodeQL runner et vérifié qu’il peut être exécuté, vous devez rendre l’exécuteur disponible pour chaque serveur CI que vous envisagez d’utiliser pour l’code scanning. Par exemple, vous pouvez configurer chaque serveur pour copier l’exécuteur à partir d’un emplacement central interne. Vous pouvez également utiliser l’API REST pour obtenir l’exécuteur directement à partir de GitHub, par exemple :

wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

En outre, chaque serveur CI a également besoin des éléments suivants :

  • Une GitHub App ou un personal access token pour l’CodeQL runner à utiliser. Vous devez utiliser un jeton d’accès avec l’étendue repo ou une GitHub App avec l’autorisation d’écriture security_events et les autorisations de lecture metadata et contents. Pour plus d’informations, consultez « Génération d’GitHub Apps » et « Création d’un personal access token ».
  • Un accès au bundle CodeQL associé à cette version de l’CodeQL runner. Ce package contient des requêtes et des bibliothèques nécessaires pour l’analyse CodeQL ainsi que l’interface CLI de CodeQL, qui est utilisée en interne par l’exécuteur. Pour plus d’informations, consultez « Interface CLI de CodeQL ».

Les options pour fournir l’accès au bundle CodeQL sont les suivantes :

  1. Autorisez les serveurs CI à accéder à https://NOM HÔTE/github/codeql-action afin que l’CodeQL runner puisse télécharger automatiquement le bundle.
  2. Téléchargez/extrayez manuellement le bundle, stockez-le avec d’autres ressources centrales et utilisez l’indicateur --codeql-path pour spécifier l’emplacement du bundle dans les appels pour initialiser l’CodeQL runner.

Appel de l’CodeQL runner

Vous devez appeler l’CodeQL runner. à partir de l’emplacement d’extraction du dépôt que vous souhaitez analyser. Les deux commandes principales sont les suivantes :

  1. init, nécessaire pour initialiser l’exécuteur et créer une base de données CodeQL pour chaque langage à analyser. Ces bases de données sont remplies et analysées par les commandes suivantes.
  2. analyze, nécessaire pour remplir les bases de données CodeQL, les analyser et charger les résultats sur GitHub Enterprise Server.

Pour les deux commandes, vous devez spécifier l’URL de GitHub Enterprise Server, le PROPRIÉTAIRE/NOM du dépôt et les GitHub Apps ou le personal access token à utiliser pour l’authentification. Vous devez également spécifier l’emplacement du bundle CodeQL, sauf si le serveur CI dispose de l’accès nécessaire pour le télécharger directement à partir du dépôt github/codeql-action.

Vous pouvez configurer l’emplacement où l’CodeQL runner stocke le bundle CodeQL pour les futures analyses sur un serveur en utilisant l’indicateur --tools-dir et l’emplacement où il stocke les fichiers temporaires pendant l’analyse en utilisant --temp-dir.

Pour afficher les informations de référence sur la ligne de commande de l’exécuteur, utilisez l’indicateur -h. Par exemple, pour lister toutes les commandes exécutées : codeql-runner-OS -h, ou pour lister tous les indicateurs disponibles pour la commande init exécutée : codeql-runner-OS init -h (où OS varie selon l’exécutable que vous utilisez). Pour plus d’informations, consultez « Configuration de l’code scanning dans votre système CI ».

Remarques :

  • Un chargement SARIF prend en charge un maximum de 5 000 résultats par chargement. Tous les résultats au-delà de cette limite sont ignorés. Si un outil génère trop de résultats, vous devez mettre à jour la configuration pour vous concentrer sur les résultats des règles ou requêtes les plus importantes.

  • À chaque chargement, le chargement SARIF prend en charge une taille maximale de 10 Mo pour le fichier SARIF compressé au format gzip. Tous les chargements au-delà de cette limite sont rejetés. Si votre fichier SARIF est trop volumineux parce qu’il contient trop de résultats, vous devez mettre à jour la configuration pour vous concentrer sur les résultats des règles ou requêtes les plus importantes.

Exemple de base

Cet exemple exécute l’analyse CodeQL sur un serveur CI Linux pour le dépôt octo-org/example-repo hébergé sur https://github.example.com. Le processus est très simple, car le dépôt contient uniquement des langages qui peuvent être analysés directement par CodeQL, sans être générés (autrement dit, Go, JavaScript, Python et TypeScript).

Dans cet exemple, le serveur dispose de l’accès nécessaire pour télécharger le bundle CodeQL directement à partir du dépôt github/codeql-action. Il n’est donc pas indispensable d’utiliser l’indicateur --codeql-path.

  1. Extrayez le dépôt à analyser.

  2. Accédez au répertoire dans lequel le dépôt est extrait.

  3. Lancez l’CodeQL runner et créez des bases de données CodeQL pour les langages détectés.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. Remplissez les base de données CodeQL, analysez-les, puis chargez les résultats vers GitHub Enterprise Server. Les résultats s’affichent sous l’onglet Sécurité de votre dépôt.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  5. Pour charger les résultats de l’code scanning sous forme de vérifications des demandes de tirage, spécifiez la demande de tirage à l’aide de l’indicateur --ref. Nous vous recommandons de configurer l’CodeQL runner pour qu’il s’exécute sur l’événement de webhook pull_request.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

Pour plus d’informations sur la visualisation des alertes d’code scanning, consultez « Triage des alertes d’analyse du code dans les demandes de tirage » et « Gestion des alertes d’analyse de code pour votre dépôt ».

Exemple de langage compilé

Cet exemple est similaire à l’exemple précédent, mais cette fois, le dépôt a du code en C/C++, C# ou Java. Pour créer une base de données CodeQL pour ces langages, l’interface CLI doit superviser la génération. À la fin du processus d’initialisation, l’exécuteur signale la commande dont vous avez besoin pour configurer l’environnement avant de générer le code. Vous devez exécuter cette commande, avant d’appeler le processus de génération CI normal, puis d’exécuter la commande analyze.

  1. Extrayez le dépôt à analyser.

  2. Accédez au répertoire dans lequel le dépôt est extrait.

  3. Lancez l’CodeQL runner et créez des bases de données CodeQL pour les langages détectés.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth-stdin
    > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
    > ...
    > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
      and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
      Please export these variables to future processes so that CodeQL can monitor the build, for example by running
      ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. Sourcez le script généré par l’action init pour configurer l’environnement afin de superviser la génération. Notez le point et l’espace de début dans l’extrait de code suivant.

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. Génération du code Sur macOS, vous devez préfixer la commande de génération avec la variable d’environnement $CODEQL_RUNNER. Pour plus d’informations, consultez « Résolution des problèmes de l’CodeQL runner dans votre système CI ».

  6. Remplissez les base de données CodeQL, analysez-les, puis chargez les résultats vers GitHub Enterprise Server. Les résultats s’affichent sous l’onglet Sécurité de votre dépôt.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  7. Pour charger les résultats de l’code scanning sous forme de vérifications des demandes de tirage, spécifiez la demande de tirage à l’aide de l’indicateur --ref. Nous vous recommandons de configurer l’CodeQL runner pour qu’il s’exécute sur l’événement de webhook pull_request.

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

Pour plus d’informations sur la visualisation des alertes d’code scanning, consultez « Triage des alertes d’analyse du code dans les demandes de tirage » et « Gestion des alertes d’analyse de code pour votre dépôt ».

Remarque : Si vous utilisez une build conteneurisée, vous avez besoin d’exécuter l’CodeQL runner dans le conteneur dans lequel votre tâche de génération se produit.

Pour aller plus loin