TRG 8.01 - CodeQL

Status	Created	Post-History
Active	26-Mar-2024	Initial release
Draft	01-Mar-2024	Draft release

Why

Use CodeQL for deep, static code analysis to identify vulnerabilities and improve code quality across a wide range of programming languages.

Description

Use CodeQL for all repos with classic code (e.g., C#, Java) without exception. Do not use it for documentation-only or pure IaC repos; it's intended solely for analyzing classic code vulnerabilities. Exclude files as necessary.

The GitHub Actions configuration must include the following triggers:

• workflow_dispatch: Manual workflow execution.
• schedule: Schedule the workflow to run at least once a week with 0 0 * * 0.
• push and pull_request: Activate the workflow on both push and pull request events targeting the branch that contains the code for the currently supported version, which may not necessarily be the main branch. This is the branch from which new releases will be made.

Findings appear in the GitHub Advanced Security Dashboard. Dismiss high/error findings as non-exploitable or false positives with required justification in the vulnerability alert.

caution

Address high severity findings; it is recommended to also address medium severity findings.

You can tailor the failure conditions (fail-on) for high severity issues in the workflow to suit your team's preferences.

Adjust your code's language and build settings as indicated within the workflow comments.

Example CodeQL workflow:

name: "CodeQL"

on:
  push:
    branches: ["main"]
    paths-ignore:
      - "**/*.md"
      - "**/*.txt"
  pull_request:
    # The branches below must be a subset of the branches above
    branches: ["main"]
    paths-ignore:
      - "**/*.md"
      - "**/*.txt"
  schedule:
    - cron: "0 0 * * 0"
  workflow_dispatch:

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    timeout-minutes: 360
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: ["java"] # Define languages here
        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' ]
        # Use only 'java' to analyze code written in Java, Kotlin or both
        # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both
        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support

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

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: ${{ matrix.language }}
          # If you wish to specify custom queries, you can do so here or in a config file
          # By default, queries listed here will override any specified in a config file
          # Prefix the list here with "+" to use these queries and those in the config file

          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
          # Use +security-extended,security-and-quality for wider security and better code quality
          queries: +security-extended,security-and-quality

      # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift)
      # Automates dependency installation for Python, Ruby, and JavaScript, optimizing the CodeQL analysis setup
      # If this step fails, then you should remove it and run the build manually (see below)
      - name: Autobuild
        uses: github/codeql-action/autobuild@v2

      # ℹ️ Command-line programs to run using the OS shell.
      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun

      # If the Autobuild fails above, remove it and uncomment the following three lines modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance

      # - run: |
      #     echo "Run, Build Application using script"
      #     ./location_of_script_within_repo/buildscript.sh

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