-
Notifications
You must be signed in to change notification settings - Fork 74
/
README.md
248 lines (183 loc) · 12.3 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
# GitHub Action for Vulnerability Scanning
**:zap: _Find threats in files or containers at lightning speed_ :zap:**
[![Test Status][test-img]][test]
[](https://github.com/anchore/scan-action/releases/latest)
[](https://github.com/anchore/scan-action/blob/main/LICENSE)
[](https://anchore.com/discourse)
This is a GitHub Action for invoking the [Grype](https://github.com/anchore/grype) scanner and returning the vulnerabilities found,
and optionally fail if a vulnerability is found with a configurable severity level.
Use this in your workflows to quickly verify files or containers' content after a build and before pushing, allowing PRs, or deploying updates.
The action invokes the `grype` command-line tool, with these benefits:
- Runs locally, without sending data outbound - no credentials required!
- Speedy scan operations
- Scans both paths and container images
- Easy failure evaluation depending on vulnerability severity
The example workflows have lots of usage examples for scanning both containers and directories.
By default, a scan will produce very detailed output on system packages like an RPM or DEB, but also language-based packages. These are some of the supported packages and libraries:
Supported Linux Distributions:
- Alpine
- BusyBox
- CentOS and RedHat
- Debian and Debian-based distros like Ubuntu
Supported packages and libraries:
- Ruby Bundles
- Python Wheel, Egg, `requirements.txt`
- JavaScript NPM/Yarn
- Java JAR/EAR/WAR, Jenkins plugins JPI/HPI
- Go modules
## Container scanning
The simplest workflow for scanning a `localbuild/testimage` container:
```yaml
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
- name: build local container
uses: docker/build-push-action@v4
with:
tags: localbuild/testimage:latest
push: false
load: true
- name: Scan image
uses: anchore/scan-action@v3
with:
image: "localbuild/testimage:latest"
```
## Directory scanning
To scan a directory, add the following step:
```yaml
- name: Scan current project
uses: anchore/scan-action@v3
with:
path: "."
```
The `path` key allows any valid path for the current project. The root of the path (`"."` in this example) is the repository root.
## Scanning an SBOM file
Use the `sbom` key to scan an SBOM file:
```yaml
- name: Create SBOM
uses: anchore/sbom-action@v0
with:
format: spdx-json
output-file: "${{ github.event.repository.name }}-sbom.spdx.json"
- name: Scan SBOM
uses: anchore/scan-action@v3
with:
sbom: "${{ github.event.repository.name }}-sbom.spdx.json"
```
## Failing a build on vulnerability severity
By default, if any vulnerability at `medium` or higher is seen, the build fails. To have the build step fail in cases where there are vulnerabilities with a severity level different than the default, set the `severity-cutoff` field to one of `low`, `high`, or `critical`:
With a different severity level:
```yaml
- name: Scan image
uses: anchore/scan-action@v3
with:
image: "localbuild/testimage:latest"
fail-build: true
severity-cutoff: critical
```
Optionally, change the `fail-build` field to `false` to avoid failing the build regardless of severity:
```yaml
- name: Scan image
uses: anchore/scan-action@v3
with:
image: "localbuild/testimage:latest"
fail-build: false
```
### Action Inputs
The inputs `image`, `path`, and `sbom` are mutually exclusive to specify the source to scan; all the other keys are optional. These are all the available keys to configure this action, along with the defaults:
| Input Name | Description | Default Value |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `image` | The image to scan | N/A |
| `path` | The file path to scan | N/A |
| `sbom` | The SBOM to scan | N/A |
| `registry-username` | The registry username to use when authenticating to an external registry | |
| `registry-password` | The registry password to use when authenticating to an external registry | |
| `fail-build` | Fail the build if a vulnerability is found with a higher severity. That severity defaults to `medium` and can be set with `severity-cutoff`. | `true` |
| `output-format` | Set the output parameter after successful action execution. Valid choices are `json`, `sarif`, and `table`, where `table` output will print to the console instead of generating a file. | `sarif` |
| `severity-cutoff` | Optionally specify the minimum vulnerability severity to trigger a failure. Valid choices are "negligible", "low", "medium", "high" and "critical". Any vulnerability with a severity less than this value will lead to a "warning" result. Default is "medium". | `medium` |
| `only-fixed` | Specify whether to only report vulnerabilities that have a fix available. | `false` |
| `add-cpes-if-none` | Specify whether to autogenerate missing CPEs. | `false` |
| `by-cve` | Specify whether to orient results by CVE rather than GHSA. | `false` |
| `vex` | Specify a list of VEX documents to consider when producing scanning results. | `false` |
| `grype-version` | An optional Grype version to download, defaults to the pinned version in [GrypeVersion.js](GrypeVersion.js). | |
### Action Outputs
| Output Name | Description | Type |
| ----------- | ------------------------------------------------------------ | ------ |
| `sarif` | Path to the SARIF report file, if `output-format` is `sarif` | string |
| `json` | Path to the report file , if `output-format` is `json` | string |
### Example Workflows
Assuming your repository has a Dockerfile in the root directory:
```yaml
name: Container Image CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- name: Build the container image
run: docker build . --file Dockerfile --tag localbuild/testimage:latest
- uses: anchore/scan-action@v3
with:
image: "localbuild/testimage:latest"
fail-build: true
```
Same example as above, but with SARIF output format - as is the default, the action will generate a SARIF report, which can be uploaded and then displayed as a Code Scanning Report in the GitHub UI.
> :bulb: Code Scanning is a Github service that is currently in Beta. [Follow the instructions on how to enable this service for your project](https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/enabling-code-scanning-for-a-repository).
```yaml
name: Container Image CI
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
- name: Build the Container image
run: docker build . --file Dockerfile --tag localbuild/testimage:latest
- uses: anchore/scan-action@v3
id: scan
with:
image: "localbuild/testimage:latest"
- name: upload Anchore scan SARIF report
uses: github/codeql-action/upload-sarif@v2
with:
sarif_file: ${{ steps.scan.outputs.sarif }}
```
Optionally, you can add a step to inspect the SARIF report produced:
```yaml
- name: Inspect action SARIF report
run: cat ${{ steps.scan.outputs.sarif }}
```
## Additional configuration
You may add a `.grype.yaml` file at your repository root
for more [Grype configuration](https://github.com/anchore/grype#configuration)
such as [ignoring certain matches](https://github.com/anchore/grype#specifying-matches-to-ignore).
## anchore/scan-action/download-grype
A sub-action to [download Grype](download-grype/action.yml).
Input parameters:
| Parameter | Description | Default |
| --------------- | ------------------------------------------------------------------------------------------------------------ | ------- |
| `grype-version` | An optional Grype version to download, defaults to the pinned version in [GrypeVersion.js](GrypeVersion.js). | |
Output parameters:
| Parameter | Description |
| --------- | -------------------------------------------------------------------- |
| `cmd` | a reference to the [Grype](https://github.com/anchore/grype) binary. |
`cmd` can be referenced in a workflow like other output parameters:
`${{ steps.<step-id>.outputs.cmd }}`
Example usage:
```yaml
- uses: anchore/scan-action/download-grype@v3
id: grype
- run: ${{steps.grype.outputs.cmd}} dir:.
```
## Contributing
We love contributions, feedback, and bug reports. For issues with the invocation of this action, file [issues](https://github.com/anchore/scan-action/issues) in this repository.
For contributing, see [Contributing](CONTRIBUTING.md).
## More Information
For documentation on Grype itself, including other output capabilities, see the [grype project](https://github.com/anchore/grype)
Connect with the community directly on [Discourse](https://anchore.com/discourse).
[test]: https://github.com/anchore/scan-action
[test-img]: https://github.com/anchore/scan-action/workflows/Tests/badge.svg
## Diagnostics
This action makes extensive use of GitHub Action debug logging,
which can be enabled as [described here](https://github.com/actions/toolkit/blob/master/docs/action-debugging.md)
by setting a secret in your repository of `ACTIONS_STEP_DEBUG` to `true`.