Skip to content

Commit

Permalink
docs: improve SBOM documentation (#208)
Browse files Browse the repository at this point in the history 
* fix: dependency graph name ocurrences

* feat: improve readability and add useful links

* feat: improve readability and instructions 

Improves readability and adds missing information about github_token, another authentication method.

* feat: add github_token instructions

* feat: add github_token to inputs table

* feat: add "what is an SBOM" link

* fix: GitHub dependency graph name ocurrence

* feat: improve SBOM input description

* fix: remove "on pull request" trigger

Co-authored-by: Duncan Casteleyn <[email protected]>

* fix: outdated input name

---------

Co-authored-by: Duncan Casteleyn <[email protected]>
  • Loading branch information
@saerosV @DuncanCasteleyn
saerosV and DuncanCasteleyn authored Mar 29, 2023
1 parent 1f0aa58 commit 1a09192
Showing 1 changed file with 36 additions and 31 deletions.
67 changes: 36 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -299,19 +299,24 @@ jobs:
```

### Using Trivy to generate SBOM
It's possible for Trivy to generate an SBOM of your dependencies and submit them to a consumer like GitHub Dependency Snapshot.
It's possible for Trivy to generate an [SBOM](https://www.aquasec.com/cloud-native-academy/supply-chain-security/sbom/) of your dependencies and submit them to a consumer like [GitHub Dependency Graph](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph).

The sending of SBOM to GitHub feature is only available if you currently have [GitHub Dependency Snapshot](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api) available to you in your repo.
The [sending of an SBOM to GitHub](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api) feature is only available if you currently have GitHub Dependency Graph [enabled in your repo](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-graph#enabling-and-disabling-the-dependency-graph-for-a-private-repository).

In order to send results to GitHub Dependency Graph, you will need to create a [GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) or use the [GitHub installation access token](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) (also known as `GITHUB_TOKEN`):

In order to send results to the GitHub Dependency Snapshot, you will need to create a [GitHub PAT](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
```yaml
---
name: Pull Request
on:
push:
branches:
- master
pull_request:
## GITHUB_TOKEN authentication, add only if you're not going to use a PAT
permissions:
contents: write
jobs:
build:
name: Checks
Expand All @@ -320,14 +325,14 @@ jobs:
- name: Checkout code
uses: actions/checkout@v3
- name: Run Trivy in GitHub SBOM mode and submit results to Dependency Snapshots
- name: Run Trivy in GitHub SBOM mode and submit results to Dependency Graph
uses: aquasecurity/trivy-action@master
with:
scan-type: 'fs'
format: 'github'
output: 'dependency-results.sbom.json'
image-ref: '.'
github-pat: '<github_pat_token>'
github-pat: ${{ secrets.GITHUB_TOKEN }} # or ${{ secrets.github_pat_name }} if you're using a PAT
```

### Using Trivy to scan your private registry
Expand Down Expand Up @@ -478,31 +483,31 @@ jobs:

Following inputs can be used as `step.with` keys:

| Name | Type | Default | Description |
|------------------------------|---------|------------------------------------|-------------------------------------------------------------------------------------------------|
| `scan-type` | String | `image` | Scan type, e.g. `image` or `fs` |
| `input` | String | | Tar reference, e.g. `alpine-latest.tar` |
| `image-ref` | String | | Image reference, e.g. `alpine:3.10.2` |
| `scan-ref` | String | `/github/workspace/` | Scan reference, e.g. `/github/workspace/` or `.` |
| `format` | String | `table` | Output format (`table`, `json`, `sarif`, `github`) |
| `template` | String | | Output template (`@/contrib/gitlab.tpl`, `@/contrib/junit.tpl`) |
| `output` | String | | Save results to a file |
| `exit-code` | String | `0` | Exit code when specified vulnerabilities are found |
| `ignore-unfixed` | Boolean | false | Ignore unpatched/unfixed vulnerabilities |
| `vuln-type` | String | `os,library` | Vulnerability types (os,library) |
| `severity` | String | `UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL` | Severities of vulnerabilities to scanned for and displayed |
| `skip-dirs` | String | | Comma separated list of directories where traversal is skipped |
| `skip-files` | String | | Comma separated list of files where traversal is skipped |
| `cache-dir` | String | | Cache directory |
| `timeout` | String | `5m0s` | Scan timeout duration |
| `ignore-policy` | String | | Filter vulnerabilities with OPA rego language |
| `hide-progress` | String | `true` | Suppress progress bar |
| `list-all-pkgs` | String | | Output all packages regardless of vulnerability |
| `scanners` | String | `vuln,secret` | comma-separated list of what security issues to detect (`vuln`,`secret`,`config`) |
| `trivyignores` | String | | comma-separated list of relative paths in repository to one or more `.trivyignore` files |
| `trivy-config` | String | | Path to trivy.yaml config |
| `github-pat` | String | | GitHub Personal Access Token (PAT) for sending SBOM scan results to GitHub Dependency Snapshots |
| `limit-severities-for-sarif` | Boolean | false | By default *SARIF* format enforces output of all vulnerabilities regardless of configured severities. To override this behavior set this parameter to **true** |
| Name | Type | Default | Description |
|-------------------|---------|------------------------------------|-------------------------------------------------------------------------------------------------|
| `scan-type` | String | `image` | Scan type, e.g. `image` or `fs` |
| `input` | String | | Tar reference, e.g. `alpine-latest.tar` |
| `image-ref` | String | | Image reference, e.g. `alpine:3.10.2` |
| `scan-ref` | String | `/github/workspace/` | Scan reference, e.g. `/github/workspace/` or `.` |
| `format` | String | `table` | Output format (`table`, `json`, `sarif`, `github`) |
| `template` | String | | Output template (`@/contrib/gitlab.tpl`, `@/contrib/junit.tpl`) |
| `output` | String | | Save results to a file |
| `exit-code` | String | `0` | Exit code when specified vulnerabilities are found |
| `ignore-unfixed` | Boolean | false | Ignore unpatched/unfixed vulnerabilities |
| `vuln-type` | String | `os,library` | Vulnerability types (os,library) |
| `severity` | String | `UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL` | Severities of vulnerabilities to scanned for and displayed |
| `skip-dirs` | String | | Comma separated list of directories where traversal is skipped |
| `skip-files` | String | | Comma separated list of files where traversal is skipped |
| `cache-dir` | String | | Cache directory |
| `timeout` | String | `5m0s` | Scan timeout duration |
| `ignore-policy` | String | | Filter vulnerabilities with OPA rego language |
| `hide-progress` | String | `true` | Suppress progress bar |
| `list-all-pkgs` | String | | Output all packages regardless of vulnerability |
| `scanners` | String | `vuln,secret` | comma-separated list of what security issues to detect (`vuln`,`secret`,`config`) |
| `trivyignores` | String | | comma-separated list of relative paths in repository to one or more `.trivyignore` files |
| `trivy-config` | String | | Path to trivy.yaml config |
| `github-pat` | String | | Authentication token to enable sending SBOM scan results to GitHub Dependency Graph. Can be either a GitHub Personal Access Token (PAT) or GITHUB_TOKEN |
| `limit-severities-for-sarif` | Boolean | false | By default *SARIF* format enforces output of all vulnerabilities regardless of configured severities. To override this behavior set this parameter to **true** |

[release]: https://github.com/aquasecurity/trivy-action/releases/latest
[release-img]: https://img.shields.io/github/release/aquasecurity/trivy-action.svg?logo=github
Expand Down

0 comments on commit 1a09192

Please sign in to comment.