Skip to content
Declara
⌘K
engineer

Connect Dependency-Track

Was this page helpful?

If you already run OWASP Dependency-Track, Declara can read your SBOMs from it rather than you uploading them twice. You map each Dependency-Track project to a Declara product. Once a day, Declara fetches each project's current CycloneDX BOM and records it as an SBOM upload for the version the project names. It is then parsed and matched like any other upload.

Declara pulls from Dependency-Track; it never sends anything to it. No alert, reminder or test message goes to your Dependency-Track server.

Dependency-Track is on the plans that include integrations.

Before you start

  • A Dependency-Track server reachable over HTTPS from the internet. If yours is only reachable inside your network, Declara refuses it. Use the push script instead.
  • The address of the API server. When the frontend and the API server are on different hosts, use the API server's host.
  • Each project you map needs its version set in Dependency-Track, such as 4.2.0. That version becomes the Declara product version. It can be up to 100 characters of letters, digits and . _ + ~ : / @ -, and must start with a letter or digit.

Create an API key in Dependency-Track

  1. In Dependency-Track, open Administration → Access Management → Teams and create a team for Declara, for example declara-import.
  2. Give the team the permission to view the portfolio. In Dependency-Track 4.x this is VIEW_PORTFOLIO, and it covers both reading a project and exporting its BOM. Permission names have changed between releases, so check your Dependency-Track version's documentation. Grant read access only: Declara needs no permission to upload, change or delete anything.
  3. If portfolio access control is on, give the team access to the projects you will map.
  4. Generate an API key for the team and copy it.

Declara sends the key in the X-Api-Key header on two requests per project: GET /api/v1/project/{uuid} to read the version, then GET /api/v1/bom/cyclonedx/project/{uuid}?format=json to export the BOM.

Connect it

  1. Open Settings → Integrations. In the Dependency-Track panel, press Connect Dependency-Track.
  2. Enter the API server URL, such as https://dtrack.example.com, and paste the API key.
  3. For each project, add a row with the project's UUID and choose the Declara product it feeds. The UUID is in the project's URL in Dependency-Track. You can map up to 50 projects per connection. Two projects can feed the same product, for example two maintained release lines.
  4. Press Connect.

The key is encrypted before it is stored and is never shown again. The panel says only that it is set. To replace it, press Edit and paste a new one. Leaving the field empty keeps the stored key.

When it runs

  • Daily. Every active connection is synced once a day, early in the morning UTC.
  • Sync now. Press Sync now to queue a sync straight away. It runs in the background, so refresh the page after a minute to see the results.

For each project, the panel shows the outcome of the last sync:

  • imported. The BOM was new or had changed, and an upload was recorded on that version. If the version did not exist yet in Declara, it was created.
  • unchanged. The BOM is identical (same SHA-256) to the latest upload on that version, so nothing was recorded.
  • error. The reason is given in a sentence. Examples: the key was refused, the project has no version, a redirect was answered, or the product no longer exists in this workspace. Declara records only the status code, never what the server said.

One project failing does not stop the others. A connection with any failed project is also counted under Needs attention on the overview, as a failing integration.

Limits and safeguards

  • HTTPS only. The URL may not contain a user name, password, query or fragment.
  • The address is checked before every request, not only when you save it. An address that resolves to a private, loopback or link-local network is refused.
  • Redirects are not followed. A 3xx answer is reported as an error, so give the API server's own URL.
  • Each request times out after 30 seconds. A BOM larger than 25 MB is cut off and reported as an error.

On-premises servers: use the push script

If your Dependency-Track server is not reachable from the internet, run the export where it is reachable and push the result to Declara's SBOM API. You need a Declara API key with the sboms:write scope and the product's ID. Run this from a scheduled job inside your network:

#!/usr/bin/env bash
set -euo pipefail

DT_URL="https://dtrack.internal.example"     # your Dependency-Track API server
DT_API_KEY="..."                              # read-only Dependency-Track key
PROJECT_UUID="3f1c6c2e-8b1a-4f3e-9a51-0d7c2b9e4a10"
DECLARA_URL="https://your-declara-host"
DECLARA_API_KEY="..."                         # Declara key with sboms:write
PRODUCT_ID="your-product-id"

# The project's version becomes the Declara product version.
VERSION=$(curl -sSf -H "X-Api-Key: $DT_API_KEY" \
  "$DT_URL/api/v1/project/$PROJECT_UUID" | jq -r '.version')

curl -sSf -H "X-Api-Key: $DT_API_KEY" \
  "$DT_URL/api/v1/bom/cyclonedx/project/$PROJECT_UUID?format=json" \
  -o bom.json

curl -sS --fail-with-body -X POST \
  "$DECLARA_URL/api/v1/products/$PRODUCT_ID/sboms?version=$(jq -rn --arg v "$VERSION" '$v|@uri')" \
  -H "Authorization: Bearer $DECLARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @bom.json

The push API accepts documents up to 4 MB. For a larger BOM, upload it through the browser. Unlike the daily import, the push records a new upload every time it runs, even when the BOM has not changed, so run it when a project changes rather than on a tight schedule.

Related