diff --git a/docs/semgrep-supply-chain/advisories.md b/docs/semgrep-supply-chain/advisories.md index 7bc18688a7..573bdc395c 100644 --- a/docs/semgrep-supply-chain/advisories.md +++ b/docs/semgrep-supply-chain/advisories.md @@ -1,7 +1,7 @@ --- slug: advisories append_help_link: true -title: Advisories +title: Advisories and related findings displayed_sidebar: scanSidebar hide_title: true description: "View the advisories related to your organization and search for relevant findings." diff --git a/docs/semgrep-supply-chain/dependency-path.md b/docs/semgrep-supply-chain/dependency-path.md new file mode 100644 index 0000000000..571c059d90 --- /dev/null +++ b/docs/semgrep-supply-chain/dependency-path.md @@ -0,0 +1,65 @@ +--- +slug: dependency-path +append_help_link: true +title: Dependency paths (beta) +hide_title: true +description: "View dependency paths for your transitive dependencies." +tags: + - Semgrep Supply Chain + - Semgrep AppSec Platform +--- + +# Dependency paths (beta) + +:::info +This feature is currently in invite-only beta. Please contact [Semgrep Support](/support) for more information. +::: + +The %%Dependency|dependency%% paths feature allows you to view dependency paths for all transitive dependencies introduced in a project, up to seven layers of depth. With this information, you can understand: + +- How a transitive dependency was introduced +- How deeply the transitive dependency is nested in the dependency tree. + +## Supported languages + +Semgrep generates dependency paths for most C#, Java, JavaScript, Kotlin, and Python projects. + +### C# + +Semgrep generates dependency paths for C# projects using NuGet. + +### Java + +Semgrep generates dependency paths for Java projects that include a `maven_dep_tree.txt` file whenever you invoke a scan using `semgrep ci`. + +Semgrep can also generate dependency paths for Java projects with lockfiles and Java projects **without lockfiles** if they're built using Maven or Gradle with the help of the Gradle Wrapper. %%Dependency|dependency%% paths for such projects are available when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). + +### JavaScript + +Semgrep generates dependency paths for JavaScript projects that use `npm`, `yarn`, or `pnpm` and include a lockfile whenever you invoke a scan using `semgrep ci`. + +### Kotlin + +Semgrep generates dependency paths for Kotlin projects built using Maven when a `maven_dep_tree.txt` file is present, and for Maven or Gradle when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). + +### Python + +Semgrep generates dependency paths for Python projects that use the following package managers: + +- `poetry` and `poetry.lock` file +- `uv` (requires Semgrep version `1.127.0` or later) + +Semgrep also generates dependency paths for Python projects that use the following package managers: + +- `Pipenv` +- `piptools` +- `pip` with `requirements.txt` + +when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). + +## View the dependency path + +Once [Semgrep Support](/support) has added you to the %%Dependency|dependency%% paths beta program and a new scan has completed on one of your projects, you can view dependency paths in Semgrep AppSec Platform using one of the following two methods: + +- Go to the [**Supply Chain** findings page](https://semgrep.dev/orgs/-/supply-chain), and used the **Transitivity > Transitive** filter to show transitive findings. Click the finding to open its **finding details** page. Click **Dependency path**. +- Go to the **Supply Chain > Dependencies** tab. Filter for **Transitive** dependencies. Click the dependency's **Transitive** link to proceed. diff --git a/docs/semgrep-supply-chain/dependency-search.md b/docs/semgrep-supply-chain/dependency-search.md index d588aa3c96..c37cfc9996 100644 --- a/docs/semgrep-supply-chain/dependency-search.md +++ b/docs/semgrep-supply-chain/dependency-search.md @@ -1,7 +1,7 @@ --- slug: dependency-search append_help_link: true -title: View and search for dependencies +title: Dependency search hide_title: true description: "View and search through all your dependencies in all your onboarded repositories at any time." tags: @@ -12,7 +12,7 @@ tags: # View and search for dependencies :::info Prerequisite -At least one project (a repository or subfolder in a monorepo) that scans for dependencies through Semgrep Supply Chain. See [Scan third-party dependencies](/semgrep-supply-chain/getting-started). +At least one project (a repository or subfolder in a monorepo) that scans for dependencies through Semgrep Supply Chain. See [Supply Chain configuration](/semgrep-supply-chain/getting-started). ::: Semgrep Supply Chain's dependency search feature allows you to view and query for any dependency in your project at any time. This feature detects all transitive and direct dependencies across all of your projects in Semgrep AppSec Platform. %%Dependency|dependency%% search lists all the versions of a dependency, as well as the projects that use the dependency. @@ -28,8 +28,7 @@ To search your dependencies: 1. Click **%%Dependency|dependency%% search** if it's not already enabled. 2. Navigate to **Supply Chain > Dependencies**. - -At this point, Semgrep displays the manifest files or lockfiles that it has used to determine dependency information and the dependencies included in each of the manifest files or lockfiles. +At this point, Semgrep displays the manifest files or lockfiles that it has used to determine dependency information and the dependencies included in each of these files. You can view this information in Semgrep AppSec Platform by going to [Supply Chain > Dependencies](https://semgrep.dev/orgs/-/supply-chain/t/dependencies). ### View additional manifest files or lockfiles @@ -81,61 +80,6 @@ You can search for multiple packages simultaneously. | License | The dependency's license type. | | Language | The language of the dependency. | -## Dependency paths (beta) - -:::info -This feature is currently in invite-only beta. Please contact [Semgrep Support](/support) for more information. -::: - -The %%Dependency|dependency%% paths feature allows you to view dependency paths for all transitive dependencies introduced in a project, up to seven layers of depth. With this information, you can understand: - -- How a transitive dependency was introduced -- How deeply the transitive dependency is nested in the dependency tree. - -### Supported languages - -Semgrep generates dependency paths for most C#, Java, JavaScript, Kotlin, and Python projects. - -#### C# - -Semgrep generates dependency paths for C# projects using NuGet. - -#### Java - -Semgrep generates dependency paths for Java projects that include a `maven_dep_tree.txt` file whenever you invoke a scan using `semgrep ci`. - -Semgrep can also generate dependency paths for Java projects with lockfiles and Java projects **without lockfiles** if they're built using Maven or Gradle with the help of the Gradle Wrapper. %%Dependency|dependency%% paths for such projects are available when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). - -#### JavaScript - -Semgrep generates dependency paths for JavaScript projects that use `npm`, `yarn`, or `pnpm` and include a lockfile whenever you invoke a scan using `semgrep ci`. - -#### Kotlin - -Semgrep generates dependency paths for Kotlin projects built using Maven when a `maven_dep_tree.txt` file is present, and for Maven or Gradle when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). - -#### Python - -Semgrep generates dependency paths for Python projects that use the following package managers: - -- `poetry` and `poetry.lock` file -- `uv` (requires Semgrep version `1.127.0` or later) - -Semgrep also generates dependency paths for Python projects that use the following package managers: - -- `Pipenv` -- `piptools` -- `pip` with `requirements.txt` - -when [scanning without lockfiles](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta). - -### View the dependency path - -After you have been added to the %%Dependency|dependency%% paths beta and a new scan completes on a repository, view the dependency paths in Semgrep AppSec Platform on: - -- The **%%Finding|finding%% Details** page for a transitive finding -- The **Supply Chain > Dependencies** tab when you view a transitive dependency; click **Transitive** to see the dependency path - ## Troubleshooting: no dependencies appear on the Dependencies page If you don't see any results on the Dependencies page, ensure that: diff --git a/docs/semgrep-supply-chain/feature-support.md b/docs/semgrep-supply-chain/feature-support.md deleted file mode 100644 index 5dc26bd09e..0000000000 --- a/docs/semgrep-supply-chain/feature-support.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -slug: sca-feature-support -append_help_link: true -title: Feature support -hide_title: true -description: Feature coverage for Semgrep Supply Chain across supported languages. -tags: - - Semgrep Supply Chain ---- - -import SscIntro from "/src/components/concept/_ssc-intro.md" - -# Supply Chain feature support - -This document discusses the features supported by Semgrep Supply Chain. - -## Lockfiles and manifest files - -For projects with lockfiles, Semgrep parses lockfiles for dependencies, then scans your codebase for reachable findings based on the lockfiles. For a lockfile to be scanned by Semgrep Supply Chain, it must have one of the supported lockfile names. - -For some languages, a lockfile or manifest file is required to determine %%transitivity|transitivity%%. See [Transitive dependencies and reachability analysis](/semgrep-supply-chain/overview/#transitive-dependencies-and-reachability-analysis) for more information. - -Additionally, Semgrep offers beta support for the scanning of projects written in the following languages without lockfiles using Dynamic Dependency Resolution. See the following table for more information. - -## Supply Chain features for each language - - -The following table lists all Supply Chain features for each language. Languages with **reachability** support are listed first. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LanguageReachability
(see CVE coverage)		Scan without lockfiles (beta)License detectionMalicious dependency
detection
C#✅✅
CI and CLI only		✅✅
Go✅--✅✅
Java✅✅✅--
JavaScript or TypeScript✅--✅✅
Kotlin✅✅✅--
Python✅✅
setup.py in CLI or CI		✅
For PyPi only		✅
Ruby✅--✅✅
Scala✅✅
SBT in CLI or CI		✅--
Swift✅--✅†--
PHP✅--✅--
RustNo reachability analysis. However, Semgrep can compare a package's version against a list of versions with known vulnerabilities.--✅✅
Dart------
Elixir------
- - -_†License detection for new packages is asynchronous and processed after the initial scan. Policies aren't applied on first detection, but are enforced in subsequent scans._ - -## CVE coverage - -For customers with an active paid subscription, Semgrep’s reachability analysis -covers all **critical and high severity** CVEs from [supported sources](#supported-sources) -starting in 2017 across all supported languages. - -### Supported sources - -- [ Reviewed GitHub Security Advisories](https://github.com/advisories?query=type%3Areviewed) -- [ Electron release notes](https://releases.electronjs.org/releases/stable) diff --git a/docs/semgrep-supply-chain/getting-started.md b/docs/semgrep-supply-chain/getting-started.md index 31f8d0f837..febb4d9622 100644 --- a/docs/semgrep-supply-chain/getting-started.md +++ b/docs/semgrep-supply-chain/getting-started.md @@ -4,7 +4,7 @@ append_help_link: true description: "Scan your project with Semgrep Supply Chain." tags: - Semgrep Supply Chain -title: Third-party dependencies +title: Configuration hide_title: true --- @@ -15,17 +15,17 @@ import DetectGhRepos from "/src/components/procedure/_detect-gh-repos.md" -# Scan third-party dependencies +# Supply Chain configuration -This article walks you through the setup needed to scan your project with Semgrep Supply Chain and its configuration and customization options. Once you enable Semgrep Supply Chain, it automatically scans repositories that you have added to Semgrep AppSec Platform, but your repository must first meet the requirements for a successful scan. +This article explains how to set up and use Semgrep Supply Chain, including its configuration and customization options. Once you turn on Supply Chain, it automatically scans projects added to Semgrep AppSec Platform as shown in [Quickstart](/getting-started/quickstart-managed-scans). However, your projects must meet Semgrep's required criteria before your scans succeed. ## Project directory structure -To scan your project with Semgrep Supply Chain, it must use a [supported package manager and supported file names](/docs/semgrep-supply-chain/sca-package-manager-support). +To scan your project with Supply Chain, it must use a [supported package manager and include a lockfile or manifest file with a supported file name](/semgrep-supply-chain/requirements-and-feature-support). -Semgrep Supply Chain can correctly parse code files, manifest files, and lockfiles in subfolders as well. Code files that use the dependencies in the manifest file or lockfile must be nested in the same directory as the manifest file or lockfile. Manifest files and lockfiles must all use supported file names. +Supply Chain can correctly parse code files, manifest files, and lockfiles in subfolders as well. Code files that use the dependencies in the manifest file or lockfile must be nested in the same directory as the manifest file or lockfile. Manifest files and lockfiles must all use supported file names. -In the following example, Semgrep Supply Chain assumes that all code files using the dependencies in `my-project/running/lockfile.json` are nested in `my-project/running/` or deeper directories. +In the following example, Supply Chain assumes that all code files using the dependencies in `my-project/running/lockfile.json` are nested in `my-project/running/` or deeper directories. ``` /my-project @@ -38,21 +38,21 @@ In the following example, Semgrep Supply Chain assumes that all code files using ├───/biking ``` -If you have code files in `my-project/biking,` Semgrep Supply Chain does not associate them with the dependencies in `my-project/running/lockfile.json.` If there is another manifest file or lockfile in `my-project/running`, such as `my-project/running/uphill/lockfile.json`, then this overrides the original `my-project/running/lockfile.json` for all code files in `my-project/running/uphill/` or deeper directories. +If you have code files in `my-project/biking,` Supply Chain does not associate them with the dependencies in `my-project/running/lockfile.json.` If there is another manifest file or lockfile in `my-project/running`, such as `my-project/running/uphill/lockfile.json`, then this overrides the original `my-project/running/lockfile.json` for all code files in `my-project/running/uphill/` or deeper directories. - -## Enable Semgrep Supply Chain +## Enable Supply Chain 1. Sign in to [ Semgrep AppSec Platform](https://semgrep.dev/login). 1. Go to **[Settings > General > Supply Chain](https://semgrep.dev/orgs/-/settings/general/supplyChain)**. 1. Click the ** Supply Chain scans** toggle if it is not already enabled. -## Scan frequency +## Set the scan frequency -You can modify your CI configuration so that Semgrep Supply Chain scans your code at a specified frequency or whenever a specific event occurs, such as opening a pull request or merge request. +You can modify your CI configuration so that Supply Chain scans your code at a specified frequency or whenever a specific event occurs, such as opening a pull request or merge request. ### Rule updates -Semgrep Supply Chain frequently receives rule updates. To take advantage of these updates, adjust the frequency with which Semgrep Supply Chain scans your codebase. + +Supply Chain frequently [receives rule updates](/semgrep-supply-chain/overview#new-cves-and-rule-updates). To take advantage of these updates, adjust the frequency with which Supply Chain scans your codebase. If a rule is updated, findings generated against the revised rule are considered **new findings**, even if the previous version generated a finding. The new finding is not affected by any triage actions on findings related to the prior version of the rule. Because the finding is new, you'll also receive notifications through the channels you've set up, such as Slack. @@ -62,7 +62,7 @@ If a rule is updated, findings generated against the revised rule are considered ### Event-triggered scans -You can configure your CI/CD system to trigger a Semgrep Supply Chain scan whenever one of the following events occurs: +You can configure your CI/CD system to trigger a Supply Chain scan whenever one of the following events occurs: @@ -82,16 +82,19 @@ You can configure your CI/CD system to trigger a Semgrep Supply Chain scan whene
-## Dynamic Dependency Resolution (beta) to scan without lockfiles +## Dynamic Dependency Resolution (beta) :::info This feature is currently in beta. Please contact [Semgrep Support](/support) for more information. ::: -Semgrep Supply Chain can use **Dynamic Dependency Resolution** to scan projects without requiring lockfiles. This simplifies the configuration of Supply Chain scans. See [Feature support](/semgrep-supply-chain/sca-feature-support) for more information. +Supply Chain can use **Dynamic Dependency Resolution** to scan projects without lockfiles or with incomplete lockfiles. This simplifies the configuration of Supply Chain scans. See [Feature support](/semgrep-supply-chain/requirements-and-feature-support#features-for-supported-languages) for more information. + +### CLI and self-managed CI scans + +To run a scan on the CLI, including scans with self-managed CI systems, using Dynamic Dependency Resolution: -### CLI Scans, including self-managed CI systems -1. Ensure that the environment where you run Semgrep scans has installed all of the dependencies required to build your project, such as Java and Maven or Python and pip. +1. Ensure that the environment where you run Semgrep scans has all of the dependencies required to build your project installed, such as Java and Maven or Python and pip. 2. Initiate a Semgrep scan, ensuring that you include the `--allow-local-builds` flag to enable Semgrep to invoke package managers on the system: ```console semgrep ci --allow-local-builds @@ -101,22 +104,20 @@ Semgrep Supply Chain can use **Dynamic Dependency Resolution** to scan projects This flag allows Semgrep to build the project, if needed, to dynamically resolve dependencies. Semgrep uses the build information included in the `pom.xml` or `build.gradle` file to determine the set of dependencies used by the project. ### Semgrep Managed Scans + 1. [Configure private - registry credentials](/semgrep-supply-chain/triage-and-remediation#connect-a-private-registry-to-semgrep) in **Settings > Integrations**. Note that only Maven registries are currently supported for Managed Scans. -2. Contact [Semgrep Support](/support) to enable Dynamic Dependency resolution - for the necessary repositories. + registry credentials](/semgrep-supply-chain/triage-and-remediation#connect-a-private-registry-to-semgrep) in Semgrep AppSec Platform in **Settings > Integrations**. Note that only Maven registries are currently supported for Managed Scans. +2. Contact [Semgrep Support](/support) to enable Dynamic Dependency Resolution for the necessary repositories. ## Run a scan using the CLI -You can start a stand-alone Semgrep Supply Chain scan by running the following command in the CLI: +You can start a stand-alone Supply Chain scan by running the following command in the CLI: ```console semgrep ci --supply-chain ``` -Semgrep prints a list of findings directly to the CLI, including the finding's reachability determination, severity level, a brief description, and suggested remediation. - -You can also view your results in Semgrep AppSec Platform. It displays all of the information displayed in the CLI, but it also offers you the ability to: +Semgrep prints a list of findings directly to the CLI, including the finding's reachability determination, severity level, a brief description, and suggested remediation. You can also view your results in Semgrep AppSec Platform. It displays all of the information displayed in the CLI, but it also offers you the ability to: * [See additional finding details](/semgrep-supply-chain/findings), such as whether the finding is always reachable or if it's reachable if certain conditions are met, and its transitivity status * Use the [dependency search](/semgrep-supply-chain/dependency-search) feature @@ -124,8 +125,4 @@ You can also view your results in Semgrep AppSec Platform. It displays all of th ## Scan a monorepo's dependencies -Semgrep Supply Chain supports the scanning of monorepos. As outlined in [Project directory structure](#project-directory-structure), findings are grouped by directory based on the %%manifest file|manifest_file%% or %%lockfile|lockfile%% present in the monorepo. - -## Block pull requests or merge requests - -You can comment on or potentially block pull requests or merge requests by defining a [Supply Chain Policy](/semgrep-supply-chain/policies). +Supply Chain supports the scanning of monorepos. As outlined in [Project directory structure](#project-directory-structure), findings are grouped by directory based on the %%manifest file|manifest_file%% or %%lockfile|lockfile%% present in the monorepo. diff --git a/docs/semgrep-supply-chain/malicious-dependencies.md b/docs/semgrep-supply-chain/malicious-dependencies.md index 948440d674..c50410af94 100644 --- a/docs/semgrep-supply-chain/malicious-dependencies.md +++ b/docs/semgrep-supply-chain/malicious-dependencies.md @@ -7,7 +7,7 @@ tags: - Semgrep Supply Chain --- -# Detect and remove malicious dependencies +# Malicious dependencies **Malicious dependencies** are dangerous packages, or dangerous versions of packages, that are designed to compromise systems. These threats include packages that have always been malicious, such as typo-squatting attacks, or packages that become malicious after an attacker compromises a maintainer or injects harmful code. They are also known as malware. diff --git a/docs/semgrep-supply-chain/overview.md b/docs/semgrep-supply-chain/overview.md index 9f67ce1abb..025eb74d33 100644 --- a/docs/semgrep-supply-chain/overview.md +++ b/docs/semgrep-supply-chain/overview.md @@ -13,80 +13,101 @@ import AdmonitionSotCves from "/src/components/reference/_admonition-sot-cves.md -## Open source security vulnerabilities +## Detect vulnerabilities Semgrep Supply Chain detects [security vulnerabilities](https://nvd.nist.gov/vuln/full-listing) in your codebase introduced by open source dependencies using high-signal rules, which are instructions Semgrep uses detect patterns in code, to determine the vulnerability's %%reachability|reachability%%. -To do this, Semgrep Supply Chain first determines the list of dependencies and versions in the code, then scans your codebase using rules that specify the following information: +To do this, Supply Chain first determines the list of dependencies and versions in the code, then scans your codebase using rules that specify the following information: * The dependency versions that contain a vulnerability * The pattern for the vulnerable code that Semgrep compares against your code * The severity of the vulnerability -The following diagram shows the relationship between a Semgrep Supply Chain rule, the codebase scanned, and in this case, a lockfile: +For projects with a missing or incomplete lockfile, Supply Chain's **Dynamic Dependency Resolution** provides a complete inventory of your project's dependencies using a combination of manifest parsing and repository integration with package managers and private registries. -![Relationship between a Semgrep Supply Chain rule, manifest file or lockfile, CVE record, and codebase](/img/sc-reachability-analysis.png) +The following diagram shows the relationship between a Supply Chain rule, the codebase scanned, and in this case, a lockfile: + +![Relationship between a Supply Chain rule, manifest file or lockfile, CVE record, and codebase](/img/sc-reachability-analysis.png) _**Figure**. Relationship between a Supply Chain rule, manifest file or lockfile, CVE record, and codebase._ -### Types of Semgrep Supply Chain findings +### Types of Supply Chain findings -Semgrep Supply Chain generates a **finding** whenever it determines that your codebase uses or imports a package containing a vulnerability. In addition, Semgrep supports **reachability** for [generally available (GA) languages](/supported-languages): +Supply Chain generates a **finding** whenever it determines that your codebase uses or imports a package containing a vulnerability. In addition, Semgrep supports **reachability** for [generally available (GA) languages](/supported-languages): -* **GA languages**: Semgrep writes rules for all critical and high CVE severity levels for GA languages. That means Semgrep Supply Chain can flag all your critical/high-severity findings as either reachable or unreachable. +* **GA languages**: Semgrep writes rules for all critical and high CVE severity levels for GA languages. That means Supply Chain can flag all your critical/high-severity findings as either reachable or unreachable. * If there's a code pattern in the codebase that matches the vulnerability definition, the finding is flagged as **reachable**. * A finding is **always reachable** if the only way to fix the vulnerability is to upgrade the dependency. Semgrep strongly recommends upgrading the dependencies involved in these findings. * A finding is **conditionally reachable** if the vulnerability can be exploited when specific conditions are met. The finding is reachable if, in addition to the dataflow reachability in code, additional factors, such as the use of a specific operating system, are met. Semgrep cannot determine whether such factors are true, so conditionally reachable findings require manual review. - * If Semgrep Supply Chain determines that you don't use the vulnerable library package imported or you don't use the vulnerable piece of code of the library or package imported, the finding is flagged as **unreachable**. - * If Semgrep Supply Chain determines that you use a vulnerable version of a dependency, but Semgrep Supply Chain doesn't have a relevant reachability rule, it flags the finding as **no reachability analysis**. -* For **languages where Semgrep Supply Chain doesn't currently offer %%reachability rules|reachability_rules%%** languages, Semgrep Supply Chain's performance is comparable to that of [GitHub's Dependabot](https://github.com/dependabot). Semgrep Supply Chain generates these findings by checking the dependency's version against a list of versions with known vulnerabilities, but it does not run reachability analysis. Because Semgrep Supply Chain doesn't run reachability analysis, it can't determine whether the vulnerability is reachable. Such vulnerabilities are, therefore, flagged as **no reachability analysis**. + * If Supply Chain determines that you don't use the vulnerable library package imported or you don't use the vulnerable piece of code of the library or package imported, the finding is flagged as **unreachable**. + * If Supply Chain determines that you use a vulnerable version of a dependency, but Supply Chain doesn't have a relevant reachability rule, it flags the finding as **no reachability analysis**. +* For **languages where Supply Chain doesn't currently offer %%reachability rules|reachability_rules%%** languages, Supply Chain's performance is comparable to that of [GitHub's Dependabot](https://github.com/dependabot). Supply Chain generates these findings by checking the dependency's version against a list of versions with known vulnerabilities, but it does not run reachability analysis. Because Supply Chain doesn't run reachability analysis, it can't determine whether the vulnerability is reachable. Such vulnerabilities are, therefore, flagged as **no reachability analysis**. Specific dependency and code match findings are called **usages**. Semgrep AppSec Platform groups all usages together by vulnerability. For each vulnerability, the UI also displays a CVE number corresponding to the [CVE program record](https://www.cve.org/About/Overview). -### Transitive dependencies and reachability analysis +#### Transitive dependencies and reachability analysis + +A %%transitive dependency|transitive_or_indirect_dependency%%, also known as an indirect dependency, is a dependency of a dependency. Supply Chain scans transitive dependencies for [all supported languages](/supported-languages#semgrep-supply-chain), looking for security vulnerabilities, but it does *not* perform reachability analysis. This means that Supply Chain doesn't check the source code of your project's dependencies to determine if their dependencies produce a reachable finding in your code. + +However, some dependencies are vulnerable simply through their inclusion in a codebase; in such cases, Supply Chain generates reachable findings involving these dependencies, even if they're transitive, not direct, dependencies. -A %%transitive dependency|transitive_or_indirect_dependency%%, also known as an indirect dependency, is a dependency of a dependency. Semgrep Supply Chain scans transitive dependencies for [all supported languages](/supported-languages#semgrep-supply-chain), looking for security vulnerabilities, but it does *not* perform reachability analysis. This means that Semgrep Supply Chain doesn't check the source code of your project's dependencies to determine if their dependencies produce a reachable finding in your code. +Some package ecosystems allow the use of a transitive dependency as if it were a direct dependency. Though this feature is uncommon, Supply Chain can scan for such usages and flag vulnerabilities in transitive dependencies as unreachable if not used directly. -However, some dependencies are vulnerable simply through their inclusion in a codebase; in such cases, Semgrep Supply Chain generates reachable findings involving these dependencies, even if they're transitive, not direct, dependencies. +## Triage and fix vulnerabilities -Some package ecosystems allow the use of a transitive dependency as if it were a direct dependency. Though this feature is uncommon, Semgrep Supply Chain can scan for such usages and flag vulnerabilities in transitive dependencies as unreachable if not used directly. +Once Supply Chain has identified vulnerabilities in your code and generated findings, you can take the following actions: -## Language support and integrations +- **Ignore findings**: If the finding is a false positive, or if your company's business policies deem the use of the dependency an acceptable risk, you can choose to ignore the finding. +- **Remediate true positives**: If the finding is one that you must address, you can: + - **Remove dependencies and refactor code**: You can remediate true positives identified by Supply Chain by updating the dependency to a safe version or removing the dependency, then refactoring all usages of that dependency in your project. + - **Use upgrade guidance and Autofix**: If the remediation for a finding is to upgrade the package, **Upgrade guidance** uses program analysis and AI to analyze the results of your Semgrep scans to see if you can safely and reliably update a vulnerable package or dependency to a fixed version. Semgrep can also open a pull request (PR) or merge request (MR) that updates the vulnerable version used by your repository and guide the developer on any breaking changes in the PR or MR description. -Semgrep Supply Chain supports a broad set of languages with varying feature coverage. +## Policies -* See the full list of [supported programming languages](/supported-languages) -* For a list of Semgrep-supported package managers for each language, see [Package manager support](/semgrep-supply-chain/sca-package-manager-support). -* For feature support by language, see [Supply Chain feature support](/semgrep-supply-chain/sca-feature-support). -* For definitions of language maturity levels, see [Language maturity levels](/docs/references/language-maturity-levels#semgrep-supply-chain). -* For analysis terminology, see [Feature definitions](/docs/references/feature-definitions). -* For a list of supported source code managers (SCM), see [Supported source code managers](/getting-started/scm-support) or learn how to [Connect a source code manager](/docs/deployment/connect-scm). +Policies, which are scoped on a per-project basis, allow you to define the conditions that must be met for an automation action to occur. These actions include: +- Leaving a comment on the PR or MR +- Blocking the PR or MR from being merged +- Failing the build -## Software bill of materials +## Malware detection and response + +Semgrep can [detect malicious dependencies](/semgrep-supply-chain/malicious-dependencies), which are treated as critical severity findings. If you have set up your [policies](/semgrep-supply-chain/policies) to block critical severity findings, Semgrep prevents developers from merging pull requests or merge requests with malicious dependencies. -Semgrep Supply Chain can [generate a software bill of materials (SBOM)](/semgrep-supply-chain/sbom), a complete inventory of your third-party or open source components, to assist you with your auditing procedures. +Supply Chain's [dependency search](/semgrep-supply-chain/dependency-search) feature allows you to query for dependencies in your codebase; it can detect direct and transitive dependencies in any repository on which you have run a full scan. The results list the dependency, along with all of the repositories that use the dependency. -## Dependency search +### Dependency paths -Semgrep Supply Chain's [dependency search](/semgrep-supply-chain/dependency-search) feature allows you to query for dependencies in your codebase; it can detect direct and transitive dependencies in any repository on which you have run a full scan. The results list the dependency, along with all of the repositories that use the dependency. +Supply Chain's dependency paths feature allows you to view dependency paths for all transitive dependencies introduced in a project, up to seven layers of depth. This provides information on how a transitive dependency was introduced and how deeply the transitive dependency is nested in the dependency tree. ## License compliance The [license compliance](/semgrep-supply-chain/license-compliance) feature ensures that you're only using open source packages whose licensing meets your organization's requirements. -## Malicious dependencies detection +## Reporting -Semgrep can [detect malicious dependencies](/semgrep-supply-chain/malicious-dependencies), which are treated as critical severity findings. If you have set up your [policies](/semgrep-supply-chain/policies) to block critical severity findings, Semgrep prevents developers from merging pull requests or merge requests with malicious dependencies. +### Reports through the Semgrep API + +The Semgrep API allows you to obtain project and dependency information, as well as generate an SBOM. The following endpoints are available to you: + +- [List dependencies](https://semgrep.dev/api/v1/docs/#tag/SupplyChainService/operation/SupplyChainService_ListDependencies) +- [List repositories with dependencies](https://semgrep.dev/api/v1/docs/#tag/SupplyChainService/operation/SupplyChainService_ListRepositoriesForDependencies) +- [List lockfiles in a given repository with dependencies](https://semgrep.dev/api/v1/docs/#tag/SupplyChainService/operation/SupplyChainService_ListLockfilesForDependencies) +- [Create a new SBOM export job](https://semgrep.dev/api/v1/docs/#tag/SupplyChainService/operation/SupplyChainService_CreateSbomExport) +- [Get the status of a SBOM export job](https://semgrep.dev/api/v1/docs/#tag/SupplyChainService/operation/SupplyChainService_GetSbomExport) + +### Software bill of materials + +Supply Chain can [generate a software bill of materials (SBOM)](/semgrep-supply-chain/sbom), a complete inventory of your third-party or open source components, to assist you with your auditing procedures. ## Next steps -Semgrep Supply Chain automatically scans repositories that you have added to Semgrep AppSec Platform. Once your first scan is completed: +Supply Chain automatically scans repositories that you have added to Semgrep AppSec Platform. Once your first scan is completed: * [View, triage, and remediate](/semgrep-supply-chain/triage-and-remediation) your Supply Chain findings. - * [Customize Semgrep Supply Chain to ignore files and dependencies](/semgrep-supply-chain/ignoring-dependencies) to support your security and business goals. + * [Customize Supply Chain to ignore files and dependencies](/semgrep-supply-chain/ignoring-dependencies) to support your security and business goals. * [Generate a software bill of materials (SBOM)](/semgrep-supply-chain/sbom). * Query for dependencies in your codebase using [dependency search](/semgrep-supply-chain/dependency-search). * Ensure that you're only [using open source packages whose licensing meets your organization's requirements](/semgrep-supply-chain/license-compliance). diff --git a/docs/semgrep-supply-chain/package-manager-support.md b/docs/semgrep-supply-chain/package-manager-support.md deleted file mode 100644 index 42cb5286e7..0000000000 --- a/docs/semgrep-supply-chain/package-manager-support.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -slug: sca-package-manager-support -append_help_link: true -title: Package manager support -hide_title: true -description: Supported package managers and lockfiles for Semgrep Supply Chain scans. -tags: - - Semgrep Supply Chain ---- - -# Package manager support - -Semgrep Supply Chain (SCA) scans dependencies by parsing manifest files or lockfiles, or with Dynamic Dependency Resolution (beta). This page lists the supported package managers and file types. - -For language-level coverage and feature maturity, see -[Supported languages](/supported-languages). - -For some languages, a lockfile or manifest file is required to accurately to determine %%transitivity|transitivity%%. See [Transitive dependencies and reachability analysis](/semgrep-supply-chain/overview/#transitive-dependencies-and-reachability-analysis) for more information. - - -The following table lists all Semgrep-supported package managers for each language. Languages with **reachability** support are listed first. - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LanguageSupported package managersManifest file or lockfile
C#NuGet.csproj
GoGo modules (go mod)go.mod
JavaGradlegradle.lockfile or
build.gradle or - build.gradle.kts through Dynamic - Dependency Resolution.
MavenMaven-generated dependency tree (see Setting up SSC scans for Apache Maven for instructions) or
pom.xml through Dynamic - Dependency Resolution.
JavaScript or TypeScriptnpmpackage-lock.json
Yarnyarn.lock
pnpmpnpm-lock.yaml
KotlinGradlegradle.lockfile
MavenMaven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.)
PythonpipA
  • `*requirement*.txt`, `*requirement*.pip`, `**/requirements/*.txt`, or `**/requirements/*.pip` with dependencies pinned†
  • setup.py with Dynamic - Dependency Resolution.
pip-tools
PipenvPipfile.lock
Poetrypoetry.lock
uvuv.lock
RubyRubyGemsGemfile.lock
ScalaMavenMaven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.)
SwiftSwiftPMPackage.swift file and Swift-generated Package.resolved file. (See Swift documentation for instructions.)
RustCargo‡cargo.lock
DartPubpubspec.lock
ElixirHexmix.lock
PHPComposercomposer.lock
-
- - -_†Supply Chain can treat `requirements.txt` as a lockfile with Pip-compiled output and fully pinned dependencies or as a manifest file with more flexible specifiers. If your `requirements.txt` file doesn't use pinned dependencies exclusively, use the [`--allow-local-builds` flag](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta) when invoking your scan. This ensures that the dependencies using non-exact version specifiers, such as `>=`, `>`, `~=`, are included in the dependency graph. Otherwise, Semgrep ingests only pinned (`==`) dependencies._

-_‡Supply Chain does not analyze the transitivity of packages for -these language and manifest file or lockfile combinations. All dependencies are -listed as **No %%Reachability|reachability%% Analysis.**_
diff --git a/docs/semgrep-supply-chain/requirements-and-feature-support.md b/docs/semgrep-supply-chain/requirements-and-feature-support.md new file mode 100644 index 0000000000..a6e70898bd --- /dev/null +++ b/docs/semgrep-supply-chain/requirements-and-feature-support.md @@ -0,0 +1,283 @@ +--- +slug: requirements-and-feature-support +append_help_link: true +title: Supported languages and package managers +hide_title: true +description: Supply Chain supported package managers, lockfiles, and features. +tags: + - Semgrep Supply Chain +--- + +# Supported languages and package managers + +Supply Chain begins the scan process by parsing the manifest file or lockfile. For projects without a lockfile or an incomplete lockfile, Supply Chain's Dynamic Dependency Resolution provides a complete inventory of dependencies. This article lists the requirements for both projects with and without lockfiles, as well as the features available to you based on your project's language and package manager. + +## Language and package manager support + +See [Supported languages](/supported-languages) for language-level coverage and feature maturity. + +For some languages, a lockfile or manifest file is **required** to accurately to determine %%transitivity|transitivity%%. See [Transitive dependencies and reachability analysis](/semgrep-supply-chain/overview/#transitive-dependencies-and-reachability-analysis) for more information. + +The following table lists all Semgrep-supported package managers for each language. Languages with **reachability** support are listed first. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageSupported package managersManifest file or lockfile
C#NuGet.csproj
GoGo modules (go mod)go.mod
JavaGradlegradle.lockfile or
build.gradle or + build.gradle.kts through Dynamic + Dependency Resolution.
MavenMaven-generated dependency tree (see Setting up SSC scans for Apache Maven for instructions) or
pom.xml through Dynamic + Dependency Resolution.
JavaScript or TypeScriptnpmpackage-lock.json
Yarnyarn.lock
pnpmpnpm-lock.yaml
KotlinGradlegradle.lockfile
MavenMaven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.)
PythonpipA
  • `*requirement*.txt`, `*requirement*.pip`, `**/requirements/*.txt`, or `**/requirements/*.pip` with dependencies pinned†
  • setup.py with Dynamic + Dependency Resolution.
pip-tools
PipenvPipfile.lock
Poetrypoetry.lock
uvuv.lock
RubyRubyGemsGemfile.lock
ScalaMavenMaven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.)
SwiftSwiftPMPackage.swift file and Swift-generated Package.resolved file. (See Swift documentation for instructions.)
RustCargo‡cargo.lock
DartPubpubspec.lock
ElixirHexmix.lock
PHPComposercomposer.lock
+
+ +_†Supply Chain can treat `requirements.txt` as a lockfile with Pip-compiled output and fully pinned dependencies or as a manifest file with more flexible specifiers. If your `requirements.txt` file doesn't use pinned dependencies exclusively, use the [`--allow-local-builds` flag](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta) when invoking your scan. This ensures that the dependencies using non-exact version specifiers, such as `>=`, `>`, `~=`, are included in the dependency graph. Otherwise, Semgrep ingests only pinned (`==`) dependencies._

+_‡Supply Chain does not analyze the transitivity of packages for +these language and manifest file or lockfile combinations. All dependencies are +listed as **No %%Reachability|reachability%% Analysis.**_
+ +## Feature support + +The following section discusses the features supported by Supply Chain. + +### Lockfiles and manifest files + +For projects with lockfiles, Semgrep parses lockfiles for dependencies, then scans your codebase for reachable findings based on the lockfiles. For a lockfile to be scanned by Semgrep Supply Chain, it must have one of the supported lockfile names. + +For some languages, a lockfile or manifest file is required to determine %%transitivity|transitivity%%. See [Transitive dependencies and reachability analysis](/semgrep-supply-chain/overview/#transitive-dependencies-and-reachability-analysis) for more information. + +Additionally, Semgrep offers beta support for the scanning of projects written in the following languages without lockfiles using Dynamic Dependency Resolution. See the following table for more information. + +### Features for supported languages + + +The following table lists all Supply Chain features for each language. Languages with **reachability** support are listed first. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageReachability
(see CVE coverage)		Scan without lockfiles (beta)License detectionMalicious dependency
detection
C#✅✅
CI and CLI only		✅✅
Go✅--✅✅
Java✅✅✅--
JavaScript or TypeScript✅--✅✅
Kotlin✅✅✅--
Python✅✅
setup.py in CLI or CI		✅
For PyPi only		✅
Ruby✅--✅✅
Scala✅✅
SBT in CLI or CI		✅--
Swift✅--✅†--
PHP✅--✅--
RustNo reachability analysis. However, Semgrep can compare a package's version against a list of versions with known vulnerabilities.--✅✅
Dart------
Elixir------
+ +_†License detection for new packages is asynchronous and processed after the initial scan. Policies aren't applied on first detection, but are enforced in subsequent scans._ + +### CVE coverage + +For customers with an active paid subscription, Semgrep’s reachability analysis +covers all **critical and high severity** CVEs from [supported sources](#supported-sources) +starting in 2017 across all supported languages. + +#### Supported sources + +- [ Reviewed GitHub Security Advisories](https://github.com/advisories?query=type%3Areviewed) +- [ Electron release notes](https://releases.electronjs.org/releases/stable) +- [ OSV](http://osv.dev/) diff --git a/sidebars.js b/sidebars.js index 6e257a4231..db77b2869d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -388,43 +388,62 @@ module.exports = { label: 'SCA (Supply Chain)', items: [ 'semgrep-supply-chain/overview', + 'semgrep-supply-chain/requirements-and-feature-support', + 'semgrep-supply-chain/getting-started', { type: 'category', collapsible: true, - label: 'Coverage', + label: 'Detect vulnerabilities', items: [ - 'semgrep-supply-chain/package-manager-support', - 'semgrep-supply-chain/feature-support', + { + type: 'category', + collapsible: true, + label: 'View findings', + link: {type: 'doc', id: 'semgrep-supply-chain/findings',}, + items: [ + 'semgrep-supply-chain/finding-details' + ] + }, + 'semgrep-supply-chain/advisories', + 'semgrep-supply-chain/dependency-search', + 'semgrep-supply-chain/triage-remediation' ] }, { - type: 'category', - collapsible: true, - label: 'Open source security vulnerabilities', - link: { - type: 'doc', - id: 'semgrep-supply-chain/getting-started', - }, - items: [ - { - type: 'category', - collapsible: true, - label: 'View findings', - link: {type: 'doc', id: 'semgrep-supply-chain/findings',}, - items: [ - 'semgrep-supply-chain/finding-details', - ] - }, - 'semgrep-supply-chain/triage-remediation', - 'semgrep-supply-chain/advisories', + type: 'category', + collapsible: true, + label: 'Triage and fix vulnerabilities', + items: [ + 'semgrep-supply-chain/triage-remediation' + ] + }, + { + type: 'category', + collapsible: true, + label: 'Policies', + items: [ 'semgrep-supply-chain/policies', - 'semgrep-supply-chain/ignoring-deps', - ] + 'semgrep-supply-chain/ignoring-deps' + ] + }, + { + type: 'category', + collapsible: true, + label: 'Malware detection and response', + items: [ + 'semgrep-supply-chain/malicious-dependencies' + ] }, - 'semgrep-supply-chain/sbom', - 'semgrep-supply-chain/dependency-search', 'semgrep-supply-chain/license-compliance', - 'semgrep-supply-chain/malicious-dependencies' + { + type: 'category', + + collapsible: true, + label: 'Reporting', + items: [ + 'semgrep-supply-chain/sbom' + ] + }, ] }, { diff --git a/src/components/concept/_ssc-intro.md b/src/components/concept/_ssc-intro.md index 0adf5b05fc..a91e9900fd 100644 --- a/src/components/concept/_ssc-intro.md +++ b/src/components/concept/_ssc-intro.md @@ -1,6 +1,7 @@ -Semgrep Supply Chain is a software composition analysis (SCA) tool that detects security vulnerabilities in your codebase introduced by open source dependencies. It can also: +Semgrep Supply Chain is a software composition analysis (SCA) tool that discovers and detects security vulnerabilities in your codebase introduced by open source dependencies. It can also: -* Generate a software bill of materials (SBOM) that provides a complete inventory of your open source components -* Query for information about your dependencies -* Support the enforcement of your business' [open source package licensing requirements](/semgrep-supply-chain/license-compliance) -* Detect malicious dependencies +- Assist with the triage and remediation of security issues +- Prevent future security issues from the introduction and use of insecure packages +- Detect malicious dependencies associated with Supply Chain attacks +- Support the enforcement of your business' [open source package licensing requirements](/semgrep-supply-chain/license-compliance) +- Generate reports and software bills of materials (SBOM) that provide a complete inventory of your open source components \ No newline at end of file diff --git a/src/components/reference/_admonition-sot-cves.md b/src/components/reference/_admonition-sot-cves.md index 331758c86a..c53b758c0e 100644 --- a/src/components/reference/_admonition-sot-cves.md +++ b/src/components/reference/_admonition-sot-cves.md @@ -8,7 +8,7 @@ Semgrep ingests CVE information and security advisories from the following sourc Semgrep processes new information multiple times per day, ensuring a maximum lag time of no more than one hour. With this information, Semgrep: -* Generates rules for new security advisories -* Updates existing rules based on changes to security advisories +- Generates rules for new security advisories +- Updates existing rules based on changes to security advisories -For major incidents that might affect customers, Semgrep's Security Research team ships its own advisories, even before third-party databases are updated. Semgrep processes [KEVs](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) the same way it processes other types of vulnerabilities. \ No newline at end of file +For major incidents that might affect customers, Semgrep's Security Research team ships its own advisories, even before third-party databases are updated. Semgrep processes [KEVs](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) the same way it processes other types of vulnerabilities.