Skip to content
stackrox

GitHub Action

Install roxctl

v1.1.2 Latest version

Install roxctl

stackrox

Install roxctl

Download roxctl for use in GitHub Actions

Installation

Copy and paste the following snippet into your .yml file.

              

- name: Install roxctl

uses: stackrox/[email protected]

Learn more about this action in stackrox/roxctl-installer-action

Choose a version

roxctl-installer-action GitHub Action

This is a GitHub action for installing roxctl on Github Action runners. roxctl is a command-line interface (CLI) for running commands on Red Hat Advanced Cluster Security for Kubernetes (RHACS).

Table of Contents

Parameters

Parameter name Required? Description
install-dir (optional) Path of directory to install roxctl to.
version (optional) roxctl release version to use, e.g. "4.4.0". The latest available version is used by default. Ignored when central-endpoint is specified.
central-endpoint (optional) RHACS Central endpoint to download roxctl from. If left unspecified, roxctl is downloaded from mirror.openshift.com instead. Requires central-token to be set.
central-token (optional) Token to access RHACS Central endpoint.
skip-tls-verify (optional) Skip TLS certificate verification for Central's API endpoint. false by default.

Authentication

Authenticate with short-lived access tokens

Short-lived access tokens are the recommended authentication method when using roxctl in GitHub workflows. To generate a suitable token, configure a machine access configuration in Central and run the central-login Github Action to set up an authenticated environment.

For example, to allow access from GitHub workflows in the stackrox/stackrox repository:

  1. Create a machine access configuration of type GitHub in Central.
  2. Add a new rule with Key = sub, Value = repo:stackrox/stackrox.* and Role = Continuous Integration.

The following examples assume env.CENTRAL_ENDPOINT=https://my-central.com to be a valid Central URL.

See Scan images in CI pipelines and Check images in CI pipelines for full length examples.

steps:
  - name: Central login
    uses: stackrox/central-login@v1
    with:
      endpoint: ${{ env.CENTRAL_ENDPOINT }}
  - name: Install roxctl
    uses: stackrox/roxctl-installer-action@v1
    with:
      central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
      central-token: ${{ env.ROX_API_TOKEN }}

Authenticate with long-lived API tokens

Long-lived API tokens are not recommended because they carry an increased risk of credential exposure. They should only be used when short-lived access tokens are not an option.

To authenticate with a Central API token, create a GitHub secret secrets.ROX_API_TOKEN and assign its value to the API token.

name: Scan image with roxctl
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Install roxctl
        uses: stackrox/roxctl-installer-action@v1
        with:
          central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
          central-token: ${{ secrets.ROX_API_TOKEN }}
      - name: Scan image with roxctl
        shell: bash
        env:
          ROX_ENDPOINT: ${{ env.CENTRAL_ENDPOINT }}
          ROX_API_TOKEN: ${{ secrets.ROX_API_TOKEN }}
        run: |
          roxctl image scan --output=table --image="quay.io/stackrox-io/main"

Usage

Scan images in CI pipelines

See roxctl image scan for the full parameter list.

name: Scan image with roxctl
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Central login
        uses: stackrox/central-login@v1
        with:
          endpoint: ${{ env.CENTRAL_ENDPOINT }}
      - name: Install roxctl
        uses: stackrox/roxctl-installer-action@v1
        with:
          central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
          central-token: ${{ env.ROX_API_TOKEN }}
      - name: Scan image with roxctl
        shell: bash
        run: |
          roxctl image scan --output=table --image="quay.io/stackrox-io/main"

Check images in CI pipelines

See roxctl image check for the full parameter list.

name: Check image with roxctl
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Central login
        uses: stackrox/central-login@v1
        with:
          endpoint: ${{ env.CENTRAL_ENDPOINT }}
      - name: Install roxctl
        uses: stackrox/roxctl-installer-action@v1
        with:
          central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
          central-token: ${{ env.ROX_API_TOKEN }}
      - name: Check image with roxctl
        shell: bash
        run: |
          roxctl image check --output=table --image="quay.io/stackrox-io/main"

Download roxctl from mirror.openshift.com

See roxctl image scan for the full parameter list.

name: Scan image with roxctl
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: Central login
        uses: stackrox/central-login@v1
        with:
          endpoint: ${{ env.CENTRAL_ENDPOINT }}
      - name: Install roxctl
        uses: stackrox/roxctl-installer-action@v1
        with:
          version: 4.4.0
      - name: Scan image with roxctl
        shell: bash
        run: |
          roxctl image scan --output=table --image="quay.io/stackrox-io/main"

GitHub code scanning

See roxctl image scan for the full parameter list.

name: Code scanning with roxctl
on:
  push:
    branches: ["main"]
  pull_request:
jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      security-events: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Central login
        uses: stackrox/central-login@v1
        with:
          endpoint: ${{ env.CENTRAL_ENDPOINT }}
      - name: Install roxctl
        uses: stackrox/roxctl-installer-action@v1
        with:
          central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
          central-token: ${{ env.ROX_API_TOKEN }}
      - name: Scan image with roxctl
        shell: bash
        run: |
          roxctl image scan --output=sarif --image="quay.io/stackrox-io/main" > results.sarif
      - name: Upload roxctl scan results to GitHub code scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          category: stackrox-io/main
          sarif_file: results.sarif