Add features list; document BOM uploading

.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

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

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

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**.
+
+<!-- vale Google.Headings = NO -->
+## Upload via REST API
+<!-- vale Google.Headings = YES -->
+
+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.
+
+<!-- vale Google.Headings = NO -->
+## Upload from GitHub Actions
+<!-- vale Google.Headings = YES -->
+
+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.
+
+<!-- vale Google.Headings = NO -->
+## Upload from Jenkins
+<!-- vale Google.Headings = YES -->
+
+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).

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).