diff --git a/backend/engine/plugins/README.md b/backend/engine/plugins/README.md index cfa2ad58..5548d5f3 100644 --- a/backend/engine/plugins/README.md +++ b/backend/engine/plugins/README.md @@ -191,7 +191,46 @@ Example: ### SBOM -TODO: Add documentation here +SBOM ([software bill of materials](https://en.wikipedia.org/wiki/Software_supply_chain)) plugins gather an inventory of software components such as library dependencies. + +The `details` returned is a 2-element array. + +The first element is an array of SBOMs. These are not modified and are saved as-is for later retrieval. The specific format depends on the plugin, but should be a standard JSON format such as [CycloneDX](https://cyclonedx.org/) or [SPDX](https://spdx.dev/). This may be an empty array if no user-downloadable SBOMs are generated. + +The second element is an array of detected components, with the following fields: + +- `bom-ref`: Unique reference ID for this component. +- `type`: Component type (e.g. `jar`, `gomod`, etc.). This is tool-specific. For example, see the [list of types for Trivy](https://github.com/aquasecurity/trivy/blob/49f354085fdaf0f45f8f8f52c9a2a06fffbc2e63/pkg/fanal/analyzer/const.go). +- `name`: Component name, such as a package ID or filename. +- `version`: Component version. If not available or does not apply for this component type, must be `none`. +- `licenses`: Array of licenses: + - `id`: The [SPDX license identifier](https://spdx.org/licenses/). + - `name`: The license name. + +Full example: + +```jsonc +[ + [ + { /* SBOM for component 1... */ }, + { /* SBOM for component 2... */ } + ], + [ + { + "bom-ref": "pkg:golang/cloud.google.com/go/datastore@1.1.0", + "type": "gomod", + "name": "cloud.google.com/go/datastore", + "version": "1.1.0", + "licenses": [ + { + "id": "Apache-2.0", + "name": "Apache-2.0" + } + ] + } + ] +] +``` ### Inventory diff --git a/backend/utilities/plugin_runner/toolbox/lint.go b/backend/utilities/plugin_runner/toolbox/lint.go index a63c7db6..e5bc10aa 100644 --- a/backend/utilities/plugin_runner/toolbox/lint.go +++ b/backend/utilities/plugin_runner/toolbox/lint.go @@ -37,6 +37,7 @@ var pluginTypeSchemaMap = map[string]string{ "configuration": "configuration-finding", "inventory": "unknown-finding", // Open-ended schema. "secrets": "secrets-finding", + "sbom": "sbom-finding", "static_analysis": "static-analysis-finding", "vulnerability": "vulnerability-finding", } diff --git a/backend/utilities/plugin_runner/toolbox/schemas/sbom-finding.json b/backend/utilities/plugin_runner/toolbox/schemas/sbom-finding.json new file mode 100644 index 00000000..a8ee542a --- /dev/null +++ b/backend/utilities/plugin_runner/toolbox/schemas/sbom-finding.json @@ -0,0 +1,55 @@ +{ + "$id": "https://wbd.com/artemis/plugin/sbom-finding.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + + "title": "SBOMFinding", + "type": "array", + "items": false, + "prefixItems": [ + { + "type": "array", + "items": { "type": "object" } + }, + { + "type": "array", + "items": { "$ref": "#/$defs/component" } + } + ], + "minItems": 2, + "maxItems": 2, + + "$defs": { + "component": { + "type": "object", + "required": [ + "bom-ref", + "type", + "name", + "version", + "licenses" + ], + "properties": { + "bom-ref": { "type": "string" }, + "type": { "type": "string" }, + "name": { "type": "string" }, + "version": { "type": "string" }, + "licenses": { + "type": "array", + "items": { "$ref": "#/$defs/license" } + } + } + }, + + "license": { + "type": "object", + "required": [ + "id", + "name" + ], + "properties": { + "id": { "type": "string" }, + "name": { "type": "string" } + } + } + } +}