Optimiser vos analyses de sécurité GitHub avec des requêtes CodeQL custom

L’objectif de cet article est de présenter un POC autour de la personnalisation du CodeQL pour analyser un projet C++. 
L’idée est de démontrer, étape par étape, comment configurer un workflow d’analyse pour écrire des requêtes QL personnalisées et interpréter les résultats afin d’adapter la détection de vulnérabilités au contexte du projet. 
Cette personnalisation permet aussi d’optimiser l’exécution de CodeQL, en réduisant le bruit et parfois le temps d’analyse grâce à un ciblage plus précis des règles et des chemins. Nous allons suivre les étapes suivantes : 

1. Créer un workflow codeql.yml 
   pour analyser le code automatiquement via GitHub Actions et exporter les résultats au format SARIF. 
2. Configurer un fichier codeql-config.yml 
     afin de définir les chemins à inclure ou ignorer, sélectionner les packs de règles, et ajouter des queries personnalisées. 
3. Écrire des custom queries .ql avec métadonnées 
     en utilisant les propriétés telles que @problem.severity, @precision, @tags et @security-severity pour ajuster la sévérité et la pertinence des résultats. 
4. Utiliser les query-filters 
     pour réduire le bruit, exclure certaines règles peu précises ou recommandations, et concentrer l’analyse sur les résultats critiques.
5. Tester et interpréter les résultats
     en visualisant les alertes dans GitHub Security ainsi que dans les fichiers SARIF exportés, afin de valider que la configuration et les requêtes répondent bien aux besoins du projet 

I-Créer le workflow codeql.yml

Créer un fichier .github/workflows/codeql.yml. 
Ce fichier décrit les étapes du workflow GitHub Actions qui exécute CodeQL. Voici un example pour un projet C++ : 

Explication du fichier : 

uses: github/codeql-action/init@v3: cette étape installe et configure CodeQL en précisant le langage à analyser. Elle charge le fichier codeql-config.yml pour savoir quels dossiers à inclure/exclure et quelles règles (queries) à exécuter. 

uses: github/codeql-action/autobuild@v3: GitHub essaie de compiler automatiquement le projet. Pour les langages compilés (C#, Java, C++), CodeQL a besoin d’une compilation (build) obligatoire pour comprendre la structure de le code. Si l’autobuild échoue, on peut remplacer avec un build manuel (make, cmake, mvn, dotnet build, yarn build, etc.) 

uses : github/codeql-action/analyze@v3: cette action exécute l’analyse CodeQL avec les règles choisies. Les résultats sont exportés après, dans un fichier SARIF (ce fichier contient les vulnérabilités, leur sévérité et leur précision.) 

uses: actions/upload-artifact@v4: sauvegarde le fichier SARIF comme artefact téléchargeable du workflow. On peut aussi l’ouvrir dans GitHub Security ou bien l’importer dans un outil tiers (SonarQube…etc) 

II- Fichier de configuration codeql-config.yml 

Ce fichier permet de personnaliser ce qui est scanné et quelles règles sont utilisées : 

Explication du fichier 

On indique quelles queries CodeQL doit on exécuter pour notre projet : 

• security-extended : pack officiel GitHub avec plus de règles de sécurité (recommandé). 

• security-and-quality : ajoute en plus des règles de bonnes pratiques et de qualité de code. 

• ./github/codeql/queries/test-query.ql : la query custom, qui détecte par exemple l’usage dangereux de la fonction classique strcpy() dans du C/C++ 

1. Filtrer les résultats avec query-filters 

Les query-filters permettent de contrôler finement les résultats de CodeQL sans modifier les requêtes elles-mêmes. Concrètement, ils servent à exclure ou inclure certains résultats en fonction de critères comme : 

• problem.severity : exclure par exemple les warnings pour ne garder que les errors. 

• Precision : ignorer les règles de faible précision (low) pour réduire les faux positifs. 

• Tags : cibler uniquement certaines catégories (ex. security, correctness, etc.). 

Le fichier SARIF résultant, ne contient plus les severités filtrées (low, warning) 

III- Comprendre un fichier de requête CodeQL (.ql) 

Un fichier .ql est une requête qui décrit un pattern à détecter dans le code. Il est une sorte de langage déclaratif inspiré de SQL et de la logique, qui manipule les bases de données CodeQL générées à partir du code source (About CodeQL queries — CodeQL). 

On peut s’inspirer ou utiliser directement ces build-in queries via codeql/cpp/ql/src/Likely Bugs/Likely Typos/UsingStrcpyAsBoolean.ql at main · github/codeql)  

Exemple de requête pour détecter strcpy() : 

Explication du fichier : 

La première partie est la description du fichier .ql : 

• @name : le nom affiché dans GitHub Security. 

• @description : explication du problème. 

• @kind : type de résultat (problem, path-problem, etc.). 

• @precision: niveau de confiance (low, medium, high, very-high). 

• @problem.severity: sévérité (error, warning, recommendation). 

• @tags : classification pour filtrer ou relier à CWE, bonnes pratiques, etc. 

• @security-severity : score de 0.0 à 10.0 → traduit en Critical / High / Medium / Low dans GitHub 

1. Ensuite pour le reste du fichier : 
   • On importe la librairie CodeQL pour le langage C++ (CodeQL library for C and C++ — CodeQL) 
   • from FunctionCall call
     → on définit une variable call qui représente chaque appel de fonction trouvé dans le code C++. 
   • where call.getTarget().getName() = « strcpy »
     → on filtre uniquement les appels à la fonction strcpy. 
   • select call, « Avoid using strcpy… »
     → on retourne chaque appel détecté avec un message d’alerte. 

IV- Les Bonnes Pratiques au niveau Pull Requests 

Au-delà de la création des custom queries et de la configuration des workflows, il est essentiel de mettre en place des règles de protection sur les branches pour garantir que le code vulnérable ne soit jamais fusionné vers la branche principale, par erreur ou par un Bypass/Force merge de PR. 

RuleSets à activer dans GitHub : 

• Require status checks to pass : obliger le workflow CodeQL à réussir avant de permettre un merge. Il devient en mode « Required ». 

• Require branches to be up to date before merging → la PR doit être mise à jour avec la dernière version de la branche cible pour éviter d’intégrer du code non-scanné 

• Require code scanning results : forcer la présence des résultats CodeQL avec un : 

• Seuil de Security alerts: High or higher 

• Type d’alertes bloquantes : Errors ou bien All 

Cela signifie que si une alerte de sévérité High ou Critical est détectée, le merge sera bloqué jusqu’à correction. 

Avec ce ruleset, une PR ne peut pas être fusionnée tant que le workflow CodeQL n’a pas tourné et les alertes de sécurité de type High ou plus graves n’ont pas été résolues. 

Conclusion 

En résumé, les queries CodeQL personnalisées offrent une grande flexibilité : elles permettent d’aller au-delà des règles standard de GHAS, de répondre à des besoins métier spécifiques et de renforcer la détection de vulnérabilités selon le contexte du projet.