Export SBOM and VEX

Hand your dependency inventory and reachability results to the tools that already track them.

Every scan can be exported in three standard formats. Use an SBOM for the inventory procurement and compliance ask for, and OpenVEX to tell a vulnerability tool which CVEs don't affect you.

FormatWhat it carriesTypical consumer
CycloneDX 1.5Every direct and transitive component, with licenses and package URLs. On request, CVEs with their reachability and patch statusDependency-Track, ASPM tools, customers who ask for an SBOM
SPDX 2.3The same inventory in SPDXProcurement, federal and regulatory requests
OpenVEX 0.2.0A status per CVE: affected, not affected, fixed, or under investigation, with the reachability reason or the patch that fixed itASPM and vulnerability management tools that import VEX

Before you start: a completed scan, and its ID. The scan ID is the last part of the scan's report URL, after /sbom/. For VEX, use a scan from full application reachability where you can. A precomputed scan exports every direct-dependency CVE as under_investigation, so it carries far fewer not-affected statements; in one test app, 37 of 49 statements were under_investigation on the precomputed scan.

export SOCKET_CLI_API_TOKEN=...
SCAN_ID=your-scan-id

SBOM

# CycloneDX
curl -s -H "Authorization: Bearer $SOCKET_CLI_API_TOKEN" \
  "https://api.socket.dev/v0/orgs/your-org/export/cdx/$SCAN_ID" > sbom.cdx.json
jq '{bomFormat, specVersion, components: (.components | length)}' sbom.cdx.json

# SPDX
curl -s -H "Authorization: Bearer $SOCKET_CLI_API_TOKEN" \
  "https://api.socket.dev/v0/orgs/your-org/export/spdx/$SCAN_ID" > sbom.spdx.json
jq '{spdxVersion, name, packages: (.packages | length)}' sbom.spdx.json

The CycloneDX check prints:

{ "bomFormat": "CycloneDX", "specVersion": "1.5", "components": <count> }
📘

The SBOM is an inventory, not a risk report

By default neither SBOM carries vulnerabilities, and neither carries Socket's behavioral findings such as malware or install scripts. The CycloneDX export adds vulnerabilities when you pass include_vulnerabilities=true. CVEs and their reachability travel in the OpenVEX export. Behavioral findings stay in the dashboard and API. For a full picture in Dependency-Track or an ASPM tool, import the CycloneDX SBOM and apply the OpenVEX document to it.

With include_vulnerabilities=true, each CVE in the CycloneDX export comes with an analysis that gives its status:

analysis.stateMeaning
not_affectedUnreachable. justification is code_not_reachable
exploitableReachable or potentially reachable. detail gives the call path when one was recorded
in_triageNo conclusion. detail says why
resolved_with_pedigreeFixed by an applied Socket Certified Patch. See Patched packages

A CVE the scan has no reachability result for has no analysis. A CVE that affects several components with different results is listed once per result, under the same ID.

OpenVEX

curl -s -H "Authorization: Bearer $SOCKET_CLI_API_TOKEN" \
  "https://api.socket.dev/v0/orgs/your-org/export/openvex/$SCAN_ID" > socket.vex.json

jq '.statements | group_by(.status) | map({status: .[0].status, count: length})' socket.vex.json
jq '[.statements[] | select(.status == "not_affected")][0]
    | {cve: .vulnerability.name, product: .products[0], justification}' socket.vex.json

Each statement names the CVE (with its GHSA alias), the package URL, and a status:

StatusMeaning
affectedReachable or potentially reachable; status_notes gives the call path when one was recorded. A CVE the scan has no reachability result for is also affected, with no status_notes
not_affectedUnreachable. justification is vulnerable_code_not_in_execute_path
fixedA Socket Certified Patch that fixes the CVE is applied. status_notes names the patch and gives the reachability result when the scan has one
under_investigationNo conclusion: pending, not yet supported, or a direct dependency on a precomputed scan. status_notes says which

In a monorepo a package can have one result per workspace. Both the OpenVEX and the CycloneDX export treat it as reachable if any workspace reaches the vulnerable code, and as unreachable only if every workspace finds it unreachable.

Import socket.vex.json with your tool's VEX or OpenVEX import. The not_affected statements are what let it suppress unreachable findings. Spot-check a few of them against the same scan in the dashboard before you rely on the import.

Patched packages

When a scan includes packages patched with Socket Certified Patches, each export records the patch. The package URL stays the upstream one, so other tools still match the component.

CycloneDX

A patched component carries a pedigree with the patch and the advisories it resolves, and a socket:patch:uuid property:

{
  "type": "library",
  "name": "minimist",
  "version": "1.2.2",
  "purl": "pkg:npm/[email protected]",
  "pedigree": {
    "patches": [
      {
        "type": "unofficial",
        "diff": { "url": "https://socket.dev/patch/642d7f02-ebc1-4ab0-99e2-07f5dd8463cb" },
        "resolves": [
          {
            "type": "security",
            "id": "CVE-2021-44906",
            "name": "GHSA-xvch-5gv4-984h",
            "source": {
              "name": "GitHub Security Advisory",
              "url": "https://github.com/advisories/GHSA-xvch-5gv4-984h"
            }
          }
        ]
      }
    ],
    "notes": "Socket patch 642d7f02-ebc1-4ab0-99e2-07f5dd8463cb applied"
  },
  "supplier": { "name": "Socket Inc" },
  "properties": [
    { "name": "socket:patch:uuid", "value": "642d7f02-ebc1-4ab0-99e2-07f5dd8463cb" }
  ]
}
  • diff.url is the patch's page on socket.dev, with its diff and the CVEs it fixes.
  • resolves lists each advisory once. id is the CVE ID when there is one, and the GHSA ID otherwise.
  • type is unofficial because the patch comes from Socket, not from the package's maintainer.
  • supplier is Socket Inc, which supplies the patched copy. publisher stays the package's original author.

Add include_vulnerabilities=true to list vulnerabilities in the SBOM. An advisory that the patch fixes then gets its own entry for the patched component:

{
  "id": "GHSA-xvch-5gv4-984h",
  "source": {
    "name": "GitHub Security Advisory",
    "url": "https://github.com/advisories/GHSA-xvch-5gv4-984h"
  },
  "affects": [{ "ref": "<bom-ref of the patched component>" }],
  "analysis": {
    "state": "resolved_with_pedigree",
    "detail": "Fixed by Socket patch 642d7f02-ebc1-4ab0-99e2-07f5dd8463cb"
  }
}

When the scan has a reachability result for the CVE, detail continues with it: Fixed by Socket patch 642d7f02-ebc1-4ab0-99e2-07f5dd8463cb. Reachability:Unreachable(vulnerability is not reachable in this context).

A component that has the same vulnerability and no patch keeps its own entry, with its reachability analysis.

List the patched components and what each patch fixes:

curl -s -H "Authorization: Bearer $SOCKET_CLI_API_TOKEN" \
  "https://api.socket.dev/v0/orgs/your-org/export/cdx/$SCAN_ID?include_vulnerabilities=true" > sbom.cdx.json

jq -r '.components[] | select(.pedigree.patches)
    | "\(.purl)  \(.pedigree.patches[0].diff.url)  fixes: \([.pedigree.patches[0].resolves[]?.id] | join(", "))"' sbom.cdx.json

SPDX

SPDX 2.3 has no field for a vulnerability's status, so a patched package carries a SECURITY external reference of type fix instead. Its comment names the advisories:

{
  "referenceCategory": "SECURITY",
  "referenceType": "fix",
  "referenceLocator": "https://socket.dev/patch/642d7f02-ebc1-4ab0-99e2-07f5dd8463cb",
  "comment": "Socket patch 642d7f02-ebc1-4ab0-99e2-07f5dd8463cb applied; fixes CVE-2021-44906 (GHSA-xvch-5gv4-984h)"
}
jq -r '.packages[] | select(any(.externalRefs[]?; .referenceCategory == "SECURITY" and .referenceType == "fix"))
    | "\(.name)@\(.versionInfo)"' sbom.spdx.json

The patched package's supplier is Organization: Socket Inc. Its originator names the original author, or is NOASSERTION when the scan does not know one.

include_vulnerabilities has no effect on the SPDX export. A scan made from an uploaded SPDX file is exported from that file and carries no patch references.

OpenVEX

A CVE fixed by an applied patch is reported as fixed, whatever its reachability:

{
  "vulnerability": {
    "name": "CVE-2021-44906",
    "@id": "https://nvd.nist.gov/vuln/detail/CVE-2021-44906",
    "aliases": ["GHSA-xvch-5gv4-984h"]
  },
  "products": [
    {
      "@id": "pkg:npm/[email protected]",
      "identifiers": { "purl": "pkg:npm/[email protected]" }
    }
  ],
  "status": "fixed",
  "status_notes": "Vulnerability patched by Socket Security patch 642d7f02-ebc1-4ab0-99e2-07f5dd8463cb.",
  "timestamp": "2026-11-18T15:38:37Z"
}
jq -r '.statements[] | select(.status == "fixed") | "\(.vulnerability.name)  \(.status_notes)"' socket.vex.json

When the scan has a reachability result for the CVE, status_notes continues with it, for example Reachability analysis determined the vulnerable code path is not executed in this context.

What counts as patched

  • The exports record a patch only when the scan recognised it, which the dashboard shows with the Patched badge. Socket reads applied patches from npm, Python, Go, Rust and Ruby lockfiles.
  • A patch that Socket has withdrawn is not reported as a fix.
  • socket-patch vex writes its own OpenVEX document straight from your project, without a scan. It reports a patched CVE as not_affected. See Prove what you patched.

Verify

  • Both SBOM exports return valid JSON, with direct and transitive dependencies listed
  • specVersion is 1.5 in the CycloneDX export
  • The OpenVEX export has statements, including at least one not_affected with vulnerable_code_not_in_execute_path
  • affected statements for reachable CVEs include a call path in status_notes
  • If the scan has patched packages, the CycloneDX export shows pedigree.patches on them and the OpenVEX export reports their CVEs as fixed
  • The receiving tool imports both files and suppresses the not-affected CVEs

Troubleshooting

SymptomCauseFix
404Wrong pathOnly export/cdx, export/spdx and export/openvex exist. There is no export/vex
No not_affected statementsThe scan has no Unreachable results yetExport a full application scan, or rescan if results were pending
CycloneDX export has no vulnerabilitiesinclude_vulnerabilities defaults to falseAdd ?include_vulnerabilities=true
SBOM is missing packagesThe scan was made without a lockfileSee the troubleshooting table in Connect your repositories

Reference


Did this page help you?