Skip to content

Commit 01986cb

Browse files
stehesselstehessel
authored
ROX-23083: add more usage examples (#13)
* ROX-23083: add more usage examples * address feedback * move section * fix toc * fix link
1 parent 07a2fe8 commit 01986cb

3 files changed

Lines changed: 208 additions & 20 deletions

File tree

‎README.md‎

Lines changed: 208 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,228 @@
22

33
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)).
44

5-
### Example
5+
![](./docs/images/roxctl-action.png)
66

7-
This example uses [central-login](https://github.com/stackrox/central-login) Github Action to login to ACS Central for `roxctl` download.
7+
## Table of Contents
8+
9+
- [Parameters](#parameters)
10+
- [Authentication](#authentication)
11+
- [Authenticate with short-lived access tokens](#authenticate-with-short-lived-access-tokens)
12+
- [Authenticate with long-lived API tokens](#authenticate-with-long-lived-api-tokens)
13+
- [Usage](#usage)
14+
- [Scan images in CI pipelines](#scan-images-in-ci-pipelines)
15+
- [Check images in CI pipelines](#check-images-in-ci-pipelines)
16+
- [Download roxctl from mirror.openshift.com](#download-roxctl-from-mirroropenshiftcom)
17+
- [GitHub code scanning](#github-code-scanning)
18+
19+
## Parameters
20+
21+
| Parameter name | Required? | Description |
22+
| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23+
| `install-dir` | (optional) | Path of directory to install `roxctl` to. |
24+
| `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. |
25+
| `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. |
26+
| `central-token` | (optional) | Token to access RHACS Central endpoint. |
27+
| `skip-tls-verify` | (optional) | Skip TLS certificate verification for Central's API endpoint. `false` by default. |
28+
29+
## Authentication
30+
31+
### Authenticate with short-lived access tokens
32+
33+
Short-lived access tokens are the recommended authentication method when using `roxctl` in GitHub workflows.
34+
To generate a suitable token, configure a machine access configuration in Central and run the
35+
[central-login](https://github.com/stackrox/central-login) Github Action to set up an authenticated environment.
36+
37+
For example, to allow access from GitHub workflows in the `stackrox/stackrox` repository:
38+
39+
1. Create a machine access configuration of type `GitHub` in Central.
40+
2. Add a new rule with `Key = sub`, `Value = repo:stackrox/stackrox.*` and `Role = Continuous Integration`.
41+
42+
![](./docs/images/machine-access.png)
43+
44+
The following examples assume `env.CENTRAL_ENDPOINT=https://my-central.com` to be a valid Central URL.
45+
46+
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.
47+
48+
```yaml
49+
steps:
50+
- name: Central login
51+
uses: stackrox/central-login@v1
52+
with:
53+
endpoint: ${{ env.CENTRAL_ENDPOINT }}
54+
- name: Install roxctl
55+
uses: stackrox/roxctl-installer-action@v1
56+
with:
57+
central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
58+
central-token: ${{ env.ROX_API_TOKEN }}
59+
```
60+
61+
### Authenticate with long-lived API tokens
62+
63+
Long-lived API tokens are not recommended because they carry an increased risk of credential exposure.
64+
They should only be used when short-lived access tokens are not an option.
65+
66+
To authenticate with a Central API token, create a GitHub secret `secrets.ROX_API_TOKEN` and assign its value to the API token.
67+
68+
```yaml
69+
name: Scan image with roxctl
70+
on:
71+
push:
72+
branches: ["main"]
73+
pull_request:
74+
jobs:
75+
scan:
76+
runs-on: ubuntu-latest
77+
permissions:
78+
id-token: write
79+
steps:
80+
- name: Install roxctl
81+
uses: stackrox/roxctl-installer-action@v1
82+
with:
83+
central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
84+
central-token: ${{ secrets.ROX_API_TOKEN }}
85+
- name: Scan image with roxctl
86+
shell: bash
87+
env:
88+
ROX_ENDPOINT: ${{ env.CENTRAL_ENDPOINT }}
89+
ROX_API_TOKEN: ${{ secrets.ROX_API_TOKEN }}
90+
run: |
91+
roxctl image scan --output=table --image="quay.io/stackrox-io/main"
92+
```
93+
94+
## Usage
95+
96+
### Scan images in CI pipelines
97+
98+
See [`roxctl image scan`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image)
99+
for the full parameter list.
100+
101+
```yaml
102+
name: Scan image with roxctl
103+
on:
104+
push:
105+
branches: ["main"]
106+
pull_request:
107+
jobs:
108+
scan:
109+
runs-on: ubuntu-latest
110+
permissions:
111+
id-token: write
112+
steps:
113+
- name: Central login
114+
uses: stackrox/central-login@v1
115+
with:
116+
endpoint: ${{ env.CENTRAL_ENDPOINT }}
117+
- name: Install roxctl
118+
uses: stackrox/roxctl-installer-action@v1
119+
with:
120+
central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
121+
central-token: ${{ env.ROX_API_TOKEN }}
122+
- name: Scan image with roxctl
123+
shell: bash
124+
run: |
125+
roxctl image scan --output=table --image="quay.io/stackrox-io/main"
126+
```
127+
128+
### Check images in CI pipelines
129+
130+
See [`roxctl image check`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-check_roxctl-image)
131+
for the full parameter list.
8132

9133
```yaml
134+
name: Check image with roxctl
135+
on:
136+
push:
137+
branches: ["main"]
138+
pull_request:
10139
jobs:
11-
example:
12-
runs-on: macos-latest
140+
check:
141+
runs-on: ubuntu-latest
13142
permissions:
14143
id-token: write
15144
steps:
16-
- name: Central Login
145+
- name: Central login
17146
uses: stackrox/central-login@v1
18147
with:
19-
endpoint: https://${{ env.ROX_ENDPOINT }}
20-
- uses: stackrox/roxctl-installer-action@main
148+
endpoint: ${{ env.CENTRAL_ENDPOINT }}
149+
- name: Install roxctl
150+
uses: stackrox/roxctl-installer-action@v1
21151
with:
22-
install-dir: /usr/local/bin
23-
roxctl-release: 4.4.0
24-
central-endpoint: https://${{ env.ROX_ENDPOINT }}
152+
central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
25153
central-token: ${{ env.ROX_API_TOKEN }}
154+
- name: Check image with roxctl
155+
shell: bash
156+
run: |
157+
roxctl image check --output=table --image="quay.io/stackrox-io/main"
158+
```
159+
160+
### Download roxctl from mirror.openshift.com
161+
162+
See [`roxctl image scan`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image)
163+
for the full parameter list.
26164

27-
- name: Validate the roxctl install and its token
165+
```yaml
166+
name: Scan image with roxctl
167+
on:
168+
push:
169+
branches: ["main"]
170+
pull_request:
171+
jobs:
172+
scan:
173+
runs-on: ubuntu-latest
174+
permissions:
175+
id-token: write
176+
steps:
177+
- name: Central login
178+
uses: stackrox/central-login@v1
179+
with:
180+
endpoint: ${{ env.CENTRAL_ENDPOINT }}
181+
- name: Install roxctl
182+
uses: stackrox/roxctl-installer-action@v1
183+
with:
184+
version: 4.4.0
185+
- name: Scan image with roxctl
28186
shell: bash
29187
run: |
30-
roxctl image scan --image=nginx:latest
188+
roxctl image scan --output=table --image="quay.io/stackrox-io/main"
31189
```
32190

33-
### Parameters
191+
### GitHub code scanning
34192

35-
| Parameter name | Required? | Description |
36-
|--------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
37-
| `install-dir` | (optional) | Path of directory to install `roxctl` to. |
38-
| `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. |
39-
| `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. |
40-
| `central-token` | (optional) | Token to access RHACS Central endpoint. |
41-
| `skip-tls-verify` | (optional) | Skip TLS certificate verification for Central's API endpoint. `false` by default. |
193+
See [`roxctl image scan`](https://docs.openshift.com/acs/4.4/cli/command-reference/roxctl-image.html#roxctl-image-scan_roxctl-image)
194+
for the full parameter list.
195+
196+
```yaml
197+
name: Code scanning with roxctl
198+
on:
199+
push:
200+
branches: ["main"]
201+
pull_request:
202+
jobs:
203+
scan:
204+
runs-on: ubuntu-latest
205+
permissions:
206+
id-token: write
207+
security-events: write
208+
steps:
209+
- name: Checkout
210+
uses: actions/checkout@v4
211+
- name: Central login
212+
uses: stackrox/central-login@v1
213+
with:
214+
endpoint: ${{ env.CENTRAL_ENDPOINT }}
215+
- name: Install roxctl
216+
uses: stackrox/roxctl-installer-action@v1
217+
with:
218+
central-endpoint: ${{ env.CENTRAL_ENDPOINT }}
219+
central-token: ${{ env.ROX_API_TOKEN }}
220+
- name: Scan image with roxctl
221+
shell: bash
222+
run: |
223+
roxctl image scan --output=sarif --image="quay.io/stackrox-io/main" > results.sarif
224+
- name: Upload roxctl scan results to GitHub code scanning
225+
uses: github/codeql-action/upload-sarif@v3
226+
with:
227+
category: stackrox-io/main
228+
sarif_file: results.sarif
229+
```

‎docs/images/machine-access.png‎

334 KB
Loading

‎docs/images/roxctl-action.png‎

434 KB
Loading

0 commit comments

Comments
 (0)