Customize your dependency review configuration
By default, dependency review will help you catch insecure dependencies before they’re introduced into your code. But there’s more you can do with dependency review by configuring the dependency review action. We're going to stick to three very common modifications: failing builds based on vulnerability severity level, dependency license, and scope.
In this guide, you will learn:
How to edit the dependency review workflow file
How to implement common dependency review customizations
One common question is whether you should use allowlists or blocklists to screen dependencies and licenses. GitHub principal field security specialist Keith Hoodlet, who has extensive experience working with large enterprises, offers some perspective:
We generally recommend block lists over allow lists. Allow lists are the de facto most secure way in which you can ensure deployment of things from a security perspective, but very few organizations have the resources to do this well. It's more feasible to compile a list of really bad things than to create an inclusive list of all the really good libraries you want to allow. Failing based on the severity of a vulnerability is a good way to balance the need for security with the need to create low-friction experiences for developers. Of course, your mileage may vary depending on the nature of a repository and your team's resources.
Much the same applies to licenses. There are a wide variety of licenses out there, so it's usually more practical to exclude those you know are incompatible with current licenses than it is to compile a complete list of compatible licenses.
1. Add the dependency review action.
Make sure GitHub Actions and dependency graph are enabled.
Click the Actions tab.
Find the Security section and click View all.
Find Dependency review and click Configure.
This will open dependency review’s GitHub Actions workflow file, dependency-review.yml. It should contain the following:
name: 'Dependency Review'
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v3
- name: 'Dependency Review'
uses: actions/dependency-review-action@v3
2. Change the severity.
As explained in the workflow file above, you can block code containing vulnerable dependencies from ever being merged by setting the dependency review action to required. But blocking low-risk vulnerabilities may be too restrictive in some circumstances. We can change the severity of vulnerability that will cause a build to fail with the fail-on-severity option.
Add the following to the end of the dependency-review.yml file:
- name: Dependency Review
uses: actions/dependency-review-action@v3
with:
fail-on-severity: moderate
3. Add licenses to block.
Vulnerabilities aren’t the only reason you might want to block a dependency. If your organization has restrictions on what sorts of licenses you can use, you can use dependency review to enforce those policies with the deny-licenses option.
To break the build if anyone introduces a dependency that contains an LGPL-2.0 or BSD-2-Clause license, let’s add the following to the dependency-review.yml file:
deny-licenses: LGPL-2.0, BSD-2-Clause
4. Add scopes.
Finally, we'll use fail-on-scopes to prevent merging vulnerable dependencies to specific deployment environments.
Let’s keep those dependencies out of our development environment by adding the following to your dependency-review.yml file:
fail-on-scopes: development
The dependency-review.yml file should now look like this:
name: 'Dependency Review'
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: 'Checkout Repository'
uses: actions/checkout@v3
- name: Dependency Review
uses: actions/dependency-review-action@v3
with:
fail-on-severity: moderate
deny-licenses: LGPL-2.0, BSD-2-Clause
fail-on-scopes: development
You can use this file as a template for your own custom configurations.
Up Next: Intermediate module on GitHub Advanced Security wrap-up
Now let’s review what we’ve learned so far and take a look at what else we can do with GitHub Advanced Security.