gh-codeql-scan

GitHub CLI CodeQL Scan Extension to help abstract CodeQL away from users.

Motivation

This project was created to make the lives of users that use CodeQL simpiler. CodeQL outside of GitHub Actions can be complicated but this projects aim is to make it as simple as possible.

Requirements

• GitHub CLI
• CodeQL GH Extension (optional)

Install and Setup

This installs CodeQL and this scan tool:

gh extensions install github/gh-codeql
gh extensions install advanced-security/gh-codeql-scan

gh codeql-scan --help

CLI Help

GitHub CodeQL Scan tool

gh codeql-scan {MODE} {ARGS}

# Modes

gh codeql-scan              # default: "scan"
gh codeql-scan init         # initialise the scan 
gh codeql-scan analyze      # run the analysis
gh codeql-scan upload       # upload present SARIF files
gh codeql-scan scan         # full end-to-end scan 

# Arguments

> All arguments can be set with enviroment variables

-h|--help               # Print help
--debug                 # Enable debugging
    
-r=*|--repo=*           # GitHub Respository (OWNER/NAME)
-i=*|--instance=*       # GitHub Instance (github.com or Enterprise Server)

-l=*|--language=*       # Set language to scan
--auto-detect           # Auto-detect languages

-s=*|--suite=*          # Query Suite to use
-d=*|--databases=*      # Location of the databases to store
-b=*|--binary=*         # Path to the CodeQL Binary
-w=*|--workspace=*      # Workspace for the souce code

-c=*|--command=*        # Set the build comment (compiled languages)
-m=*|--mode=*           # Build mode (autobuild | none)
--buildless             # Enable buildless / build mode none

--view-in-vscode        # Auto-open the results in VSCode

--disable-tracing       # Disable Build Tracing
--disable-trap-caching  # Disable Trap file caching
--disable-upload        # Disable Uploading SARIF to GitHub
--disable-banner        # Disable printing banner

Alias / Stub

A couple of tips and tricks:

# Create an alias to make things even easier
alias codeql-scan="gh codeql-scan"

Usage

The main use of the script is to automatically run CodeQL in a number of modes.

# End-to-end analysis and upload results
gh codeql-scan

Initialise with language

Automatically detect languages or manually set the language to create an initial CodeQL database.

gh codeql-scan init --auto-detect
# or manually set language
gh codeql-scan init -l=java 

Scan without build

This will scan your code in build mode none.

gh codeql-scan -m="none"
# or simply
gh codeql-scan --buildless

Scan with Build Command

Pass in the build command for a compiled language and it will be run along with CodeQL.

gh codeql-scan -c "mvn build ..."

Indirect build tracing

For Compiled languages, complicated build process using indirect build tracing

gh codeql-scan init
echo "password=$password" > settings.xml
mvn build --random-custom=flags
gh codeql-scan analyze

Running analysis

Run query-suites on an existing database (auto-detects databases)

gh codeql-scan analyze

Uploading results to GitHub

The upload mode will upload all SARIF files for you to a repository

gh codeql-scan upload

Maintainers

• @GeekMasher

Support / Maintainance

Support is via GitHub Issues

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.