Analyse de Code CodeQL

Cette compétence fournit des conseils procéduraux pour configurer et exécuter l'analyse de code CodeQL — à la fois via les workflows GitHub Actions et l'interface de ligne de commande CodeQL autonome.

Quand utiliser cette compétence

Utilisez cette compétence lorsque la demande implique :

• Créer ou personnaliser un workflow GitHub Actions codeql.yml
• Choisir entre la configuration par défaut et la configuration avancée pour l'analyse de code
• Configurer la matrice de langages CodeQL, les modes de compilation ou les suites de requêtes
• Exécuter l'interface de ligne de commande CodeQL localement (codeql database create, database analyze, github upload-results)
• Comprendre ou interpréter la sortie SARIF de CodeQL
• Résoudre les problèmes d'analyse CodeQL (modes de compilation, langages compilés, exigences des runners)
• Configurer CodeQL pour les monorepos avec analyse par composant
• Configurer la mise en cache des dépendances, les packs de requêtes personnalisées ou les packs de modèles

Langages pris en charge

CodeQL supporte les identifiants de langue suivants :

Les identifiants alternatifs sont équivalents à l'identifiant standard (par exemple, javascript n'exclut pas l'analyse TypeScript).

Workflow principal — GitHub Actions

Étape 1 : Choisir le type de configuration

• Configuration par défaut — Activer depuis les paramètres du dépôt → Advanced Security → CodeQL analysis. Meilleur pour démarrer rapidement. Utilise le mode de compilation none pour la plupart des langages.
• Configuration avancée — Créer un fichier .github/workflows/codeql.yml pour un contrôle total sur les déclencheurs, les modes de compilation, les suites de requêtes et les stratégies de matrice.

Pour passer de la configuration par défaut à la configuration avancée : désactiver d'abord la configuration par défaut, puis valider le fichier de workflow.

Étape 2 : Configurer les déclencheurs du workflow

Définir quand l'analyse s'exécute :

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

• push — analyse à chaque push vers les branches spécifiées ; les résultats apparaissent dans l'onglet Security
• pull_request — analyse les commits de fusion PR ; les résultats apparaissent sous forme d'annotations de vérification PR
• schedule — analyses périodiques de la branche par défaut (cron doit exister sur la branche par défaut)
• merge_group — ajouter si le dépôt utilise des files d'attente de fusion

Pour ignorer les analyses pour les PR de documentation uniquement :

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore contrôle si le workflow s'exécute, pas les fichiers analysés.

Étape 3 : Configurer les permissions

Définir les permissions avec le moins de privilèges :

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

Étape 4 : Configurer la matrice de langages

Utiliser une stratégie de matrice pour analyser chaque langue en parallèle :

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

Pour les langages compilés, définir le build-mode approprié :

• none — aucune compilation requise (pris en charge pour C/C++, C#, Java, Rust)
• autobuild — détection automatique de la compilation
• manual — commandes de compilation personnalisées (configuration avancée uniquement)

Pour le comportement autobuild détaillé par langue et les exigences des runners, consultez references/compiled-languages.md.

Étape 5 : Configurer l'initialisation et l'analyse CodeQL

steps:
  - name: Checkout repository
    uses: actions/checkout@v4

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}
      queries: security-extended
      dependency-caching: true

  - name: Perform CodeQL Analysis
    uses: github/codeql-action/analyze@v4
    with:
      category: "/language:${{ matrix.language }}"

Options de suite de requêtes :

• security-extended — requêtes de sécurité par défaut plus couverture supplémentaire
• security-and-quality — sécurité plus requêtes de qualité du code
• Packs de requêtes personnalisés via l'entrée packs: (par exemple, codeql/javascript-queries:AlertSuppression.ql)

Mise en cache des dépendances : Définir dependency-caching: true sur l'action init pour mettre en cache les dépendances restaurées d'une exécution à l'autre.

Catégorie d'analyse : Utiliser category pour distinguer les résultats SARIF dans les monorepos (par exemple, par langue, par composant).

Étape 6 : Configuration des monorepos

Pour les monorepos avec plusieurs composants, utiliser le paramètre category pour séparer les résultats SARIF :

category: "/language:${{ matrix.language }}/component:frontend"

Pour restreindre l'analyse à des répertoires spécifiques, utiliser un fichier de configuration CodeQL (.github/codeql/codeql-config.yml) :

paths:
  - apps/
  - services/
paths-ignore:
  - node_modules/
  - '**/test/**'

Le référencer dans le workflow :

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

Étape 7 : Étapes de compilation manuelle (langages compilés)

Si autobuild échoue ou si des commandes de compilation personnalisées sont nécessaires :

- language: c-cpp
  build-mode: manual

Puis ajouter des étapes de compilation explicites entre init et analyze :

- if: matrix.build-mode == 'manual'
  name: Build
  run: |
    make bootstrap
    make release

Workflow principal — Interface de ligne de commande CodeQL

Étape 1 : Installer l'interface de ligne de commande CodeQL

Télécharger le bundle CodeQL (inclut l'interface de ligne de commande + requêtes précompilées) :

# Download from https://github.com/github/codeql-action/releases
# Extract and add to PATH
export PATH="$HOME/codeql:$PATH"

# Verify installation
codeql resolve packs
codeql resolve languages

Toujours utiliser le bundle CodeQL, pas un téléchargement d'interface de ligne de commande autonome. Le bundle garantit la compatibilité des requêtes et fournit les requêtes précompilées pour de meilleures performances.

Étape 2 : Créer une base de données CodeQL

# Single language
codeql database create codeql-db \
  --language=javascript-typescript \
  --source-root=src

# Multiple languages (cluster mode)
codeql database create codeql-dbs \
  --db-cluster \
  --language=java,python \
  --command=./build.sh \
  --source-root=src

Pour les langages compilés, fournir la commande de compilation via --command.

Étape 3 : Analyser la base de données

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

Suites de requêtes courantes : <language>-code-scanning.qls, <language>-security-extended.qls, <language>-security-and-quality.qls.

Étape 4 : Charger les résultats sur GitHub

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

Nécessite une variable d'environnement GITHUB_TOKEN avec permission security-events: write.

Mode serveur de l'interface de ligne de commande

Pour éviter l'initialisation répétée de la JVM lors de l'exécution de plusieurs commandes :

codeql execute cli-server

Pour la référence complète des commandes de l'interface de ligne de commande, consultez references/cli-commands.md.

Gestion des alertes

Niveaux de sévérité

Les alertes ont deux dimensions de sévérité :

• Sévérité standard : Error, Warning, Note
• Sévérité de sécurité : Critical, High, Medium, Low (dérivée des scores CVSS ; prend la priorité d'affichage)

Correctifs automatiques Copilot

GitHub Copilot Autofix génère automatiquement des suggestions de correctif pour les alertes CodeQL dans les pull requests — aucun abonnement Copilot requis. Examiner attentivement les suggestions avant de valider.

Triage des alertes dans les PR

• Les alertes apparaissent sous forme d'annotations de vérification sur les lignes modifiées
• La vérification échoue par défaut pour les alertes avec sévérité error/critical/high
• Configurer les ensembles de règles de protection de fusion pour personnaliser le seuil
• Rejeter les faux positifs avec une raison documentée pour l'audit

Pour des conseils détaillés sur la gestion des alertes, consultez references/alert-management.md.

Requêtes et packs personnalisés

Utiliser les packs de requêtes personnalisés

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/my-security-queries@1.0.0
      codeql/javascript-queries:AlertSuppression.ql

Créer des packs de requêtes personnalisés

Utiliser l'interface de ligne de commande CodeQL pour créer et publier les packs :

# Initialize a new pack
codeql pack init my-org/my-queries

# Install dependencies
codeql pack install

# Publish to GitHub Container Registry
codeql pack publish

Fichier de configuration CodeQL

Pour la configuration avancée des requêtes et des chemins, créer .github/codeql/codeql-config.yml :

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

Journaux d'analyse de code

Métriques de résumé

Les journaux de workflow incluent les métriques clés :

• Lignes de code dans la base de code — référence avant extraction
• Lignes extraites — incluant les bibliothèques externes et les fichiers générés automatiquement
• Erreurs/avertissements d'extraction — fichiers qui ont échoué ou qui ont produit des avertissements lors de l'extraction

Journalisation de débogage

Pour activer les diagnostics détaillés :

• GitHub Actions : relancer le workflow avec « Enable debug logging » coché
• Interface de ligne de commande CodeQL : utiliser --verbosity=progress++ et --logdir=codeql-logs

Résolution des problèmes

Problèmes courants

Pour une résolution des problèmes complète avec des solutions détaillées, consultez references/troubleshooting.md.

Exigences matérielles (runners auto-hébergés)

Toutes les tailles : SSD avec ≥14 Go d'espace disque libre.

Versioning des actions

Épingler les actions CodeQL à une version majeure spécifique :

uses: github/codeql-action/init@v4      # Recommended
uses: github/codeql-action/autobuild@v4
uses: github/codeql-action/analyze@v4

Pour une sécurité maximale, épingler sur un SHA de commit complet au lieu d'une balise de version.

Fichiers de référence

Pour la documentation détaillée, charger les fichiers de référence suivants selon vos besoins :

• references/workflow-configuration.md — Options complètes de déclenchement du workflow, runner et configuration
  • Motifs de recherche : trigger, schedule, paths-ignore, db-location, model packs, alert severity, merge protection, concurrency, config file
• references/cli-commands.md — Référence complète des commandes de l'interface de ligne de commande CodeQL
  • Motifs de recherche : database create, database analyze, upload-results, resolve packs, cli-server, installation, CI integration
• references/sarif-output.md — Modèle d'objet SARIF v2.1.0, limites de chargement et support tiers
  • Motifs de recherche : sarifLog, result, location, region, codeFlow, fingerprint, suppression, upload limits, third-party, precision, security-severity
• references/compiled-languages.md — Modes de compilation et comportement autobuild par langue
  • Motifs de recherche : C/C++, C#, Java, Go, Rust, Swift, autobuild, build-mode, hardware, dependency caching
• references/troubleshooting.md — Diagnostic et résolution des erreurs complets
  • Motifs de recherche : no source code, out of disk, out of memory, 403, C# compiler, analysis too long, fewer lines, Kotlin, extraction errors, debug logging, SARIF upload, SARIF limits
• references/alert-management.md — Sévérité des alertes, triage, Copilot Autofix et rejet
  • Motifs de recherche : severity, security severity, CVSS, Copilot Autofix, dismiss, triage, PR alerts, data flow, merge protection, REST API