How to enable CodeQL using Jenkins

Question

I received a pull request to enable CodeQL scanning in my applications GitHub repository. How do I enable CodeQL when I’m using the Jenkins CI tool?

Answer

The pull request includes a number of changes to your repository to set up CodeQL scanning using GitHub Actions. Even if CodeQL was previously enabled, additional changes are required to meet current VA scanning requirements. Enabling CodeQL at VA requires some additional configuration before merging the pull request. This technical note provides an overview of the process to update these changes to support running CodeQL on your Jenkins CI tool. The technical notes linked below provide more details on how to perform each step.

Note: If you are using the GitHub CI tools, please see this technical note instead.

Note: If your repository build process does not require access to resources behind the Veterans Affairs firewall, you may be able to leverage GitHub CI by default to perform your code scanning and simplify your enablement process. Please see the How to Identify Support for GitHub CI technical note for additional information.

The overall process to enable CodeQL for a repository consists of the following:

  1. Ignore repository (optional) - If the repository should not be scanned the developer must add a .emass-repo-ignore file. See Ignore repository for additional information.

  2. Update emass.json (required) - The pull request adds a file named emass.json which must be updated to map your application to an eMASS system. See Update emass.json for additional information.

  3. Exclude languages that can’t be scanned (optional) - The pull request identifies the languages supported by CodeQL that are present in the repository. If any of those languages cannot be scanned, you must exclude them from the scan, or you will receive weekly notifications that these scans are not running. See Exclude languages from the scan for additional information.

  4. Remove codeql-analysis workflow (optional) - The pull request adds a workflow file named codeql-analysis.yml which must be removed if you are only using Jenkins only. Delete this file from the pull request branch and commit the change back to the pull request branch. If you intend to use both Jenkins and GitHub Actions, you keep this file.

  5. Update Jenkins pipeline (optional) - If you have scans that need to be performed on Jenkins, add the CodeQL Shared Library to your Jenkins instance, or embed the shared library in your pipeline files and call the ExecuteCodeQL function. See Update Jenkins pipeline for additional information.

Prerequisites

To use CodeQL with Jenkins, you must have the installed the CodeQL CLI on your Jenkins build agents. You can download the CodeQL CLI from the CodeQL CLI downloads page. Once you’ve downloaded and extracted the CodeQL CLI, you must add the codeql executable to your PATH by adding the expanded directory to your PATH environment variable.

If you are unable to install the CLI on your Jenkins build agents, you may specify a flag to force the provided Shared Library to download the CodeQL CLI from GitHub. This is not recommended, as it will increase the time it takes to run the CodeQL scan. See Update Jenkins pipeline for additional information.

For Linux-based Jenkins build agents using the provided tooling for installing CodeQL CLI at runtime, you must have the following software installed on your build agents:

  • cURL
  • tar
  • jq

For Windows-based Jenkins build agents using the provided tooling for installing CodeQL CLI at runtime, you must have the following software installed on your build agents:

  • tar

To utilize the CodeQL CLI in Jenkins, you must also have a Personal Access Token for a GitHub account that has write access to the repository you are scanning as CodeQL will upload the results of your scans to the GitHub Security Center in your repository. This token must be stored as a Jenkins Secret Text credential. You may follow the instructions in the VA GitHub Handbook on Creating a Service Account.

Limitations

Due to the nature of Jenkins and CodeQL, there are some limitations to the way CodeQL scans can be performed using Jenkins. If running scans in parallel using the parallel keyword, you must ensure the parallel stages execute on different Jenkins build nodes. If you have a Jenkins build node that has more than one executor where multiple scans can be run in parallel on the same node, the job will fail.