From 2f59625b625168542197692211e059a5d64fd76d Mon Sep 17 00:00:00 2001 From: Courtney Claessens Date: Thu, 10 Nov 2022 19:51:20 -0500 Subject: [PATCH 1/7] reorg the readme --- README.md | 264 +++++++++--------------------------------------------- 1 file changed, 41 insertions(+), 223 deletions(-) diff --git a/README.md b/README.md index 27216d526..bd830428a 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ raise an error if any vulnerabilities or invalid licenses are being introduced. The action is available for all public repositories, as well as private repositories that have GitHub Advanced Security licensed. -You can see the results on the job logs +You can see the results on the job logs: Screen Shot 2022-03-31 at 1 10 51 PM -or on the job summary +or on the job summary: @@ -33,7 +33,7 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: 'Dependency Review' - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 ``` ### GitHub Enterprise Server @@ -59,183 +59,34 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: 'Dependency Review' - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 ``` -## Configuration +## Configuration options -Configure this action by either using an external configuration file, -or by inlining these options in your workflow file. +Configure this action by either inlining these options in your workflow file or by using an external configuration file. All configuration options are optional. -## Configuration Options +| Option | Usage | Possible values | Default value | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------| +| `fail-on-severity` | Defines the threshold for level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | +| `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any `spdx_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/licenses) | none | +| `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any `spdx_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/licenses) | none | +| `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. | `development`, `runtime`, `unknown` | `runtime` | +| `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | +| `license-check` | Disable the license check performed by the action. | `true`, `false` | `false` | +| `vulnerability-check` | Disable the vulnerability check performed by the action. | `true`, `false` | `false` | +| `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request_target`. | Any valid git ref(s) in your project | none | -### config-file +*not supported for use with GitHub Enterprise Server -A string representing the path to a configuraton file. It can be a -local file, or a file located in an external repository. You can use -this syntax for external repositories: `OWNER/REPOSITORY/FILENAME@BRANCH`. +†will be supported with GitHub Enterprise Server 3.8 -If the configuration file is located in an external private repository, -use the [external-repo-token](#external-repo-token) parameter of the -action to specify a token that has read access to the repository. - -**Possible values**: A string representing a path to a file located -in the current repository, or in an external one. - -**Example**: `config-file: ./.github/dependency-review-config.yml # local file`. - -**Example**: `config-file: github/octorepo/dependency-review-config.yml@main # external repo` - -### fail-on-severity - -Configure the severity level for alerting. See "[Vulnerability Severity](https://github.com/actions/dependency-review-action#vulnerability-severity)". - -**Possible values**: `critical`, `high`, `moderate`, `low`. - -**Example**: `fail-on-severity: moderate`. - -### fail-on-scopes - -A list of strings representing the build environments you want to -support. The default value is `development, runtime`. - -**Possible values**: `development`, `runtime`, `unknown` - -**Inline example**: `fail-on-scopes: development, runtime` - -**YAML example**: - -```yaml -# this prevents scanning development dependencies -fail-on-scopes: - - runtime -``` - -### allow-licenses - -Only allow the licenses that comply with the expressions in this list. See "[Licenses](https://github.com/actions/dependency-review-action#licenses)". - -**Possible values**: A list of of [SPDX-compliant license identifiers](https://spdx.org/licenses/). - -**Inline example**: `allow-licenses: BSD-3-Clause, LGPL-2.1 OR MIT OR BSD-3-Clause` - -**YAML example**: - -```yaml -allow-licenses: - - BSD-3-Clause - - LGPL-2.1 - - MIT - - BSD-3-Clause -``` - -### deny-licenses - -Add a custom list of licenses you want to block. See -"[Licenses](https://github.com/actions/dependency-review-action#licenses)". - -**Possible values**: Any valid set of [SPDX licenses](https://spdx.org/licenses/). - -**Inline example**: `deny-licenses: LGPL-2.0, GPL-2.0+ WITH Bison-exception-2.2` - -**YAML example**: - -```yaml -deny-licenses: - - LGPL-2.0 - - GPL-2.0+ WITH Bison-exception-2.2 -``` - -### allow-ghsas - -A list of GitHub Security Advisory IDs that can be skipped during detection. - -**Possible values**: Any valid GHSAs from the [GitHub Advisory Database](https://github.com/advisories). - -**Inline example**: `allow-ghsas: GHSA-abcd-1234-5679, GHSA-efgh-1234-5679` - -**YAML example**: - -```yaml -allow-ghsas: - - GHSA-abcd-1234-5679 - - GHSA-efgh-1234-5679 -``` - -### license-check/vulnerability-check - -Disable the license checks or vulnerability checks performed by this Action. -You can't disable both checks. - -**Possible values**: `true` or `false` - -**Example**: - -```yaml -license-check: true -vulnerability-check: false -``` - -### base-ref/head-ref - -Provide custom git references for the git base/head when performing -the comparison. If you are using pull requests, or -`pull_request_target` events you do not need to worry about setting -this. The values need to be specified for all other event types. - -**Possible values**: Any valid git ref(s) in your project. - -**Example**: - -```yaml -base-ref: 8bb8a58d6a4028b6c2e314d5caaf273f57644896 -head-ref: 69af5638bf660cf218aad5709a4c100e42a2f37b -``` - -### external-repo-token - -A token for fetching external configuration files if they live in -an external private repository. - -Visit the [developer settings](https://github.com/settings/tokens) to -create a new personal access token with `read` permissions for the -repository that hosts the config file. - -**Possible values**: Any GitHub token with read access to the external repository. - -**Example**: `external-repo-token: ghp_123456789abcdef...` - -### Configuration File - -You can use an external configuration file to specify the settings for -this Action. - -Start by specifying that you will be using an external configuration -file: - -```yaml -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - config-file: './.github/dependency-review-config.yml' -``` - -And then create the file in the path you just specified. **All of these fields are -optional**: - -```yaml -fail-on-severity: 'critical' -allow-licenses: - - 'GPL-3.0' - - 'BSD-3-Clause' - - 'MIT' -``` ### Inline Configuration -You can pass options to the Dependency Review -Action using your workflow file. Here's an example of what the full -file would look like: +You can pass options to the Dependency Review GitHub Action using your workflow file. + +#### Example ```yaml name: 'Dependency Review' @@ -249,7 +100,7 @@ jobs: - name: 'Checkout Repository' uses: actions/checkout@v3 - name: Dependency Review - uses: actions/dependency-review-action@v2 + uses: actions/dependency-review-action@v3 with: fail-on-severity: moderate @@ -257,71 +108,41 @@ jobs: deny-licenses: LGPL-2.0, BSD-2-Clause ``` -### Vulnerability Severity +### Configuration File -By default the action will fail on any pull request that contains a -vulnerable dependency, regardless of the severity level. You can override this behavior by -using the `fail-on-severity` option, which will cause a failure on any pull requests that introduce vulnerabilities of the specified severity level or higher. The possible values are: `critical`, `high`, `moderate`, or `low`. The -action defaults to `low`. +You can use an external configuration file to specify the settings for this action. It can be a local file or a file in an external repository. Refer to the following options for specification. -This example will only fail on pull requests with `critical` and `high` vulnerabilities: +| Option | Usage | Possible values | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| `config-file` | A path to a file in the current repository or an external repository. Use this syntax for external files: `OWNER/REPOSITORY/FILENAME@BRANCH` | local file: `./.github/dependency-review-config.yml`,
external repo: `github/octorepo/dependency-review-config.yml@main` | +| `external-repo-token` | Specifies a token for fetching the configuration file, if the file resides in a private external repository. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. | -```yaml -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - fail-on-severity: high -``` +#### Example -### Dependency Scoping - -By default the action will only fail on `runtime` dependencies that have vulnerabilities or unacceptable licenses, ignoring `development` dependencies. You can override this behavior with the `fail-on-scopes` option, which will allow you to list the specific dependency scopes you care about. The possible values are: `unknown`, `runtime`, and `development`. Note: Filtering by scope will not be supported on Enterprise Server just yet, as the REST API's introduction of `scope` will be released in an upcoming Enterprise Server version. We will treat all dependencies on Enterprise Server as having a `runtime` scope and thus will not be filtered away. +Start by specifying that you will be using an external configuration file: ```yaml - name: Dependency Review uses: actions/dependency-review-action@v2 with: - fail-on-scopes: runtime, development + config-file: './.github/dependency-review-config.yml' ``` -### Licenses - -You can set the action to fail on pull requests based on the licenses of the dependencies -they introduce. With `allow-licenses` you can define the list of licenses -your repository will accept. Alternatively, you can use `deny-licenses` to only -forbid a subset of licenses. These options are not supported on Enterprise Server. - -You can use the [Licenses -API](https://docs.github.com/en/rest/licenses) to see the full list of -supported licenses. Use [SPDX licenses](https://spdx.org/licenses/) -to filter the licenses. A couple of examples: - -```yaml -# only allow MIT-licensed dependents -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - allow-licenses: MIT -``` +And then create the file in the path you just specified: ```yaml -# Block Apache 1.1 and 2.0 licensed dependents -- name: Dependency Review - uses: actions/dependency-review-action@v2 - with: - deny-licenses: Apache-1.1+ +fail-on-severity: 'critical' +allow-licenses: + - 'GPL-3.0' + - 'BSD-3-Clause' + - 'MIT' ``` ### Considerations - Checking for licenses is not supported on Enterprise Server. -- The action will only accept one of the two parameters; an error will - be raised if you provide both. -- By default both parameters are empty (no license checking is - performed). -- We don't have license information for all of your dependents. If we - can't detect the license for a dependency **we will inform you, but the - action won't fail**. +- The action will only accept one of the two `license` parameters; an error will be raised if you provide both. +- We don't have license information for all of your dependents. If we can't detect the license for a dependency **we will inform you, but the action won't fail**. ## Blocking pull requests @@ -329,14 +150,11 @@ The Dependency Review GitHub Action check will only block a pull request from be ## Getting help -If you have bug reports, questions or suggestions please [create a new -issue](https://github.com/actions/dependency-review-action/issues/new/choose). +If you have bug reports, questions or suggestions please [create a new issue](https://github.com/actions/dependency-review-action/issues/new/choose). ## Contributing -We are grateful for any contributions made to this project. - -Please read [CONTRIBUTING.MD](https://github.com/actions/dependency-review-action/blob/main/CONTRIBUTING.md) to get started. +We are grateful for any contributions made to this project. Please read [CONTRIBUTING.MD](https://github.com/actions/dependency-review-action/blob/main/CONTRIBUTING.md) to get started. ## License From 8d7a4c48ad8980453d8f6b7ce0da81d522c4ef80 Mon Sep 17 00:00:00 2001 From: Courtney Claessens Date: Thu, 10 Nov 2022 19:55:22 -0500 Subject: [PATCH 2/7] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bd830428a..6aa4f2dda 100644 --- a/README.md +++ b/README.md @@ -73,8 +73,8 @@ Configure this action by either inlining these options in your workflow file or | `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any `spdx_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/licenses) | none | | `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. | `development`, `runtime`, `unknown` | `runtime` | | `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | -| `license-check` | Disable the license check performed by the action. | `true`, `false` | `false` | -| `vulnerability-check` | Disable the vulnerability check performed by the action. | `true`, `false` | `false` | +| `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `false` | +| `vulnerability-check` | Enable or disable the vulnerability check performed by the action. | `true`, `false` | `true` | | `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request_target`. | Any valid git ref(s) in your project | none | *not supported for use with GitHub Enterprise Server From 89a074ec7e84aa2b8c24cd9b5cdc2b5125448a66 Mon Sep 17 00:00:00 2001 From: Courtney Claessens Date: Thu, 10 Nov 2022 19:59:21 -0500 Subject: [PATCH 3/7] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6aa4f2dda..b3b9be1a3 100644 --- a/README.md +++ b/README.md @@ -69,8 +69,8 @@ Configure this action by either inlining these options in your workflow file or | Option | Usage | Possible values | Default value | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------| | `fail-on-severity` | Defines the threshold for level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | -| `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any `spdx_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/licenses) | none | -| `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any `spdx_id` value(s) from the [Licenses API](https://docs.github.com/en/rest/licenses) | none | +| `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | +| `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | | `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. | `development`, `runtime`, `unknown` | `runtime` | | `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | | `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `false` | From 8e5000107a795a41a0eaaef64093760d03d0b217 Mon Sep 17 00:00:00 2001 From: Courtney Claessens Date: Thu, 10 Nov 2022 20:01:11 -0500 Subject: [PATCH 4/7] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b3b9be1a3..e0d9143fe 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ Configure this action by either inlining these options in your workflow file or | `fail-on-severity` | Defines the threshold for level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | | `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | | `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | -| `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. | `development`, `runtime`, `unknown` | `runtime` | +| `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. |`runtime`, `development`, `unknown` | `runtime` | | `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | | `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `false` | | `vulnerability-check` | Enable or disable the vulnerability check performed by the action. | `true`, `false` | `true` | From 28c7c8c3143bbab053a8419206b7b30b046f446e Mon Sep 17 00:00:00 2001 From: Federico Builes Date: Fri, 11 Nov 2022 11:17:08 +0100 Subject: [PATCH 5/7] Set the correct default for license-check in README. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0d9143fe..091b937e8 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Configure this action by either inlining these options in your workflow file or | `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | | `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. |`runtime`, `development`, `unknown` | `runtime` | | `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | -| `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `false` | +| `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `true` | | `vulnerability-check` | Enable or disable the vulnerability check performed by the action. | `true`, `false` | `true` | | `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request_target`. | Any valid git ref(s) in your project | none | From a4761312ac8cd71b4ce101ba780165af3d17e864 Mon Sep 17 00:00:00 2001 From: Federico Builes Date: Fri, 11 Nov 2022 11:23:46 +0100 Subject: [PATCH 6/7] Add `pull_request` to the list of events that don't need refs. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 091b937e8..0e536bc4c 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ Configure this action by either inlining these options in your workflow file or | `allow-ghsas` | Contains a list of GitHub Advisory Database IDs that can be skipped during detection. | Any GHSAs from the [GitHub Advisory Database](https://github.com/advisories) | none | | `license-check` | Enable or disable the license check performed by the action. | `true`, `false` | `true` | | `vulnerability-check` | Enable or disable the vulnerability check performed by the action. | `true`, `false` | `true` | -| `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request_target`. | Any valid git ref(s) in your project | none | +| `base-ref`/`head-ref` | Provide custom git references for the git base/head when performing the comparison check. This is only used for event types other than `pull_request` and `pull_request_target`. | Any valid git ref(s) in your project | none | *not supported for use with GitHub Enterprise Server From 9b3a7f61dd4fbd3b6757cc7876ba1c900244da9c Mon Sep 17 00:00:00 2001 From: Federico Builes Date: Fri, 11 Nov 2022 11:26:05 +0100 Subject: [PATCH 7/7] Minor README tweaks. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0e536bc4c..b1d0d1184 100644 --- a/README.md +++ b/README.md @@ -64,11 +64,11 @@ jobs: ## Configuration options -Configure this action by either inlining these options in your workflow file or by using an external configuration file. All configuration options are optional. +Configure this action by either inlining these options in your workflow file, or by using an external configuration file. All configuration options are optional. | Option | Usage | Possible values | Default value | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------|---------------| -| `fail-on-severity` | Defines the threshold for level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | +| `fail-on-severity` | Defines the threshold for the level of severity. The action will fail on any pull requests that introduce vulnerabilities of the specified severity level or higher. | `low`, `moderate`, `high`, `critical` | `low` | | `allow-licenses`* | Contains a list of allowed licenses. The action will fail on pull requests that introduce dependencies with licenses that do not match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | | `deny-licenses`* | Contains a list of prohibited licenses. The action will fail on pull requests that introduce dependencies with licenses that match the list. | Any [SPDX-compliant identifier(s)](https://spdx.org/licenses/) | none | | `fail-on-scopes`† | Contains a list of strings of the build environments you want to support. The action will fail on pull requests that introduce vulnerabilities in the scopes that match the list. |`runtime`, `development`, `unknown` | `runtime` | @@ -110,12 +110,12 @@ jobs: ### Configuration File -You can use an external configuration file to specify the settings for this action. It can be a local file or a file in an external repository. Refer to the following options for specification. +You can use an external configuration file to specify the settings for this action. It can be a local file or a file in an external repository. Refer to the following options for the specification. | Option | Usage | Possible values | |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| -| `config-file` | A path to a file in the current repository or an external repository. Use this syntax for external files: `OWNER/REPOSITORY/FILENAME@BRANCH` | local file: `./.github/dependency-review-config.yml`,
external repo: `github/octorepo/dependency-review-config.yml@main` | -| `external-repo-token` | Specifies a token for fetching the configuration file, if the file resides in a private external repository. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. | +| `config-file` | A path to a file in the current repository or an external repository. Use this syntax for external files: `OWNER/REPOSITORY/FILENAME@BRANCH` | **Local file**: `./.github/dependency-review-config.yml`
**External repo**: `github/octorepo/dependency-review-config.yml@main` | +| `external-repo-token` | Specifies a token for fetching the configuration file if the file resides in a private external repository. Create a token in [developer settings](https://github.com/settings/tokens). | Any token with `read` permissions to the repository hosting the config file. | #### Example