forked from google/osv-scanner
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into add-formatting-docs
- Loading branch information
Showing
30 changed files
with
325 additions
and
286 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -20,18 +20,16 @@ nav_order: 7 | |
|
|
||
| OSV-Scanner is offered as a GitHub Action. We currently have two different GitHub Actions: | ||
|
|
||
| 1. 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. | ||
| 2. 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. | ||
| 1. An action that triggers a scan with each [pull request](./github-action.md#scan-on-pull-request) and will only report new vulnerabilities introduced through the pull request. | ||
| 2. An action that performs a full vulnerability scan, which can be configured to scan on a [regular schedule](./github-action.md#scheduled-scans). The full vulnerability scan can also be configured to run [on release](./github-action.md#scan-on-release) to prevent releasing with known vulnerabilities in dependencies. | ||
|
|
||
| ## Scans on PRs | ||
| ## Scan on pull request | ||
|
|
||
| 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 target branch to a vulnerability scan of the feature branch, and will fail if there are new vulnerabilities found which doesn't exist in the target 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. | ||
| 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 target branch to a vulnerability scan of the feature branch, and will fail if there are new vulnerabilities introduced through the feature branch. You may 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, but by default the check will only warn users. | ||
|
|
||
| ### 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: | ||
| In your project repository, create a new file `.github/workflows/osv-scanner-pr.yml` and include the following: | ||
|
|
||
| ```yml | ||
| name: OSV-Scanner PR Scan | ||
|
|
@@ -51,104 +49,20 @@ permissions: | |
|
|
||
| jobs: | ||
| scan-pr: | ||
| uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable-pr.yml@main" | ||
| uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0" | ||
| ``` | ||
| ### 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: | ||
| ```bash | ||
| --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` | ||
| - `download-artifact`: Optional artifact to download for scanning. Can be used if you need to do some preprocessing to prepare the lockfiles for scanning. | ||
| If the file names in the artifact are not standard lockfile names, make sure to add custom scan-args to specify the lockfile type and path (see [specify lockfiles](./usage#specify-lockfiles)). | ||
| - `upload-sarif`: Whether to upload the results to Security > Code Scanning. Defaults to `true`. | ||
|
|
||
| <details markdown="block"> | ||
| <summary> | ||
| Examples | ||
| </summary> | ||
|
|
||
| ##### Scan specific lockfiles | ||
|
|
||
| ```yml | ||
| jobs: | ||
| scan-pr: | ||
| uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml" | ||
| with: | ||
| scan-args: |- | ||
| --lockfile=./path/to/lockfile1 | ||
| --lockfile=requirements.txt:./path/to/python-lockfile2.txt | ||
| ``` | ||
|
|
||
| ##### Default arguments | ||
|
|
||
| ```yml | ||
| jobs: | ||
| scan-pr: | ||
| uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml" | ||
| with: | ||
| scan-args: |- | ||
| --recursive | ||
| --skip-git=true | ||
| ./ | ||
| ``` | ||
|
|
||
| ##### Using download-artifact input to support preprocessing | ||
|
|
||
| ```yml | ||
| jobs: | ||
| extract-deps: | ||
| name: Extract Dependencies | ||
| # ... | ||
| steps: | ||
| # ... Steps to extract your dependencies | ||
| - name: "upload osv-scanner deps" # Upload the deps | ||
| uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: converted-OSV-Scanner-deps | ||
| path: osv-scanner-deps.json | ||
| retention-days: 2 | ||
| vuln-scan: | ||
| name: Vulnerability scanning | ||
| # makes sure the extraction step is completed before running the scanner | ||
| needs: extract-deps | ||
| uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml@main" | ||
| with: | ||
| # Download the artifact uploaded in extract-deps step | ||
| download-artifact: converted-OSV-Scanner-deps | ||
| # Scan only the file inside the uploaded artifact | ||
| scan-args: |- | ||
| --lockfile=osv-scanner:osv-scanner-deps.json | ||
| permissions: | ||
| # Needed to upload the SARIF results to code-scanning dashboard. | ||
| security-events: write | ||
| contents: read | ||
| ``` | ||
|
|
||
| </details> | ||
|
|
||
| ## 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. If vulnerabilities are found the action will return a failed status. | ||
| ### Instructions | ||
| In your project repository, create a new file `.github/workflows/osv-scanner-scheduled.yml`. | ||
|
|
||
| Include the following in the [`osv-scanner-scheduled.yml`](https://github.com/google/osv-scanner/blob/main/.github/workflows/osv-scanner-scheduled.yml) file: | ||
| In your project repository, create a new file `.github/workflows/osv-scanner-scheduled.yml` and include the following: | ||
|
|
||
| ```yml | ||
| name: OSV-Scanner Scheduled Scan | ||
|
|
@@ -168,15 +82,11 @@ permissions: | |
| jobs: | ||
| scan-scheduled: | ||
| uses: "google/osv-scanner/.github/workflows/osv-scanner-reusable.yml@main" | ||
| uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v1.5.0" | ||
| ``` | ||
|
|
||
| As written, the scanner will run on 12:30 pm UTC every Monday, and also on every push to the main branch. You can change the schedule by following the instructions [here](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule). | ||
|
|
||
| ### Customization | ||
|
|
||
| `osv-scanner-reusable-pr.yml` has the same customization options as `osv-scanner-reusable.yml`, which is described [here](./github-action.md#customization). | ||
|
|
||
| ### View results | ||
|
|
||
| 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. | ||
|
|
@@ -223,3 +133,83 @@ jobs: | |
| ### View results | ||
| Results may be viewed by clicking on the details of the failed release action from the action tab. | ||
| ## Customization | ||
| The GitHub Actions have the following 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. The `--format` and `--output` flags are already set by the reusable workflow and should not be overridden here. | ||
| Default: | ||
| ```bash | ||
| --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` | ||
| - `download-artifact`: Optional artifact to download for scanning. Can be used if you need to do some preprocessing to prepare the lockfiles for scanning. If the file names in the artifact are not standard lockfile names, make sure to add custom scan-args to specify the lockfile type and path (see [specify lockfiles](./usage#specify-lockfiles)). | ||
| - `upload-sarif`: Whether to upload the results to Security > Code Scanning. Defaults to `true`. | ||
|
|
||
| <details markdown="block"> | ||
| <summary> | ||
| Examples | ||
| </summary> | ||
|
|
||
| #### Scan specific lockfiles | ||
|
|
||
| ```yml | ||
| jobs: | ||
| scan-pr: | ||
| uses: "google/osv-scanner-action/.github/workflows/[email protected]" | ||
| with: | ||
| scan-args: |- | ||
| --lockfile=./path/to/lockfile1 | ||
| --lockfile=requirements.txt:./path/to/python-lockfile2.txt | ||
| ``` | ||
|
|
||
| #### Default arguments | ||
|
|
||
| ```yml | ||
| jobs: | ||
| scan-pr: | ||
| uses: "google/osv-scanner-action/.github/workflows/[email protected]" | ||
| with: | ||
| scan-args: |- | ||
| --recursive | ||
| --skip-git=true | ||
| ./ | ||
| ``` | ||
|
|
||
| #### Using download-artifact input to support preprocessing | ||
|
|
||
| ```yml | ||
| jobs: | ||
| extract-deps: | ||
| name: Extract Dependencies | ||
| # ... | ||
| steps: | ||
| # ... Steps to extract your dependencies | ||
| - name: "upload osv-scanner deps" # Upload the deps | ||
| uses: actions/upload-artifact@v4 | ||
| with: | ||
| name: converted-OSV-Scanner-deps | ||
| path: osv-scanner-deps.json | ||
| retention-days: 2 | ||
| vuln-scan: | ||
| name: Vulnerability scanning | ||
| # makes sure the extraction step is completed before running the scanner | ||
| needs: extract-deps | ||
| uses: "google/osv-scanner-action/.github/workflows/[email protected]" | ||
| with: | ||
| # Download the artifact uploaded in extract-deps step | ||
| download-artifact: converted-OSV-Scanner-deps | ||
| # Scan only the file inside the uploaded artifact | ||
| scan-args: |- | ||
| --lockfile=osv-scanner:osv-scanner-deps.json | ||
| permissions: | ||
| # Needed to upload the SARIF results to code-scanning dashboard. | ||
| security-events: write | ||
| contents: read | ||
| ``` | ||
|
|
||
| </details> | ||
Oops, something went wrong.