Trivy tweaks

dev/docker-compose.trivy.yml

@@ -0,0 +1,31 @@
+# This file is part of Dependency-Track.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+services:
+  trivy:
+    image: aquasec/trivy:latest
+    command:
+    - server
+    - --listen
+    - :8080
+    - --token
+    - TrivyToken
+    volumes:
+    - "trivy-cache:/root/.cache/trivy"
+    restart: unless-stopped
+
+volumes:
+  trivy-cache: { }

docs/_docs/datasources/trivy.md

@@ -5,22 +5,86 @@ chapter: 4
 order: 6
 ---
 
-[Trivy](https://www.aquasec.com/products/trivy/) is a tool provided by aquas allowing you to scan for vulnerabilities.
+[Trivy](https://www.aquasec.com/products/trivy/) is a *comprehensive and versatile security scanner* by [Aqua Security],
+supporting most popular programming languages, operating systems, and platforms. More details on scanning coverage
+can be found in [Trivy's documentation](https://aquasecurity.github.io/trivy/latest/docs/coverage/).
 
-Dependency-Track integrates with Trivy using its undocumented REST API.
+Dependency-Track integrates with Trivy using its [client/server mode]. 
 
-The Trivy integration is disabled by default.
+The Trivy integration requires an external Trivy server and is disabled by default.
 
 ### Configuration
 
 To configure the Trivy integration, navigate to *Analyzers* -> *Trivy* in the administration panel.
+The following options are available:
 
-|:---|:----|
-| Base URL | Base URL of the Trivy REST API. Defaults to `http://localhost:8081`. |
-| API Token | Authentication token for the REST API. |
+| Option         | Description                                                         | Default |
+|:---------------|:--------------------------------------------------------------------|:--------|
+| Enable         | Controls whether the Trivy integration is enabled                   | false   |
+| Base URL       | Base URL of the Trivy REST API                                      | -       |
+| API Token      | Authentication token for the REST API                               | -       | 
+| Ignore Unfixed | Whether to ignore vulnerabilities for which no fix is available yet | false   |
 
 ![Trivy Configuration](../../images/screenshots/trivy-configuration.png)
 
-### Run Trivy as Server
+### Running Trivy in Server Mode
 
-Trivy can be runned as a [server](https://github.com/aquasecurity/trivy/blob/b5874e3ad38e77ac86eedd7a65785b2933f3685f/docs/docs/references/configuration/cli/trivy_server.md) by executing the command `trivy server --listen localhost:8081 --token dummy -d` or by setting it up on a container.
+To run Trivy in server mode, use the [server command]. For example:
+
+```shell
+trivy server \
+  --listen :8080 \
+  --token yourAuthToken
+```
+
+> **Note**  
+> To prevent service disruption, you need to make sure that the Trivy server *keeps running*, and is automatically
+> launched after the host system reboots.  
+> The easiest way to achieve this is to run Trivy with Docker, and using an appropriate [restart policy].
+> See below for an example with Docker Compose.
+
+When deploying Dependency-Track via Docker Compose, Trivy can simply be added as yet another service in `docker-compose.yml`:
+
+```yml
+services:
+  trivy:
+    image: aquasec/trivy:latest
+    command:
+    - server
+    - --listen
+    - :8080
+    - --token
+    - yourAuthToken
+    volumes:
+    - "trivy-cache:/root/.cache/trivy"
+    restart: unless-stopped
+
+  # <Dependency-Track services here>
+
+volumes:
+  trivy-cache: {}
+  # <Dependency-Track volumes here>
+```
+
+Deploying Trivy in the same Compose project allows you to specify `http://trivy:8080` as *base URL* in the Trivy configuration.  
+Other deployment models will require you to configure the proper IP or hostname of the machine where Trivy is running.
+
+### Known Limitations
+
+* When scanning SBOMs, Trivy heavily relies on structures and properties that it populates when generating an SBOM.
+This means that scanning SBOMs that were generated with tools other than Trivy may not yield as many results,
+as when scanning an SBOM generated by Trivy itself.
+* Trivy may report vulnerabilities from sources that Dependency-Track does not recognize. Because Trivy maintains
+its own vulnerability database, it is inevitable that it deviates from Dependency-Track's. Vulnerabilities for which
+this is the case will be labeled with source `UNKNOWN` in Dependency-Track.
+* Vulnerability aliases can not be resolved for vulnerabilities of source `UNKNOWN`.
+* Trivy may report vulnerabilities for which no official ID was assigned (yet). For example, the Debian project uses
+[fake names] for certain vulnerabilities. Because Trivy integrates with Debian's vulnerability database directly,
+it will report such vulnerabilities if applicable. The chance of encountering such vulnerabilities can be reduced by
+enabling the *ignore unfixed vulnerabilities* option.
+
+[Aqua Security]: https://www.aquasec.com/
+[client/server mode]: https://aquasecurity.github.io/trivy/latest/docs/references/modes/client-server/
+[fake names]: https://security-tracker.debian.org/tracker/data/fake-names
+[restart policy]: https://docs.docker.com/config/containers/start-containers-automatically/#use-a-restart-policy
+[server command]: https://github.com/aquasecurity/trivy/blob/v0.50.1/docs/docs/references/configuration/cli/trivy_server.md

docs/_posts/2024-xx-xx-v4.11.0.md

@@ -13,7 +13,7 @@ Because the new implementation can have a big impact on how Dependency-Track beh
 it is disabled by default for this release. It may be enabled by setting the environment variable `BOM_PROCESSING_TASK_V2_ENABLED`
 to `true`. Users are highly encouraged to do so.
 * **BOM Validation**. Historically, Dependency-Track did not validate uploaded BOMs and VEXs against the CycloneDX
-schema. While this allowed BOMs to be processed that did not strictly adhere to the schema, it could lead to confusion
+schema. While this allowed BOMs to be processed that did not strictly adhere to the schema, it could also lead to confusion
 when uploaded files were accepted, but then failed to be ingested during asynchronous processing. Starting with this
 release, uploaded files will be rejected if they fail schema validation. Note that this may reveal issues in BOM
 generators that currently produce invalid CycloneDX documents. Validation may be turned off by setting the
@@ -25,9 +25,11 @@ has explicit access to. It is possible to inspect individual findings, or aggreg
 making it possible to spot the most prevalent vulnerabilities.
   * *This feature was demoed in our April community meeting! Watch it [here](https://www.youtube.com/watch?v=3iIeajRJK8o&t=572s).*
 * **Trivy Analyzer Integration**. It is now possible to leverage [Trivy] in [server mode] for vulnerability analysis.
+  * Refer to the [analyzer's documentation]({{ site.baseurl }}{% link _docs/datasources/trivy.md %}) for further details,
+  in particular the [known limitations]({{ site.baseurl }}{% link _docs/datasources/trivy.md %}#known-limitations).
   * *This feature was demoed in our April community meeting! Watch it [here](https://www.youtube.com/watch?v=3iIeajRJK8o&t=725s).*
 * **Official Helm Chart**. The Dependency-Track project now offers an official Helm chart for Kubernetes deployments.
-Community input and contributions are explicitly requested. The chart repository can be found at
+Community input and contributions are highly requested. The chart repository can be found at
 [https://github.com/DependencyTrack/helm-charts](https://github.com/DependencyTrack/helm-charts)
 
 **Features:**
@@ -295,6 +297,6 @@ Special thanks to everyone who contributed code to implement enhancements and fi
 [Mapped Diagnostic Context]: https://logback.qos.ch/manual/mdc.html
 [Trivy]: https://trivy.dev/
 [component identity]: https://docs.dependencytrack.org/analysis-types/component-identity/
-[customized their logging configuration]: https://docs.dependencytrack.org/getting-started/monitoring/#custom-logging-configuration
+[customized their logging configuration]: {{ site.baseurl }}{% link _docs/getting-started/monitoring.md %}#custom-logging-configuration
 [logback.xml]: https://github.com/DependencyTrack/dependency-track/blob/master/src/main/docker/logback.xml
 [server mode]: https://aquasecurity.github.io/trivy/v0.50/docs/references/modes/client-server/

src/main/java/org/dependencytrack/model/ConfigPropertyConstants.java

@@ -61,7 +61,7 @@ public enum ConfigPropertyConstants {
     SCANNER_SNYK_BASE_URL("scanner", "snyk.base.url", "https://api.snyk.io", PropertyType.URL, "Base Url pointing to the hostname and path for Snyk analysis"),
     SCANNER_TRIVY_ENABLED("scanner", "trivy.enabled", "false", PropertyType.BOOLEAN, "Flag to enable/disable Trivy Vulnerability Analysis"),
     SCANNER_TRIVY_API_TOKEN("scanner", "trivy.api.token", null, PropertyType.ENCRYPTEDSTRING, "The API token used for Trivy API authentication"),
-    SCANNER_TRIVY_BASE_URL("scanner", "trivy.base.url", "http://localhost:8081", PropertyType.URL, "Base Url pointing to the hostname and path for Trivy analysis"),
+    SCANNER_TRIVY_BASE_URL("scanner", "trivy.base.url", null, PropertyType.URL, "Base Url pointing to the hostname and path for Trivy analysis"),
     SCANNER_TRIVY_IGNORE_UNFIXED("scanner", "trivy.ignore.unfixed", "false", PropertyType.BOOLEAN, "Flag to ignore unfixed vulnerabilities"),
     VULNERABILITY_SOURCE_NVD_ENABLED("vuln-source", "nvd.enabled", "true", PropertyType.BOOLEAN, "Flag to enable/disable National Vulnerability Database"),
     VULNERABILITY_SOURCE_NVD_FEEDS_URL("vuln-source", "nvd.feeds.url", "https://nvd.nist.gov/feeds", PropertyType.URL, "A base URL pointing to the hostname and path of the NVD feeds"),