How to Upload Vulnerability Reports to Teamscale

A vulnerability report is a machine-readable document describing the third-party components a build depends on, together with metadata such as their versions, licenses and known vulnerabilities. Teamscale currently accepts vulnerability reports in the form of Software Bills of Materials (SBOMs); the feature is named generically because support for further report formats may be added in the future. Teamscale can import the reports your builds produce and display their components and vulnerabilities in the Software Composition perspective.

Uploading vulnerability reports complements the JFrog Xray connector: it lets you populate the Software Composition perspective straight from your CI pipeline. It does not require a Software Composition Analysis (SCA) tool connector to be configured for the project.

• Supported Formats
  • Generating a Report
• Prerequisites
• Uploading a Report
  • Parameters
  • Sample Upload with curl
  • Uploading from a CI Pipeline
• Vulnerabilities
• Viewing Uploaded Reports

Supported Formats

Teamscale accepts the following SBOM formats:

Format	Serialization	Notes
CycloneDX	JSON or XML	Prefer this format if you need vulnerability data (see Vulnerabilities).
SPDX 2.x	JSON only	Components and licenses only; SPDX carries no vulnerability data (see Vulnerabilities).

The format is detected automatically by Teamscale. A file that is neither recognized nor parseable is rejected with an HTTP 400 error.

Generating a Report

Any tool that writes one of the formats above can feed Teamscale. Common choices are:

• The CycloneDX plugins for build tools such as Maven, Gradle, npm or .NET.
• Syft for containers, images and file systems.
• Trivy, which additionally reports the vulnerabilities it finds.
• Grype, which adds vulnerabilities to an SBOM you already have.

Build-tool plugins such as the CycloneDX ones list the components but no vulnerabilities. Use a scanner if you want Teamscale to show vulnerabilities as well. Refer to the documentation of your tool for how to make it write CycloneDX or SPDX.

Prerequisites

• The Teamscale server must be reachable via HTTP(S) from the machine performing the upload.
• You need a Teamscale user with the Perform External Uploads permission for the target project — the same permission required for other external uploads. For a production setup we recommend creating a technical user with the Build role.
• All requests authenticate via HTTP Basic Authentication with that user's access key (not their password). You can generate an access key on the profile page: <TEAMSCALE_URL>/user/access-key.

No analysis profile setting or SCA connector needs to be enabled for the upload to work.

Uploading a Report

External analysis reports such as test coverage, findings and metrics are uploaded through the external-analysis session endpoints (see How to Upload External Analysis Data). Vulnerability reports are also external data, but they use a dedicated endpoint:

• HTTP method: POST
• Request URL:

  http://<TEAMSCALE_URL>/api/projects/<PROJECT>/vulnerability-report?build-name=<BUILD_NAME>&version=<VERSION>&revision=<COMMIT_HASH>

• Body: multipart/form-data with a single form field named file holding the report file.
• Authentication: HTTP Basic Authentication with a Teamscale user and their access key (not their password).
• Response: HTTP 204 (no content) on success. An unparseable or empty file, or a missing parameter, results in HTTP 400 with an explanatory message.

Parameters

Parameter	Required	Description
<PROJECT>	yes	The ID of the Teamscale project to upload to.
build-name	yes	Name identifying the build the report belongs to. It groups successive versions of the same build pipeline.
version	yes	The build number identifying this upload within the build. You supply it yourself (for example, your CI build number).
revision	yes	The version control commit hash the build was produced from. Teamscale uses it to link the build (and the violations derived from it) to the corresponding code commit.

A report is identified by its build-name and version together. Re-uploading with the same build-name and version overwrites the previously uploaded report. Both values may contain slashes, so CI build identifiers such as Jenkins job paths (for example, folder/job/main) can be used as-is. Neither value may contain the # character.

Teamscale stores and parses the report while handling the request, so its components and vulnerabilities are available in the Web UI and via the REST API as soon as the upload returns.

Sample Upload with curl

curl --request POST --user build:<ACCESSKEY> \
  --form "file=@sbom.cyclonedx.json" \
  "http://teamscale-server:8080/api/projects/my-project/vulnerability-report?build-name=my-service&version=1.4.2&revision=0842320ef195b2d9190ab32b2d24b4a77eb522b1"

Always Quote the URL

The URL must be enclosed in quotes. Most shells treat the & character specially and would otherwise truncate the URL.

Reading the Uploaded Data

The components, vulnerabilities and violations of the uploaded reports can also be read via the REST API, for example, to gate a pipeline on them. These endpoints are documented in the API reference of your Teamscale instance, as described here.

Uploading from a CI Pipeline

Generate the report as part of your build with the tool of your choice, then upload the resulting file with the identifiers your CI system already provides. The following example uses GitLab CI variables; the equivalents for other systems are, for example, BUILD_TAG/BUILD_NUMBER/GIT_COMMIT on Jenkins and Build.DefinitionName/Build.BuildNumber/Build.SourceVersion on Azure DevOps.

# Upload the generated report, using the CI job name as build name and the pipeline number as version
curl --fail --request POST --user build:"$TEAMSCALE_ACCESS_KEY" \
  --form "file=@bom.json" \
  "https://teamscale-server:8080/api/projects/my-project/vulnerability-report?build-name=$CI_JOB_NAME&version=$CI_PIPELINE_IID&revision=$CI_COMMIT_SHA"

Pass --fail to curl so that the pipeline step fails if Teamscale rejects the report. Store the access key as a masked CI variable rather than in the pipeline definition.

Upload one report per build version. Uploading a report for every pipeline run gives you the history of a build in the Builds view, while the SBOM view always shows the most recently uploaded version of each build.

Vulnerabilities

Teamscale surfaces only the vulnerabilities the uploaded report itself contains. It does not run its own security checks on the components and does not query external vulnerability databases. How much vulnerability data is available therefore depends on the format:

• CycloneDX files can carry a dedicated vulnerabilities section, which Teamscale imports in full.
• SPDX 2.x has no vulnerability section, so reports in this format generally carry no vulnerability data.

Use CycloneDX if you want Teamscale to show vulnerabilities and the resulting policy violations for your components.

Each vulnerability in the report becomes both a vulnerability (shown on the build details) and a violation of type security (shown in the Violations view, where it can be marked as tolerated or false positive). Teamscale normalizes the severity ratings of the report to Critical, High, Medium, Low, None or Unknown.

Viewing Uploaded Reports

Uploaded reports appear in the Software Composition perspective:

• The SBOM view lists all components across your builds.
• The Builds view lists each build and its versions; the build details include an SBOM tab with that version's components and a Vulnerabilities tab.
• The Violations view lists the policy violations derived from the report's vulnerabilities, where you can mark them as tolerated or false positive.