Dependency-Track

Plans: Every plan. Refused with 402 while the workspace is read-only. Who: an owner or admin creates the API token; a Dependency-Track administrator sets up the alert.

If you already upload BOMs to Dependency-Track, it can send each one on to Pharus as soon as it has processed it, so there is no script to maintain. Dependency-Track’s BOM_PROCESSED notification carries the BOM; Pharus stores it for a product family exactly as if it came through POST /api/v1/sboms.

POST https://app.pharussecurity.com/api/v1/connectors/dependency-track

Before you start

Dependency-Track 4.11 or a later 4.x release. Version 5 leaves the BOM out of its notifications, and versions before 4.11 can’t send the token in a header. For those, use the export job below.
BOMs uploaded to Dependency-Track as CycloneDX JSON. Dependency-Track forwards the BOM exactly as it was uploaded, and Pharus doesn’t read XML.
BOMs up to about 3 MB. Notifications aren’t compressed, and a request may be at most 4 MB. Use the export job for larger BOMs.

Map projects to product families

A token belongs to one product family, so you set up one alert per family:

Pharus	Dependency-Track
One product family	One alert, limited to that family’s projects
One API token for the family	Sent by that alert in a header
The product version	The project version, else the version in the BOM, else the family’s current version

Without a limit to projects, BOMs from every project in Dependency-Track end up in that one product family.

Set up the alert

Create a token in Pharus

Under Settings → API tokens, create a token for the product family that the Dependency-Track projects belong to. See create a token.

Create the alert in Dependency-Track

In Dependency-Track, go to Administration → Notifications → Alerts and choose Create Alert. Name it Pharus, then set Scope to Portfolio, Notification level to Informational and Publisher to Outbound Webhook.

Point it at Pharus

Open the new alert and fill in:

Destination: https://app.pharussecurity.com/api/v1/connectors/dependency-track
API token header: Authorization
API token: type Bearer, a space, then the token from step 1. Dependency-Track sends it in a header, never in the URL.

Under Group, tick BOM_PROCESSED only, then choose Submit.

Limit it to the family's projects

Choose Limit To and add this family’s projects under Limit to projects.

Test it

Choose Perform Test. When the token’s Last used time under Settings → API tokens changes, the alert works. From then on, each BOM shows up under SBOMs in Pharus shortly after Dependency-Track has processed it.

The Dependency-Track tab of Connect a pipeline on the SBOMs page has the same steps, with your destination URL ready to copy.

Authentication

Pharus reads the token from the Authorization header, as Bearer phr_... or a bare phr_..., or from Dependency-Track’s default X-Api-Key header. It never accepts the token in the URL.

What Pharus does with a notification

Notification	What happens
`BOM_PROCESSED` with a BOM	Pharus stores the BOM for the token’s family and matches it. The same BOM sent again is ignored.
`BOM_CONSUMED` with a BOM	Treated like `BOM_PROCESSED`
`Perform Test`	Pharus checks the token and answers that it works. Nothing is stored.
Any other group	Acknowledged and dropped

The SBOM shows Dependency-Track as its Source, and the Dependency-Track project’s name as the Repository in its Pipeline card. Requests count towards the token’s rate limit of 60 per hour, test notifications too.

Responses

A stored BOM gets the same 202 and 200 answers as POST /api/v1/sboms. The endpoint also answers:

Status	Body	Meaning
200	`{ "test": true, "group": "BOM_PROCESSED", "message": "..." }`	A `Perform Test` notification. The message warns when the workspace is read-only.
202	`{ "ignored": true, "group": "...", "message": "..." }`	A group other than `BOM_PROCESSED` or `BOM_CONSUMED`
400	`invalid_json`	The body isn’t JSON
400	`invalid_notification`	Not a Dependency-Track BOM notification. Use the `Outbound Webhook` publisher with its default template. `detail` says what was missing.
401	`unauthorized`	Set `API token header` to `Authorization` and `API token` to `Bearer phr_...`
415	`unsupported_media_type`	The notification wasn’t sent as JSON
415	`xml_unsupported`	The BOM was uploaded to Dependency-Track as XML. Upload CycloneDX JSON, or use the export job.
422	`bom_omitted`	The notification has no BOM in it, as with Dependency-Track 5. Use the export job.

The other errors (402, 413, 415 unsupported_format, 422 too_many_components, 429) are the same as for POST /api/v1/sboms. Dependency-Track logs the response, so the message is there when an alert fails.

Or push from a job

For Dependency-Track 5, versions before 4.11 and BOMs above about 3 MB, export the project’s BOM through the Dependency-Track API and send it to Pharus, for example from a nightly job. The Dependency-Track API key needs the VIEW_PORTFOLIO permission.

# DTRACK_URL: your Dependency-Track API server · DTRACK_API_KEY: key with VIEW_PORTFOLIO
# DTRACK_PROJECT: the project UUID · PRODUCT_VERSION: e.g. 4.2 · PHARUS_TOKEN: the family's token
curl -sSf "$DTRACK_URL/api/v1/bom/cyclonedx/project/$DTRACK_PROJECT?format=json" \
  -H "X-Api-Key: $DTRACK_API_KEY" \
  | gzip | curl --fail-with-body -sS -X POST "https://app.pharussecurity.com/api/v1/sboms" \
      -H "Authorization: Bearer $PHARUS_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Content-Encoding: gzip" \
      -H "X-Pharus-Source: dependency_track" \
      -H "X-Pharus-Version: $PRODUCT_VERSION" \
      --data-binary @-

Overview

SBOM ingest

CI pipelines

Outgoing webhooks

Public endpoints

Dependency-Track

Before you start

Map projects to product families

Set up the alert

Authentication

What Pharus does with a notification

Responses

Or push from a job

Upload an SBOM

API introduction

SBOMs

Product families

​Before you start

​Map projects to product families

​Set up the alert

​Authentication

​What Pharus does with a notification

​Responses

​Or push from a job

​Related

Upload an SBOM

API introduction

SBOMs

Product families

Before you start

Map projects to product families

Set up the alert

Authentication

What Pharus does with a notification

Responses

Or push from a job

Related