codeql.yml

Overview

codeql.yml is a GitHub Actions workflow configuration file designed to automate the process of static code analysis using CodeQL. CodeQL is a powerful semantic code analysis engine that helps identify security vulnerabilities, code quality issues, and other potential problems in source code.

This workflow is triggered on pushes and pull requests targeting the main branch, as well as on a scheduled cron job. It supports multiple programming languages and allows customization of the build and analysis process.

Workflow Purpose and Functionality

• Automation of Code Scanning: Automatically runs CodeQL analysis on specified branches and according to a schedule.

• Multi-language Support: Uses a matrix strategy to analyze different programming languages within the repository.

• Customizable Build Modes: Supports manual build mode for user-defined build steps.

• Resource Optimization: Selects runner environments based on the language being analyzed (e.g., macOS for Swift, Ubuntu for others).

• Security Permissions: Grants the necessary permissions for security event writing and package reading to execute the scanning.

Detailed Breakdown of Workflow Components

Triggers (on)

• push: Runs on pushes to the main branch.

• pull_request: Runs on pull requests targeting the main branch.

• schedule: Runs periodically according to the cron expression (35 1 1 * *), which corresponds to 1:35 AM on the first day of every month.

Jobs

analyze

• Name: "Analyze (${{ matrix.language }})"
  Dynamically names the job based on the language being analyzed.

• Runner Selection (runs-on):
  Uses macos-latest for Swift language analysis; otherwise uses ubuntu-latest.

• Permissions:

  • security-events: write to report findings.

  • packages: read to access CodeQL packs.

  • actions: read and contents: read for private repositories.

• Strategy:
  Defines a matrix to run separate jobs for each language specified. Currently, only c-cpp is included with manual build mode, but other languages can be added.

• Steps:

  1. Checkout repository: Uses actions/checkout@v4 to retrieve the source code.

  2. Initialize CodeQL: Uses github/codeql-action/init@v4 to set up the CodeQL environment for the specific language and build mode from the matrix.

     • Parameters:

       • languages: The language to analyze (from matrix).

       • build-mode: The build mode (manual).

  3. Install dependencies:
     Installs necessary build tools (ninja-build and cmake) using apt-get.

  4. Build dependencies (json-c):
     Clones and builds the json-c library, configuring it with cmake to use a Release build type and installing it into a local libs/ directory.

  5. Build project:
     Runs the project-specific build script ./build.sh located in the root of the repository. This script is responsible for compiling the project and can encapsulate all necessary build configurations and steps.

  6. Perform CodeQL Analysis:
     Uses github/codeql-action/analyze@v4 to run the analysis and upload results.

     • Parameters:

       • category: Sets the analysis category dynamically based on language.

Important Implementation Details

• Matrix Strategy:
  Enables parallel and language-specific analysis. It can be expanded to include other supported languages such as java-kotlin, javascript-typescript, python, etc.

• Build Modes:

  • manual: Requires explicit build commands from the user. The workflow includes concrete build steps for the c-cpp language using a dedicated build script (build.sh) and dependency management.

• Runner Selection Logic:
  The workflow selects macOS runners for Swift analysis due to its platform requirements and Ubuntu runners for other languages for efficiency.

• Security and Access Control:
  Permissions are tightly scoped to allow only necessary access for the GitHub Actions workflow, enhancing security.

• Customization Points:

  • Languages analyzed (matrix.language).

  • Build mode (matrix.build-mode).

  • Custom CodeQL queries can be specified in the init step if needed.

Interaction with Other System Components

• GitHub Repository:
  The workflow checks out the repository to access source code.

• GitHub Code Scanning:
  Integrates with GitHub’s code scanning features by uploading CodeQL analysis results as security events.

• CodeQL Packs:
  Downloads and uses CodeQL query packs for analysis, which can be internal (private) or public.

• CI/CD Pipeline:
  Runs as part of the repository's continuous integration pipeline triggered by commits, pull requests, or scheduled runs.

• External Dependencies:
  Builds and installs the json-c library as part of the dependency setup for the project using a Release build configuration.

• Project Build Script:
  Utilizes a custom build script (build.sh) located at the root of the repository to compile the project, allowing flexibility to manage build configurations and commands.

Usage Example

To add support for javascript-typescript with manual build mode, one would modify the matrix as follows:

matrix:
  include:
    - language: c-cpp
      build-mode: manual
    - language: javascript-typescript
      build-mode: manual

Then, replace the build steps accordingly to install dependencies and build the JavaScript/TypeScript project, adjusting or replacing the build.sh script as needed.

Mermaid Diagram: Workflow Structure and Step Relationships

flowchart TD
A[Trigger: push, pull_request, schedule] --> B[Job: analyze]
B --> C{Matrix: language, build-mode}
C --> D[c-cpp / manual]
C --> E[Other languages / manual]
D --> F[Checkout repository]
E --> F
F --> G[Initialize CodeQL]
G --> H[Install dependencies]
H --> I[Build dependencies (json-c)]
I --> J[Build project (./build.sh)]
J --> K[Perform CodeQL Analysis]
K --> L[Upload results / Report security events]

End of codeql.yml Documentation