Upload a VEX document

Plans: Every plan. Refused with 402 while the workspace is read-only. Who: anyone with an API token for the product family; owners and admins create tokens.

POST /api/v1/vex stores one VEX document for the product family the token belongs to, binds its statements to the family’s components and matches the family again. It takes the same CI upload token as POST /api/v1/sboms. Send the same file again and Pharus answers with the document it already has, so retries are safe. What Pharus does with the statements is on VEX from other tools.

POST https://app.pharussecurity.com/api/v1/vex

Example

export PHARUS_TOKEN=phr_...   # the product family's token (Settings → API tokens)

govulncheck -format openvex ./... | gzip | curl --fail-with-body -sS -X POST "https://app.pharussecurity.com/api/v1/vex" \
  -H "Authorization: Bearer $PHARUS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: gzip" \
  -H "X-Pharus-Version: 4.2" \
  --data-binary @-

To send Dependency-Track’s analysis with its justifications, export the project’s VDR:

curl -sS -H "X-Api-Key: $DTRACK_API_KEY" \
  "$DTRACK_URL/api/v1/bom/cyclonedx/project/$DTRACK_PROJECT?variant=vdr&format=json" \
  | gzip | curl --fail-with-body -sS -X POST "https://app.pharussecurity.com/api/v1/vex" \
      -H "Authorization: Bearer $PHARUS_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Content-Encoding: gzip" \
      -H "X-Pharus-Source: dependency_track" \
      --data-binary @-

Trivy and Grype findings travel inside a CycloneDX SBOM. Send that SBOM to /api/v1/sboms as usual: Pharus keeps its vulnerabilities as the SBOM’s VEX document.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer phr_...`: an API token for the product family. See authentication.
`Content-Type`	Recommended	`application/json`, `application/vnd.cyclonedx+json` or `application/vnd.openvex+json`. Pharus recognises the format from the content.
`Content-Encoding`	When compressed	`gzip` or `zstd`. Any encoding other than `gzip`, `x-gzip`, `zstd` or `identity` is refused.
`X-Pharus-Version`	No	The product version the document is about, such as `4.2`. Up to 100 characters. Without it, the document holds for every version the family has.
`X-Pharus-Source`	No	Where it came from, shown as Source: `github`, `azure_devops`, `dependency_track`, `sbomify` or `api`. Anything else, or none, shows as API.

The query parameter version works when there is no X-Pharus-Version header.

Body

The raw VEX document, plain or compressed. Not a multipart form, and not wrapped in another JSON object.

OpenVEX, such as govulncheck’s -format openvex output.
CSAF 2.0 VEX.
CycloneDX JSON 1.4–1.7 with a vulnerabilities section: a VEX document, Dependency-Track’s VDR, or Trivy and Grype output.
At most 4 MB as sent, 50 MB decompressed, and 50 000 statements.

A later document from the same tool for the same version replaces the earlier one. See how statements bind.

Responses

202 Accepted

A new document was stored. Matching runs after the response.

{
  "id": "2a7d9c41-6b3e-4f18-9d02-7e5c1a8b3f64",
  "format": "openvex",
  "statements": 12,
  "findings": 0,
  "unbound": 1,
  "version": "4.2",
  "replaced": 1,
  "url": "https://app.pharussecurity.com/sboms/vex/2a7d9c41-6b3e-4f18-9d02-7e5c1a8b3f64",
  "duplicate": false
}

200 OK

The family already has a document with exactly these bytes. Nothing new was stored, replaced is 0, and duplicate is true.

Field	Meaning
`id`	The document’s id in Pharus
`format`	`openvex`, `csaf` or `cyclonedx`
`statements`	Statements with a verdict
`findings`	Scanner findings without a verdict
`unbound`	Statements that name nothing Pharus can bind: no purl or CPE, or an unknown reference
`version`	The product version it holds for, or `null` for every version
`replaced`	Earlier documents from the same source for the same version that this one replaced
`url`	The document’s page in Pharus, for people who are signed in
`duplicate`	`true` when Pharus already had this file for the family

Errors

Errors return { "error", "message" }, sometimes with detail. See the error format.

Status	`error`	What to do
400	`invalid_json`	The body isn’t valid JSON. Check that the file was written completely.
400	`invalid_vex`	The format was recognised, but its structure is broken.
400	`empty`	The body is empty. Check the file path and `--data-binary`.
400	`bad_encoding`	The body couldn’t be decompressed. Send gzip, zstd or plain JSON.
401	`unauthorized`	Check the token, its expiry and its status under Settings → API tokens. The response has a `WWW-Authenticate` header.
402	`billing_lapsed`	The workspace is read-only. An owner subscribes under Settings → Billing, or reopens a closed workspace.
404	`family_not_found`	The token’s product family is no longer available.
413	`too_large`	The document is over 4 MB as sent or 50 MB decompressed.
415	`unsupported_vex`	Send OpenVEX, CSAF 2.0 VEX, or CycloneDX JSON 1.4–1.7 with a `vulnerabilities` section. An SBOM goes to `/api/v1/sboms`.
422	`no_statements`	The document has no vulnerability statements or findings.
422	`too_many_statements`	The document has more than 50 000 statements.
429	`rate_limited`	Wait the number of seconds in `Retry-After`. Each token has 60 requests per hour, shared with `POST /api/v1/sboms`.
500	`internal`	Try again.

Overview

SBOM ingest

CI pipelines

Alerts

Public endpoints

Upload a VEX document

Example

Headers

Body

Responses

202 Accepted

200 OK

Errors

VEX from other tools

Upload an SBOM

Dependency-Track

API introduction

​Example

​Headers

​Body

​Responses

​202 Accepted

​200 OK

​Errors

​Related

VEX from other tools

Upload an SBOM

Dependency-Track

API introduction

Example

Headers

Body

Responses

202 Accepted

200 OK

Errors

Related