From d59e4e8030b211723e80d7e3938b508868ebd9a8 Mon Sep 17 00:00:00 2001 From: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Date: Wed, 4 Dec 2024 09:14:37 +0000 Subject: [PATCH] Improve clarity around "dependency review" and "dependency review action" (#53273) Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com> --- ...es-to-secure-your-use-of-github-actions.md | 8 +--- .../end-to-end-supply-chain/securing-code.md | 2 +- .../about-dependency-review.md | 21 +++++----- ...nfiguring-the-dependency-review-action.md} | 42 ++++--------------- ...-dependency-review-action-configuration.md | 6 +-- ...ependency-review-across-an-organization.md | 4 +- .../index.md | 2 +- ...ng-dependency-changes-in-a-pull-request.md | 2 +- .../about-dependency-review-action.md | 2 +- 9 files changed, 29 insertions(+), 60 deletions(-) rename content/code-security/supply-chain-security/understanding-your-software-supply-chain/{configuring-dependency-review.md => configuring-the-dependency-review-action.md} (75%) diff --git a/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md b/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md index 917cc3022d24..51d15a76a4e1 100644 --- a/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md +++ b/content/actions/security-for-github-actions/security-guides/using-githubs-security-features-to-secure-your-use-of-github-actions.md @@ -56,13 +56,9 @@ When you open pull requests to update your workflows, it is good practice to use If any of the changes you made to your workflows are flagged as vulnerable, you can avoid adding them to your project or update them to a secure version. -For more information about dependency review, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" and "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review)." +For more information about dependency review, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)." -{% data reusables.dependency-review.about-dependency-review-action %} - -![Screenshot of a workflow run that uses the dependency review action.](/assets/images/help/graphs/dependency-review-action.png) - -{% data reusables.dependency-review.about-dependency-review-action2 %} +{% data reusables.dependency-review.about-dependency-review-action %} For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action)." ## Keeping the actions in your workflows secure and up to date diff --git a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md index bf4199b74c87..bbacbeeb81c8 100644 --- a/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md +++ b/content/code-security/supply-chain-security/end-to-end-supply-chain/securing-code.md @@ -51,7 +51,7 @@ As a first step, you want to make a complete inventory of your dependencies. The ### Automatic detection of vulnerabilities in pull requests -The {% data variables.dependency-review.action_name %} enforces a dependency review on your pull requests, making it easy for you to see if a pull request will introduce a vulnerable version of a dependency to your repository. When a vulnerability is detected, the {% data variables.dependency-review.action_name %} can block the pull request from merging. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement)." +The {% data variables.dependency-review.action_name %} enforces a dependency review on your pull requests, making it easy for you to see if a pull request will introduce a vulnerable version of a dependency to your repository. When a vulnerability is detected, the {% data variables.dependency-review.action_name %} can block the pull request from merging. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#the-dependency-review-action)." ### Assessment of exposure to risk from a vulnerable dependency diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md index 208e4bac5444..76bb1177c9ed 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review.md @@ -24,12 +24,13 @@ redirect_from: For pull requests that contain changes to package manifests or lock files, you can display a dependency review to see what has changed. The dependency review includes details of changes to indirect dependencies in lock files, and it tells you if any of the added or updated dependencies contain known vulnerabilities. +>[!NOTE] +> The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context, and add enforcement mechanisms to the {% data variables.product.prodname_actions %} workflow. For more information, see "[The {% data variables.dependency-review.action_name %}](#about-the-dependency-review-action)" later in this article. + Sometimes you might just want to update the version of one dependency in a manifest and generate a pull request. However, if the updated version of this direct dependency also has updated dependencies, your pull request may have more changes than you expected. The dependency review for each manifest and lock file provides an easy way to see what has changed, and whether any of the new dependency versions contain known vulnerabilities. By checking the dependency reviews in a pull request, and changing any dependencies that are flagged as vulnerable, you can avoid vulnerabilities being added to your project. For more information about how dependency review works, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request)." -For more information about configuring dependency review, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review)." - {% data variables.product.prodname_dependabot_alerts %} will find vulnerabilities that are already in your dependencies, but it's much better to avoid introducing potential problems than to fix problems at a later date. For more information about {% data variables.product.prodname_dependabot_alerts %}, see "[AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts#dependabot-alerts-for-vulnerable-dependencies)." Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/dependency-graph-supported-package-ecosystems#supported-package-ecosystems)." @@ -43,13 +44,7 @@ For more information on supply chain features available on {% data variables.pro The dependency review feature becomes available when you enable the dependency graph. For more information, see "{% ifversion ghec %}[Enabling the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph#enabling-the-dependency-graph){% elsif ghes %}[Enabling the dependency graph for your enterprise](/admin/code-security/managing-supply-chain-security-for-your-enterprise/enabling-the-dependency-graph-for-your-enterprise){% endif %}." {% endif %} -## Dependency review enforcement - -The action is available for all {% ifversion fpt or ghec %}public repositories, as well as private {% endif %}repositories that have {% data variables.product.prodname_GH_advanced_security %} enabled. - -{% data reusables.dependency-review.org-level-enforcement %} - -{% data reusables.dependency-review.action-enterprise %} +## About the {% data variables.dependency-review.action_name %} {% data reusables.dependency-review.about-dependency-review-action %} @@ -57,11 +52,17 @@ The action is available for all {% ifversion fpt or ghec %}public repositories, {% data reusables.dependency-review.about-dependency-review-action2 %} +The action is available for all {% ifversion fpt or ghec %}public repositories, as well as private {% endif %}repositories that have {% data variables.product.prodname_GH_advanced_security %} enabled. + +{% data reusables.dependency-review.org-level-enforcement %} + +{% data reusables.dependency-review.action-enterprise %} + The action uses the dependency review REST API to get the diff of dependency changes between the base commit and head commit. You can use the dependency review API to get the diff of dependency changes, including vulnerability data, between any two commits on a repository. For more information, see "[AUTOTITLE](/rest/dependency-graph/dependency-review)."{% ifversion dependency-review-submission-api %} The action also considers dependencies submitted via the {% data variables.dependency-submission-api.name %}. For more information about the {% data variables.dependency-submission-api.name %}, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/using-the-dependency-submission-api)." {% data reusables.dependency-review.works-with-submission-api-beta %} -You can configure the {% data variables.dependency-review.action_name %} to better suit your needs. For example, you can specify the severity level that will make the action fail{% ifversion dependency-review-action-licenses %}, or set an allow or deny list for licenses to scan{% endif %}. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#configuring-the-dependency-review-github-action)." +You can configure the {% data variables.dependency-review.action_name %} to better suit your needs. For example, you can specify the severity level that will make the action fail{% ifversion dependency-review-action-licenses %}, or set an allow or deny list for licenses to scan{% endif %}. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action)." {% endif %} diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md similarity index 75% rename from content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md rename to content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md index 4ccb3dc539c6..88b678b6b34c 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action.md @@ -1,7 +1,7 @@ --- -title: Configuring dependency review -intro: You can use dependency review to catch vulnerabilities before they are added to your project. -shortTitle: Configure dependency review +title: Configuring the dependency review action +shortTitle: Configure dependency review action +intro: You can use the {% data variables.dependency-review.action_name %} to catch vulnerabilities before they are added to your project. permissions: '{% data reusables.permissions.security-repo-enable %}' versions: fpt: '*' @@ -14,41 +14,13 @@ topics: - Vulnerabilities - Dependencies - Pull requests +redirect_from: + - /code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review --- -## About dependency review +## About the {% data variables.dependency-review.action_name %} -{% data reusables.dependency-review.feature-overview %} - -For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" and "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request)." - -## About configuring dependency review - -{% ifversion fpt %} -Dependency review is available in all public repositories in all products and cannot be disabled. Dependency review is available in private repositories owned by organizations that use GitHub Enterprise Cloud and have a license for [{% data variables.product.prodname_GH_advanced_security %}](/get-started/learning-about-github/about-github-advanced-security). For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review). - -{% elsif ghec %} -Dependency review is included in {% data variables.product.product_name %} for public repositories. To use dependency review in private repositories owned by organizations, you must have a license for [{% data variables.product.prodname_GH_advanced_security %}](/get-started/learning-about-github/about-github-advanced-security) and have the dependency graph enabled. - -{% data reusables.dependabot.enabling-disabling-dependency-graph-private-repo %} -1. Scroll down the page and if "{% data variables.product.prodname_GH_advanced_security %}" is not enabled, click **Enable** next to the feature. - -{% elsif ghes %} - -Dependency review is available when dependency graph is enabled for the instance and {% data variables.product.prodname_advanced_security %} is enabled for the organization or repository.{% ifversion ghes %} For more information, see "[AUTOTITLE](/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise)."{% endif %} - -### Checking if the dependency graph is enabled - -{% data reusables.repositories.navigate-to-repo %} -{% data reusables.repositories.sidebar-settings %} -{% data reusables.repositories.navigate-to-code-security-and-analysis %} -1. Under "Configure security and analysis features", check if the dependency graph is enabled. -1. If dependency graph is enabled, click **Enable** next to "{% data variables.product.prodname_GH_advanced_security %}" to enable {% data variables.product.prodname_advanced_security %}, including dependency review. The enable button is disabled if your enterprise has no available licenses for {% data variables.product.prodname_advanced_security %}.{% ifversion ghes %} - ![Screenshot of "Code security and analysis features".](/assets/images/enterprise/3.4/repository/code-security-and-analysis-enable-ghas-3.4.png){% endif %} - -{% endif %} - -## About configuring the {% data variables.dependency-review.action_name %} +The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context, and add enforcement mechanisms to the {% data variables.product.prodname_actions %} workflow. {% data reusables.dependency-review.dependency-review-action-overview %} diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md index 774148d0c1a1..7db54ca354ed 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/customizing-your-dependency-review-action-configuration.md @@ -1,6 +1,7 @@ --- title: Customizing your dependency review action configuration -intro: 'Learn how to add a basic customization to your dependency review configuration.' +shortTitle: Customize dependency review action +intro: 'Learn how to add a basic customization to your dependency review action configuration.' permissions: '{% data reusables.permissions.security-repo-enable %}' versions: fpt: '*' @@ -11,7 +12,6 @@ topics: - Dependency graph - Dependencies - Repositories -shortTitle: Customize dependency review --- ## Introduction @@ -144,5 +144,5 @@ When customizing your dependency review configuration, there are some best pract ## Further reading -* "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#about-configuring-the-dependency-review-action)"{% ifversion repo-rules %} +* "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action)"{% ifversion repo-rules %} * "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization)"{% endif %} diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md index 197f601e9272..fdbd281b0895 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/enforcing-dependency-review-across-an-organization.md @@ -18,13 +18,13 @@ topics: {% data reusables.dependency-review.action-enterprise %} -{% data reusables.dependency-review.about-dependency-review-action %} For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)." +{% data reusables.dependency-review.about-dependency-review-action %} For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#about-the-dependency-review-action)." You can enforce the use of the {% data variables.dependency-review.action_name %} in your organization by setting up a repository ruleset that will require the `dependency-review-action` workflow to pass before pull requests can be merged. Repository rulesets are rule settings that allow you to control how users can interact with selected branches and tags in your repositories. For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)" and "[Require workflows to pass before merging](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging)." ## Prerequisites -You need to add the {% data variables.dependency-review.action_name %} to one of the repositories in your organization, and configure the action. For more information, see "[Configuring the dependency review action](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#configuring-the-dependency-review-action)." +You need to add the {% data variables.dependency-review.action_name %} to one of the repositories in your organization, and configure the action. For more information, see "[Configuring the dependency review action](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action)." ## Enforcing dependency review for your organization diff --git a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md index c63a2aa2e2ec..191fd095c07b 100644 --- a/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md +++ b/content/code-security/supply-chain-security/understanding-your-software-supply-chain/index.md @@ -18,7 +18,7 @@ children: - /exporting-a-software-bill-of-materials-for-your-repository - /using-the-dependency-submission-api - /about-dependency-review - - /configuring-dependency-review + - /configuring-the-dependency-review-action - /customizing-your-dependency-review-action-configuration - /enforcing-dependency-review-across-an-organization - /exploring-the-dependencies-of-a-repository diff --git a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md index d02258476b9d..ccb1419e44f6 100644 --- a/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md +++ b/content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request.md @@ -33,7 +33,7 @@ Dependency review allows you to "shift left". You can use the provided predictiv You can use the {% data variables.dependency-review.action_name %} to help enforce dependency reviews on pull requests in your repository. {% data reusables.dependency-review.dependency-review-action-overview %} -You can configure the {% data variables.dependency-review.action_name %} to better suit your needs by specifying the type of dependency vulnerability you wish to catch. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-dependency-review#configuring-the-dependency-review-github-action)." +You can configure the {% data variables.dependency-review.action_name %} to better suit your needs by specifying the type of dependency vulnerability you wish to catch. For more information, see "[AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/configuring-the-dependency-review-action)." ## Reviewing dependencies in a pull request diff --git a/data/reusables/dependency-review/about-dependency-review-action.md b/data/reusables/dependency-review/about-dependency-review-action.md index 0cd8fa7e0f73..c8ff157196a9 100644 --- a/data/reusables/dependency-review/about-dependency-review-action.md +++ b/data/reusables/dependency-review/about-dependency-review-action.md @@ -1 +1 @@ -You can use the [`dependency-review-action`](https://github.com/actions/dependency-review-action) in your repository to enforce dependency reviews on your pull requests. The action scans for vulnerable versions of dependencies introduced by package version changes in pull requests, and warns you about the associated security vulnerabilities. This gives you better visibility of what's changing in a pull request, and helps prevent vulnerabilities being added to your repository. +The "{% data variables.dependency-review.action_name %}" refers to the specific action that can report on differences in a pull request within the {% data variables.product.prodname_actions %} context. See [`dependency-review-action`](https://github.com/actions/dependency-review-action). You can use the {% data variables.dependency-review.action_name %} in your repository to enforce dependency reviews on your pull requests. The action scans for vulnerable versions of dependencies introduced by package version changes in pull requests, and warns you about the associated security vulnerabilities. This gives you better visibility of what's changing in a pull request, and helps prevent vulnerabilities being added to your repository.