> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SCA SBOM Exports

> CycloneDX, SPDX, and VEX artifacts backed by the ZeroPath SCA inventory

## Overview

ZeroPath's SBOM service generates export-ready CycloneDX, SPDX, and VEX documents directly from the SCA inventory your scans already produced. Because SBOMs reuse the same normalized dependency graph that powers alerting, every artifact matches what developers see in the UI — no third-party scanners, no drift.

<Steps>
  <Step title="Request">
    Accepts a request tied to a scan. You can optionally specify an SCA scan for richer inventory data, but it is not required — SBOMs can be generated from any completed code scan.
  </Step>

  <Step title="Process">
    The job is queued and processed, ensuring no duplicate generation.
  </Step>

  <Step title="Build">
    The SBOM is built from the chosen data source (preferably the SCA inventory).
  </Step>

  <Step title="Upload">
    Uploads the JSON artifact to managed object storage and returns a pre-signed download URL.
  </Step>

  <Step title="Track">
    Tracks status, attempt count, and expiration so you can poll or receive webhook updates.
  </Step>
</Steps>

## Request Flow

<Steps>
  <Step title="Submit">
    Choose the scan, desired format (CycloneDX or SPDX), and whether to include VEX data. Jobs can be created through the UI or API.
  </Step>

  <Step title="Process">
    ZeroPath processes the job, hydrates the dependency inventory, and generates the artifact. Automatic retries handle any interruptions.
  </Step>

  <Step title="Store">
    Finished SBOMs are uploaded to ZeroPath's artifact bucket with a time-limited retention policy (24 hours by default, configurable per tenant).
  </Step>

  <Step title="Retrieve">
    The API returns a signed URL; optional webhooks fire when the job transitions to `Succeeded` or `Failed`.
  </Step>
</Steps>

## Formats & VEX Support

<Tabs>
  <Tab title="CycloneDX JSON">
    Best for tooling that expects component graphs, dependency relationships, and VEX attachments. When VEX is requested we include vulnerability status (`affected`, `not_affected`, `fixed`) plus severity and remediation guidance.
  </Tab>

  <Tab title="SPDX JSON">
    Aligns with procurement/legal workflows. ZeroPath includes annotations for direct vs transitive dependencies, license declarations, and dependency relationships (`DEPENDS_ON`, `DESCRIBES`).
  </Tab>

  <Tab title="VEX">
    Only available when the SBOM is sourced from the ZeroPath SCA inventory (that's where we track vulnerability status). If a job targets a raw repository snapshot, VEX must be disabled.
  </Tab>
</Tabs>

## Data Sources

<Tabs>
  <Tab title="Preferred: SCA Inventory">
    * Uses the canonical inventory built by the ZeroPath SCA service, so it includes direct/transitive classification, license data, application ownership, and previously validated vulnerability context.
    * SBOMs generated from inventory are deterministic — package IDs, ordering, and dependency edges match the UI and alerting systems exactly.
    * VEX data is available because the inventory knows which packages are affected, fixed, or not applicable.
  </Tab>

  <Tab title="Fallback: Repository Snapshot">
    * Used when a team requests an SBOM before a full SCA scan finishes.
    * ZeroPath clones the repository at the requested commit, parses manifests/lockfiles, and outputs the same CycloneDX/SPDX structure.
    * Because no historical inventory exists, these SBOMs focus on component/relationship data and omit VEX status.
  </Tab>
</Tabs>

## Artifact Contents

Every JSON export includes:

* Repository metadata (name, branch, commit SHA, scan timestamp).
* One entry per manifest path (package-lock.json, requirements.txt, go.mod, pom.xml, Podfile, etc.).
* Normalized ecosystems and Package URLs (PURL) for each dependency.
* Direct vs transitive annotations plus a summary of the dependency path so teams know how a package entered the build.
* License information per package, sourced from manifest fields and/or deps.dev.
* Dependency relationships (CycloneDX `dependencies`, SPDX `relationships`).
* Optional VEX blocks showing current status, ZeroPath vulnerability IDs, severity, and remediation hints.

## Storage & Access

* SBOMs are stored in ZeroPath-managed object storage with an automatic expiration policy (24 hours by default; can be extended for enterprise tenants).
* Download links are pre-signed URLs that carry the same expiration. Pull the artifact into your own storage if you need longer retention.
* Every job records organization, repository, requester, format, and expiration so you always know who generated which SBOM.

## Adoption Guide

<Steps>
  <Step title="Run at Least One SCA Scan">
    This unlocks inventory-backed SBOMs and VEX exports. Schedules keep inventories fresh without manual effort.
  </Step>

  <Step title="Submit SBOM Requests per Release">
    Kick off a job whenever you cut a release branch, tag, or artifact that needs provenance.
  </Step>

  <Step title="Choose the Right Format">
    Use CycloneDX + VEX for engineering/security workflows, SPDX for procurement/legal stakeholders, or both.
  </Step>

  <Step title="Integrate Delivery">
    Plug pre-signed URLs into CI/CD approvals, artifact registries, or audit tickets so reviewers can fetch the document automatically.
  </Step>

  <Step title="Mirror Long-Lived Artifacts">
    If policy requires multi-year retention, copy the SBOM into your own storage before the link expires.
  </Step>
</Steps>

## Troubleshooting Tips

<AccordionGroup>
  <Accordion title="&#x22;VEX requires SCA inventory&#x22;">
    Rerun the job with a completed SCA scan selected or disable VEX for snapshot-based exports.
  </Accordion>

  <Accordion title="&#x22;Repository snapshot failed&#x22;">
    Usually caused by missing SCM credentials or a deleted branch/tag. Re-run after fixing access or target a different commit.
  </Accordion>

  <Accordion title="Incomplete dependency list">
    Verify the latest SCA scan finished successfully and that manifests were included (shown in the SCA tab). SBOMs mirror whatever the scan captured.
  </Accordion>

  <Accordion title="Jobs stuck in Pending or Processing">
    SBOM jobs now update their status automatically when generation completes or fails, even if you close the browser or navigate away before the result appears. If a job still shows as pending after ten minutes, ensure SBOM workers are running for your workspace and contact support if it persists.
  </Accordion>

  <Accordion title="Generation failed with an error message">
    SBOM jobs surface specific failure reasons so you can act on them quickly. Common failure categories include:

    * **Artifact download failed** — the generated SBOM could not be retrieved from storage. This is usually transient; retry the job.
    * **Artifact missing** — generation completed but no downloadable file was produced. Re-run with a scan that has inventory data.
    * **Generation failed** — an error occurred during SBOM assembly. The error message will include details from the processing pipeline.
    * **Timeout** — the job did not finish within the allowed window. This can happen for very large repositories; contact support if it persists.

    Check the error message on the failed job for details — it will indicate whether the issue is with the scan data, artifact storage, or processing pipeline.
  </Accordion>
</AccordionGroup>

## Comparing Results with Other SBOM Tools

When comparing ZeroPath SBOMs against tools like Syft, Trivy, or Grype, you may notice differences in package counts.

### Why Package Counts Differ

| Factor                          | ZeroPath                                | Other Tools (e.g., Syft)                                              |
| ------------------------------- | --------------------------------------- | --------------------------------------------------------------------- |
| **Dev dependencies**            | Excluded by default                     | Often included                                                        |
| **Data source**                 | Lockfiles and manifests                 | May also scan `node_modules` directory, binaries, or container layers |
| **Optional/peer dependencies**  | Included only when resolved in lockfile | May include unresolved optional deps                                  |
| **Workspace/monorepo packages** | Scoped to the target manifest           | May include all workspace packages                                    |