From 8da35f011503af43d67750f93dfbb1a56da88564 Mon Sep 17 00:00:00 2001 From: Rex P <106129829+another-rex@users.noreply.github.com> Date: Tue, 10 Oct 2023 14:24:13 +1100 Subject: [PATCH] Improve documentation for github actions (#575) Attempt at the 3 remaining items mentioned in https://github.com/google/osv-scanner/issues/516. Feel free to do any rewording or rearranging @hayleycd to make things clearer! Also fix the SARIF test since it was still calling `createTextFixture` instead of `assertTextFixture` --- .github/workflows/osv-scanner-reusable-pr.yml | 10 +- .github/workflows/osv-scanner-reusable.yml | 2 +- docs/github-action.md | 127 ++++++++++--- docs/output.md | 168 +++++++++++++++++- .../output/fixtures/test-vuln-results-a.sarif | 2 +- internal/output/sarif_test.go | 2 +- 6 files changed, 276 insertions(+), 35 deletions(-) diff --git a/.github/workflows/osv-scanner-reusable-pr.yml b/.github/workflows/osv-scanner-reusable-pr.yml index c2f54394a9..ed570d341d 100644 --- a/.github/workflows/osv-scanner-reusable-pr.yml +++ b/.github/workflows/osv-scanner-reusable-pr.yml @@ -24,6 +24,10 @@ on: -r --skip-git ./ + results-file-name: + description: "File name of the result SARIF file" + type: string + default: results.sarif jobs: scan-pr: @@ -57,7 +61,7 @@ jobs: uses: google/osv-scanner/actions/reporter@main with: scan-args: |- - --output=final-results.sarif + --output=${{ inputs.results-file-name }} --old=old-results.json --new=new-results.json --gh-annotations=true @@ -68,7 +72,7 @@ jobs: uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3 with: name: SARIF file - path: final-results.sarif + path: ${{ inputs.results-file-name }} retention-days: 5 - name: "Upload old scan json results" if: '!cancelled()' @@ -89,4 +93,4 @@ jobs: if: '!cancelled()' uses: github/codeql-action/upload-sarif@2cb752a87e96af96708ab57187ab6372ee1973ab # v2.22.0 with: - sarif_file: final-results.sarif + sarif_file: ${{ inputs.results-file-name }} diff --git a/.github/workflows/osv-scanner-reusable.yml b/.github/workflows/osv-scanner-reusable.yml index 18325e3ae6..8153029f20 100644 --- a/.github/workflows/osv-scanner-reusable.yml +++ b/.github/workflows/osv-scanner-reusable.yml @@ -30,7 +30,7 @@ on: default: results.sarif jobs: - scan-scheduled: + osv-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/docs/github-action.md b/docs/github-action.md index d5d920efd6..fdd4f8e93c 100644 --- a/docs/github-action.md +++ b/docs/github-action.md @@ -11,9 +11,81 @@ nav_order: 6 OSV-Scanner is offered as a GitHub Action. We currently have two different GitHub Actions: -1. An action that performs a vulnerability scan on a [regular schedule](./github-action.md#scheduled-scans). +1. An action that performs a single vulnerability scan, which can be configured to scan on a [regular schedule](./github-action.md#scheduled-scans), or used as a check [on releases](./github-action.md#scan-on-release) to prevent releasing with known vulnerabilities in dependencies. 2. An action that triggers a scan with each [pull request](./github-action.md#scans-on-prs) and will only check for new vulnerabilities introduced through the pull request. +## Scans on PRs + +Scanning your project on each pull request can help you keep vulnerabilities out of your project. This GitHub Action compares a vulnerability scan of the main branch to a vulnerability scan of the feature branch. You will be notified of any new vulnerabilities introduced through the feature branch. You can also choose to [prevent merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) if new vulnerabilities are introduced through the feature branch. + +### Instructions + +In your project repository, create a new file `.github/workflows/osv-scanner-pr.yml`. + +Include the following in the [`osv-scanner-pr.yml`](https://github.com/google/osv-scanner/blob/main/.github/workflows/osv-scanner-pr.yml) file: + +```yml +name: OSV-Scanner PR Scan + +# Change "main" to your default branch if you use a different name, i.e. "master" +on: + pull_request: + branches: [ main ] + merge_group: + branches: [ main ] + +# Declare default permissions as read only. +permissions: read-all + +jobs: + scan-pr: + uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable-pr.yml@main" +``` + +### View results + +Results may be viewed by clicking on the details of the failed action, either from your project's actions tab or directly on the PR. Results are also included in GitHub annotations on the "Files changed" tab for the PR. + +### Customization + +`osv-scanner-reusable.yml` takes two optional inputs: + +- `scan-args`: This value is passed to `osv-scanner` CLI after being split by each line. See the [usage]()./usage) page for the available options. + Importantly `--format` and `--output` flags are already set by the reusable workflow and should not be overridden here. + Default: + ``` + --recursive # Recursively scan subdirectories + --skip-git=true # Skip commit scanning to focus on dependencies + ./ # Start the scan from the root of the repository + ``` +- `results-file-name`: This is the name of the final SARIF file uploaded to Github. + Default: `results.sarif` + +#### Examples +```yml +# Scan specific lockfiles +jobs: + scan-pr: + uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml" + with: + scan-args: |- + ./path/to/lockfile1 + ./path/to/lockfile2 +``` + +```yml +# Default arguments +jobs: + scan-pr: + uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml" + with: + scan-args: |- + --recursive + --skip-git=true + ./ +``` + + ## Scheduled scans Regularly scanning your project for vulnerabilities can alert you to new vulnerabilities in your dependency tree. This GitHub Action will scan your project on a set schedule and report all known vulnerabilities. @@ -47,40 +119,55 @@ jobs: As written, the scanner will run on 12:12 pm UTC every Monday. You can change the schedule by following the instructions [here](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule). -### View results +### Customization -Maintainers can review results of the scan by navigating to their project's security > code scanning tab. Vulnerability details can also be viewed by clicking on the details of the failed action. +`osv-scanner-reusable-pr.yml` has the same customization options as `osv-scanner-reusable.yml`, which is described [here](./github-action.md#customization). -## Scans on PRs +### View results -Scanning your project on each pull request can help you keep vulnerabilities out of your project. This GitHub Action compares a vulnerability scan of the main branch to a vulnerability scan of the feature branch. You will be notified of any new vulnerabilities introduced through the feature branch. You can also choose to [prevent merging](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging) if new vulnerabilities are introduced through the feature branch. +Maintainers can review results of the scan by navigating to their project's `security > code scanning` tab. Vulnerability details can also be viewed by clicking on the details of the failed action. -### Instructions -In your project repository, create a new file `.github/workflows/osv-scanner-pr.yml`. +## Scan on release -Include the following in the [`osv-scanner-pr.yml`](https://github.com/google/osv-scanner/blob/main/.github/workflows/osv-scanner-pr.yml) file: +Here is a example of blocking on release, though the actual implementation will heavily depend on your specific release process. ```yml -name: OSV-Scanner PR Scan +name: Go Release Process -# Change "main" to your default branch if you use a different name, i.e. "master" on: - pull_request: - branches: [ main ] - merge_group: - branches: [ main ] + push: + tags: + - "*" # triggers only if push new tag version, like `0.8.4` or else -# Declare default permissions as read only. -permissions: read-all +permissions: + contents: read # to fetch code (actions/checkout) jobs: - scan-pr: - uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable-pr.yml@main" + osv-scan: + uses: google/osv-scanner/.github/workflows/osv-scanner-reusable.yml + with: + # Only scan the top level go.mod file without recursively scanning directories since + # this is pipeline is about releasing the go module and binary + scan-args: |- + --skip-git + ./ + permissions: + # Require writing security events to upload SARIF file to security tab + security-events: write + tests: + name: Run unit tests + ... + release: + needs: # Needs both tests and osv-scan to pass + - tests + - osv-scan + # Your actual release steps + steps: + ... ``` ### View results -Results may be viewed by clicking on the details of the failed action, either from your project's actions tab or directly on the PR. Results are also included in GitHub annotations on the "Files changed" tab for the PR. +Results may be viewed by clicking on the details of the failed release action from the action tab. -Results are also available to maintainers by navigating to their project's security > code scanning tab. diff --git a/docs/output.md b/docs/output.md index c4b4ddebc7..b2b65bb354 100644 --- a/docs/output.md +++ b/docs/output.md @@ -196,6 +196,156 @@ osv-scanner --format json -L path/to/lockfile > /path/to/file.json +--- + +### SARIF + +```bash +osv-scanner --format sarif your/project/dir +``` + +Outputs the result in the [SARIF](https://sarifweb.azurewebsites.net/) v2.1.0 format. Each vulnerability (grouped by aliases) is a separate rule, and each package containing a vulnerable dependency is a rule violation. The help text within the SARIF report contains detailed information about the vulnerability and remediation instructions for how to resolve it. + +
+Sample SARIF output + +```json +{ + "version": "2.1.0", + "$schema": "https://json.schemastore.org/sarif-2.1.0.json", + "runs": [ + { + "tool": { + "driver": { + "informationUri": "https://github.com/google/osv-scanner", + "name": "osv-scanner", + "rules": [ + { + "id": "CVE-2022-24713", + "shortDescription": { + "text": "CVE-2022-24713: " + }, + "fullDescription": { + "text": "...", + "markdown": "..." + }, + // Deprecated IDs field contains all alias IDs + "deprecatedIds": [ + "CVE-2022-24713", + "RUSTSEC-2022-0013", + "GHSA-m5pq-gvj9-9vr8" + ], + "help": { + "text": "...", + "markdown": "..." + } + }, + ], + "version": "1.4.1" + } + }, + "artifacts": [ + { + "location": { + "uri": "file:///path/to/sub-rust-project/Cargo.lock" + }, + "length": -1 + } + ], + "results": [ + { + "ruleId": "CVE-2022-24713", + "ruleIndex": 0, + "level": "warning", + "message": { + "text": "Package 'regex@1.5.1' is vulnerable to 'CVE-2022-24713' (also known as 'RUSTSEC-2022-0013', 'GHSA-m5pq-gvj9-9vr8')." + }, + "locations": [ + { + "physicalLocation": { + "artifactLocation": { + "uri": "file:///path/to/sub-rust-project/Cargo.lock" + } + } + } + ] + } + ] + } + ] +} +``` + +
+ +
+Sample SARIF Help Text + + +> **Your dependency is vulnerable to [CVE-2022-24713](https://osv.dev/list?q=CVE-2022-24713)** +> (Also published as: [RUSTSEC-2022-0013](https://osv.dev/vulnerability/RUSTSEC-2022-0013), [GHSA-m5pq-gvj9-9vr8](https://osv.dev/vulnerability/GHSA-m5pq-gvj9-9vr8), ). +> +> +> ## [RUSTSEC-2022-0013](https://osv.dev/vulnerability/RUSTSEC-2022-0013) +> +>
+> Details +> +> > Full advisory details... +> +>
+> +> +> +> ## [GHSA-m5pq-gvj9-9vr8](https://osv.dev/vulnerability/GHSA-m5pq-gvj9-9vr8) +> +>
+> Details +> +> > Full advisory details... +> +>
+> +> +> --- +> +> ### Affected Packages +> | Source | Package Name | Package Version | +> | --- | --- | --- | +> | lockfile:/path/to/rust-project/Cargo.lock | regex | 1.5.1 | +> +> ## Remediation +> +> +> +> To fix these vulnerabilities, update the vulnerabilities past the listed fixed versions below. +> +> ### Fixed Versions +> | Vulnerability ID | Package Name | Fixed Version | +> | --- | --- | --- | +> | GHSA-m5pq-gvj9-9vr8 | regex | 1.5.5 | +> | RUSTSEC-2022-0013 | regex | 1.5.5 | +> +> +> If you believe these vulnerabilities do not affect your code and wish to ignore them, add them to the ignore list in an +> `osv-scanner.toml` file located in the same directory as the lockfile containing the vulnerable dependency. +> +> See the format and more options in our documentation here: https://google.github.io/osv-scanner/configuration/ +> +> Add or append these values to the following config files to ignore this vulnerability: +> +> +> `/path/to/rust-project/osv-scanner.toml` +> ``` +> [[IgnoredVulns]] +> id = "CVE-2022-24713" +> reason = "Your reason for ignoring this vulnerability" +> ``` + +
+ +--- + ## Call analysis With `--experimental-call-analysis` flag enabled, call information will be included in the output. @@ -367,12 +517,12 @@ osv-scanner --format json --experimental-call-analysis -L path/to/lockfile > /pa ## Return Codes -|----- -| Exit Code |Reason| -|:---------------:|------------| -| `0` | Packages were found when scanning, but does not match any known vulnerabilities. | -| `1` | Packages were found when scanning, and there are vulnerabilities. | -| `1-126` | Reserved for vulnerability result related errors. | -| `127` | General Error. | -| `128` | No packages found (likely caused by the scanning format not picking up any files to scan). | -| `129-255` | Reserved for non result related errors. | +|----- +| Exit Code |Reason| +|:---------------:|------------| +| `0` | Packages were found when scanning, but does not match any known vulnerabilities. | +| `1` | Packages were found when scanning, and there are vulnerabilities. | +| `1-126` | Reserved for vulnerability result related errors. | +| `127` | General Error. | +| `128` | No packages found (likely caused by the scanning format not picking up any files to scan). | +| `129-255` | Reserved for non result related errors. | diff --git a/internal/output/fixtures/test-vuln-results-a.sarif b/internal/output/fixtures/test-vuln-results-a.sarif index ea1ca9fa6d..dd0f4995de 100644 --- a/internal/output/fixtures/test-vuln-results-a.sarif +++ b/internal/output/fixtures/test-vuln-results-a.sarif @@ -47,7 +47,7 @@ } } ], - "version": "1.4.0" + "version": "1.4.1" } }, "artifacts": [ diff --git a/internal/output/sarif_test.go b/internal/output/sarif_test.go index 99c469670d..b609a532c6 100644 --- a/internal/output/sarif_test.go +++ b/internal/output/sarif_test.go @@ -67,7 +67,7 @@ func TestPrintSARIFReport(t *testing.T) { if err != nil { t.Errorf("Error writing SARIF output: %s", err) } - testutility.CreateTextFixture(t, tt.wantPath, bufOut.String()) + testutility.AssertMatchFixtureText(t, tt.wantPath, bufOut.String()) }) } }