Running v4 and v5 in parallel

Given an existing production deployment of v4, it can be helpful to run a v5 test deployment in parallel, to compare behavior and test new features on real data. This is useful for evaluation and validation before committing to the one-shot data migration described in Migrating from v4 to v5.

Note that this technique mirrors only BOM uploads, not full request traffic. v4 emits a BOM_PROCESSED notification after synchronizing each BOM with its database; the parallel v5 instance receives that notification and re-uploads the BOM. Anything not driven by a BOM upload (manual project edits, policy changes, findings triage, notifications) does not replicate.

The subject of BOM_PROCESSED notifications contains the original BOM (Base64-encoded), plus the name and version of the target project, which is enough to construct a BOM upload request for another Dependency-Track instance.

All that's needed is an app that can:

• Receive Webhooks, and parse the JSON payload within them
• Perform a mapping from notification subject, to BOM upload request
• Forward the BOM upload request to another Dependency-Track instance

This can be scripted, but Bento reduces it to a single config file.

Tip

You can use the same approach outlined here to construct a pre-prod / staging environment.

Conceptually, this is what the setup does:

sequenceDiagram
    Client->>DT v4: Upload BOM<br/>PUT /api/v1/bom
    DT v4->>DT v4: Validate and<br/>Process
    DT v4->>Bento: Notification<br/>BOM_PROCESSED
    Bento->>Bento: Map to BOM<br/>upload request
    Bento->>DT v5: Upload BOM<br/>PUT /api/v1/bom
    DT v5->>DT v5: Validate and<br/>Process

Creating an API key

To upload BOMs to the Dependency-Track v5 system, an API key with BOM_UPLOAD and PROJECT_CREATION_UPLOAD permissions is required. Log into your Dependency-Track v5 instance, navigate to Administration -> Access Management -> Teams, and create a new team with accompanying API key:

Deploy Bento

Bento works with the concept of pipelines, which are configured via YAML. The following pipeline achieves the desired outcome:

---
input:
  http_server:
    path: /notification/bom-processed
    allowed_verbs:
    - POST
    timeout: 5s
    sync_response:
      status: "202"

pipeline:
  processors:
  - mapping: |
      root.projectName = this.notification.subject.project.name
      root.projectVersion = this.notification.subject.project.version
      root.projectTags = this.notification.subject.project.tags.split(",").catch([]).map_each(tag -> {"name": tag})
      root.bom = this.notification.subject.bom.content
      root.autoCreate = true

output:
  http_client:
    url: "${DTV5_API_URL}/api/v1/bom"
    verb: PUT
    headers:
      Content-Type: application/json
      X-Api-Key: "${DTV5_API_KEY}"
    max_in_flight: 10
    # tls:
    #  skip_cert_verify: true
    #  ^-- Uncomment this if you're using self-signed certificates.

Refer to the respective pipeline component's documentation for more details:

• http_server input
• mapping processor
• http_client output

Run Bento as container:

docker run -d --name bento \
    -p "4195:4195" \
    -v "$(pwd)/config.yaml:/bento.yaml" \
    -e 'DTV5_API_URL=https://dtv5.example.com' \
    -e 'DTV5_API_KEY=odt_****************' \
    ghcr.io/warpstreamlabs/bento

Configure notification

Log into your Dependency-Track v4 instance, navigate to Administration -> Notifications -> Alerts, and create a new alert with the following settings:

• Scope: Portfolio
• Notification level: Informational
• Publisher: Outbound Webhook

Once created, enable BOM_PROCESSED under Groups, and configure the URL of your Bento endpoint as Destination:

Testing

• Upload a BOM to a project in your Dependency-Track v4 instance.
• Head over to your Dependency-Track v5 instance and wait for the upload to replicate.

If all goes well, you're done.

Tip

If the BOM upload does not replicate:

1. Check the logs of your Dependency-Track v4 deployment for any errors during notification publishing.
2. Check the logs of Bento for any errors or warnings.
3. Check the logs of your Dependency-Track v5 deployment for any errors during BOM processing.
4. Ensure that the API key you created has the correct permissions.
5. Ensure that Bento is reachable from your Dependency-Track v4 deployment.
6. Ensure that your Dependency-Track v5 deployment is reachable from Bento.