diff --git a/docs/developer-tools/snyk-cli/commands/monitor.md b/docs/developer-tools/snyk-cli/commands/monitor.md index 929f3dc24193..e3367257d6d6 100644 --- a/docs/developer-tools/snyk-cli/commands/monitor.md +++ b/docs/developer-tools/snyk-cli/commands/monitor.md @@ -99,6 +99,8 @@ Default: false Print the dependency tree before sending it for analysis. +The output includes Snyk-specific component properties for each dependency. For npm and Yarn projects, each dependency includes a `snyk:npm:scope` property (`prod`, `dev`, or `unknown`). For Maven projects, each dependency includes a `snyk:maven:build_scope` property (`compile`, `provided`, `runtime`, `test`, `system`, or `unknown`). For details, see [Snyk-specific SBOM component properties](sbom.md#snyk-specific-sbom-component-properties). + ### `--remote-repo-url=` Set or override the remote URL for the repository. diff --git a/docs/developer-tools/snyk-cli/commands/sbom.md b/docs/developer-tools/snyk-cli/commands/sbom.md index 6a13d1296cbf..c931f9a60255 100644 --- a/docs/developer-tools/snyk-cli/commands/sbom.md +++ b/docs/developer-tools/snyk-cli/commands/sbom.md @@ -77,7 +77,7 @@ Applicable only for some package managers, for example, `devDependencies` in npm When `--dev` is used with the SPDX format, the development-only dependencies are included in the `DEV_DEPENDENCY_OF` relationship. -When `--dev` is used with the CycloneDX format, development-only dependencies are not labeled differently from non-development dependencies. +When `--dev` is used with the CycloneDX format, development-only dependencies are identified via the `snyk:npm:scope` component property with value `dev`. See [Snyk-specific SBOM component properties](sbom.md#snyk-specific-sbom-component-properties). **Note**: This option can be used with Maven, npm, and Yarn projects. @@ -300,6 +300,72 @@ Use a double dash (`--`) after the complete Snyk command to pass additional opti Example: `snyk sbom -- -s settings.xml` +## Snyk-specific SBOM component properties + +Snyk enriches every component (CycloneDX) or package (SPDX) in the generated SBOM with custom properties that provide additional metadata about each dependency. These properties are present in all commands that produce SBOM output, including `snyk sbom`, `snyk test --print-deps --json`, and `snyk monitor --print-deps --json`. + +### CycloneDX format + +In CycloneDX SBOM documents, Snyk-specific properties appear in the `properties` array of each component. Example: + +```json +{ + "type": "library", + "name": "lodash", + "version": "4.17.21", + "purl": "pkg:npm/lodash@4.17.21", + "properties": [ + { + "name": "snyk:npm:scope", + "value": "prod" + } + ] +} +``` + +### SPDX format + +In SPDX v2.3 JSON SBOM documents, Snyk-specific properties appear as annotations on the corresponding package entry. Example: + +```json +{ + "SPDXID": "SPDXRef-lodash", + "name": "lodash", + "versionInfo": "4.17.21", + "annotations": [ + { + "annotationType": "OTHER", + "annotator": "Tool: Snyk", + "annotationDate": "2024-01-01T00:00:00Z", + "comment": "snyk:npm:scope=prod" + } + ] +} +``` + +### `snyk:npm:scope` + +For NPM, PNPM and Yarn projects, each component includes a `snyk:npm:scope` property indicating the dependency scope. + +| Value | Description | +|---|---| +| `prod` | Production dependency (`dependencies` in `package.json`) | +| `dev` | Development-only dependency (`devDependencies` in `package.json`) | +| `unknown` | Scope could not be determined | + +### `snyk:maven:build_scope` + +For Maven projects, each component includes a `snyk:maven:build_scope` property indicating the Maven dependency scope declared in `pom.xml`. + +| Value | Description | +|---|---| +| `compile` | Default scope; available on the classpath in all phases | +| `provided` | Available at compile time; provided by the JDK or runtime container and not included in the final artifact | +| `runtime` | Not required for compilation but required for execution | +| `test` | Only required for test compilation and execution; not included in the final artifact | +| `system` | Similar to `provided` but the dependency JAR is specified explicitly via a local path | +| `unknown` | Scope could not be determined | + ## Examples for the snyk sbom command ### Create a CycloneDX JSON document for a local software project diff --git a/docs/developer-tools/snyk-cli/commands/test.md b/docs/developer-tools/snyk-cli/commands/test.md index 51c14204b4c8..c6ed22a5154c 100644 --- a/docs/developer-tools/snyk-cli/commands/test.md +++ b/docs/developer-tools/snyk-cli/commands/test.md @@ -92,6 +92,8 @@ Default: false Print the dependency tree before sending it for analysis. +The output includes Snyk-specific component properties for each dependency. For npm and Yarn projects, each dependency includes a `snyk:npm:scope` property (`prod`, `dev`, or `unknown`). For Maven projects, each dependency includes a `snyk:maven:build_scope` property (`compile`, `provided`, `runtime`, `test`, `system`, or `unknown`). For details, see [Snyk-specific SBOM component properties](sbom.md#snyk-specific-sbom-component-properties). + ### `--remote-repo-url=` Set or override the remote URL for the repository. diff --git a/docs/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md b/docs/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md index 84a21ffdf1aa..75b14a24559b 100644 --- a/docs/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md +++ b/docs/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md @@ -26,10 +26,22 @@ SBOM documents can be generated in [CycloneDX](https://cyclonedx.org/) v1.4, v1. ## Custom CycloneDX properties -An SBOM document generated by Snyk will include some Snyk-specific metadata about what has been exported. This is included in the `metadata.properties` section of the document when exported as CycloneDX. +An SBOM document generated by Snyk includes Snyk-specific properties at two levels: the document metadata and individual components. + +### Document-level properties + +Snyk-specific metadata about the exported project is included in the `metadata.properties` section of the CycloneDX document.
Property NameDescription
snyk:org_idThe organization ID (UUID), if applicable
snyk:collection_idThe project collection’s ID (UUID), if applicable
snyk:project_idThe project’s ID (UUID), if applicable
snyk:target_idThe target’s ID (UUID), if applicable
+### Component-level properties + +Snyk enriches each component in the generated SBOM with additional properties that describe the dependency scope within the project. These properties appear in the `properties` array of each CycloneDX component, and as package annotations in SPDX documents. + +
Property NameApplicable ecosystemsDescription
snyk:npm:scopeNPM, PNPM, YarnThe dependency scope for NPM, PNPM and Yarn packages. Possible values: prod (production dependency), dev (development-only dependency), unknown (scope could not be determined).
snyk:maven:build_scopeMavenThe Maven build scope declared in pom.xml. Possible values: compile, provided, runtime, test, system, unknown.
+ +For a detailed description of each scope value, see [Snyk-specific SBOM component properties](../../../developer-tools/snyk-cli/commands/sbom.md#snyk-specific-sbom-component-properties) in the `snyk sbom` command reference. + ## Troubleshooting for the endpoint Get a project's SBOM document The following response code indicates success.