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

# Dependency-Track

> Forward every BOM that Dependency-Track 4.11 or later 4.x processes to Pharus with an Outbound Webhook alert, one per product family.

<Info>
  **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.
</Info>

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`](/api-reference/sboms).

```text theme={null}
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](#or-push-from-a-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 |

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

## Set up the alert

<Steps>
  <Step title="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](/api-reference/introduction#create-a-token).
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Limit it to the family's projects">
    Choose `Limit To` and add this family's projects under `Limit to projects`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/api-reference/introduction#rate-limits) of 60 per hour, test notifications too.

## Responses

A stored BOM gets the same `202` and `200` answers as [`POST /api/v1/sboms`](/api-reference/sboms#responses). 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`](/api-reference/sboms#errors). 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.

```bash theme={null}
# 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 @-
```

Pharus ignores a BOM it already has, so running the job every night is safe.

## Related

<CardGroup cols={2}>
  <Card title="Upload an SBOM" icon="upload" href="/api-reference/sboms" />

  <Card title="API introduction" icon="key-round" href="/api-reference/introduction" />

  <Card title="SBOMs" icon="package" href="/monitoring/sboms" />

  <Card title="Product families" icon="cpu" href="/monitoring/product-families" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.