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.
| Format | What it carries | Typical consumer |
|---|---|---|
| CycloneDX 1.5 | Every direct and transitive component, with licenses and package URLs. On request, CVEs with their reachability and patch status | Dependency-Track, ASPM tools, customers who ask for an SBOM |
| SPDX 2.3 | The same inventory in SPDX | Procurement, federal and regulatory requests |
| OpenVEX 0.2.0 | A status per CVE: affected, not affected, fixed, or under investigation, with the reachability reason or the patch that fixed it | ASPM 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-idSBOM
# 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.jsonThe CycloneDX check prints:
{ "bomFormat": "CycloneDX", "specVersion": "1.5", "components": <count> }
The SBOM is an inventory, not a risk reportBy 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.state | Meaning |
|---|---|
not_affected | Unreachable. justification is code_not_reachable |
exploitable | Reachable or potentially reachable. detail gives the call path when one was recorded |
in_triage | No conclusion. detail says why |
resolved_with_pedigree | Fixed 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.jsonEach statement names the CVE (with its GHSA alias), the package URL, and a status:
| Status | Meaning |
|---|---|
affected | Reachable 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_affected | Unreachable. justification is vulnerable_code_not_in_execute_path |
fixed | A 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_investigation | No 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.urlis the patch's page on socket.dev, with its diff and the CVEs it fixes.resolveslists each advisory once.idis the CVE ID when there is one, and the GHSA ID otherwise.typeisunofficialbecause the patch comes from Socket, not from the package's maintainer.supplieris Socket Inc, which supplies the patched copy.publisherstays 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.jsonSPDX
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.jsonThe 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.jsonWhen 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 vexwrites its own OpenVEX document straight from your project, without a scan. It reports a patched CVE asnot_affected. See Prove what you patched.
Verify
- Both SBOM exports return valid JSON, with direct and transitive dependencies listed
-
specVersionis1.5in the CycloneDX export - The OpenVEX export has
statements, including at least onenot_affectedwithvulnerable_code_not_in_execute_path -
affectedstatements for reachable CVEs include a call path instatus_notes - If the scan has patched packages, the CycloneDX export shows
pedigree.patcheson them and the OpenVEX export reports their CVEs asfixed - The receiving tool imports both files and suppresses the not-affected CVEs
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| 404 | Wrong path | Only export/cdx, export/spdx and export/openvex exist. There is no export/vex |
No not_affected statements | The scan has no Unreachable results yet | Export a full application scan, or rescan if results were pending |
CycloneDX export has no vulnerabilities | include_vulnerabilities defaults to false | Add ?include_vulnerabilities=true |
| SBOM is missing packages | The scan was made without a lockfile | See the troubleshooting table in Connect your repositories |
Reference
Updated 4 days ago