diff --git a/README.md b/README.md index be92b90..faab299 100644 --- a/README.md +++ b/README.md @@ -2,40 +2,228 @@ 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](https://redhat.com/en/technologies/cloud-computing/openshift/advanced-cluster-security-kubernetes)). -### Example +![](./docs/images/roxctl-action.png) -This example uses [central-login](https://github.com/stackrox/central-login) Github Action to login to ACS Central for `roxctl` download. +## Table of Contents + +- [Parameters](#parameters) +- [Authentication](#authentication) + - [Authenticate with short-lived access tokens](#authenticate-with-short-lived-access-tokens) + - [Authenticate with long-lived API tokens](#authenticate-with-long-lived-api-tokens) +- [Usage](#usage) + - [Scan images in CI pipelines](#scan-images-in-ci-pipelines) + - [Check images in CI pipelines](#check-images-in-ci-pipelines) + - [Download roxctl from mirror.openshift.com](#download-roxctl-from-mirroropenshiftcom) + - [GitHub code scanning](#github-code-scanning) + +## 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](https://github.com/stackrox/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`. + +![](./docs/images/machine-access.png) + +The following examples assume `env.CENTRAL_ENDPOINT=https://my-central.com` to be a valid Central URL. + +See [Scan images in CI pipelines](#scan-images-in-ci-pipelines) and [Check images in CI pipelines](#check-images-in-ci-pipelines) for full length examples. + +```yaml +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. + +```yaml +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`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image) +for the full parameter list. + +```yaml +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`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-check_roxctl-image) +for the full parameter list. ```yaml +name: Check image with roxctl +on: + push: + branches: ["main"] + pull_request: jobs: - example: - runs-on: macos-latest + check: + runs-on: ubuntu-latest permissions: id-token: write steps: - - name: Central Login + - name: Central login uses: stackrox/central-login@v1 with: - endpoint: https://${{ env.ROX_ENDPOINT }} - - uses: stackrox/roxctl-installer-action@main + endpoint: ${{ env.CENTRAL_ENDPOINT }} + - name: Install roxctl + uses: stackrox/roxctl-installer-action@v1 with: - install-dir: /usr/local/bin - roxctl-release: 4.4.0 - central-endpoint: https://${{ env.ROX_ENDPOINT }} + 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`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image) +for the full parameter list. - - name: Validate the roxctl install and its token +```yaml +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 --image=nginx:latest + roxctl image scan --output=table --image="quay.io/stackrox-io/main" ``` -### Parameters +### GitHub code scanning -| 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. | +See [`roxctl image scan`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image) +for the full parameter list. + +```yaml +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 +``` diff --git a/docs/images/machine-access.png b/docs/images/machine-access.png new file mode 100644 index 0000000..0421b87 Binary files /dev/null and b/docs/images/machine-access.png differ diff --git a/docs/images/roxctl-action.png b/docs/images/roxctl-action.png new file mode 100644 index 0000000..bf93698 Binary files /dev/null and b/docs/images/roxctl-action.png differ