Merge pull request #18365 from github/3501-dependency-review-phase1

mchammer01 · web-flow · commit 62c4a4f120fe · 2021-03-25T08:45:59.000Z
Dependency review reorg - take 2
diff --git a/content/code-security/getting-started/about-securing-your-repository.md b/content/code-security/getting-started/about-securing-your-repository.md
@@ -69,7 +69,7 @@ These features are available {% if currentVersion == "free-pro-team@latest" %}fo
 {% endif %}
 
 {% if currentVersion == "free-pro-team@latest" %}
-- **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
+- **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."
 {% endif %}
 
 {% if currentVersion != "github-ae@latest" %}
diff --git a/content/code-security/supply-chain-security/about-alerts-for-vulnerable-dependencies.md b/content/code-security/supply-chain-security/about-alerts-for-vulnerable-dependencies.md
@@ -24,8 +24,7 @@ When your code depends on a package that has a security vulnerability, this vuln
  {% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" %}{% data variables.product.prodname_dependabot %} detects vulnerable dependencies and sends {% data variables.product.prodname_dependabot_alerts %}{% else %}{% data variables.product.product_name %} detects vulnerable dependencies and sends security alerts{% endif %} when:
 
 {% if currentVersion == "free-pro-team@latest" %}
-- A new vulnerability is added to the {% data variables.product.prodname_advisory_database %}. For more information, see "[Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}](/github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database)."
-- New vulnerability data from [WhiteSource](https://www.whitesourcesoftware.com/vulnerability-database) is processed.{% else %}
+- A new vulnerability is added to the {% data variables.product.prodname_advisory_database %}. For more information, see "[Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}](/github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database)."{% else %}
 - New advisory data is synchronized to {% data variables.product.prodname_ghe_server %} each hour from {% data variables.product.prodname_dotcom_the_website %}. For more information about advisory data, see "<a href="/github/managing-security-vulnerabilities/browsing-security-vulnerabilities-in-the-github-advisory-database" class="dotcom-only">Browsing security vulnerabilities in the {% data variables.product.prodname_advisory_database %}</a>."{% endif %}
 - The dependency graph for a repository changes. For example, when a contributor pushes a commit to change the packages or versions it depends on{% if currentVersion == "free-pro-team@latest" %}, or when the code of one of the dependencies changes{% endif %}. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)."
 
diff --git a/content/code-security/supply-chain-security/about-dependency-review.md b/content/code-security/supply-chain-security/about-dependency-review.md
@@ -0,0 +1,33 @@
+---
+title: About dependency review
+intro: 'Dependency review lets you catch vulnerable dependencies before you introduce them to your environment, and provides information on license, dependents, and age of dependencies.'
+versions:
+  free-pro-team: '*'
+topics:
+  - pull requests
+---
+
+{% note %}
+
+**Note:** Dependency review is currently in beta and subject to change.
+
+{% endnote %}
+
+### About dependency review
+
+{% data reusables.dependency-review.feature-overview %}
+
+If a pull request targets your repository's default branch and contains 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.
+
+Dependency review is available in:
+
+* All public repositories. 
+* Private repositories owned by organizations with an {% data variables.product.prodname_advanced_security %} license that have the dependency graph enabled. For more information, see "[Exploring the dependencies of a repository](/github/visualizing-repository-data-with-graphs/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph-for-a-private-repository)."
+
+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 "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
+
+{% 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 "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies#dependabot-alerts-for-vulnerable-dependencies)."
+
+Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph#supported-package-ecosystems)."
diff --git a/content/code-security/supply-chain-security/about-managing-vulnerable-dependencies.md b/content/code-security/supply-chain-security/about-managing-vulnerable-dependencies.md
@@ -17,7 +17,7 @@ The dependency graph is a summary of the manifest and lock files stored in a rep
 For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph)."
 
 #### Dependency review
-By checking the dependency reviews on pull requests you can avoid introducing vulnerabilities from dependencies into your codebase. If the pull requests adds a vulnerable dependency, or changes a dependency to a vulnerable version, this is highlighted in the dependency review. You can change the dependency to a patched version before merging the pull request. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
+By checking the dependency reviews on pull requests you can avoid introducing vulnerabilities from dependencies into your codebase. If the pull requests adds a vulnerable dependency, or changes a dependency to a vulnerable version, this is highlighted in the dependency review. You can change the dependency to a patched version before merging the pull request. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."
 
 #### {% data variables.product.prodname_dependabot_alerts %}
 {% data variables.product.prodname_dotcom %} can create {% data variables.product.prodname_dependabot_alerts %} when it detects vulnerable dependencies in your repository. The alert is displayed on the Security tab for the repository. The alert includes a link to the affected file in the project, and information about a fixed version. {% data variables.product.prodname_dotcom %} also notifies the maintainers of the repository, according to their notification preferences. For more information, see "[About alerts for vulnerable dependencies](/code-security/supply-chain-security/about-alerts-for-vulnerable-dependencies)."
diff --git a/content/code-security/supply-chain-security/about-the-dependency-graph.md b/content/code-security/supply-chain-security/about-the-dependency-graph.md
@@ -27,7 +27,7 @@ The dependency graph is a summary of the manifest and lock files stored in a rep
 When you push a commit to {% data variables.product.product_name %} that changes or adds a supported manifest or lock file to the default branch, the dependency graph is automatically updated.{% if currentVersion == "free-pro-team@latest" %} In addition, the graph is updated when anyone pushes a change to the repository of one of your dependencies.{% endif %} For information on the supported ecosystems and manifest files, see "[Supported package ecosystems](#supported-package-ecosystems)" below.
 
 {% if currentVersion == "free-pro-team@latest" %}
-When you create a pull request containing changes to dependencies that targets the default branch, {% data variables.product.prodname_dotcom %} uses the dependency graph to add dependency reviews to the pull request. These indicate whether the dependencies contain vulnerabilities and, if so, the version of the dependency in which the vulnerability was fixed. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
+When you create a pull request containing changes to dependencies that targets the default branch, {% data variables.product.prodname_dotcom %} uses the dependency graph to add dependency reviews to the pull request. These indicate whether the dependencies contain vulnerabilities and, if so, the version of the dependency in which the vulnerability was fixed. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."
 {% endif %}
 
 ### Dependencies included
diff --git a/content/code-security/supply-chain-security/index.md b/content/code-security/supply-chain-security/index.md
@@ -16,6 +16,7 @@ topics:
 
 {% topic_link_in_list /understanding-your-software-supply-chain %}
     {% link_in_list /about-the-dependency-graph %}
+    {% link_in_list /about-dependency-review %}
     {% link_in_list /exploring-the-dependencies-of-a-repository %}
 {% topic_link_in_list /keeping-your-dependencies-updated-automatically %}
     {% link_in_list /about-dependabot-version-updates %}
diff --git a/content/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md b/content/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request.md
@@ -16,18 +16,9 @@ topics:
 
 ### About dependency review
 
-If a pull request targets your repository's default branch and contains 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.
+{% data reusables.dependency-review.feature-overview %} 
 
-Dependency review is available in:
-
-* All public repositories. 
-* Private repositories owned by organizations with an {% data variables.product.prodname_advanced_security %} license that have the dependency graph enabled. For more information, see "[Exploring the dependencies of a repository](/github/visualizing-repository-data-with-graphs/exploring-the-dependencies-of-a-repository#enabling-and-disabling-the-dependency-graph-for-a-private-repository)."
-
-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. {% 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 them at some later date. For more information about {% data variables.product.prodname_dependabot_alerts %}, see "[About alerts for vulnerable dependencies](/github/managing-security-vulnerabilities/about-alerts-for-vulnerable-dependencies#dependabot-alerts-for-vulnerable-dependencies)."
-
-Dependency review supports the same languages and package management ecosystems as the dependency graph. For more information, see "[About the dependency graph](/github/visualizing-repository-data-with-graphs/about-the-dependency-graph#supported-package-ecosystems)."
+Dependency review allows you to "shift left". You can use the provided predictive information to catch vulnerable dependencies before they hit production. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."
 
 ### Reviewing dependencies in a pull request
 
diff --git a/content/github/getting-started-with-github/about-github-advanced-security.md b/content/github/getting-started-with-github/about-github-advanced-security.md
@@ -25,7 +25,7 @@ A {% data variables.product.prodname_GH_advanced_security %} license provides th
 - **{% data variables.product.prodname_secret_scanning_caps %}** - Detect secrets, for example keys and tokens, that have been checked into the repository. For more information, see "[About {% data variables.product.prodname_secret_scanning %}](/github/administering-a-repository/about-secret-scanning)."
 
 {% if currentVersion == "free-pro-team@latest" %}
-- **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see "[Reviewing dependency changes in a pull request](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request)."
+- **Dependency review** - Show the full impact of changes to dependencies and see details of any vulnerable versions before you merge a pull request. For more information, see "[About dependency review](/code-security/supply-chain-security/about-dependency-review)."
 {% endif %}
 
 For information about {% data variables.product.prodname_advanced_security %} features that are in development, see "[{% data variables.product.prodname_dotcom %} public roadmap](https://github.com/github/roadmap)." For an overview of all security features, see "[About securing your repository](/github/administering-a-repository/about-securing-your-repository#setting-up-your-repository-securely)."
diff --git a/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md b/content/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization.md
@@ -146,7 +146,7 @@ In this section, you can find the repository permission levels required for secu
 | Create [security advisories](/github/managing-security-vulnerabilities/about-github-security-advisories) | | | | | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.22" or currentVersion == "github-ae@latest" %} 
 | Manage access to {% data variables.product.prodname_GH_advanced_security %} features (see "[Managing security and analysis settings for your organization](/github/setting-up-and-managing-organizations-and-teams/managing-security-and-analysis-settings-for-your-organization)") | | | | | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" %}
 | [Enable the dependency graph](/code-security/supply-chain-security/exploring-the-dependencies-of-a-repository) for a private repository | | | | | **X** |
-| [View dependency reviews](/github/collaborating-with-issues-and-pull-requests/reviewing-dependency-changes-in-a-pull-request) | **X** | **X** | **X** | **X** | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest" %}
+| [View dependency reviews](/code-security/supply-chain-security/about-dependency-review) | **X** | **X** | **X** | **X** | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@2.21" or currentVersion == "github-ae@latest" %}
 | [View {% data variables.product.prodname_code_scanning %} alerts on pull requests](/github/finding-security-vulnerabilities-and-errors-in-your-code/triaging-code-scanning-alerts-in-pull-requests) | **X** | **X** | **X** | **X** | **X** |
 | [List, dismiss, and delete {% data variables.product.prodname_code_scanning %} alerts](/github/finding-security-vulnerabilities-and-errors-in-your-code/managing-code-scanning-alerts-for-your-repository) | | | **X** | **X** | **X** |{% endif %}{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" or currentVersion == 'github-ae@next' %}
 | [View {% data variables.product.prodname_secret_scanning %} alerts in a repository](/github/administering-a-repository/managing-alerts-from-secret-scanning) | | | **X**<sup>[1]</sup> | **X**<sup>[1]</sup> | **X** |
diff --git a/data/reusables/dependency-review/feature-overview.md b/data/reusables/dependency-review/feature-overview.md
@@ -0,0 +1,4 @@
+Dependency review helps you understand dependency changes and the security impact of these changes at every pull request. It provides an easily understandable visualization of dependency changes with a rich diff on the "Files Changed" tab of a pull request. Dependency review informs you of:
+- Which dependencies were added, removed, or updated, along with the release dates.
+- How many projects use these components.
+- Vulnerability data for these dependencies.
