Document Dependabot metrics (#55730)

Co-authored-by: Nish Sinha <nishnha@github.com>
Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>

content/code-security/securing-your-organization/index.md

@@ -16,6 +16,7 @@ children:
   - /enabling-security-features-in-your-organization
   - /managing-the-security-of-your-organization
   - /understanding-your-organizations-exposure-to-leaked-secrets
+  - /understanding-your-organizations-exposure-to-vulnerabilites
   - /fixing-security-alerts-at-scale
   - /troubleshooting-security-configurations
 ---

content/code-security/securing-your-organization/understanding-your-organizations-exposure-to-vulnerabilites/about-your-exposure-to-vulnerable-dependencies.md

@@ -0,0 +1,69 @@
+---
+title: About your exposure to vulnerable dependencies
+shortTitle: Dependency vulnerability exposure
+intro: 'Understanding your organization’s exposure to vulnerable dependencies is essential for identifying and prioritizing security risks. Leveraging {% data variables.product.prodname_dependabot %} metrics on {% data variables.product.github %} enables you to efficiently assess, prioritize, and remediate vulnerabilities, reducing the likelihood of security breaches.'
+allowTitleToDifferFromFilename: true
+product: '{% data reusables.gated-features.ghas-billing %}'
+versions:
+  feature: dependabot-metrics
+topics:
+  - Code Security
+  - Secret Protection
+  - Organizations
+  - Security
+---
+
+## About exposure to vulnerable dependencies
+
+Assessing your exposure to vulnerable dependencies is crucial if you want to prevent:
+
+* **Supply chain compromise**. Attackers can exploit vulnerabilities in open source or third-party dependencies to inject malicious code, elevate privileges, or gain unauthorized access to your systems. Compromised dependencies can serve as indirect entry points for malicious actors, leading to wide-reaching security incidents.
+
+* **Widespread propagation of risk**. Vulnerable dependencies are often reused across multiple applications and services, meaning a single flaw can propagate throughout your organization, compounding the risk and impact of exploitation.
+
+* **Unplanned downtime and operational disruption**. Exploitation of dependency vulnerabilities can result in application outages, degraded service quality, or cascading failures in critical systems, disrupting your business operations.
+
+* **Regulatory and licensing issues**. Many regulations and industry standards require organizations to proactively address known vulnerabilities in their software supply chain. Failing to remediate vulnerable dependencies can result in non-compliance, audits, legal penalties, or breaches of open source license obligations.
+
+* **Increased remediation costs**. The longer vulnerable dependencies remain unaddressed, the more difficult and expensive they become to fix, especially if they are deeply integrated or if incidents occur. Early detection and remediation reduce the risk of costly incident response, emergency patching, and reputational harm.
+
+Regularly assessing your exposure to dependency vulnerabilities is good practice to help identify risks early, implement effective remediation strategies, and maintain resilient, trustworthy software.
+
+{% data variables.product.prodname_dependabot %} automatically monitors your project’s dependencies for vulnerabilities and outdated packages. When it detects a security issue or a new version, it creates pull requests to update the affected dependencies, helping you quickly address security risks and keep your software up to date. This reduces manual effort and helps ensure your project remains secure. See [AUTOTITLE](/code-security/getting-started/dependabot-quickstart-guide).
+
+{% data variables.product.github %} provides a comprehensive set of {% data variables.product.prodname_dependabot %} metrics to help you monitor, prioritize, and remediate these risks across all repositories in your organization. See [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-dependabot-alerts).
+
+## Key tasks for AppSec managers
+
+### 1. Monitor vulnerability metrics
+
+Use the metrics overview for {% data variables.product.prodname_dependabot %} to gain visibility into the current state of your organization's dependency vulnerabilities. See [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-dependabot-alerts).
+
+* **Alert prioritization:** Review the number of open {% data variables.product.prodname_dependabot_alerts %} and use filters such as CVSS severity, EPSS exploit likelihood, patch availability, and whether a vulnerable dependency is actually used in deployed artifacts. {% data reusables.security-overview.dependabot-filters-link %}
+* **Repository-level breakdown:** Identify which repositories have the highest number of critical or exploitable vulnerabilities.
+* **Remediation tracking:** Track the number and percentage of alerts fixed over time to measure the effectiveness of your vulnerability management program.
+
+### 2. Prioritize remediation efforts
+
+Focus on vulnerabilities that present the highest risk to your organization.
+
+* Prioritize alerts with high or critical severity, high EPSS scores, and available patches.
+* Use the repository breakdown to direct remediation efforts to the most at-risk projects.
+* Encourage development teams to address vulnerabilities that are actually used in deployed artifacts through repository custom properties.
+
+### 3. Communicate risk and progress
+
+* Use the {% data variables.product.prodname_dependabot %} metrics page to communicate key risk factors and remediation progress to stakeholders.
+* Provide regular updates on trends, such as the reduction in open critical vulnerabilities or improvements in remediation rates.
+* Highlight repositories or teams that require additional support or attention.
+
+### 4. Establish and enforce policies
+
+* Set organization-wide policies to require dependency review and {% data variables.product.prodname_dependabot_alerts %} on all repositories. See [AUTOTITLE](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review) and [AUTOTITLE](/code-security/dependabot/dependabot-alerts/about-dependabot-alerts).
+* Ensure that new repositories are automatically enrolled in dependency monitoring.
+* Work with repository administrators to enable automated security updates where possible. See [AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates).
+
+### 5. Assess the impact of {% data variables.product.prodname_dependabot_alerts %}
+
+* Regularly review how {% data variables.product.prodname_dependabot_alerts %} are helping to block security vulnerabilities from entering your codebase.
+* Use historical data to demonstrate the value of proactive dependency management.

content/code-security/securing-your-organization/understanding-your-organizations-exposure-to-vulnerabilites/index.md

@@ -0,0 +1,15 @@
+---
+title:  'Understanding your organization''s exposure to vulnerabilities'
+shortTitle: Exposure to vulnerabilities
+intro: 'Understanding your organization’s exposure to vulnerable dependencies is crucial for identifying and prioritizing security risks. This awareness allows you to prioritize remediation efforts, reduce the likelihood of security breaches, protect sensitive data, and maintain the overall integrity and reputation of the organization.'
+versions:
+  feature: dependabot-metrics
+topics:
+  - Code Security
+  - Dependabot
+  - Organizations
+  - Security
+children:
+  - /about-your-exposure-to-vulnerable-dependencies
+  - /prioritizing-dependabot-alerts-using-metrics
+---

content/code-security/securing-your-organization/understanding-your-organizations-exposure-to-vulnerabilites/prioritizing-dependabot-alerts-using-metrics.md

@@ -0,0 +1,73 @@
+---
+title: Prioritizing Dependabot alerts using metrics
+shortTitle: Prioritize Dependabot alerts using metrics
+intro: 'You can prioritize {% data variables.product.prodname_dependabot_alerts %} in your organization by analyzing the provided metrics. Using this approach, you can tell your developers to focus on the most important vulnerabilities first.'
+allowTitleToDifferFromFilename: true
+permissions: '{% data reusables.permissions.security-org-enable %}'
+versions:
+  feature: dependabot-metrics
+topics:
+  - Code Security
+  - Dependabot
+  - Organizations
+  - Security
+---
+
+## Prioritizing {% data variables.product.prodname_dependabot_alerts %} using metrics
+
+Application Security (AppSec) managers often face a flood of {% data variables.product.prodname_dependabot_alerts %}, making it challenging to determine which vulnerabilities to address first. {% data variables.product.prodname_dependabot %} metrics provide valuable insights that help prioritize alerts efficiently, ensuring that critical security issues are resolved promptly. Users can make informed decisions, focusing resources on the most impactful vulnerabilities. This approach strengthens the organization’s security posture and streamlines vulnerability management.
+
+## Understanding {% data variables.product.prodname_dependabot %} metrics
+
+{% data variables.product.prodname_dependabot %} metrics offer detailed information about vulnerabilities detected in your dependencies. Key metrics include:
+
+* **Severity**: Indicates the potential impact of a vulnerability (e.g., low, medium, high, critical).
+* **Exploitability**: Assesses how easily a vulnerability can be exploited.
+* **Dependency relationship**: Differentiates between direct and transitive dependencies.
+* **Dependency scope**: Differentiates between runtime and development dependencies. Determines if the vulnerable code is actually used in your application.
+* **Alerts closed in the last 30 days, including the number of alerts fixed by {% data variables.product.prodname_dependabot %}, manually dismissed, and auto dismissed**: Tracks alert resolution progress. Illustrates how {% data variables.product.prodname_GH_code_security %} can help you detect vulnerabilities early.
+* **Table showing the total number of open alerts for each repository, as well as severity and expoitability data**: Allows you to dig deeper at the repository level.
+
+Additionally, you can specify complex filters, which are combinations of the individual filters that are available. For more information about filters, see [{% data variables.product.prodname_dependabot %} dashboard view filters](/code-security/security-overview/filtering-alerts-in-security-overview#dependabot-dashboard-view-filters).
+
+## Steps to prioritize alerts
+
+These first steps help you identify the {% data variables.product.prodname_dependabot_alerts %} that put your organization the most at risk, so that you can tell your developers which alerts to focus on for remediation.
+
+### 1. Tailor the funnel order to suit your organization's needs
+
+You can customize the default funnel order on the "Alert prioritization" graph to ensure it reflects the unique risk profile, business priorities, and compliance requirements of your organization. See [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-dependabot-alerts#configuring-funnel-categories).
+
+### 2. Focus on critical and high severity alerts
+
+Start by identifying alerts with the highest severity by using the the `severity-critical` or `severity-high` filters. These vulnerabilities pose the greatest risk and are often prioritized by compliance standards. You can then
+
+### 3. Assess exploitability and reachability
+
+Prioritize vulnerabilities that are the most likely to be exploited in your codebase. To identify alerts that are most likely to be exploited, you can use the `epss_percentage` filter associated to a value (for example `epss_percentage>=0.10`).
+
+### 4. Review dependency scope and relationship
+
+Direct dependencies are typically easier to update and may have a greater impact on your application’s security. We recommend addressing these before transitive dependencies when possible.
+Filtering alerts using the `relationship:direct` filter allows us to see vulnerabilities on direct dependencies for supported ecosystems like npm.
+
+Runtime dependencies are used by an application in production. Updating this sort of dependency can address security vulnerabilities, bug fixes, and performance improvements that affect your end users or systems directly. On the other hand, development dependencies are only used during development, testing, or build processes. While important, issues in these dependencies usually don’t impact your running application or its users.
+
+You can use the `scope:runtime` or `scope:development` filters to only display alerts for runtime or development dependencies, respectively.
+
+### 5. Consider the age of alerts
+
+Older alerts may indicate long-standing risks. Regularly review and address aged alerts to prevent security debt from accumulating. For example, once you establish that a specific repository has more alerts that need prioritizing than other repositories, you can:
+1. Click the repository name on the per-repository table to display the alerts for that repository only.
+1. Use the "Older" filter in the **Sort** dropdown list, as well as other sorting criteria, to fine-tune the visualization to alerts meeting your criteria by age.
+
+### 6. Leverage automation
+
+Use {% data variables.product.prodname_dependabot %}’s automated pull requests to quickly remediate vulnerabilities. Integrate these updates into your CI/CD pipeline for faster resolution and improved efficiency.
+
+## Best practices
+
+* **Establish Service Level Agreements (SLAs)** for resolving vulnerabilities based on severity.
+* **Monitor metrics regularly** to identify trends and recurring issues.
+* **Collaborate with developers** to ensure timely updates and minimize disruption.
+* **Document decisions** to provide transparency and support future prioritization.

content/code-security/security-overview/filtering-alerts-in-security-overview.md

@@ -162,7 +162,7 @@ You can also filter the "Overview" view by properties of alerts.
 
 {% endif %}
 
-## {% data variables.product.prodname_dependabot %} alert view filters
+### {% data variables.product.prodname_dependabot %} alert view filters
 
 You can filter the view to show {% data variables.product.prodname_dependabot_alerts %} that are ready to fix or where additional information about exposure is available. You can click any result to see full details of the alert.
 
@@ -176,7 +176,19 @@ You can filter the view to show {% data variables.product.prodname_dependabot_al
 |`scope`|Display {% data variables.product.prodname_dependabot_alerts %} from the development dependency (`development`) or from the runtime dependency (`runtime`).|
 |`sort`| Groups {% data variables.product.prodname_dependabot_alerts %} by the manifest file path the alerts point to (`manifest-path`) or by the name of the package where the alert was detected (`package-name`). Alternatively, displays alerts from most important to least important, as determined by CVSS score, vulnerability impact, relevancy, and actionability (`most-important`), from newest to oldest (`newest`), from oldest to newest (`oldest`), or from most to least severe (`severity`).
 
-## {% data variables.product.prodname_code_scanning_caps %} alert view filters
+{% ifversion dependabot-metrics %}
+
+### {% data variables.product.prodname_dependabot %} dashboard filters
+
+You can filter the "{% data variables.product.prodname_dependabot %} dashboard" view using these filters.
+
+{% data reusables.security-overview.filter-dependabot-metrics %}
+
+Alternatively, you can use complex filters by clicking **{% octicon "filter" aria-hidden="true" aria-label="filter" %} Filter** and build custom filters to suit your needs.
+
+{% endif %}
+
+### {% data variables.product.prodname_code_scanning_caps %} alert view filters
 
 All {% data variables.product.prodname_code_scanning %} alerts have one of the categories shown below. You can click any result to see full details of the relevant query and the line of code that triggered the alert.
 

content/code-security/security-overview/index.md

@@ -20,6 +20,7 @@ children:
   - /filtering-alerts-in-security-overview
   - /enabling-security-features-for-multiple-repositories
   - /exporting-data-from-security-overview
+  - /viewing-metrics-for-dependabot-alerts
   - /viewing-metrics-for-secret-scanning-push-protection
   - /viewing-metrics-for-pull-request-alerts
   - /reviewing-requests-to-bypass-push-protection

content/code-security/security-overview/viewing-metrics-for-dependabot-alerts.md

@@ -0,0 +1,66 @@
+---
+title: Viewing metrics for Dependabot alerts
+shortTitle: View Dependabot metrics
+allowTitleToDifferFromFilename: true
+intro: 'You can use security overview to see how many {% data variables.product.prodname_dependabot_alerts %} are in repositories across your organization, to prioritize the most critical alerts to fix, and to identify repositories where you may need to take action.'
+versions:
+  feature: dependabot-metrics
+permissions: '{% data reusables.permissions.security-overview %}'
+product: '{% data reusables.gated-features.security-overview-fpt-cs-only %}'
+type: how_to
+topics:
+  - Security overview
+  - Code Security
+  - Dependabot
+  - Organizations
+  - Alerts
+  - Vulnerabilities
+---
+
+## About metrics for {% data variables.product.prodname_dependabot %}
+
+The metrics overview for {% data variables.product.prodname_dependabot %} provides valuable insights for both developers and application security (AppSec) managers. The data in the {% data variables.product.prodname_dependabot %} dashboard page contains a vulnerability prioritization funnel that helps with efficiently prioritizing, remediating, and tracking vulnerabilities across multiple repositories. This ensures that the most critical risks are addressed first and that security improvements can be measured over time.
+
+For more information about how AppSec managers can best use these metrics to optimize alert fixing, see [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-vulnerabilites/prioritizing-dependabot-alerts-using-metrics).
+
+You can see  {% data variables.product.prodname_dependabot %} metrics if you have:
+
+* The `admin` role for the repository.
+* A custom repository role with the "View {% data variables.product.prodname_dependabot_alerts %}" fine-grained permissions for the repository. For more information, see [AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/about-custom-repository-roles#security).
+* Access to alerts for the repository. For more information, see [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository#granting-access-to-security-alerts).
+
+The available metrics combine severity, exploitability, and patch availability, and help in the following ways:
+
+* **Alert prioritization:** the chart shows the number of **open {% data variables.product.prodname_dependabot_alerts %}**. You can use filters, such as availability of patches, severity, EPSS score to narrow down the list of alerts to those matching the criteria. {% data reusables.security-overview.dependabot-filters-link %}
+
+* **Remediation tracking:** The “Alerts closed” tile shows the number of alerts fixed with {% data variables.product.prodname_dependabot %}, manually dismissed, and auto dismissed, providing visibility into remediation performance and trends. The tile also shows the percent increase in the number of alerts closed in the last 30 days.
+
+* **Highest-risk package:** The "Most vulnerabilities" tile shows the dependency that has the most vulnerabilities in the organization. The tile also provides a link to the related alerts across all your repositories.
+
+* **Repository-level breakdown:** The table shows a breakdown of open alerts by repository, including counts by severity (critical, high, medium, low) and by exploitability (for example, EPSS > 1%), and can be sorted by each column. This helps you identify which projects are most at risk, prioritize remediation efforts where they matter most, and track progress over time at a granular level.
+
+These metrics help managers measure the effectiveness of their vulnerability management and ensure compliance with organizational or regulatory timelines.
+
+* **Actionable context for developers:** Developers can use the severity and patch availability filters to identify vulnerabilities they can fix immediately, reducing noise and focusing attention on issues they can address. These metrics help them understand the risk profile of their dependencies, enabling informed prioritization of work.
+
+## Viewing metrics for {% data variables.product.prodname_dependabot %} for an organization
+
+{% data reusables.organizations.navigate-to-org %}
+{% data reusables.organizations.security-overview %}
+1. In the sidebar, under "Metrics", click **{% octicon "dependabot" aria-hidden="true" aria-label="dependabot" %} {% data variables.product.prodname_dependabot %} dashboard**.
+1. Optionally, use the filters at your disposal, or build your own filters. {% data reusables.security-overview.dependabot-filters-link %}
+1. Optionally, click on a number on the x-axis of the chart to filter the alert list by the relevant criteria (for example `has:patch severity:critical,high epss_percentage:>=0.01`).
+1. Optionally, click on an individual repository to see the associated {% data variables.product.prodname_dependabot_alerts %}.
+
+## Configuring funnel categories
+
+The default funnel order is `has:patch, severity:critical,high, epss_percentage>=0.01`. By tailoring the funnel’s order, you and your teams can focus on the vulnerabilities that matter most to your organization, environments, or regulatory obligations, making remediation efforts more effective and aligned with your specific needs.
+
+{% data reusables.organizations.navigate-to-org %}
+{% data reusables.organizations.security-overview %}
+1. In the sidebar, under "Metrics", click **{% octicon "dependabot" aria-hidden="true" aria-label="dependabot" %} {% data variables.product.prodname_dependabot %} dashboard**.
+1. On the top right of the "Alert prioritization" graph, click {% octicon "gear" aria-label="Configure funnel categories" %}.
+1. In the "Configure funnel order" dialog, move the criteria as desired.
+1. Once you're done, click **Move** to save your changes.
+
+>[!TIP] You can reset the funnel order back to the default settings by clicking **Reset to default** to the right of the graph.

data/features/dependabot-metrics.yml

@@ -0,0 +1,6 @@
+# Reference: #17734
+# Dependabot Metrics page [GA]
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '> 3.18'

data/reusables/security-overview/dependabot-filters-link.md

@@ -0,0 +1 @@
+See [{% data variables.product.prodname_dependabot %} dashboard view filters](/code-security/security-overview/filtering-alerts-in-security-overview#dependabot-dashboard-view-filters).

data/reusables/security-overview/filter-dependabot-metrics.md

@@ -0,0 +1,16 @@
+
+| Qualifier | Description |
+| -------- | -------- |
+|`repo`|Display {% data variables.product.prodname_dependabot_alerts %} detected in a specified repository, for example: `repo:octo-repository`.|
+|`topic`|Display {% data variables.product.prodname_dependabot_alerts %} with the matching topic, for example: `topic:asdf`.|
+|`team`|Display {% data variables.product.prodname_dependabot_alerts %} owned by members of the specified team, for example: `team:octocat-dependabot-team`.|
+|`visibility`|Display {% data variables.product.prodname_dependabot_alerts %} detected in repositories of the specified visibility, for example: `visibility:private`.|
+|`archived`|Display {% data variables.product.prodname_dependabot_alerts %} detected in respositories that are either archived, or not, for example: `archived:true`.|
+|`state`|Display {% data variables.product.prodname_dependabot_alerts %} of the specified state, for example: `state:unresolved`.|
+|`severity`|Display {% data variables.product.prodname_dependabot_alerts %} of the specified severity, for example: `severity:critical`.|
+|`scope`|Display {% data variables.product.prodname_dependabot_alerts %} from the development dependency (`development`) or from the runtime dependency (`runtime`).|
+|`package`|Display {% data variables.product.prodname_dependabot_alerts %} detected in the specified package, for example: `package:lodash`.|
+|`ecosystem`|Display {% data variables.product.prodname_dependabot_alerts %} detected in a specified ecosystem, for example: `ecosystem:Maven`.|
+|`relationship`|Display {% data variables.product.prodname_dependabot_alerts %} of the specified relationship, for example: `relationship:indirect`.|
+|`epss_percentage`|Display {% data variables.product.prodname_dependabot_alerts %} whose EPSS score meets the defined criteria, for example: `epss_percentage:>=0.01`|
+|`exclude <QUALIFIER>`|Applies to all the available qualifiers.</br>Display alerts that do not match the selected qualifier from the list of {% data variables.product.prodname_dependabot_alerts %}|