Skip to content

Latest commit

 

History

History
142 lines (106 loc) · 7.19 KB

README.adoc

File metadata and controls

142 lines (106 loc) · 7.19 KB

Jenkins CodeQL

This repository contains Jenkins-specific CodeQL queries.

Usage

Use in a regular CodeQL workflow

You can use the Jenkins CodeQL queries as part of the regular CodeQL code scanning workflow. This is the more flexible approach in terms of your ability to configure the build, and additionally only requires one workflow to be set up to use the generic code scanning rules provided by GitHub in addition to the Jenkins-specific rules. Please note the findings will be reported part of the "CodeQL" code scanning tool on the GitHub UI.

Additionally, code-level suppressions documented as part of finding descriptions do not work by default. See advanced-security/dismiss-alerts for a GitHub-provided way to support code-level suppression. The instructions below do not add suppression support, see advanced-security/dismiss-alerts for the necessary configuration changes.

Setting up

These instructions assume use of the standard CodeQL workflow template as of 42326d0

Update your use of github/codeql-action/init@v3 to specify a with.config (related GitHub documentation).

Add Jenkins-specific queries in addition to CodeQL
with:
  config: |
    packs:
    - jenkins-infra/jenkins-codeql
Only run Jenkins-specific queries (like Jenkins Security Scan)
with:
  config: |
    disable-default-queries: true
    packs:
    - jenkins-infra/jenkins-codeql

Jenkins Security Scan GitHub Workflow

Basic local/standalone use

  1. Install the CodeQL CLI.

  2. Run codeql pack install test/ to install the dependencies.

  3. Run the desired codeql commands.

Run Jenkins queries against a CodeQL database

Generate or download a CodeQL database for the code base you want to run the queries against.

Then, run:

codeql database codeql database analyze --format=sarifv2.1.0 --output=result.sarif <path to database> src/

This will generate the result.sarif file containing the query results.

Self-contained script

The following shell script creates a database by running the specified build command, analyzes the database with the specified queries only, and then uploads the results, excluding any suppressed findings, to GitHub.

#!/usr/bin/env bash
set -e errexit
set -e nounset
set -e pipefail
[[ -f pom.xml ]] || { echo "This script must be run from a Maven project directory" ; exit 1 ; }
[[ -v "GITHUB_TOKEN" ]] || { echo "GITHUB_TOKEN is undefined. " ; exit 1 ; }  # (1)
[[ -v "GH_REPO" ]] || { echo "GH_REPO is undefined" ; exit 1 ; }              # (2)
[[ -v "GH_REF" ]] || { echo "GH_REF is undefined." ; exit 1 ; }               # (3)
[[ -v "GH_SHA" ]] || { echo "GH_SHA is undefined." ; exit 1 ; }               # (4)
for TOOL in codeql jq mvn ; do
    which "$TOOL" >/dev/null || { echo "$TOOL not found on PATH" ; exit 1 ; }
done
TEMPDIR="$( mktemp -d -t jenkins-codeql.XXXX )"
codeql database create "$TEMPDIR"/codeql-java-database \
  --language=java \
  --command='mvn clean verify -Pquick-build'                                  # (5)
codeql database analyze "$TEMPDIR"/codeql-java-database \
  --sarif-add-query-help \
  --format=sarif-latest \
  --output="$TEMPDIR"/result.sarif \
  --download \
  jenkins-infra/jenkins-codeql \                                                (6)
  codeql/java-queries:AlertSuppression.ql \
  codeql/java-queries:AlertSuppressionAnnotations.ql \
  || { echo "Failed to analyze database" ; exit 1 ; }
jq 'del(.runs[].results[] | select( .suppressions | length != 0 ))' \
  "$TEMPDIR"/result.sarif > "$TEMPDIR"/result-filtered.sarif                  # (7)
echo codeql github upload-results \
  --repository="$GH_REPO" \
  --ref="$GH_REF" --commit="$GH_SHA" \
  --sarif="$TEMPDIR"/result-filtered.sarif
# Optionally:
# rm -rf "$TEMPDIR"

  1. GITHUB_TOKEN is used by codeql github upload-results. Alternatively, a token can be passed into standard input with --github-auth-stdin argument.

  2. GH_REPO must be in the format owner/repo (e.g., jenkinsci/matrix-auth-plugin).

  3. GH_REF must be in the format refs/heads/branchname (e.g., refs/heads/develop) when analyzing a branch, or refs/pull/1234/head (when analyzing a pull request’s HEAD commit).

  4. GH_SHA is the SHA-1 of the analyzed commit.

  5. Optionally, --command specifies how the Jenkins component is built. This is useful if a custom build command should be used.

  6. Replace jenkins-infra/jenkins-codeql with /path/to/clone-of-this-repo/src/ to use locally modified sources.

  7. Optionally, this invocation of jq removes all results from the report that have suppressions applied (through comments or annotations).

Development

Run tests

codeql pack install test/
codeql test run test/

The file run-tests.sh in this repository is a self-contained script that installs CodeQL, pack dependencies, and then runs the tests. Since it downloads and extracts CodeQL CLI binaries, its use is not recommended for local development.

Update CodeQL

To update to a newer CodeQL release:

  1. Determine which release to update to. See the list of CodeQL releases and the corresponding releases of java-all.

  2. Edit all qlpack.yml files in this repository and increase the version of codeql/java-all to the corresponding version in github/codeql (java/ql/src/qlpack.yml at the tagged top-level version in tags).

  3. Run codeql pack upgrade <dir> on each of the directories containing a qlpack.yml file.

  4. Edit run-tests.sh to download the correct CodeQL release and run it to confirm everything works as expected.

Note
 https://github.com/jenkins-infra/jenkins-security-scan needs a corresponding change.

Release as CodeQL Pack

To release this as QL packs here:

  1. Update the versions from x.y.z-dev to x.y.z in qlpack.yml files and git commit this (example).

  2. Define the environment variable GITHUB_TOKEN or prepare to pass the argument --github-auth-stdin to the next command. Either way, you need a token with write:packages permission.

  3. Run codeql pack publish --groups=-test to upload everything but the tests as packs.

  4. Update the versions from x.y.z to x.y.(z+1)-dev in qlpack.yml files and git commit this (example).