Alert rules: user-configured dismiss rules for Dependabot alerts [Public Beta] (#39300)

Co-authored-by: github-actions <github-actions@github.com>
Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
Co-authored-by: Jennifer Ramirez <101611327+jennifer-ramirez-08@users.noreply.github.com>
Co-authored-by: Erin Havens <erinhav@github.com>
Co-authored-by: Anne-Marie <102995847+am-stead@users.noreply.github.com>

content/code-security/dependabot/dependabot-alerts/about-dependabot-alerts.md

@@ -34,8 +34,6 @@ shortTitle: Dependabot alerts
 
 If your code depends on a package with a security vulnerability, this can cause a range of problems for your project or the people who use it. You should upgrade to a secure version of the package as soon as possible.{% ifversion GH-advisory-db-supports-malware %} If your code uses malware, you need to replace the package with a secure alternative.{% endif %}
 
-{% data reusables.security-advisory.link-browsing-advisory-db %}
-
 {% data reusables.dependabot.quickstart-link %}
 
 ## Detection of insecure dependencies
@@ -89,6 +87,12 @@ When {% data variables.product.product_name %} identifies a vulnerable dependenc
 
 {% data reusables.dependabot.dependabot-alert-create-PR %}
 
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+
+{% data reusables.dependabot.dependabot-alert-rules %}
+
+{% endif %}
+
 {% warning %}
 
 **Note**: {% data variables.product.product_name %}'s security features do not claim to catch all vulnerabilities{% ifversion GH-advisory-db-supports-malware %} and malware{% endif %}. We actively maintain {% data variables.product.prodname_advisory_database %} and generate alerts with the most up-to-date information. However, we cannot catch everything or tell you about known vulnerabilities within a guaranteed time frame. These features are not substitutes for human review of each dependency for potential vulnerabilities or any other issues, and we recommend consulting with a security service or conducting a thorough dependency review when necessary.

content/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts.md

@@ -31,6 +31,12 @@ You can enable or disable {% data variables.product.prodname_dependabot_alerts %
 - Your organization{% ifversion dependabot-alerts-enterprise-enablement or ghes > 3.8 %}
 - Your enterprise{% endif %}
 
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+
+{% data reusables.dependabot.dependabot-alert-rules %}
+
+{% endif %}
+
 ## Managing {% data variables.product.prodname_dependabot_alerts %} for your personal account
 
 {% ifversion fpt or ghec %}

content/code-security/dependabot/dependabot-alerts/using-alert-rules-to-prioritize-dependabot-alerts.md

@@ -1,7 +1,7 @@
 ---
 title: Using alert rules to prioritize Dependabot alerts
 intro: 'You can use {% data variables.product.prodname_dependabot %} alert rules to filter out false positive alerts or alerts you''re not interested in.'
-permissions: 'People with write permissions to a private repository can enable or disable {% data variables.product.prodname_dependabot %} alert rules for the repository.'
+permissions: 'People with write permissions can view  {% data variables.product.prodname_dependabot %} alert rules for the repository. People with with admin permissions to a repository, or the security manager role for the repository, can enable or disable {% data variables.product.prodname_dependabot %} alert rules for the repository{% ifversion dependabot-alert-custom-rules-repo-level %}, as well as create custom alert rules{% endif %}.'
 versions:
   feature: dependabot-alert-rules-auto-dismissal-npm-dev-dependencies
 type: how_to
@@ -14,22 +14,29 @@ topics:
 shortTitle: Alert rules
 ---
 
-## About {% data variables.product.prodname_dependabot %} alert rules
+{% data reusables.dependabot.github-alert-rules-beta %}
-<!-- will need to review this procedural section for GHES -->
 
-{% data reusables.dependabot.github-curated-alert-rules-beta %}
+## About {% data variables.product.prodname_dependabot %} alert rules
 
 {% data variables.product.prodname_dependabot %} alert rules allow you to instruct {% data variables.product.prodname_dependabot %} to automatically dismiss or reopen certain alerts, based on complex logic from a variety of contextual criteria.
 
-When enabled, the built-in `Dismiss low impact alerts` rule auto-dismisses certain types of vulnerabilities that are found in npm dependencies used in development. These alerts cover cases that feel like false alarms to most developers as the associated vulnerabilities:
+{% ifversion dependabot-alert-custom-rules-repo-level %}
-- Are unlikely to be exploitable in a developer (non-production or runtime) environment.
+There are two types of {% data variables.product.prodname_dependabot %} alert rules:
-- May relate to resource management, programming and logic, and information disclosure issues.
-- At worst, have limited effects like slow builds or long-running tests.
-- Are not indicative of issues in production.
 
-This {% data variables.product.company_short %}-curated `Dismiss low impact alerts` rule includes vulnerabilities relating to resource management, programming and logic, and information disclosure issues. For more information, see "[Publicly disclosed CWEs used by the Dismiss low impact rule](#publicly-disclosed-cwes-used-by-the-dismiss-low-impact-rule)."
+- {% data variables.product.company_short %}-curated rules
+- User-created custom rules
 
-Filtering out these low impact alerts allows you to focus on alerts that matter to you, without having to worry about missing potentially high-risk development-scoped alerts.
+{% data variables.product.company_short %}-curated rules are enabled by default for public repositories and can be opted into for private repositories. However, it's important to note that you cannot modify the {% data variables.product.company_short %}-curated rules. With user-created custom rules, you can create your own rules to automatically dismiss or reopen alerts based on your own criteria.{% endif %}
+
+Whilst you may find it useful to auto-dismiss low impact alerts, you can still reopen auto-dismissed alerts and filter to see which alerts have been auto-dismissed. For more information, see "[Managing automatically dismissed alerts](#managing-automatically-dismissed-alerts)."
+
+Additionally, auto-dismissed alerts are still available for reporting and reviewing, and can be auto-reopened if the alert metadata changes, for example:
+- If you change the scope of a dependency from development to production.
+- If {% data variables.product.company_short %} modifies certain metadata for the related advisory.
+
+Auto-dismissed alerts are defined by the `resolution:auto-dismiss` close reason. Automatic dismissal activity is included in alert webhooks, REST and GraphQL APIs, and the audit log. For more information, see "[AUTOTITLE](/rest/dependabot/alerts)" in the REST API documentation, and the "`repository_vulnerability_alert` " section in "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#repository_vulnerability_alert-category-actions)."
+
+## About {% data variables.product.company_short %}-curated rules
 
 {% note %}
 
@@ -37,30 +44,76 @@ Filtering out these low impact alerts allows you to focus on alerts that matter
 
 {% endnote %}
 
-Whilst you may find it useful to auto-dismiss low impact alerts, you can still reopen auto-dismissed alerts, and filter to see which alerts have been auto-dismissed. For more information, see "[Managing automatically dismissed alerts](#managing-automatically-dismissed-alerts)."
+When enabled, the built-in `Dismiss low impact alerts` rule auto-dismisses certain types of vulnerabilities that are found in npm dependencies used in development. These alerts cover cases that feel like false alarms to most developers as the associated vulnerabilities:
 
-Additionally, auto-dismissed alerts are still available for reporting and reviewing, and can be re-introduced as not having been dismissed if the alert metadata changes, for example:
+- Are unlikely to be exploitable in a developer (non-production or runtime) environment.
-- If you change the scope of a dependency from development to production.
+- May relate to resource management, programming and logic, and information disclosure issues.
-- If {% data variables.product.company_short %} modifies certain metadata for the related advisory.
+- At worst, have limited effects like slow builds or long-running tests.
+- Are not indicative of issues in production.
 
-Auto-dismissed alerts are defined by the `resolution:auto-dismiss` close reason. Automatic dismissal activity is included in alert webhooks, REST and GraphQL APIs, and the audit log. For more information, see "[AUTOTITLE](/rest/dependabot/alerts)" in the REST API documentation, and the "`repository_vulnerability_alert` " section in "[Reviewing the audit log for your organization](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization#repository_vulnerability_alert-category-actions)."
+This {% data variables.product.company_short %}-curated `Dismiss low impact alerts` rule includes vulnerabilities relating to resource management, programming and logic, and information disclosure issues. For more information, see "[Publicly disclosed CWEs used by the `Dismiss low impact alerts` rule](#publicly-disclosed-cwes-used-by-the-dismiss-low-impact-alerts-rule)."
 
-By default, {% data variables.product.company_short %}-curated {% data variables.product.prodname_dependabot %} alert rules are enabled on public repositories and disabled for private repositories. Administrators of private repositories can opt in by enabling alert rules for their repository. For more information, see "[Enabling {% data variables.product.prodname_dependabot %} alert rules for your private repository](#enabling-dependabot-alert-rules-for-your-private-repository)."
+Filtering out these low impact alerts allows you to focus on alerts that matter to you, without having to worry about missing potentially high-risk development-scoped alerts.
 
-## Enabling {% data variables.product.prodname_dependabot %} alert rules for your private repository
+By default, {% data variables.product.company_short %}-curated {% data variables.product.prodname_dependabot %} alert rules are enabled on public repositories and disabled for private repositories. Administrators of private repositories can opt in by enabling alert rules for their repository.
+
+### Enabling the  `Dismiss low impact alerts` rule for your private repository
 
 {% ifversion fpt or ghec %}You first need to enable {% data variables.product.prodname_dependabot_alerts %} for the repository. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-alerts/configuring-dependabot-alerts#managing-dependabot-alerts-for-your-repository)."{% elsif ghes %}{% data variables.product.prodname_dependabot_alerts %} for your repository can be enabled or disabled by your enterprise owner. For more information, see "[AUTOTITLE](/admin/configuration/configuring-github-connect/enabling-dependabot-for-your-enterprise)."{% endif %}
 
-{% ifversion fpt or ghec %}
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-settings %}
 {% data reusables.repositories.navigate-to-code-security-and-analysis %}
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+1. Under "{% data variables.product.prodname_dependabot_alerts %}", click {% octicon "gear" aria-label="The Gear icon" %} close to "{% data variables.product.prodname_dependabot %} rules".
+
+   ![Screenshot of the "Code security and analysis" page for a repository. The gear icon is highlighted with an orange outline.](/assets/images/help/repository/dependabot-rules-page.png)
+
+1. Select **Dismiss low impact alerts**.
+1. Click **Save rules**.
+{% else %}
 1. Under "{% data variables.product.prodname_dependabot_alerts %}", click **Dismiss low impact alerts**.
+
    ![Screenshot of the "Code security and analysis" page for a repository. The "Dismiss low impact alerts" option is highlighted with an orange outline.](/assets/images/help/repository/enable-autodismissal-low-impact-dependabot-alerts.png)
+
+{% endif %}
+
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+## About user-created custom rules
+
+You can create your own {% data variables.product.prodname_dependabot %} alert rules based on alert criteria.
+
+- Dependency scope (`devDependency` or `runtime`)
+- Package name
+- CWE
+- Severity
+- Patch availability
+- Manifest path
+- Ecosystem
+
+### Adding a custom rule to your repository
+
+You can add a custom rule to your {% ifversion fpt %}public and private{% elsif ghec or ghes %}public, private, and internal{% endif %} repositories.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-settings %}
+{% data reusables.repositories.navigate-to-code-security-and-analysis %}
+1. Under "{% data variables.product.prodname_dependabot_alerts %}", click {% octicon "gear" aria-label="The Gear icon" %} close to "{% data variables.product.prodname_dependabot %} rules".
+
+   ![Screenshot of the "Code security and analysis" page for a repository. The gear icon is highlighted with an orange outline.](/assets/images/help/repository/dependabot-rules-page.png)
+
+1. Click **New ruleset**.
+
+   ![Screenshot of the "Code security and analysis" page for a repository. The gear icon is highlighted with an orange outline.](/assets/images/help/repository/dependabot-rules-new-ruleset.png)
+
+1. Under "Name", describe what this rule will do.
+1. Under "Alert criteria", select the criteria you want to use to filter alerts.
+1. Under "Rules", select the action you want to take on alerts that match the criteria.
+1. Click **Create rule**.
+
 {% endif %}
 
 ## Managing automatically dismissed alerts
-<!-- will need to review this procedural section for GHES -->
 
 You can filter to see which alerts have been auto-dismissed, and you can reopen dismissed alerts.
 
@@ -84,7 +137,7 @@ You can filter to see which alerts have been auto-dismissed, and you can reopen
 
    ![Screenshot of an alert title on the "Dependabot Alerts" page. To the left of the alert, a checkbox is highlighted in an orange outline.](/assets/images/help/repository/dependabot-reopen-closed-alert.png)
 
-## Publicly disclosed CWEs used by the Dismiss low impact rule
+## Publicly disclosed CWEs used by the `Dismiss low impact alerts` rule
 
 Along with the `ecosystem:npm` and `scope:development` alert metadata, we use the following {% data variables.product.company_short %}-curated Common Weakness Enumerations (CWEs) to filter out low impact alerts for the `Dismiss low impact alerts` rule. We regularly improve this list and vulnerability patterns covered by built-in rules.
 

content/code-security/getting-started/github-security-features.md

@@ -41,6 +41,12 @@ View alerts about dependencies that are known to contain security vulnerabilitie
 and "[AUTOTITLE](/code-security/dependabot/dependabot-security-updates/about-dependabot-security-updates)."
 {% endif %}
 
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+
+{% data reusables.dependabot.dependabot-alert-rules %}
+
+{% endif %}
+
 {% data reusables.dependabot.quickstart-link %}
 
 {% ifversion ghae %}

content/code-security/getting-started/securing-your-repository.md

@@ -54,6 +54,12 @@ For more information, see "[AUTOTITLE](/code-security/supply-chain-security/unde
 
 {% data variables.product.prodname_dependabot_alerts %} are generated when {% data variables.product.prodname_dotcom %} identifies a dependency in the dependency graph with a vulnerability. {% ifversion fpt or ghec %}You can enable {% data variables.product.prodname_dependabot_alerts %} for any repository.{% endif %}
 
+{% ifversion dependabot-alert-custom-rules-repo-level %}
+
+{% data reusables.dependabot.dependabot-alert-rules %}
+
+{% endif %}
+
 {% data reusables.dependabot.quickstart-link %}
 
 {% ifversion fpt or ghec %}

data/features/dependabot-alert-custom-rules-repo-level.yml

@@ -0,0 +1,6 @@
+# Reference: Issue #10089 - Alert rules: user-configured dismiss rules for Dependabot alerts
+
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.10'

data/features/dependabot-alert-rules-auto-dismissal-npm-dev-dependencies.yml

@@ -3,4 +3,4 @@
 versions:
   fpt: '*'
   ghec: '*'
-  ghes: '>3.9'
+  ghes: '>3.10'

data/reusables/dependabot/dependabot-alert-rules.md

@@ -0,0 +1 @@
+Additionally, you can use {% data variables.product.prodname_dependabot %} alert rules to filter out false positive alerts or alerts you're not interested in, based on complex logic from a variety of contextual criteria. For more information, see "[AUTOTITLE](/code-security/dependabot/dependabot-alerts/using-alert-rules-to-prioritize-dependabot-alerts)."

data/reusables/dependabot/github-alert-rules-beta.md

@@ -0,0 +1,5 @@
+{% note %}
+
+**Note:** {% data variables.product.prodname_dependabot %} alert rules are currently in beta and are subject to change.
+
+{% endnote %}

data/reusables/dependabot/github-curated-alert-rules-beta.md

@@ -1,5 +0,0 @@
-{% note %}
-
-**Note:** {% data variables.product.company_short %}-curated {% data variables.product.prodname_dependabot %} alert rules are currently in beta and are subject to change.
-
-{% endnote %}

data/reusables/gated-features/dependabot-alerts.md

@@ -1,5 +1,5 @@
 {%- ifversion fpt or ghec %}
-{% data variables.product.prodname_dependabot_alerts %} are free to use for all repositories on {% data variables.product.prodname_dotcom_the_website %}.
+{% data variables.product.prodname_dependabot_alerts %} are free to use for all repositories on {% data variables.product.prodname_dotcom_the_website %}. Advanced capabilities, like reachability analysis and the ability to create custom alert rules, are available on any public repositories (for free), and on any private repositories, when you have a license for {% data variables.product.prodname_GH_advanced_security %}.
 
 {%- elsif ghes %}
 {% data variables.product.prodname_dependabot_alerts %} are free to use for repositories (user-owned and organization-owned) on {% data variables.product.prodname_ghe_server %}, provided enterprise administrators enable the feature for your enterprise.