diff --git a/content/en/security/code_security/software_composition_analysis/_index.md b/content/en/security/code_security/software_composition_analysis/_index.md index bded2847dd4..a0180fa97a4 100644 --- a/content/en/security/code_security/software_composition_analysis/_index.md +++ b/content/en/security/code_security/software_composition_analysis/_index.md @@ -11,6 +11,18 @@ further_reading: - link: https://www.datadoghq.com/blog/code-security-secret-scanning tag: Blog text: Detect and block exposed credentials with Datadog Secret Scanning + - link: /security/code_security/software_composition_analysis/setup_static/ + tag: Documentation + text: Set up Static SCA + - link: /security/code_security/software_composition_analysis/setup_runtime/ + tag: Documentation + text: Set up Runtime SCA + - link: /security/code_security/software_composition_analysis/library_inventory + tag: Documentation + text: Library Inventory + - link: /pr_gates/ + tag: Documentation + text: PR Gates --- ## Overview @@ -22,28 +34,25 @@ Using Software Composition Analysis provides organizations with the following be - Risk-based prioritization and remediation based on runtime detection of vulnerabilities - Identification of malicious packages, end-of-life libraries, and library riskiness based on OpenSSF standards -Datadog SCA uses a curated proprietary database. The database is sourced from Open Source Vulnerabilities (OSV), National Vulnerability Database (NVD), GitHub advisories, and other language ecosystem advisories, as well as Datadog's own Security Research team's findings. There is a maximum of 2 hours between when a new vulnerability is published and when it appears in Datadog, with emerging vulnerabilities typically appearing in Datadog within minutes. +## How it works -## SCA language support +SCA supports two complementary detection modes: +- **Static detection** scans your repositories by analyzing dependency files (lockfiles and manifests). Scans run when changes are committed that update supported dependency manifests/lockfiles in an enabled repository. You can also run SCA in your CI/CD pipeline (CI jobs are supported on push event triggers). See [Set up Static SCA][1] to get started. +- **Runtime detection** identifies libraries that are actually loaded and used by your services at runtime, using instrumentation from Datadog APM. See [Set up Runtime SCA][2] to get started. -Software Composition Analysis (SCA) supports the following languages: +Datadog SCA uses a curated proprietary database. The database is sourced from Open Source Vulnerabilities (OSV), National Vulnerability Database (NVD), GitHub advisories, and other language ecosystem advisories, as well as Datadog's own Security Research team's findings. There is a maximum of 2 hours between when a new vulnerability is published and when it appears in Datadog, with emerging vulnerabilities typically appearing in Datadog within minutes. -{{< partial name="code_security/sca-lang-support.html" >}} +When Datadog ingests a new advisory, it is matched against your last known library inventory and appears in the Vulnerabilities Explorer even if you have not rescanned the repository. The Repositories Explorer is commit-scoped and reflects what was known at the time the scan ran—so a scan that executed before Datadog ingested the advisory will not show that newly published advisory in the Repositories Explorer for that commit. See [Understanding SCA views](#understanding-sca-views) for more details. -For steps on setting up SCA for your language, see [Set up SCA][15]. +## Key capabilities -## Set up SCA +### Review and prioritize vulnerabilities -SCA supports both static and runtime dependency detection: -- For **static detection**, you can scan your repositories from your CI/CD pipelines or directly from Datadog's infrastructure. See [static setup][1] to get started. -- For **runtime detection**, you can enable SCA on services instrumented with Datadog APM. See [runtime setup][2] to get started. +The [Vulnerabilities Explorer][11] provides a vulnerability-centric view of library vulnerabilities detected by SCA, alongside vulnerabilities detected by other Code Security capabilities (SAST, IAST, Secrets Scanning, and IaC). All vulnerabilities in the explorer are either detected on the default branch at the last commit of a scanned repository, or are affecting a running service. -## Search and filter results -### Vulnerabilities explorer -The [Vulnerabilities][11] explorer provides a vulnerability-centric view of library vulnerabilities detected by SCA, alongside vulnerabilities detected by other Code Security capabilities (SAST and IAST). All vulnerabilities in the explorer are either detected on the default branch at the last commit of a scanned repository, or are affecting a running service. +#### Datadog severity score -### Datadog severity score -Each vulnerability begins with a base CVSS score. To assist in prioritizing remediation, Datadog modifies the base CVSS score into the Datadog Severity Score by incorporating runtime context and exploitability signals. These factors help distinguish theoretical risk from vulnerabilities that are more likely to be exploited in real-world environments. The table below describes how each factor influences the final score. +To assist in prioritizing remediation, Datadog modifies the base CVSS score into the **Datadog Severity Score** by incorporating runtime context and exploitability signals. These factors help distinguish theoretical risk from vulnerabilities that are more likely to be exploited in real-world environments. The table below describes how each factor influences the final score. | Risk factor | How it is evaluated | Impact on the score | |-----------------------------------|----------------------------------------------------------------------|--------------------------------------------------------| @@ -54,14 +63,15 @@ Each vulnerability begins with a base CVSS score. To assist in prioritizing reme | Exploit availability | Availability of public exploits for the vulnerability. | Decreased if no exploit is available. | | Exploitation probability (EPSS) | Likelihood of real-world exploitation based on EPSS data. | Decreased when the probability of exploitation is low. | -### Repositories explorer -The [Repositories][12] explorer provides a repository-centric view of all scan results across Static Code Analysis (SAST) and Software Composition Analysis (SCA). Click on a repository to analyze **Library Vulnerabilities** and **Library Catalog** results from SCA scoped to your chosen branch and commit. +### View findings by repository + +The [Repositories Explorer][12] provides a repository-centric view of all scan results across Static Code Analysis (SAST), Software Composition Analysis (SCA), Secrets Scanning, and Infrastructure as Code (IaC). Click on a repository to analyze **Library Vulnerabilities** and **Library Catalog** results from SCA scoped to your chosen branch and commit. * The **Library Vulnerabilities** tab contains the vulnerable library versions found by Datadog SCA * The **Library Catalog** tab contains all of the libraries (vulnerable or not) found by Datadog SCA. Recommended steps for remediating detected vulnerabilities can be found in the side panel for each vulnerability in SCA. Steps are provided for upgrading the library to the safest (non-vulnerable) version, as well as the closest version. -To filter your results, use the facets to the left of the list or the search bar at the top. Results can be filtered by service or team facets. For more information about how results are linked to Datadog services and teams, see [Getting Started with Code Security][5]. +To filter your results, use the facets to the left of the list or the search bar at the top. Results can be filtered by service or team facets. For more information about how results are linked to Datadog services and teams, see [Link findings to Datadog services and teams][18]. Every row represents a unique library and version combination. Each combination is associated with the specific commit and branch that is selected in the filters at the top of the page (by default, the latest commit on the default branch of the repository you selected). @@ -69,7 +79,17 @@ Click on a library with a vulnerability to open a side panel that contains infor -### Library inventory +### Automatically block risky changes with PR Gates + +Use [PR Gates][16] to enforce security standards on open source library usage before changes are merged. Datadog scans the dependencies introduced in each pull request, identifies any vulnerabilities or license violations above your configured severity threshold, and reports a pass or fail status to GitHub or Azure DevOps. + +You can configure PR Gates to block on: +- **Security vulnerabilities**: libraries with known CVEs above a configured severity threshold. +- **License violations**: libraries using licenses that do not comply with your organization's policy. + +PR Gates marks a PR check as failed only if the developer **introduces a new violation as part of that PR**—existing violations already present in the codebase before the PR and its branch were created do not cause the check to fail. By default, failed checks are informational and do not block merging, but you can configure them as blocking in GitHub or Azure DevOps to prevent merging when critical issues are detected. For setup instructions, see [Set up PR Gate Rules][17]. + +### Manage your library inventory The [Library Inventory][8] provides visibility into the third-party libraries detected across your codebase. Datadog collects this information from: @@ -81,12 +101,25 @@ Use the Library Inventory to understand which dependencies you rely on, where th To learn more about how the inventory is generated, how Static and Runtime data differ, and how to interpret the library details (usage, vulnerabilities, licenses, versions, and OpenSSF score), see [Library Inventory][14]. ### Library vulnerability context in APM -SCA enriches the information Application Performance Monitoring (APM) is already collecting by flagging libraries that match with current vulnerability advisories. Potentially vulnerable services are highlighted directly in the **Security** view embedded in the [APM Software Catalog][10]. -- Whether it is reaching end of life -- Whether it is a malicious package -- The health of this library version based on its OpenSSF scorecard breakdown -- Software supply chain & Software Bill of Materials (SBOM) management +SCA enriches the information Application Performance Monitoring (APM) is already collecting by flagging libraries that match against current vulnerability advisories. Potentially vulnerable services are highlighted directly in the **Security** view embedded in the [APM Software Catalog][10]. + +## Understanding SCA views + +The Repositories Explorer and Vulnerabilities Explorer serve complementary but distinct purposes. + +**Repositories Explorer** reflects a **point-in-time snapshot** of the libraries and vulnerabilities detected at the time of the scan. It shows which libraries were present in a given repository at a specific commit, along with any vulnerabilities that were known at scan time. This view does not update retroactively if new advisories are published after the scan runs. + +**Vulnerabilities Explorer** provides a **live view** that is continuously matched against the latest advisory database. If a new vulnerability advisory is published after a repository scan, it automatically appears in the Vulnerabilities Explorer, even if the repository has not been rescanned and even if the advisory targets an older commit. This means your vulnerability exposure is always up to date, regardless of when the last scan ran. + +> **Example:** If a scan runs at 10:00 AM and a CVE advisory for a library in your repository is published at 4:00 PM the same day, the Repositories Explorer for that commit will not show the CVE, but the Vulnerabilities Explorer will reflect it as soon as the advisory is available in Datadog's database. + +### Retroactive advisory matching + +Datadog automatically applies new advisories to all existing scan results, including results from older commits. This means: +- You do not need to trigger a new scan for a newly published CVE to be reflected in your vulnerability posture. +- The Vulnerabilities Explorer always shows the most current risk picture based on your last known library inventory. +- The Repositories Explorer remains a historical record of what was known at scan time. ### Vulnerability lifecycle Vulnerabilities detected in libraries by SCA **at runtime** are closed by Datadog after a certain period, depending on the service's usage of the vulnerable library. @@ -103,11 +136,18 @@ Libraries that are loaded more than 1 hour after the service has started. Libraries from services that are alive for less than 2 hours (such as jobs). - **When vulnerabilities are auto-closed by Datadog:** After 5 days, if they have not been detected again during this period. - +## Next steps - +1. [Set up Static SCA][1] to scan your repositories. +2. [Set up Runtime SCA][2] to detect libraries loaded by your running services. +3. Review and triage findings in the [Vulnerabilities Explorer][11]. +4. Configure [PR Gates][16] to block risky changes before they are merged. ## Further Reading @@ -117,7 +157,6 @@ The Vulnerability Explorer offers remediation recommendations for detected vulne [1]: /security/code_security/software_composition_analysis/setup_static/ [2]: /security/code_security/software_composition_analysis/setup_runtime/ [3]: https://app.datadoghq.com/security/appsec/vm -[5]: /getting_started/code_security/ [8]: https://app.datadoghq.com/security/appsec/inventory/libraries [9]: /account_management/rbac/permissions/#integrations [10]: https://app.datadoghq.com/services?lens=Security @@ -125,4 +164,6 @@ The Vulnerability Explorer offers remediation recommendations for detected vulne [12]: https://app.datadoghq.com/ci/code-analysis [13]: /security/code_security/software_composition_analysis/setup_static/#upload-third-party-sbom-to-datadog [14]: /security/code_security/software_composition_analysis/library_inventory -[15]: /security/code_security/software_composition_analysis/#set-up-sca +[16]: /pr_gates/ +[17]: /pr_gates/setup +[18]: /security/code_security/software_composition_analysis/setup_static/?tab=github#link-findings-to-datadog-services-and-teams diff --git a/content/en/security/code_security/software_composition_analysis/setup_static/_index.md b/content/en/security/code_security/software_composition_analysis/setup_static/_index.md index 1d33c5e9cc4..0a24ba2f9c1 100644 --- a/content/en/security/code_security/software_composition_analysis/setup_static/_index.md +++ b/content/en/security/code_security/software_composition_analysis/setup_static/_index.md @@ -41,7 +41,7 @@ Datadog SCA scans libraries in the following languages using dependency manifest **Note:** If both a `packages.lock.json` and a `.csproj` file are present, the `packages.lock.json` takes precedence and provides more precise version resolution. ## Select where to run static SCA scans -By default, scans are automatically run upon each commit to a lockfile within an enabled repository. Default branch results are updated every hour to detect new vulnerabilities on existing packages. +By default, scans run when changes are committed that update supported dependency manifests/lockfiles in an enabled repository. You can also run SCA in your CI/CD pipeline (CI jobs are supported on `push` events). ### Scan with Datadog-hosted scanning @@ -385,4 +385,4 @@ Datadog stores findings in accordance with our [Data Rentention Periods](https:/ [26]: https://docs.datadoghq.com/account_management/teams/ [101]: https://docs.datadoghq.com/software_catalog/service_definitions/v3-0/ [102]: https://docs.datadoghq.com/internal_developer_portal/software_catalog/entity_model/?tab=v30#codelocations -[103]: https://docs.datadoghq.com/data_security/data_retention_periods/ \ No newline at end of file +[103]: https://docs.datadoghq.com/data_security/data_retention_periods/