actions/dependency-review-action
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #324 from actions/readme-update

Browse Source 
Update the README
This commit is contained in:
Federico Builes
2022-11-11 11:27:19 +01:00
committed by GitHub
parent 9da0fd4871 9b3a7f61dd
commit 235a221cf4
1 changed files with 43 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
README.md
View File

@@ -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:
<img width="854" alt="Screen Shot 2022-03-31 at 1 10 51 PM" src="https://user-images.githubusercontent.com/2161/161042286-b22d7dd3-13cb-458d-8744-ce70ed9bf562.png">
or on the job summary
or on the job summary:
<img src="https://user-images.githubusercontent.com/7847935/182871416-50332bbb-b279-4621-a136-ca72a4314301.png">
@@ -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 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` |
| `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` and `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 the 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` <br> **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
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-severity: high
config-file: './.github/dependency-review-config.yml'
```
### 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.
And then create the file in the path you just specified:
```yaml
- name: Dependency Review
uses: actions/dependency-review-action@v2
with:
fail-on-scopes: runtime, development
```
### 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
```
```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