GitHub Action

Quick Start

Add this step to any workflow file. The action runs the latest scanner (0.2.0 or later) via npx --yes @cveriskpilot/scan with your chosen inputs. Inputs you leave empty fall back to a committed .cveriskpilot.json profile, then to the scanner defaults.

# Minimal workflow
name: Compliance Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devbrewster/cveriskpilot-scan/action@main

Full Workflow Example

A complete workflow with a PR comment, SARIF upload to GitHub Code Scanning (done by the action when upload-sarif is true, the default) and upload to the CVERiskPilot dashboard. The API key is passed on pushes to main only: an upload updates the dashboard's findings for the repository, and a pull request scans code that is not merged, so it would close findings it happens to fix and open cases for code that may never merge. Pull requests still get the check and the comment.

name: Compliance Scan
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write
  security-events: write

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run CVERiskPilot Compliance Scan
        id: scan
        uses: devbrewster/cveriskpilot-scan/action@main
        with:
          preset: enterprise
          fail-on: high
          comment: 'true'
          upload-sarif: 'true'
          # upload from pushes to main only, never pull requests
          api-key: ${{ github.event_name == 'push' && secrets.CRP_API_KEY || '' }}
          # only when your organization has several clients
          client: 'Acme Production'
          fail-on-upload-error: 'true'

Inputs

All inputs are optional. Configure them under the with: key in your workflow step.

Outputs

Access outputs from subsequent steps using steps.<step-id>.outputs.<name>.

PR Comments

When comment: 'true' (the default), the action posts a detailed summary comment on the pull request. The comment includes:

• Severity summary with color-coded counts (critical, high, medium, low)
• Findings table with file paths, CWE identifiers, and matched compliance controls
• Compliance impact breakdown showing which framework controls are affected
• Rule-based triage verdicts: actionable, needs review, or auto-dismissed

The action uses a hidden HTML marker <!-- crp-scan-comment --> to identify its comments. On subsequent runs, it updates the existing comment instead of posting a new one, keeping your PR clean and free of duplicate reports.

Internally, the action uses actions/github-script@v7 to interact with the GitHub API for comment management.

Common Workflow Examples

- uses: devbrewster/cveriskpilot-scan/action@main
  with:
    preset: startup
    fail-on: critical

- name: CMMC Compliance Scan
  uses: devbrewster/cveriskpilot-scan/action@main
  with:
    preset: defense
    fail-on: high

- uses: devbrewster/cveriskpilot-scan/action@main
  with:
    preset: enterprise
    comment: 'false'
    api-key: ${{ secrets.CRP_API_KEY }}
    client: 'Acme Production'

- uses: devbrewster/cveriskpilot-scan/action@main
  with:
    scanners: deps
    fail-on: high

- uses: devbrewster/cveriskpilot-scan/action@main
  with:
    preset: enterprise
    exclude: '**/test/**,**/fixtures/**,docs/**'

Using Outputs

Reference outputs from the scan step in subsequent steps to build conditional workflows, send notifications, or gate deployments.

steps:
  - uses: actions/checkout@v4

  - name: Run Compliance Scan
    id: scan
    uses: devbrewster/cveriskpilot-scan/action@main
    with:
      preset: enterprise
      fail-on: high

  - name: Check Results
    if: always()
    run: |
      echo "Exit code: ${{ steps.scan.outputs.exit-code }}"
      echo "Total findings: ${{ steps.scan.outputs.total-findings }}"
      echo "Critical: ${{ steps.scan.outputs.critical-count }}"
      echo "High: ${{ steps.scan.outputs.high-count }}"
      echo "Controls affected: ${{ steps.scan.outputs.controls-affected }}"

  - name: Block Deploy on Critical
    if: steps.scan.outputs.critical-count != '0'
    run: |
      echo "Blocking deployment: ${{ steps.scan.outputs.critical-count }} critical findings"
      exit 1

How It Works

The GitHub Action is a composite action that orchestrates three steps internally:

With an api-key, the scan step also uploads the run to CVERiskPilot. The upload names the repository as its asset and carries the commit, branch and pull request number, and the job log shows the link to the upload on the dashboard, or the reason an upload failed. The pass/fail verdict also appears on the Pipelines page.

When upload-sarif is true (the default), the action runs a second, local-only pass that writes SARIF 2.1.0 and uploads it to GitHub Code Scanning. Branding uses a shield icon with blue color in the GitHub Marketplace listing.

Next Steps