diff --git a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt b/.vale/styles/config/vocabularies/DependencyTrack/accept.txt index ab9a8043..23692ac6 100644 --- a/.vale/styles/config/vocabularies/DependencyTrack/accept.txt +++ b/.vale/styles/config/vocabularies/DependencyTrack/accept.txt @@ -129,6 +129,7 @@ Webex [Ii]dempoten(t|cy) [Jj]etstack [Kk]enna +[Kk]eyless [Ll]iveness [Ll]ookups [Ll]oopback diff --git a/docs/concepts/vulnerability-findings.md b/docs/concepts/vulnerability-findings.md index b4db5eb3..00dec516 100644 --- a/docs/concepts/vulnerability-findings.md +++ b/docs/concepts/vulnerability-findings.md @@ -25,6 +25,12 @@ visible during triage. [Time series metrics](time-series-metrics.md) deduplicate a single underlying vulnerability counted under more than one ID still contributes once to the project's findings total and severity counts. +Analysis runs when you upload a BOM, when you trigger it manually, and on a schedule. The schedule +re-analyzes a project once its last analysis is older than +[`dt.task.portfolio-analysis.max-analysis-age-ms`](../reference/configuration/properties.md#dttaskportfolio-analysismax-analysis-age-ms), +24 hours by default. A vulnerability that a data source publishes after your last upload +still produces a finding, without a new upload. + ## Auditing a finding A finding carries an *analysis* that captures the team's triage decision. The analysis has four diff --git a/docs/guides/user/.pages b/docs/guides/user/.pages index faf4d8e5..5a67fae8 100644 --- a/docs/guides/user/.pages +++ b/docs/guides/user/.pages @@ -1,6 +1,7 @@ title: User guides nav: - index.md + - uploading-boms.md - organizing-projects.md - managing-project-versions.md - managing-component-policies.md diff --git a/docs/guides/user/uploading-boms.md b/docs/guides/user/uploading-boms.md new file mode 100644 index 00000000..f6ae6450 --- /dev/null +++ b/docs/guides/user/uploading-boms.md @@ -0,0 +1,181 @@ +# Uploading BOMs + +Dependency-Track builds a project's component inventory from the BOMs you upload. +Each upload starts vulnerability analysis and policy evaluation for the project. +Upload from the UI for a one-off, or from your pipeline so the inventory follows every build. + +Uploading requires the `BOM_UPLOAD` [permission](../../reference/permissions.md). +Creating the project on first upload also requires `PROJECT_CREATION_UPLOAD`, `PORTFOLIO_MANAGEMENT`, +or `PORTFOLIO_MANAGEMENT_CREATE`. For pipelines, give these permissions to a +[service account](../../concepts/access-control.md#service-accounts) rather than to a person. + +For the BOM formats Dependency-Track accepts, see [File formats](../../reference/file-formats.md). + +## Upload from the UI + +1. Open the project. +2. Select **Upload BOM**. +3. Select **Browse**, choose the BOM file, then select **Upload**. + + +## Upload via REST API + + +Send the BOM as a multipart request to `/api/v1/bom`: + +=== "Bash" + + ```bash + curl -sSf -X POST "https://dependency-track.example.com/api/v1/bom" \ + -H "X-Api-Key: ${DT_API_KEY}" \ + -F "projectName=my-app" \ + -F "projectVersion=1.2.3" \ + -F "autoCreate=true" \ + -F "bom=@bom.json" + ``` + +=== "PowerShell" + + ```powershell + Invoke-RestMethod -Method Post -Uri "https://dependency-track.example.com/api/v1/bom" ` + -Headers @{ "X-Api-Key" = $env:DT_API_KEY } ` + -Form @{ + projectName = "my-app" + projectVersion = "1.2.3" + autoCreate = "true" + bom = Get-Item "bom.json" + } + ``` + +Identify the target project with `project` (its UUID), **or** with `projectName` and `projectVersion`. +With `autoCreate=true`, Dependency-Track creates the project if it doesn't exist. +When it creates one, it also applies these optional fields: + +* `parentUUID`, or `parentName` and `parentVersion`, to place the project in a [hierarchy](organizing-projects.md). +* `projectTags`, a comma-separated list of tags. +* `isLatest=true`, to mark the version as the [latest](managing-project-versions.md#mark-a-version-as-latest). + +Send `isActive` only when you intend to change the project's active state. +It applies to existing projects too. + +To save bandwidth on large BOMs, compress the file with either `gzip` or `zstd` and declare its type. +With curl, use for example `-F "bom=@bom.json.gz;type=application/gzip"`. +For `zstd`, use `application/zstd`. + +A BOM that fails schema validation returns `400 Bad Request`. +For every field and response, see the `UploadBom` operation in the [REST API v1 reference](../../reference/api/v1.md). + +To authenticate without a stored API key, exchange a platform token for a session as described in +[Configuring workload identity federation](../administration/configuring-workload-identity-federation.md#exchange-the-token-in-the-workload), +then send `Authorization: Bearer ${ACCESS_TOKEN}` instead of `X-Api-Key`. + +## Wait for processing to finish + +The upload returns as soon as Dependency-Track stores the BOM. +Processing continues in the background. The response carries a token that tracks it: + +```json +{ + "token": "6a8d3bd2-3f7d-4b9c-9a54-7c1f0e1c2b4e", + "projectUuid": "dadec8ad-7053-4e8c-8044-7b6ef698e08d" +} +``` + +If a later step needs the results, for example to fail the build on policy violations, +poll `/api/v1/event/token/{token}` until processing ends: + +```json +{ + "processing": true, + "status": "RUNNING" +} +``` + +`status` is `PENDING`, `RUNNING`, `COMPLETED`, or `FAILED`. The token covers the BOM import and the +vulnerability analysis and policy evaluation that follow, so `COMPLETED` means the project's +findings and policy violations reflect the uploaded BOM. For a token Dependency-Track doesn't +know, the response carries `"processing": false` and no `status`. + +=== "Bash" + + ```bash + TOKEN=$(curl -sSf -X POST "https://dependency-track.example.com/api/v1/bom" \ + -H "X-Api-Key: ${DT_API_KEY}" \ + -F "projectName=my-app" \ + -F "projectVersion=1.2.3" \ + -F "autoCreate=true" \ + -F "bom=@bom.json" \ + | jq -r .token) + + while true; do + STATUS=$(curl -sSf -H "X-Api-Key: ${DT_API_KEY}" \ + "https://dependency-track.example.com/api/v1/event/token/${TOKEN}" \ + | jq -r '.status // "UNKNOWN"') + case "${STATUS}" in + COMPLETED) break ;; + FAILED | UNKNOWN) echo "BOM processing ended with status ${STATUS}" >&2; exit 1 ;; + esac + sleep 5 + done + ``` + +=== "PowerShell" + + ```powershell + $headers = @{ "X-Api-Key" = $env:DT_API_KEY } + $upload = Invoke-RestMethod -Method Post -Uri "https://dependency-track.example.com/api/v1/bom" ` + -Headers $headers ` + -Form @{ + projectName = "my-app" + projectVersion = "1.2.3" + autoCreate = "true" + bom = Get-Item "bom.json" + } + + while ($true) { + $status = (Invoke-RestMethod -Headers $headers ` + -Uri "https://dependency-track.example.com/api/v1/event/token/$($upload.token)").status ?? "UNKNOWN" + if ($status -eq "COMPLETED") { break } + if ($status -in "FAILED", "UNKNOWN") { throw "BOM processing ended with status $status" } + Start-Sleep -Seconds 5 + } + ``` + +Bound the loop with your CI system's job timeout. + + +## Upload from GitHub Actions + + +The [`gh-upload-sbom`](https://github.com/DependencyTrack/gh-upload-sbom) action wraps the upload request: + +```yaml +- name: Upload BOM + id: upload + uses: DependencyTrack/gh-upload-sbom@v4 + with: + server-hostname: dependency-track.example.com + api-key: ${{ secrets.DEPENDENCYTRACK_APIKEY }} + project-name: my-app + project-version: ${{ github.ref_name }} + bom-filename: bom.json + auto-create: true +``` + +To authenticate without an API key secret, replace `api-key` with `workload-identity-provider`, +`service-account`, and `oidc-audience`, and grant the job `id-token: write`. See the action's +[workload identity federation](https://github.com/DependencyTrack/gh-upload-sbom#workload-identity-federation) +section, and [GitHub Actions](../administration/configuring-workload-identity-federation.md#github-actions) +for the Dependency-Track side. + +The action doesn't wait for processing. It exposes the upload token as `steps.upload.outputs.token`, +so a later step can run the polling loop from [Wait for processing to finish](#wait-for-processing-to-finish) +with `TOKEN` set to that output. + + +## Upload from Jenkins + + +The [Dependency-Track Jenkins plugin](https://plugins.jenkins.io/dependency-track/) uploads BOMs as +a build step. See its documentation for setup. For other CI systems, call the REST API as shown in +[Upload via REST API](#upload-via-rest-api). diff --git a/docs/index.md b/docs/index.md index 7c61c3c1..1a0cef62 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,6 +18,94 @@ An API-first design makes it a natural fit for CI/CD pipelines. This documentation covers Dependency-Track v5. For v4, see the [v4 documentation](../4.x/). +## Features + +### Find and rank vulnerabilities + +- **Continuous monitoring**: Dependency-Track re-analyzes your portfolio on a schedule, + so newly disclosed [vulnerabilities](concepts/vulnerability-findings.md) surface without a new upload. +- **Multiple data sources**: combine [mirrored data sources](concepts/about-vulnerability-data-sources.md) + such as NVD, GitHub Advisories, and OSV + with [analyzers](reference/analyzers.md) such as Sonatype OSS Index, Snyk, Trivy, and VulnDB. +- **Risk-based prioritization**: rank findings by CVSS severity, EPSS exploit prediction, + and [known exploited vulnerability catalogs](concepts/about-kev-data-sources.md) from CISA, ENISA, and VulnCheck. +- **Dashboards and trends**: follow risk scores for the portfolio, each project, and each component + [over time](concepts/time-series-metrics.md). +- **Private vulnerabilities**: track + [issues your organization discovers](guides/user/managing-private-vulnerabilities.md) + alongside public ones. + +### Know what's in your software + +- **BOM import**: upload [CycloneDX](reference/file-formats.md) BOMs from any ecosystem or build tool, + including services and the dependency graph. +- **Portfolio inventory**: [organize projects](guides/user/organizing-projects.md) + with versions, hierarchies, and tags. +- **Portfolio-wide search**: find every project that uses a component, or that a vulnerability affects. +- **Outdated component detection**: check [package repositories](reference/datasources/repositories.md) + such as Maven Central, npm, and PyPI for newer versions, + and [verify component integrity](concepts/component-integrity-verification.md). + +### Enforce policies + +- **License compliance**: flag components with licenses your organization doesn't allow, + using [component policies](concepts/component-policies.md) and license groups. +- **Security and operational rules**: catch high-severity vulnerabilities, outdated or old components, + and banned packages. +- **Custom conditions**: write [condition expressions](reference/policies/condition-expressions.md) in CEL + when the built-in conditions don't fit. +- **Violation review**: [triage policy violations](guides/user/triaging-policy-violations.md) + and approve, reject, or suppress them with a recorded reason. + +### Triage and share decisions + +- **Audit trail**: record an analysis state, justification, and comments for each finding, and keep their history. +- **Automated triage**: apply decisions across the portfolio + with [vulnerability policies](concepts/vulnerability-policies.md), + optionally distributed from a central bundle. +- **VEX and VDR**: [exchange VEX documents](guides/user/exchanging-vex-documents.md) with customers and suppliers, + and export vulnerability disclosure reports. + +### Integrate and automate + +- **API-first**: automate every task available in the UI + through the [v1](reference/api/v1.md) and [v2](reference/api/v2.md) REST APIs. +- **CI/CD**: [upload SBOMs](guides/user/uploading-boms.md) from any pipeline with a single API call, + and let Dependency-Track create the project and version on first upload. +- **Notifications**: send real-time alerts or scheduled summaries + to [Slack, Microsoft Teams, Mattermost, Webex, email, Jira, webhooks, and Kafka](reference/notifications/publishers.md). +- **Vulnerability management platforms**: forward findings to DefectDojo, Fortify SSC, and Kenna Security. +- **Badges**: embed [vulnerability and policy badges](reference/badges.md) in README files and internal pages, + once an administrator turns on badge access. +- **Community integrations**: [plugins and tools](reference/community-integrations.md) + for Jenkins, GitHub Actions, Azure DevOps, Maven, Backstage, and more. + +### Control access + +- **Identity providers**: sign in through [OIDC](guides/administration/configuring-oidc.md) + or [LDAP](guides/administration/configuring-ldap.md), with optional team synchronization. +- **Teams and permissions**: grant fine-grained permissions to teams, + and limit which projects each team can see with [portfolio access control](concepts/access-control.md). +- **Machine identities**: give pipelines, scanners, and scripts their own + [service accounts](concepts/access-control.md#service-accounts), with permissions separate from any person's account. +- **Keyless authentication**: let GitHub Actions, GitLab CI, Kubernetes, or SPIFFE workloads sign in + with their platform's short-lived tokens through [workload identity federation](concepts/workload-identity-federation.md), + with no API keys to store or rotate. +- **Centralized secrets**: store integration credentials encrypted in one place + with [managed secrets](guides/user/managing-secrets.md). + +### Deploy and operate + +- **Open source and self-hosted**: free under the Apache 2.0 license, running on your own infrastructure. +- **Minimal infrastructure**: run the [container images](reference/container-images.md) + with PostgreSQL as the only external service. +- **Horizontal scaling**: [add instances](guides/administration/scaling.md) as your portfolio grows, + for example [on Kubernetes](guides/administration/deploying-to-kubernetes.md), + with health checks and Prometheus metrics. +- **Restricted networks**: run behind an [HTTP proxy](guides/administration/configuring-http-proxy.md), + or with an [internal certificate authority](guides/administration/configuring-internal-ca.md). +- **Localized interface**: use the web interface in 15 languages. + ## Getting started Get Dependency-Track running locally in minutes with the [quick start tutorial](tutorials/quickstart.md).