> For the complete documentation index, see [llms.txt](https://docs.arnica.io/arnica-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arnica.io/arnica-documentation/inventory/software-bill-of-materials-sbom/api-sbom-scan.md). # API SBOM Scan Submit a pre-built CycloneDX SBOM to Arnica for vulnerability scanning and policy enforcement via API. ## Scanning your SBOM via the Arnica API Arnica's API SBOM scan allows you to submit a pre-built CycloneDX SBOM directly to Arnica for vulnerability scanning and policy enforcement. This feature is designed to scan repositories which produce build artifacts that Arnica would not normally scan, such as jar files or binary executables, in a CI/CD pipeline. ## Prerequisites To use this API, you must create up a policy rule with a `Code risk detected during an API intiated SBOM scan` trigger. On SBOM scan, only findings matching the policy condition are created. When findings are detected, any associated policy actions are executed. There are few typical ways of using this policy trigger: 1. **Report all findings, but do not fail the scan** - Policy rule with an `Always (TRUE)` condition, but no policy actions.
Policy rule with the API initiated SBOM scan trigger, an Always (TRUE) condition and no actions

With no actions selected, Arnica only logs the findings it detects

2. **Fail scans for any High+ severity findings** - Policy rule with a finding severity condition of `High`, with a policy action of `Fail Scan`. The `Fail Scan` policy action causes the SBOM API scan to report a status of `Failure` when one or more findings matching the policy are detected.
Policy rule with the API initiated SBOM scan trigger, a High finding severity condition and a Fail Scan action

The Fail Scan action reports a status of Failure for the scan

We recommend a policy which at least has 1) so that all findings are reported, and some variant on 2) to fail scans depending on your organizational preferences. ## Supported SBOMs and Tool Versions The SBOM API supports SBOMs generated with: * [trivy rootfs](https://trivy.dev/docs/latest/guide/target/rootfs/) * [cdxgen](https://www.npmjs.com/package/@cyclonedx/cdxgen) version `11.x`. Only [specification version 1.6](https://cyclonedx.org/docs/1.6/json/) is supported. ## Using the Arnica SBOM API Directly Alternatively to the actions, the Arnica SBOM API endpoints can be called directly to upload and scan an SBOM and receive a summary of findings. To use these endpoints, sign in to Arnica with an admin account, navigate to **Admin → API**, and create an Arnica API key with the `sbom-api:read` and `sbom-api:write` scopes. ### Endpoints There are two API endpoints: 1. [POST /v1/sbom/scan/upload](https://api.app.arnica.io/swagger#/scopes:%20\[sbom-api:write]/SbomControllerV1_startSbomScan) - Endpoint to start an SBOM scan. Returns an upload URL to `PUT` SBOM JSON content to and a scan ID for polling the status of the scan. Once you have uploaded an SBOM, Arnica begins the scan. 2. [POST /v1/sbom/scan/{scanId}/status](https://api.app.arnica.io/swagger#/scopes:%20\[sbom-api:read]/SbomControllerV1_getSbomScanStatus) - Endpoint to poll for completion of the SBOM scan using the scan ID. Once complete, this endpoint provides a summary of the scan results, including findings identified that violate policies. ## Viewing Results in Arnica Findings detected during an API SBOM scan appear in the Code Risks page alongside findings from other scan types. The `Detected In` column shows `API`, and the table can be filtered by that column.
Code Risks table row for an SCA finding with Detected In set to API

API SBOM scan findings are labelled API in the Detected In column

Dependencies from API SBOM scans also appear in the Inventory SBOM Report page, labelled `API` on the asset and on each package.
SBOM inventory showing packages from an uploaded SBOM labelled API

Each package detected in an API SBOM scan is labelled API

## Configuring an SBOM upload policy At least one SBOM upload policy must be configured for the target repository before a scan can be initiated. To set one up, navigate to **Policies** in the Arnica console and create a policy with the trigger type **API-initiated SBOM scan**. This policy defines which findings will cause a scan to return a `failed` status.