Skip to content

workflows.md

Latest commit

 

History

History
132 lines (101 loc) · 3.88 KB

workflows.md

File metadata and controls

132 lines (101 loc) · 3.88 KB
Raw

Workflows

Basic Usage

To use the CodeQL Extractor, Library, and Queries for Infrastructure as Code, you will need to add the following step to your workflow:

- name: Initialize and Analyze IaC
  uses: advanced-security/codeql-extractor-iac@v0.5.1

Uploading SARIF files to GitHub

The CodeQL Extractor will produce a SARIF file but will not upload it for you. This has to be done manually or using the github/codeql-action/upload-sarif action like so:

- name: Upload SARIF file
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: codeql-iac.sarif

Full Action Example

.github/workflows/codeql-iac.yml :

name: "CodeQL IaC"

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:

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

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

      - name: Initialize and Analyze IaC
        id: codeql_iac
        uses: advanced-security/codeql-extractor-iac@v0.5.1
        # Uncomment if you want to show the tool name as CodeQL instead of CodeQL-IaC (NOTE: this may conflict with Default Setup)
        #with:
        #  rewrite-sarif-tool-name: false
      
      - name: "Upload SARIF file"
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: ${{ steps.codeql_iac.outputs.sarif-results }}

CodeQL CLI

The CodeQL CLI can be used to analyze IaC files using the CodeQL Extractor, Library, and Queries for Infrastructure as Code. You will need to follow these steps to use the CodeQL CLI:

  1. Download the latest CodeQL CLI
  2. Download and install the extractor version you want to use
    • The extractor should be placed in the codeql dist folder
    • Running codeql version --format=json will show the location of the codeql dist folder
  3. Check the extractor is installed correctly by running:
    • codeql resolve languages and checking if iac is listed
  4. Install the IaC queries pack by running:
    • codeql pack install advanced-security/iac-queries
  5. Run the CodeQL database commands to create and analyze the IaC files
    • codeql database create <database-name> --language=iac --source-root=<path-to-iac-files>
    • codeql database analyze <database-name> --format=sarif-latest --output=<output-file-name> advanced-security/iac-queries

CLI Example

Install extractor

# CodeQL Dist directory
CODEQL_DIST=$(codeql version --format=json | jq -r '.unpackedLocation')

# Download
gh release download \
    -R "advanced-security/codeql-extractor-iac" \
    -D "$CODEQL_DIST" \
    --clobber \
    --pattern 'extractor-*.tar.gz'

tar -zxf "$CODEQL_DIST/extractor-iac.tar.gz" --directory "$CODEQL_DIST"

Create and analyze database

CODEQL_DATABASE="codeql-iac"
# Create database
codeql database create \
  --language=iac \
  --overwrite \
  "$CODEQL_DATABASE"

# Analyze database and output SARIF file
codeql database analyze \
  --format="sarif-latest" \
  --output="./codeql-iac.sarif" \
  "$CODEQL_DATABASE" \
  "advanced-security/iac-queries"

Install extractor on Windows

PowerShell equivalents of the scripts above are provided for Windows. From a checkout of this repository:

# Install the extractor into $env:USERPROFILE\.codeql\extractors (default)
.\scripts\install-extractor.ps1

# Or build the extractor pack locally
.\scripts\create-extractor-pack.ps1

# Run the test suite
.\scripts\run-tests.ps1 ql\test\library-tests

Both pwsh (PowerShell 7+) and Windows PowerShell 5.1 are supported. The scripts require either codeql or gh on the PATH; if only gh is available, the gh-codeql extension will be installed automatically.