From fec13e67c47fb621b1891a7e1a83e41c61404354 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Sat, 14 Mar 2026 07:59:58 -0700 Subject: [PATCH 1/4] empty commit From 3db9fc747575cc815a587fa258781ab177e81707 Mon Sep 17 00:00:00 2001 From: "Michael B. Gale" Date: Mon, 16 Mar 2026 09:12:46 +0000 Subject: [PATCH 2/4] Code Scanning/CodeQL: Add docs for supported repository properties (#60138) Co-authored-by: Ben Ahmady <32935794+subatoi@users.noreply.github.com> Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com> --- .../concepts/code-scanning/index.md | 1 + .../code-scanning/repository-properties.md | 42 +++++++++++++++++++ .../concepts/code-scanning/setup-types.md | 10 +++-- ...iguring-default-setup-for-code-scanning.md | 11 +++++ ...ing-your-configuration-of-default-setup.md | 8 ++-- data/features/codeql-custom-properties.yml | 5 +++ 6 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 content/code-security/concepts/code-scanning/repository-properties.md create mode 100644 data/features/codeql-custom-properties.yml diff --git a/content/code-security/concepts/code-scanning/index.md b/content/code-security/concepts/code-scanning/index.md index 46a756ff81ab..f4ec4dc42867 100644 --- a/content/code-security/concepts/code-scanning/index.md +++ b/content/code-security/concepts/code-scanning/index.md @@ -24,4 +24,5 @@ children: - /codeql - /tool-status-page - /pull-request-alert-metrics + - /repository-properties --- diff --git a/content/code-security/concepts/code-scanning/repository-properties.md b/content/code-security/concepts/code-scanning/repository-properties.md new file mode 100644 index 000000000000..3b4a02ad990f --- /dev/null +++ b/content/code-security/concepts/code-scanning/repository-properties.md @@ -0,0 +1,42 @@ +--- +title: Repository properties for {% data variables.product.prodname_code_scanning %} +shortTitle: Repository properties +intro: You can use repository properties to adjust {% data variables.product.prodname_code_scanning %} to suit your needs. +topics: + - Code Security + - Code scanning +versions: + feature: codeql-custom-properties +contentType: concepts +--- + +## Prerequisites + +For the repository properties described here to have an effect, you need to have set up {% data variables.product.prodname_code_scanning %}. See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types). + +Repository properties which affect {% data variables.product.prodname_code_scanning %} must be created manually for your organization. You can then set values for them that apply to your entire organization or allow them to be configured differently for each repository. See [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization). + +## Supported repository properties for {% data variables.product.prodname_code_scanning %} + +Some {% data variables.product.prodname_code_scanning %} functionality can be configured using repository properties. Organizations can use repository properties to both enforce configurations across all repositories and for individual repositories. If {% data variables.product.prodname_code_scanning %} is customized using repository properties, the customization applies to all setup types. + +The following is an overview of repository properties you can set up which affect {% data variables.product.prodname_code_scanning %} analyses when configured: + +| Name | Type | +|------|------| +| `github-codeql-extra-queries` | Text | +| `github-codeql-disable-overlay` | True/false | +| `github-codeql-file-coverage-on-prs` | True/false | + +> [!NOTE] +> The repository properties which are supported depend on the version of the [github/codeql-action](https://github.com/github/codeql-action/) that is used by your {% data variables.product.prodname_code_scanning %} analyses. For {% data variables.product.prodname_code_scanning %} advanced setup, check that your workflow is referencing the latest major version. {% data variables.product.prodname_code_scanning_caps %} default setup automatically uses the latest version.{% ifversion ghes %} If the server on which you are running {% data variables.product.prodname_ghe_server %} is not connected to the internet, you may need to use the {% data variables.product.prodname_codeql %} action sync tool. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-enterprise-security/configure-specific-tools/configuring-code-scanning-for-your-appliance#configuring-codeql-analysis-on-a-server-without-internet-access).{% endif %} + +### Analysis customization + +The `github-codeql-extra-queries` property allows you to configure additional queries that should be run. This is useful to add queries to all relevant analyses in your organization without needing to modify individual workflows or switch to an advanced setup. This accepts the same values as the `queries` input of the [github/codeql-action](https://github.com/github/codeql-action/). See [AUTOTITLE](/code-security/reference/code-scanning/workflow-configuration-options). + +### Enabling or disabling features + +You can disable improved incremental analysis by setting the `github-codeql-disable-overlay` property to `true`. This may be useful if improved incremental analysis is failing because of increased hardware requirements. + +File coverage information is not calculated for analyses of pull requests. If you want to enable file coverage information for pull requests, you can set the `github-codeql-file-coverage-on-prs` property to `true`. diff --git a/content/code-security/concepts/code-scanning/setup-types.md b/content/code-security/concepts/code-scanning/setup-types.md index 531f1335dc14..08b762b10461 100644 --- a/content/code-security/concepts/code-scanning/setup-types.md +++ b/content/code-security/concepts/code-scanning/setup-types.md @@ -30,8 +30,6 @@ If the code in a repository changes to include any {% data variables.product.pro After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. -If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. - ### Configuration options For existing configurations of default setup, you can edit: @@ -42,6 +40,12 @@ For existing configurations of default setup, you can edit: If your codebase depends on a library or framework that is not recognized by the standard libraries included with {% data variables.product.prodname_codeql %}, you can also extend the {% data variables.product.prodname_codeql %} coverage in default setup using {% data variables.product.prodname_codeql %} model packs. For more information, see [Extending CodeQL coverage with CodeQL model packs in default setup](/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup). +{% ifversion codeql-custom-properties %} + +Additional configuration options that are shared between all {% data variables.product.prodname_code_scanning %} setup types are available. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties). + +{% endif %} + ### Available runners You can use default setup for all {% data variables.product.prodname_codeql %}-supported languages on self-hosted runners or {% data variables.product.prodname_dotcom %}-hosted runners. @@ -60,7 +64,7 @@ Unless you have a specific use case, we recommend that you only assign runners w ## About advanced setup -Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to customize your {% data variables.product.prodname_code_scanning %}. You can set up {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_actions %} or an external continuous integration or continuous delivery/deployment (CI/CD) system. +If you need more granular control over your {% data variables.product.prodname_code_scanning %} configuration, you should instead configure advanced setup. Advanced setup for {% data variables.product.prodname_code_scanning %} is helpful when you need to customize your {% data variables.product.prodname_code_scanning %}. You can set up {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_actions %} or an external continuous integration or continuous delivery/deployment (CI/CD) system. {% data reusables.code-scanning.about-multiple-configurations-link %} diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md b/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md index 9034f06113f4..6193d19916f7 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md +++ b/content/code-security/how-tos/scan-code-for-vulnerabilities/configure-code-scanning/configuring-default-setup-for-code-scanning.md @@ -71,6 +71,17 @@ Your repository is eligible for default setup for {% data variables.product.prod > [!NOTE] > If you are switching to default setup from advanced setup, you will see a warning informing you that default setup will override existing {% data variables.product.prodname_code_scanning %} configurations. This warning means default setup will disable the existing workflow file and block any {% data variables.product.prodname_codeql %} analysis API uploads. +{% ifversion org-private-registry %} + +1. If projects in your repository depend on dependencies in private package registries, you can grant {% data variables.product.prodname_code_scanning %} access to them. This can improve the outcomes and quality of analyses. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/manage-usage-and-access/giving-org-access-private-registries). + +{% endif %} +{% ifversion codeql-custom-properties %} + +1. Optionally, adjust other configuration options which affect default setup. See [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties). + +{% endif %} + 1. Optionally, to view your default setup configuration after enablement, select {% octicon "kebab-horizontal" aria-label="Menu" %}, then click **{% octicon "gear" aria-hidden="true" aria-label="gear" %} View {% data variables.product.prodname_codeql %} configuration**. > [!NOTE] diff --git a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md b/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md index 3ddcc0cf4ec6..ae841fe3be98 100644 --- a/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md +++ b/content/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup.md @@ -15,9 +15,7 @@ redirect_from: contentType: how-tos --- -After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. For more information on setup types and customization options, see [AUTOTITLE](/code-security/concepts/code-scanning/setup-types). - -If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). +After running an initial analysis of your code with default setup, you can make changes to your configuration to better meet your needs. See [AUTOTITLE](/code-security/concepts/code-scanning/setup-types){% ifversion codeql-custom-properties %} and [AUTOTITLE](/code-security/concepts/code-scanning/repository-properties){% endif %}. ## Customizing your existing configuration of default setup @@ -90,3 +88,7 @@ For more information about {% data variables.product.prodname_codeql %} model pa ![Screenshot of the "Expand CodeQL analysis" view" in the settings for an organization.](/assets/images/help/security/enable-codeql-org-model-packs.png) 1. The model packs will be automatically detected and used when {% data variables.product.prodname_code_scanning %} runs on any repository in the organization with default setup enabled. + +## Further customization + +If you need to change any other aspects of your {% data variables.product.prodname_code_scanning %} configuration, consider configuring advanced setup. See [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning). diff --git a/data/features/codeql-custom-properties.yml b/data/features/codeql-custom-properties.yml new file mode 100644 index 000000000000..54aee91d6523 --- /dev/null +++ b/data/features/codeql-custom-properties.yml @@ -0,0 +1,5 @@ +# Allows the CodeQL Action to use repository properties. +versions: + fpt: '*' + ghec: '*' + ghes: '>= 3.21' From 44c42de35c9bed6083649e549ac37b900efe7cfe Mon Sep 17 00:00:00 2001 From: Yechan Bae Date: Mon, 16 Mar 2026 19:42:40 +0900 Subject: [PATCH 3/4] Fix typo in troubleshoot-copilot-cli-auth.md (#60237) Co-authored-by: hubwriter Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../set-up-copilot-cli/troubleshoot-copilot-cli-auth.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md index bf48eca06a62..a3f4d865cf93 100644 --- a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md +++ b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/troubleshoot-copilot-cli-auth.md @@ -169,10 +169,10 @@ On Linux, use the system keyring or store credentials in plaintext. command -v secret-tool ``` -1. If `secret-tool` is not found or the search command returns no results, install `libsecret` and its dependencies. +1. If `secret-tool` is not found or the search command returns no results, install `libsecret` and its dependencies. For example, on Debian and Ubuntu you could use the following command." ```bash copy - sudo apt sudo apt list libsecret-1-0 libsecret-1-dev libsecret-common gnome-keyring gnome-keyring-pkcs11 seahorse + sudo apt install libsecret-1-0 gnome-keyring seahorse ``` 1. Once `secret-tool` is installed, search the keyring for a saved credential: From a3b3c5f73d844f369c4c473b2ebb6c553c7e6f16 Mon Sep 17 00:00:00 2001 From: mc <42146119+mchammer01@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:45:42 +0000 Subject: [PATCH 4/4] [EDI] Viewing security insights (the return) (#60189) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Sam Browning <106113886+sabrowning1@users.noreply.github.com> --- .../about-security-overview.md | 19 +- .../viewing-security-insights.md | 261 +----------------- .../reference/security-at-scale/index.md | 1 + .../security-overview-dashboard-metrics.md | 231 ++++++++++++++++ 4 files changed, 255 insertions(+), 257 deletions(-) create mode 100644 content/code-security/reference/security-at-scale/security-overview-dashboard-metrics.md diff --git a/content/code-security/concepts/security-at-scale/about-security-overview.md b/content/code-security/concepts/security-at-scale/about-security-overview.md index b884eb39f4ff..75ca2ea41849 100644 --- a/content/code-security/concepts/security-at-scale/about-security-overview.md +++ b/content/code-security/concepts/security-at-scale/about-security-overview.md @@ -77,7 +77,7 @@ You can find security overview on the **Security** tab for any organization. Eac Security overview has multiple views that provide different ways to explore enablement and alert data. -* **Overview:** visualize trends in **Detection**, **Remediation**, and **Prevention** of security alerts, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights). +* **Overview:** visualize trends in **Detection**, **Remediation**, and **Prevention** of security alerts. For information about accessing and using the dashboard, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights). For detailed explanations of metrics and calculations, see [AUTOTITLE](/code-security/reference/security-at-scale/security-overview-dashboard-metrics). * **Risk and Alert views:** explore the risk from security alerts of all types or focus on a single alert type and identify your risk from specific vulnerable dependencies, code weaknesses, or leaked secrets, see [AUTOTITLE](/code-security/security-overview/assessing-code-security-risk). * **Coverage:** assess the adoption of security features across repositories in the organization, see [AUTOTITLE](/code-security/security-overview/assessing-adoption-code-security).{% ifversion ghas-products %}{% ifversion secret-risk-assessment %} * **Assessments:** regardless of the enablement status of {% data variables.product.prodname_AS %} features, organizations on {% data variables.product.prodname_team %} and {% data variables.product.prodname_enterprise %} can run a free report to scan the code in the organization for leaked secrets, see [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/about-secret-risk-assessment).{% endif %}{% endif %}{% ifversion security-campaigns %} @@ -95,7 +95,7 @@ You also create and manage security campaigns to remediate alerts from security You can find security overview on the **Security** tab for your enterprise. Each page displays aggregated and repository-specific security information for your enterprise. -As with security overview for organizations, security overview for enterprises has multiple views that provide different ways to explore data. +Security overview for enterprises has multiple views that provide different ways to explore data, including an overview dashboard that visualizes alert trends. For information about the dashboard, see [AUTOTITLE](/code-security/security-overview/viewing-security-insights) and [AUTOTITLE](/code-security/reference/security-at-scale/security-overview-dashboard-metrics). ## Access to data in security overview @@ -111,6 +111,21 @@ Security overview displays data only for repositories you have permission to vie For detailed, role-by-role permission information, including which views are available and how repository access affects visibility, see [AUTOTITLE](/code-security/reference/permissions/security-overview-permissions). +## Understanding dashboard data accuracy + +The overview dashboard displays metrics based on the current state of your repositories and the historical state of security alerts. This data model has important implications for data consistency: + +**Data changes over time:** Dashboard metrics can change for the same historical time period when viewed at different times. This occurs when repositories are deleted, security advisories are modified, or other changes affect the underlying data. If you need consistent data for compliance reports or auditing purposes, use the audit log instead. See [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). + +**Alert data is historical; repository attributes are current:** The dashboard tracks security alerts based on their historical state during the selected time period. However, repository filters (such as archived/active status) reflect the _current state_ of repositories. + +For example, if you archive a repository today, any open alerts in that repository are automatically closed. If you then view the overview dashboard for last week: + +* The repository only appears when you filter to show archived repositories (its current state) +* The alerts from that repository appear as open (their state during last week) + +This design ensures alert trends accurately reflect security activity during the time period you're analyzing, while repository filters help you focus on your current repository structure. + ## Further reading * [AUTOTITLE](/code-security/getting-started/securing-your-repository){% ifversion fpt or ghec %} diff --git a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/viewing-security-insights.md b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/viewing-security-insights.md index b782e1812e5f..01133e5fcf40 100644 --- a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/viewing-security-insights.md +++ b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/viewing-security-insights.md @@ -1,7 +1,7 @@ --- title: Viewing security insights shortTitle: View security insights -intro: You can use the overview dashboard in security overview to monitor the security landscape of the repositories in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. +intro: Monitor your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %} security posture, identify high-risk repositories, and track alert remediation progress using the overview dashboard in security overview. permissions: '{% data reusables.permissions.security-overview %}' product: '{% data reusables.gated-features.security-overview-fpt-both %}' versions: @@ -21,50 +21,12 @@ redirect_from: allowTitleToDifferFromFilename: true --- -## {% ifversion security-overview-dashboard-enterprise %}About security insights{% else %} About organization-level security insights{% endif %} - -The overview page in security overview is a consolidated dashboard of insights about your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}'s security landscape and progress. You can use the dashboard to monitor the health of your application security program, collaborate with engineering teams, and gather data for benchmarking purposes. - -{% ifversion security-overview-dashboard-enterprise %} -Both the enterprise and organization-level security overviews have a dashboard. By default, the enterprise-level dashboard shows metrics for all the repositories in your enterprise. You can filter the data shown on the enterprise-level dashboard by owner (for example, by organization). By default, the organization-level dashboard shows metrics for all repositories owned by your organization. Both dashboards also allow you to filter by repository. -{% endif %} - -You can view a variety of metrics about the security alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. The dashboard displays trending data that tracks alert counts and activity over time, as well as snapshot data that reflects the current state. - -{% ifversion security-overview-3-tab-dashboard %} -The dashboard is divided into three tabs, each focused around a different security goal: -* **Detection:** this tab shows metrics about the status and age of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}, the secrets that have been blocked or bypassed, and the top repositories and vulnerabilities that pose the highest potential security risk. -* **Remediation:** this tab shows metrics about how alerts are resolved and alert activity over time. -* **Prevention:** this tab shows metrics about how vulnerabilities have been prevented and fixed. - ->[!NOTE] -> Unlike the **Detection** and **Remediation** tabs which report alerts on the default branch, the **Prevention** tab gives you insights for {% data variables.product.prodname_codeql %} alerts found in merged pull requests. - -{% else %} -* The top section of the dashboard shows information about the status and age of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}, as well as data about secrets that have been blocked or bypassed. -* The "Remediation" section shows information about how alerts are resolved and alert activity over time. -* The "Impact analysis" section shows the repositories that pose the highest potential security risk in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. -{% endif %} - -You can filter the overview dashboard by selecting a specific time period, and apply additional filters to focus on narrower areas of interest. All data and metrics across the dashboard will change as you apply filters. By default, the dashboard displays all alerts from {% data variables.product.prodname_dotcom %} tools, but you can use the tool filter to show alerts from a specific tool ({% data variables.product.prodname_secret_scanning %}, {% data variables.product.prodname_dependabot %}, {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_codeql %}, a specific third-party tool) or all third-party {% data variables.product.prodname_code_scanning %} tools. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). +The overview page in security overview provides a consolidated dashboard of your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}'s security landscape. You can filter the dashboard by time period, tool, and other criteria to focus on specific areas of interest. For more information about the overview dashboard, available metrics, and access permissions, see [AUTOTITLE](/code-security/concepts/security-at-scale/about-security-overview). {% ifversion security-overview-export-data %} -You can download a CSV file of the overview dashboard data for your organization or enterprise. This data file can integrate easily with external datasets, so you may find it useful for security research, data analysis, and more. For more information, see [AUTOTITLE](/code-security/security-overview/exporting-data-from-security-overview). -{% endif %} - -{% ifversion security-overview-dashboard-enterprise %}Enterprise members can access the overview page for organizations in their enterprise. {% endif %}The metrics you see will depend on your role and repository permissions. For more information, see [AUTOTITLE](/code-security/security-overview/about-security-overview#permission-to-view-data-in-security-overview). - -{% ifversion secret-risk-assessment %} - -> [!TIP] If you're interested in assessing your organization's exposure to secret leaks specifically, you can run a free {% data variables.product.prodname_secret_risk_assessment %} on {% data variables.product.github %}. The resulting report gives you aggregate insights on public leaks, private exposures, and token types, as well as provides you with actionable steps to strengthen your security and protect your code. See [AUTOTITLE](/code-security/securing-your-organization/understanding-your-organizations-exposure-to-leaked-secrets/about-secret-risk-assessment). - +You can download a CSV file of the overview dashboard data for your organization or enterprise. For more information, see [AUTOTITLE](/code-security/how-tos/view-and-interpret-data/analyze-organization-data/exporting-data-from-security-overview). {% endif %} -### Limitations - -The data that populates the overview page can and will change over time due to various factors, such as repository deletion or modifications to a security advisory. This means that the overview metrics for the same time period could vary if viewed at two different times. For compliance reports or other scenarios where data consistency is crucial, we recommend that you source data from the audit log. For more information, see [AUTOTITLE](/code-security/getting-started/auditing-security-alerts). - -Keep in mind that the overview page tracks changes over time for security alert data only. If you filter the page by non-alert attributes, such as repository status, the data you see will reflect the current state of those attributes, instead of the historical state. For example, consider that you archived a repository that contains open security alerts, an action which closes the alerts. If you then view the overview page for the week before you archived the repository, the alert data for the repository will only appear when you filter to show data from archived repositories, because the current state of the repository is archived. However, the alerts will appear as open, since they were open during that time period and the overview page tracks the historical state of alerts. {% data reusables.security-overview.alert-differences %} @@ -89,219 +51,8 @@ Keep in mind that the overview page tracks changes over time for security alert {% endif %} -## Understanding the overview dashboard - -{% ifversion security-overview-3-tab-dashboard %} - - -* [Detection tab](#detection-tab) -* [Remediation tab](#remediation-tab) -* [Prevention tab](#prevention-tab) - -Some metrics in the security overview dashboard include a trend indicator, which shows the percentage gain or loss for the chosen time period relative to previous period. For example, when you select a week with 10 alerts, if the previous week had 20 alerts, the trend indicator reports that the metric has dropped by 50%. If the average age of the open alerts is 15 days, and for the previous period it was 5 days, the trend indicator reports that the metric has risen by 200%. - ->[!NOTE] -> The number of alerts shown on the security overview dashboard may not match the number of {% data variables.product.prodname_code_scanning %} alerts. The security overview dashboard focuses on the security landscape of your organization, and only includes alerts with a security severity ("Critical," "High," "Medium," or "Low"), but {% data variables.product.prodname_codeql %} and third-party tools may separately produce non-security alerts with a level of "Error," "Warning," or "Note." For more information about alert severity and security severity levels in {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). - -### Detection tab - -* [Open alerts over time](#open-alerts-over-time) -* [Age of alerts](#age-of-alerts) -* [Reopened alerts](#reopened-alerts) -* [Secrets bypassed or blocked](#secrets-bypassed-or-blocked) -* [Impact analysis table](#impact-analysis-table) - -#### Open alerts over time - -The "Open alerts over time" graph shows the change in the number of open alerts in your organization or enterprise over the time period you have chosen. By default, alerts are grouped by severity. You can change the way alerts are grouped. - -Open alerts include both newly created and existing open security alerts. New alerts are represented on their creation date, while alerts that existed before the chosen time period are represented at the start of the period. Once an alert is remediated or dismissed, it is not included in the graph. Instead, the alert will move to the closed alerts graph. - -#### Age of alerts - -The "Age of alerts" metric is the average age of all alerts that are still open at the end of the chosen time period. - -The age of each open alert is calculated by subtracting the date the alert was created from the date that the chosen time period ends. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -#### Reopened alerts - -The "Reopened alerts" metric is the total open alerts that were reopened during the chosen time period. Only alerts that are open at the end of the reporting period are reported. This includes: - -* Alerts that were closed as of the day before the chosen time period, and that remain open at the end of the period. -* Newly created alerts that were closed, and then reopened, during the chosen time period. -* Alerts that were open at the start of the chosen time period, but closed and then reopened within the same period. - -#### Secrets bypassed or blocked - -The "Secrets bypassed" metric shows the ratio of secrets bypassed to the total secrets blocked by push protection. - -You can also see how many secrets were successfully blocked, which is calculated by subtracting the number of secrets bypassed from the total number of secrets blocked by push protection. A secret is considered to have been successfully blocked when it has been corrected, and not committed to the repository. - -You can click **View details** to view the {% data variables.product.prodname_secret_scanning %} report with the same filters and time period selected. - -For more information on {% data variables.product.prodname_secret_scanning %} push protection metrics, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -#### Impact analysis table - -The impact analysis table has separate tabs showing data for: "Repositories," "Advisories," and "SAST vulnerabilities." - -* The "Repositories" tab shows the top 10 repositories with the most open alerts at the end of the chosen time period, ranked by the total number of open alerts. For each repository, the total number of open alerts is shown alongside a breakdown by severity. - -* The "Advisories" tab shows the 10 CVE advisories that triggered the most {% data variables.product.prodname_dependabot %} alerts at the end of the chosen time period, ranked by the total number of open alerts. For each advisory, the total number of open alerts is shown alongside a severity rating. - -* The "SAST vulnerabilities" tab shows the 10 static application security testing (SAST) vulnerabilities that triggered the most {% data variables.product.prodname_code_scanning %} alerts, ranked by the total number of open alerts. For each vulnerability, the total number of open alerts is shown alongside a severity rating. - -### Remediation tab - -* [Closed alerts over time](#closed-alerts-over-time) -* [Mean time to remediate](#mean-time-to-remediate) -* [Net resolve rate](#net-resolve-rate) -* [Alert activity graph](#alert-activity-graph) - -#### Closed alerts over time - -The "Closed alerts over time" graph shows the change in the number of closed alerts in your organization or enterprise over the time period you have chosen. By default, alerts are grouped by severity. You can change the way alerts are grouped. - -Closed alerts include security alerts that have been successfully remediated or dismissed prior to or during the chosen time period. Alerts closed during the time period are represented on the graph on their closed date, while alerts remediated or dismissed before the chosen time period are represented at the start of the period. - -#### Mean time to remediate - -The "Mean time to remediate" metric is the average age of all alerts that were remediated or dismissed in the chosen time period. Alerts that were closed as "false positive" are excluded. - -The age of each closed alert is calculated by subtracting the date the alert was created from the date that the alert was last closed during the chosen time period. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -#### Net resolve rate - -The "Net resolve rate" metric is the rate at which alerts are being closed. This metric is similar to measuring "developer velocity," reflecting the speed and efficiency with which alerts are resolved. - -The rate is calculated by dividing the number of alerts that were closed and remained closed during the chosen time period, by the number of alerts created during the time period. - ->[!NOTE] The net resolve rate takes into account any new and any closed alerts during the chosen time period. This means that the set of new alerts and set of closed alerts used for the calculation do not necessarily correspond, since they may represent different populations of alerts. - -Alerts that are reopened and re-closed during the chosen time period are ignored. - -#### Alert activity graph - -Expanding on the alert trends graph, the alert activity graph shows you alert inflows and outflows over your chosen time period. - -Green bars represent the number of new alerts created during the segmented time period. Purple bars represent the number of alerts that were closed during the segmented time period. The blue dotted line represents the net alert activity, which is the difference between new and closed alerts. - -### Prevention tab - ->[!NOTE] -> Unlike the **Detection** and **Remediation** tabs which report alerts on the default branch, the **Prevention** tab gives you insights for {% data variables.product.prodname_codeql %} alerts found in merged pull requests. - -* [Introduced versus prevented](#introduced-versus-prevented) -* [Vulnerabilities fixed in pull requests](#vulnerabilities-fixed-in-pull-requests){% ifversion code-scanning-autofix %} -* [{% data variables.copilot.copilot_autofix_short %} suggestions](##pull-request-alerts-fixed-with-copilot-autofix-suggestions){% endif %} - -#### Introduced versus prevented - -The "Introduced versus Prevented" graph shows the cumulative number of vulnerabilities that were caught in the developer workflow versus the vulnerabilities introduced in your organization or enterprise over the time period you have chosen. Prevented vulnerabilities are defined as the count of pull request alerts detected by {% data variables.product.prodname_codeql %} that have been fixed for merged pull requests. Introduced vulnerabilities are the count of new pull request alerts detected by {% data variables.product.prodname_codeql %} that were dismissed as "Risk accepted" or were unresolved at the time the pull request was merged. - -The dates for prevented alerts are based on the date the alerts were fixed, and the dates for introduced alerts are based on the date the alerts were created. - -#### Vulnerabilities fixed in pull requests - -The "Vulnerabilities fixed in pull requests" metric shows the count of pull request alerts detected by {% data variables.product.prodname_codeql %} or {% data variables.product.prodname_secret_scanning %} with a close reason of "Fixed" that are tied to a merged pull request. - -{% ifversion code-scanning-autofix %} - -#### Pull request alerts fixed with {% data variables.copilot.copilot_autofix_short %} suggestions - -{% data variables.copilot.copilot_autofix %} for {% data variables.product.prodname_code_scanning %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -The "Pull request alerts fixed with autofix suggestions" metric shows the ratio of accepted {% data variables.copilot.copilot_autofix_short %} suggestions to the total number of {% data variables.copilot.copilot_autofix_short %} suggestions on pull request alerts detected by {% data variables.product.prodname_code_scanning %}. - -{% endif %} - -{% else %} - - -* [Alert trends graph](#alert-trends-graph) -* [Age of alerts](#age-of-alerts) -* [Secrets bypassed or blocked](#secrets-bypassed-or-blocked) -* [Mean time to remediate](#mean-time-to-remediate) -* [Net resolve rate](#net-resolve-rate) -* [Alert activity graph](#alert-activity-graph) -* [Impact analysis table](#impact-analysis-table) -* [Reopened alerts](#reopened-alerts) - -Some metrics in the security overview dashboard include a trend indicator, which shows the percentage gain or loss for the chosen time period relative to previous period. For example, when you select a week with 10 alerts, if the previous week had 20 alerts, the trend indicator reports that the metric has dropped by 50%. If the average age of the open alerts is 15 days, and for the previous period it was 5 days, the trend indicator reports that the metric has risen by 200%. - ->[!NOTE] -> The number of alerts shown on the security overview dashboard may not match the number of {% data variables.product.prodname_code_scanning %} alerts. The security overview dashboard focuses on the security posture of your organization, and only includes alerts with a security severity ("Critical," "High," "Medium," or "Low"), but {% data variables.product.prodname_codeql %} and third-party tools may separately produce alerts with a level of "Error," "Warning," or "Note." For more information about alert severity and security severity levels in {% data variables.product.prodname_code_scanning %}, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). - -### Alert trends graph - -The alert trends graph shows the change in the number of alerts in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %} over the time period you have chosen. By default, alerts are grouped by severity. You can toggle the graph between open and closed alerts and change the way alerts are grouped. - -Open alerts include both newly created and existing open security alerts. New alerts are represented on their creation date, while alerts that existed before the chosen time period are represented at the start of the period. Once an alert is remediated or dismissed, it is not included in the graph. Instead, the alert will move to the closed alerts graph. - -Closed alerts include security alerts that have been successfully remediated or dismissed prior to or during the chosen time period. Alerts closed during the time period are represented on the graph on their closed date, while alerts remediated or dismissed before the chosen time period are represented at the start of the period. - -### Age of alerts - -The "Age of alerts" metric is the average age of all alerts that are still open at the end of the chosen time period. - -The age of each open alert is calculated by subtracting the date the alert was created from the date that the chosen time period ends. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -### Reopened alerts - -The "Reopened alerts" metric is the total open alerts that were reopened during the chosen time period. Only alerts that are open at the end of the reporting period are reported. This includes: - -* Alerts that were closed as of the day before the chosen time period, and that remain open at the end of the period. -* Newly created alerts that were closed, and then reopened, during the chosen time period. -* Alerts that were open at the start of the chosen time period, but closed and then reopened within the same period. - -### Secrets bypassed or blocked - -The "Secrets bypassed / blocked" metric shows the ratio of secrets bypassed to the total secrets blocked by push protection. - -You can also see how many secrets were successfully blocked, which is calculated by subtracting the number of secrets bypassed from the total number of secrets blocked by push protection. A secret is considered to have been successfully blocked when it has been corrected, and not committed to the repository. - -You can click **View details** to view the {% data variables.product.prodname_secret_scanning %} report with the same filters and time period selected. - -For more information on secret scanning push protection metrics, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). - -### Mean time to remediate - -The "Mean time to remediate" metric is the average age of all alerts that were remediated or dismissed in the chosen time period. Alerts that were closed as "false positive" are excluded. - -The age of each closed alert is calculated by subtracting the date the alert was created from the date that the alert was last closed during the chosen time period. For reopened alerts, the age is calculated by subtracting the original created date rather than the date the alert was reopened. - -### Net resolve rate - -The "Net resolve rate" metric is the rate at which alerts are being closed. This metric is similar to measuring "developer velocity," reflecting the speed and efficiency with which alerts are resolved. - -The rate is calculated by dividing the number of alerts that were closed and remained closed during the chosen time period, by the number of alerts created during the time period. - ->[!NOTE] The net resolve rate takes into account any new and any closed alerts during the chosen time period. This means that the set of new alerts and set of closed alerts used for the calculation do not necessarily correspond, since they may represent different populations of alerts. - -Alerts that are reopened and re-closed during the chosen time period are ignored. - -{% ifversion code-scanning-autofix %} - -### {% data variables.copilot.copilot_autofix_short %} suggestions - -{% data variables.copilot.copilot_autofix %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts (including {% data variables.product.prodname_codeql %} alerts). For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). - -The "{% data variables.copilot.copilot_autofix_short %} suggestions" metric is the total number of {% data variables.copilot.copilot_autofix_short %} suggestions generated in open and closed pull requests during the chosen time period. - -{% endif %} - -### Alert activity graph - -Expanding on the alert trends graph, the alert activity graph shows you alert inflows and outflows over your chosen time period. - -Green bars represent the number of new alerts created during the segmented time period. Purple bars represent the number of alerts that were closed during the segmented time period. The blue dotted line represents the net alert activity, which is the difference between new and closed alerts. - -### Impact analysis table +## Next steps -The impact analysis table has separate tabs showing data for: "Repositories" and "Advisories." +The dashboard displays metrics about alert status, remediation velocity, and high-risk repositories in your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. For detailed explanations of each metric and how it's calculated, see [AUTOTITLE](/code-security/reference/security-at-scale/security-overview-dashboard-metrics). -* The "Repositories" tab shows the top 10 repositories with the most open alerts at the end of the chosen time period, ranked by the total number of open alerts. For each repository, the total number of open alerts is shown alongside a breakdown by severity. - -* The "Advisories" tab shows the 10 CVE advisories that triggered the most {% data variables.product.prodname_dependabot %} alerts at the end of the chosen time period, ranked by the total number of open alerts. For each advisory, the total number of open alerts is shown alongside a severity rating. - -{% endif %} +You can filter the dashboard by time period, tool, repository, and other criteria. For more information, see [AUTOTITLE](/code-security/security-overview/filtering-alerts-in-security-overview). diff --git a/content/code-security/reference/security-at-scale/index.md b/content/code-security/reference/security-at-scale/index.md index dc771849d2e7..db2712d994a7 100644 --- a/content/code-security/reference/security-at-scale/index.md +++ b/content/code-security/reference/security-at-scale/index.md @@ -15,6 +15,7 @@ topics: - Enterprise contentType: reference children: + - /security-overview-dashboard-metrics - /available-filters-for-security-overview - /security-configuration-enforcement - /troubleshoot-security-configurations diff --git a/content/code-security/reference/security-at-scale/security-overview-dashboard-metrics.md b/content/code-security/reference/security-at-scale/security-overview-dashboard-metrics.md new file mode 100644 index 000000000000..ed67859ff6d4 --- /dev/null +++ b/content/code-security/reference/security-at-scale/security-overview-dashboard-metrics.md @@ -0,0 +1,231 @@ +--- +title: Security overview dashboard metrics +intro: Detailed explanations of metrics, calculations, and data visualizations on the overview page of your security overview. +versions: + fpt: '*' + ghec: '*' + ghes: '*' +contentType: reference +--- + +## Dashboard metrics + +The overview dashboard of security overview displays security alert metrics for your organization{% ifversion security-overview-dashboard-enterprise %} or enterprise{% endif %}. + +**Trend indicators** show percentage change compared to the previous period. For example: +* 10 alerts this week vs. 20 alerts last week = 50% decrease +* An average alert age of 15 days vs. 5 days = 200% increase + +**Alert severity filtering:** The dashboard only includes alerts with security severity levels: `Critical`, `High`, `Medium`, or `Low`. Non-security alerts (`Error`, `Warning`, or `Note`) are excluded. This may cause the dashboard count to differ from {% data variables.product.prodname_code_scanning %} alert totals. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alert-severity-and-security-severity-levels). + +{% ifversion security-overview-3-tab-dashboard %} + + +## Dashboard structure + +The **Detection** tab includes information on: +* Alert status and age +* Secrets blocked or bypassed +* High-risk repositories and vulnerabilities + +The **Remediation** tab includes information on: +* How alerts are resolved +* Alert activity over time + +The **Prevention** tab includes information on: +* Vulnerabilities prevented and fixed in pull requests +* {% data variables.product.prodname_codeql %} alerts in merged pull requests (not on the default branch) + +{% endif %} + +## Detection metrics + +{% ifversion security-overview-3-tab-dashboard %}Track the current state of security alerts.{% else %}Track current state and trends of security alerts.{% endif %} + +### Open alerts over time + +{% ifversion security-overview-3-tab-dashboard %}Shows{% else %}Graph showing{% endif %} the number of open alerts over time. + +**Included** +* New alerts (shown on creation date) +* Existing open alerts (shown at start of period) + +**Excluded** +* Remediated or dismissed alerts + +**Default grouping:** Alert severity + +### Age of alerts + +Average age of alerts still open at the end of the time period. + +**Formula:** (Period end date - Alert creation date) averaged across all open alerts + +**Note:** Reopened alerts use the original creation date, not the reopen date + +### Reopened alerts + +Total open alerts that were reopened during the time period. + +**Counted if:** +* Closed before the period and still open at period end +* Created, closed, and reopened during the period +* Open at period start, closed, then reopened during the period + +**Requirement:** Must be open at the end of the reporting period. + +### Secrets bypassed or blocked + +Ratio of secrets bypassed to total secrets blocked by push protection. + +**Metrics** +* **Bypassed:** Detected secrets that were committed anyway +* **Successfully blocked:** Total blocked minus bypassed + +**View details:** Click to see the {% data variables.product.prodname_secret_scanning %} report with matching filters. + +For more information, see [AUTOTITLE](/code-security/security-overview/viewing-metrics-for-secret-scanning-push-protection). + +{% ifversion security-overview-3-tab-dashboard %} + +### Impact analysis table + +Shows repositories and vulnerabilities with the highest security risk. + +**Repositories tab** +* Top 10 repositories by open alert count +* Total alerts and severity breakdown + +**Advisories tab** +* Top 10 CVE advisories by alert count +* {% data variables.product.prodname_dependabot %} alerts only + +**SAST vulnerabilities tab** +* Top 10 Static Application Security Testing (SAST) vulnerabilities +* {% data variables.product.prodname_dependabot_alerts %} only + +{% else %} + +### Alert trends graph + +Graph showing alert count changes over time. Toggle between open and closed alerts. + +**Open alerts** +* New alerts (shown on creation date) +* Existing alerts (shown at start of period) + +**Closed alerts** +* Alerts closed during period (shown on close date) +* Alerts closed before period (shown at start of period) + +**Default grouping:** Alert severity + +### Impact analysis table + +Shows repositories and advisories with the highest security risk. + +**Repositories tab** +* Top 10 repositories by open alert count +* Total alerts and severity breakdown + +**Advisories tab** +* Top 10 CVE advisories by alert count +* {% data variables.product.prodname_dependabot_alerts %} only + +{% endif %} + +## Remediation metrics + +Track how quickly and effectively alerts are resolved. + +### Closed alerts over time + +Graph showing the number of closed alerts over time. + +**Included** +* Alerts closed during period (shown on close date) +* Alerts closed before period (shown at start of period) + +**Default grouping:** Alert severity + +### Mean time to remediate + +Average age of alerts remediated or dismissed during the time period. + +**Formula:** (Alert close date - Alert creation date) averaged across all closed alerts + +**Excluded:** Alerts closed as "false positive" + +>[!NOTE] +> Reopened alerts use the original creation date, not the reopen date. + +### Net resolve rate + +Rate at which alerts are being closed (measures resolution velocity). + +**Formula:** Closed alerts (that stayed closed) รท New alerts created + +**Important:** Uses all new and closed alerts in the period. These may be different alert populations. + +**Excluded:** Alerts reopened and re-closed during the period. + +### Alert activity graph + +Shows alert inflows and outflows over time. + +**Visual key** +* **Green bars:** New alerts created +* **Purple bars:** Alerts closed +* **Blue line:** Net activity (new minus closed) + +{% ifversion security-overview-3-tab-dashboard %} + +## Prevention metrics + +Track vulnerabilities caught and fixed before reaching production. + +**Data source:** {% data variables.product.prodname_codeql %} alerts in merged pull requests (not on the default branch) + +### Introduced versus prevented + +Cumulative vulnerabilities caught versus introduced. + +**Prevented** +* Pull request alerts fixed before merge +* Detected by {% data variables.product.prodname_codeql %} +* Dates based on fix date + +**Introduced** +* New pull request alerts dismissed as "Risk accepted" or unresolved at merge +* Detected by {% data variables.product.prodname_codeql %} +* Dates based on creation date + +### Vulnerabilities fixed in pull requests + +Count of pull request alerts with close reason "Fixed" in merged pull requests. + +**Alert types:** {% data variables.product.prodname_codeql %} or {% data variables.product.prodname_secret_scanning %} + +{% ifversion code-scanning-autofix %} + +### Pull request alerts fixed with {% data variables.copilot.copilot_autofix_short %} suggestions + +Ratio of accepted to total {% data variables.copilot.copilot_autofix_short %} suggestions on pull request alerts. + +**{% data variables.copilot.copilot_autofix_short %}** provides targeted fix recommendations for {% data variables.product.prodname_code_scanning %} alerts. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). + +{% endif %} + +{% else %} + +{% ifversion code-scanning-autofix %} + +## {% data variables.copilot.copilot_autofix_short %} suggestions + +Total {% data variables.copilot.copilot_autofix_short %} suggestions generated in open and closed pull requests during the time period. + +**{% data variables.copilot.copilot_autofix_short %}** provides targeted fix recommendations for {% data variables.product.prodname_code_scanning %} alerts (including {% data variables.product.prodname_codeql %} alerts). For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning). + +{% endif %} + +{% endif %} \ No newline at end of file