- Trustify: Provides vulnerability data and recommendations Trustify
- Postgres Database: Stores data needed for the Model Cards functionality. See Model Cards
- Redis cache: Allows caching licenses, recommendations and remediations. Can be configured with the
quarkus.redis.hostparameter - Deps.dev: For license information
It is possible to integrate with any number of vulnerability providers that follow the Trustify API specification.
You can define any number of vulnerability providers where the key is the identifier
providers.provider1.host- The base URL of the Trustify provider endpoint (e.g.,https://trustify.example.com)providers.provider1.auth.server-url- OIDC/OAuth2 server URL for authentication (e.g.,https://auth.example.com/realms/trustify)providers.provider1.auth.client-id- OAuth2 client ID for authenticating with the providerproviders.provider1.auth.client-secret- OAuth2 client secret for authenticating with the providerproviders.provider1.auth.token-timeout- Token request timeout duration (default:10s)providers.provider1.auth.client-timeout- OAuth2 client timeout duration (default:30s)providers.provider1.disabled- Boolean flag to disable this specific provider (default:false)
We rely on Deps.dev API for retrieving license data
You can use the following configuration properties:
api.licenses.depsdev.host: DepsDev API endpoint (https://api.deps.dev)api.licenses.depsdev.timeout: Connection timeout (60s)categories.file: Classpath resource or relative/absolute path to the license category configuration file (default:license-categories.yaml).
- OpenAPI Spec: There is an openapi.yaml
- Swagger UI: Available at http://localhost:8080/q/swagger-ui for development or when enabled with the property
quarkus.swagger-ui.always-include=true
By default the service will look for Red Hat Trusted Content remmediations and recommendations. If you want to opt out from this service
you can use the recommend query parameter and set it to false. Example /analysis?recommend=false
Here you can find the Dependency Analytics API Specification together with the Java and Javascript generated data model.
The endpoint retrieves information about licenses found in the given package URLs. It returns a dictionary with the licenses found by the license providers (evidence) and a concluded license based on the category ordering described below.
The system uses the configuration file selected by categories.file (default: license-categories.yaml) to categorize
the retrieved licenses into:
PERMISSIVEWEAK_COPYLEFTSTRONG_COPYLEFTUNKNOWN
The bundled mapping is src/main/resources/license-categories.yaml.
For category lookup, the backend separates the base license and exception at WITH or the deprecated -with- form,
then strips -only, -or-later, or a remaining legacy + suffix from the base identifier before checking list membership.
For example, GPL-3.0-only uses the GPL-3.0 entry. An unmapped base, unsupported SPDX leaf, or unrecognized single
license ID receives UNKNOWN; category lookup leaves the returned SPDX metadata intact.
The weak-copyleft-exceptions list defines which SPDX exceptions change a STRONG_COPYLEFT license to WEAK_COPYLEFT;
exception IDs are matched case-insensitively.
For example, GPL-2.0-only WITH Classpath-exception-2.0 is categorized as WEAK_COPYLEFT. An unlisted exception leaves
the base license category unchanged; the -only suffix is not an exception.
See the license categories glossary for terminology, the mapping procedure for evidence requirements, and ADR 0001 for the reviewed public-domain categorization decision.
License results for packages are cached in Redis under
licenses:v1:<classifier revision>:<mapping fingerprint>:<package coordinates>.
The fingerprint is SHA-256 of the effective categorization configuration loaded through categories.file, including
the exception rules, rather than the filename or raw YAML text. Ordering, duplicate entries, comments, and exception-ID
letter case do not change compatibility. Both cache reads and writes use this identity, and package coordinates still
exclude qualifiers. The v1 namespace identifies the cached-value format.
The classifier revision spdx-tree-v1 identifies recursive expression evaluation.
Developers must change this code-defined revision whenever classifier semantics change in a way
that can make cached results incompatible, even if the YAML is identical (for example, changing mixed AND/OR
evaluation). Change the cache-format namespace when the stored representation is incompatible.
Relevant mapping changes change the fingerprint automatically. These identities describe compatibility, not version age:
hashes cannot establish which result is newer. No operator-managed revision setting is required.
Current pods treat legacy licenses:<package coordinates> entries and entries for other compatibility identities as
misses; they do not fall back to those classifications. An unchanged old pod can still write its own keys, even after
a current write or targeted invalidation, but cannot overwrite the namespace consumed by current readers. This isolates
both old UNKNOWN mapping results and old mixed-expression classifications such as the incorrectly flattened
PERMISSIVE result for GPL-3.0 AND (MIT OR Apache-2.0).
licenses.cache.ttl defaults to 1d; writes set the configured TTL and reads do not renew it. Unused namespaces
expire naturally. For an operator-approved targeted invalidation, delete only the affected package keys under the
serving pods' actual compatibility namespace; deleting a legacy key does not invalidate a current entry. The startup log
reports the compatibility identity as <classifier revision>:<mapping fingerprint>. After confirming the Redis instance
and database, an exact-key deletion has the form DEL "licenses:v1:<reported identity>:<package coordinates>". Compatible
in-flight requests may repopulate current keys with compatible results. Do not run a broad Redis flush. No durable
database migration is needed: license classification does not persist these categories to a durable database.
During a rolling deployment, old pods may continue serving old results until drained. Any legacy entry's expiration is
measured from its last old write, not from rollout start, so a rollout alone does not guarantee fleet-wide freshness
within one TTL. Current readers are isolated immediately by their namespace. Direct license lookup
(GET /api/v5/licenses/{licenseId}) bypasses the package cache but still uses the serving pod's application version and
effective mapping; route to updated pods or drain old ones when current classification is required.
All licenses found in the license provider response are considered evidence. The system selects a concluded license using the following category-based heuristic; legal compatibility requires separate assessment:
- If multiple licenses are found, the backend doesn't decide which source is more reliable or if one should invalidate another. It just takes the more permissive license.
- An expression's category derives from its identifiers and parsed structure, rather than a lookup of the whole
expression in the mapping. For example,
MIT AND Apache-2.0isPERMISSIVEbecause both identifiers are permissive. - Within an SPDX expression, each
ORgroup selects the most permissive category among its child expressions; eachANDgroup selects the most restrictive category among its child expressions. Evaluation is recursive, respecting parentheses and the parsed SPDX tree, not a flattened list of identifiers. - The category ordering is
PERMISSIVE > WEAK_COPYLEFT > STRONG_COPYLEFT > UNKNOWN. Thus anUNKNOWNchild makes anANDgroupUNKNOWN, but anORgroup can select a known alternative. Leaves follow the category lookup and exception rules.
For example, GPL-3.0 AND (MIT OR Apache-2.0) is STRONG_COPYLEFT, while
(GPL-3.0 AND MIT) OR Apache-2.0 is PERMISSIVE. The aggregate does not replace leaf categories:
MIT and Apache-2.0 remain PERMISSIVE identifiers in both expressions, with their SPDX metadata unchanged.
(MIT OR Apache-2.0) AND (GPL-3.0 OR LGPL-2.1) is WEAK_COPYLEFT.
The JavaScript client's getCompatibility() treats an UNKNOWN dependency as incompatible when the project category
is known; runLicenseCheck() produces incompatible-dependency results, displayed as warnings by the VS Code extension.
This warning policy applies to every remaining UNKNOWN
result; mapping an identifier to PERMISSIVE removes its UNKNOWN-triggered warning while actual compatibility requires review.
For parser and model implementation details, see SPDX license handling.
The report will also provide a summary of the different licenses found.
echo '{
"purls": [
"pkg:npm/atob@2.1.2",
"pkg:npm/node-forge@1.3.0",
"pkg:npm/rc@1.2.8",
"pkg:npm/dompurify@2.3.0",
"pkg:npm/diff-lcs@1.3.0",
"pkg:npm/type-fest@0.20.2",
"pkg:npm/path-is-inside@1.0.0"
]
}' | http -v :8080/api/v5/licenses "summary": {
"concluded": 7, // number of concluded licenses
"permissive": 8, // total number of permissive licenses found. Including the declared but not concluded.
"strongCopyleft": 1, // total number of strong-copyleft licenses found. Including the declared but not concluded.
"total": 12, // total number of declared licenses found.
"unknown": 2, // total number of unknown licenses found. Including the declared but not concluded.
"weakCopyleft": 1 // total number of weak-copyleft licenses found. Including the declared but not concluded.
} "pkg:npm/rc@1.2.8": {
"concluded": {
"category": "PERMISSIVE",
"expression": "Apache-2.0 OR BSD-2-Clause OR MIT",
"identifiers": [
"Apache-2.0",
"BSD-2-Clause",
"MIT"
],
"name": "Apache-2.0 OR BSD-2-Clause OR MIT",
"source": "deps.dev",
"sourceUrl": "https://api.deps.dev"
},
"evidence": [
{
"category": "PERMISSIVE",
"expression": "Apache-2.0 OR BSD-2-Clause OR MIT",
"identifiers": [
"Apache-2.0",
"BSD-2-Clause",
"MIT"
],
"name": "Apache-2.0 OR BSD-2-Clause OR MIT",
"source": "deps.dev",
"sourceUrl": "https://api.deps.dev"
}
]
},The endpoint identifies an SPDX license from raw license file text. Send the license file content (typically the license header) in the request body as plain text. The service extracts the first 5 lines of the header, matches it against bundled SPDX license texts, and returns the identified license with its SPDX ID, name, and category.
echo 'SPDX-License-Identifier: Apache-2.0
Copyright 2023 Example.
Licensed under the Apache License, Version 2.0' | http -v :8080/api/v5/licenses/identify Content-Type:text/plainReturns a LicenseIdentifier with id, name, category, and related fields. Responds with 404 if the license header cannot be matched.
The expected input data format is a Software Bill of Materials (SBOM) containing the aggregate of all direct and transitive dependencies of a project.
License information: The analysis report includes license information retrieved from the dependencies defined in the SBOM. License data is gathered from:
- SBOM-provided license data: For CycloneDX SBOMs, license information already declared in the SBOM components is used
- deps.dev: License data is fetched from Deps.dev API based on the SBOM component package URLs (purls)
- Project license: The project's own license (when present in the SBOM metadata) is also included in the report
See License Analysis for how licenses are categorized and concluded.
The Content-Type HTTP header will allow Dependency Analytics distinguish between the different supported SBOM formats.
You can generate a CycloneDx JSON SBOM with the following command:
mvn org.cyclonedx:cyclonedx-maven-plugin:2.7.6:makeBom -DoutputFormat=json -DexcludeTestProjectThe generated file will be located under ./target/bom.json. Make sure the request Content-Type is set to application/vnd.cyclonedx+json.
Then you can analyze the vulnerabilities with the following command:
$ http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"application/json" @'target/bom.json'When the Dependency Graph Analysis returns a JSON report it contains all vulnerability data by default. The Verbose mode can be disabled
in order to retrieve just a Summary. Use the verbose=false Query parameter to disable it.
$ http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"application/json" @'target/sbom.json' verbose==false
{
"licenses": [
{
"packages": {},
"status": {
"message": "OK",
"name": "deps.dev",
"ok": true,
"warnings": {}
},
"summary": {
"concluded": 10,
"permissive": 8,
"strong-copyleft": 0,
"total": 12,
"unknown": 2,
"weak-copyleft": 2
}
}
],
"providers": {
"rhtpa": {
"sources": {
"osv-github": {
"summary": {
"critical": 1,
"dependencies": 3,
"direct": 0,
"high": 4,
"low": 0,
"medium": 2,
"recommendations": 3,
"remediations": 0,
"total": 7,
"transitive": 7,
"unscanned": 0
}
},
"redhat-csaf": {
"summary": {
"critical": 1,
"dependencies": 2,
"direct": 0,
"high": 1,
"low": 0,
"medium": 0,
"recommendations": 3,
"remediations": 0,
"total": 2,
"transitive": 2,
"unscanned": 0
}
}
},
"status": {
"code": 200,
"message": "OK",
"name": "rhtpa",
"ok": true,
"warnings": {}
}
}
},
"scanned": {
"direct": 3,
"total": 10,
"transitive": 7
}
}If clients don't provide the token to authenticate against the Vulnerability Provider the default one will be used instead but vulnerabilities unique to that specific provider will not show all the details.
To provide the client authentication tokens use HTTP Headers in the request. The format for the tokens Headers is ex-provider-token. e.g. ex-trustify-token:
http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"text/html" @'target/sbom.json' ex-trustify-token:the-client-tokenIn case the vulnerability provider requires of Basic Authentication the headers will be ex-provider-user and ex-provider-token.
http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"text/html" @'target/sbom.json' ex-oss-index-user:the-client-username ex-oss-index-token:the-client-tokenBy default the response Content-Type will be application/json but if the text/html media type is requested instead, the response
will be processed and converted into HTML.
The HTML report will show limited information:
- Public vulnerabilities retrieved with the default token will not show the Exploit Maturity
- Private vulnerabilities (i.e. vulnerabilities reported by the provider) will not be displayed.
$ http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"text/html" @'target/sbom.json'
<html>
...
</html>It is also possible to get a MIME Multipart response containing a JSON report with the HTML attached.
For that, use the Accept: multipart/mixed request header.
http :8080/api/v5/analysis Content-Type:"application/vnd.cyclonedx+json" Accept:"multipart/mixed" @'target/sbom.json'
HTTP/1.1 200 OK
boundary="----=_Part_2_2047647971.1682593849895"
Content-Type: multipart/mixed;
MIME-Version: 1.0
Message-Id: <49857413.3.1682593849896@granada>
User-Agent: HTTPie/3.2.1
transfer-encoding: chunked
x-quarkus-hot-deployment-done: true
------=_Part_2_2047647971.1682593849895
Content-Type: application/json
Content-Transfer-Encoding: binary
{
{
"scanned": {
"total": 9,
"direct": 2,
"transitive": 7
},
"providers": {
"oss-index": {
"status": {
"ok": true,
"name": "oss-index",
"code": 200,
"message": "OK"
},
sources": {
"oss-index": {
"summary": {
...
},
"dependencies": [
{
"ref": {
"name": "log4j:log4j",
"version": "1.2.17"
},
...
}
}
}
}
}
}
------=_Part_2_2047647971.1682593849895
Content-Type: text/html
Content-Transfer-Encoding: 8bit
Content-Disposition: attachment; filename=report.html
<html>
<header>
<title>Dependency Analytics Report</title>
</header>
<body>
<h1>Dependency Report</h1>
<p>This is an example</p>
</body>
</html>
------=_Part_2_2047647971.1682593849895--
This API performs dependency analysis for multiple projects.
The expected input data format is a dictionary. The keys are the package urls of the projects, while the values are the SBOMs of the projects.
All the parameters for the Dependency Analysis API are applicable to the Batch Dependency Analysis API.
The expected response varies based on the media type of the request:
- When media type
application/jsonis requested, the response will be a dictionary of JSON reports. - When media type
text/htmlis requested, the response will be an html report with vulnerability information for all the requested projects. - When media type
multipart/mixedis requested, the response will contain both the dictionary of JSON reports and the html report.
Clients are allowed to validate the vulnerability provider token with a specific endpoint. That will allow IDEs and the CLI to persist the different tokens and validate them when saving them.
The request will be a GET to the /token path containing the HTTP header with the token. The header format will follow the same rules as for the
other HTTP requests. i.e. ex-<provider>-token
http -v :8080/api/v5/token ex-trustify-token==example-tokenThe possible responses are:
- 200 - Token validated successfully
- 400 - Missing provider authentication headers
- 401 - Invalid auth token provided or Missing required authentication header (trust-da-token)
- 403 - The token is not authorized
- 429 - Rate limit exceeded
- 500 - Server error
These API endpoints provide security and safety metrics about Large Language Models coming from different sources together with recommendations that will help users make informed decisions about which LLM is more suitable to their needs and how to increase the security with the use of recommended guardrails.
See Model Cards Readme for more details.
API Clients are expected to send the following HTTP Headers in order to help observe the use of the Backend service:
trust-da-tokenHTTP Header that will be used to correlate different events related to the same user. If the header is not provided an anonymous event with a generated UUID will be sent instead.trust-da-sourceThe client consuming the Dependency Analytics API. It will default to theUser-AgentHTTP Headertrust-da-operation-typeWhen performing an analysis, clients might specify whether it is a component-analysis or a stack-analysistrust-da-pkg-managerThe Package manager that the SBOM was generated from (examples:maven,gradle-kotlin)
Telemetry connects to Segment for sending events from the HTML Report. The connection can be configured with the following properties.
telemetry.disabled: To completely disable telemetrytelemetry.write-key: Authentication key to connect to Segment
We are using Sentry (GlitchTip) to report errors for troubleshooting. By default monitoring is disabled but you can enabled it with:
monitoring.enabled=true
To configure Sentry use the following properties:
# Get the DSN Url in your project settings
monitoring.sentry.dsn=<your_dsn_url>
# Server Name to use as a tag
monitoring.sentry.servername=localhost
# Environment to use as a tag. Defaults to production
monitoring.sentry.environment=production
Three different error types can be reported:
- Client Exceptions: Bad requests from clients
- Server Errors: Unexpected errors
- Provider Errors: Errors coming from the providers responses
In all cases, the original request and headers are logged for the SRE Team to review.
The required parameters can be injected as environment variables through a secret. Create the trust-da-secret Secret before deploying the application.
oc create secret generic -n trust-da --from-literal=api-trustify-token=<api_token> trust-da-secretAfter that you can use the trust-da.yaml
oc apply -f deploy/trust-da.yamlYou can run your application in dev mode that enables live coding using:
./mvnw compile quarkus:devNOTE: Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.
The application can be packaged using:
./mvnw packageIt produces the quarkus-run.jar file in the target/quarkus-app/ directory.
Be aware that it’s not an uber-jar as the dependencies are copied into the target/quarkus-app/lib/ directory.
The application is now runnable using java -jar target/quarkus-app/quarkus-run.jar.
If you want to build an uber-jar, execute the following command:
./mvnw package -Dquarkus.package.type=uber-jarThe application, packaged as an uber-jar, is now runnable using java -jar target/*-runner.jar.
To disable frontend production bundle files creation and copying into the freemarker/generated directory execute the following command:
./mvnw package -P devYou can create a native executable using:
./mvnw package -PnativeOr, if you don't have GraalVM installed, you can run the native executable build in a container using:
./mvnw package -Pnative -Dquarkus.native.container-build=trueYou can then execute your native executable with: ./target/<artifactId>-<version>-runner (e.g., ./target/trustify-dependency-analytics-2.0.0-SNAPSHOT-runner)
If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.
You can run the frontend as a stand-alone application in dev mode by switching to the UI folder and executing the following command:
yarn startOpen http://localhost:3000 to view it in the browser.
Once ready to build for production, from the UI folder execute:
yarn buildThis will create 4 bundle files and copy it into the freemarker/generated directory.:
- main.js - This is all the code under the ui/src directory
- vendor.js - these are the dependencies we pull in from node_modules, like react, and @patternfly
- main.css - styles under the ui/src directory
- vendor.css - styles coming from node_modules, like all the PatternFly styles
These files are included in the freemarker template file (report.ftl) via [#include] statements.