JFrog Xray

Application Security

Overview

The JFrog Xray Connector integrates with the JFrog Xray security scanning platform to synchronize vulnerability findings and definitions. It connects to the Xray Reports API to fetch open source vulnerability data across all monitored repositories.

---

Data retrieved from JFrog Xray

Connector Object	Required	Maps to Data Model
Vulnerability	Yes	Open Source Finding
Vulnerability Definition	Yes	Open Source Finding Definition

Model relationships

note

For detailed steps on how to view the data retrieved from JFrog Xray in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select JFrog Xray from the Connector dropdown and provide the following:

Setting	Required	Default	Description
API url	Yes	—	JFrog api url
Access token	Yes	—	JFrog access token
Page size	No	100	Maximum number of records to get per API request
Parallel requests	No	Runtime CPUs (max 4)	Maximum number of parallel API requests
Included Repositories	No	—	Comma-separated list of repository names to scan. Takes priority over Excluded Repositories.
Excluded Repositories	No	—	Comma-separated list of repository names to skip during sync. Has no effect if Included Repositories is set.
Report Timeout in Hours	No	5	Maximum number of hours to wait for X-ray reports to complete before timing out. Default is 5 hours.
Report Poll Interval in Seconds	No	5	Time in seconds to wait before and between checks for X-ray report completion. Lower values speed up syncs when reports complete quickly; raise it if the Xray server is slow or rate-limited. Default is 5 seconds.

Authentication

The connector uses a JFrog Platform Access Token for authentication via bearer token.

Generating an Access Token

1. Log in to your JFrog Platform instance
2. Navigate to Administration → Identity and Access → Access Tokens
3. Click Generate Token
4. Select Scoped Token with applied-permissions/admin scope
5. Copy the generated token

Usage

All API requests include the access token as a bearer token:

Authorization: Bearer <access-token>

Test Connection

Method	URL
GET	{url}/xray/api/v2/policies

Request Headers

Header	Value
Authorization	Bearer <access-token>
Accept	application/json

Sample Response

[
  {
    "name": "example-security-policy",
    "type": "security",
    "description": "Block critical CVEs",
    "rules": [
      {
        "name": "critical-block",
        "priority": 1
      }
    ]
  }
]

Response Fields

Field	Description
name	Policy name
type	Policy type (e.g. security, license)
description	Policy description
rules	List of rules defined on the policy

A successful connection returns a 200 OK with a list of policies. Authentication failures throw NonRetryableException.

The same Authorization: Bearer <access-token> header is sent on every subsequent API request (repository listing, report creation, report polling, and report data retrieval).

---

How to obtain JFrog Xray credentials

Generate a JFrog access token

For the JFrog Xray connector to use the JFrog API, you must provide an access token. JFrog does not allow retrieving the access token for an existing user. To generate a new token, follow these steps:

1. Log in to your organization's JFrog portal as an administrator.

2. Navigate to User Management > Access Tokens.

   

3. Click Generate Token, select Scoped Token, and then complete the following fields:

   • Description: Provide a description for the token.

   • Token scope: Click the dropdown and select the appropriate scope for your integration. You have three options:

     • Admin: Grants full administrative access. Use this option if retrieving your data requires complete control over all aspects of JFrog Xray. Proceed with caution, as this option provides extensive permissions.

     • User: Grants access based on a specific user's permissions. Use this option if retrieving your data requires performing actions that a typical user would require.

     • Group: Grants access based on a group of users' permissions. Use this option if retrieving your data needs permissions common to a specific group.

Note: While all three options can be used to authenticate API requests, Brinqa recommends that you use the User or Group scope, as these can provide more controlled access. Consult the JFrog documentation to help you better understand which scope may better suit your needs.

• User name: Provide a user name for the token.

• Service: Click the dropdown and select Xray.

• Expiration time: If desired, click the dropdown and set an expiry for the token. Options include: Never, 1 day, 3 days, 1 week, 1 month, or a custom time.

• Create reference token: Not checked by default. Leave as is.

  

4. Click Generate.

   Your access token displays. You cannot view the token after this. Copy and save it to a secure location.

Note: If you do not have permissions to create an access token, contact your JFrog administrator. For additional information, see JFrog documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Vulnerability

Source Field Name	SDM Attribute
MD5 hash of repository + issueId + path + componentPhysicalPath	UID
VulnerabilityResource.artifactScanTime	LAST_SCANNED
VulnerabilityResource.componentPhysicalPath	COMPONENT_PHYSICAL_PATH
VulnerabilityResource.cves	TYPE
VulnerabilityResource.fixedVersions	FIXED_VERSION
VulnerabilityResource.impactedArtifact + impactPath	RESULTS
VulnerabilityResource.issueId	NAME
VulnerabilityResource.packageType	PACKAGE_TYPE
VulnerabilityResource.path	PATH
VulnerabilityResource.projectKeys + repo name	TARGETS
VulnerabilityResource.vulnerableComponent	VULNERABLE_COMPONENT
—	PROVIDER_STATUS
—	SOURCE_STATUS
—	LAST_CAPTURED

Vulnerability Definition

Source Field Name	SDM Attribute
VulnerabilityResource.cves	UID
VulnerabilityResource.cves	NAME
VulnerabilityResource.cves	CVE_IDS
VulnerabilityResource.cves	CVE_RECORDS
VulnerabilityResource.cvss2MaxScore	CVSS_V2_BASE_SCORE
VulnerabilityResource.cvss3MaxScore	CVSS_V3_BASE_SCORE
VulnerabilityResource.description	DESCRIPTION
VulnerabilityResource.packageType	CATEGORIES
VulnerabilityResource.provider	PROVIDER
VulnerabilityResource.provider	TAGS
VulnerabilityResource.published	PUBLISHED_DATE
VulnerabilityResource.references	REFERENCES
VulnerabilityResource.severity	SEVERITY
VulnerabilityResource.severity	SEVERITY_SCORE
VulnerabilityResource.severity	SOURCE_SEVERITY
VulnerabilityResource.severitySource	SEVERITY_SOURCE
VulnerabilityResource.summary	SUMMARY
—	LAST_CAPTURED

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Vulnerability

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Vulnerability on every run and applies no incremental date filter.

API

• Type: REST (report-based workflow) · Endpoint: POST /xray/api/v1/reports/vulnerabilities/{reportId}
• Default filters: The report-creation request scopes each report to one repository (resources.repositories[].name) and applies optional severities, published (start/end), and scan_date (start/end) filters from the sync operation options. On delta syncs (when a SyncToken is present) a scan_date range from the previous sync time to now is added automatically. The report-data request body sends an empty filters object:

Vulnerability Definition

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Vulnerability Definition on every run and applies no incremental date filter.

API

• Type: REST (report-based workflow) · Endpoint: POST /xray/api/v1/reports/vulnerabilities/{reportId}
• Default filters: Definitions are derived from the same vulnerability report rows as the Vulnerability model, then deduplicated by CVE ID in KV storage. Report-creation filters (severities, published, scan_date) from the sync operation options apply, and a scan_date window is added automatically on delta syncs. The report-data request body sends an empty filters object:

Changelog

Changelog

The JFrog Xray connector has undergone the following changes:

Version	Description	Migration Steps
3.0.10	Improvements - Failed Xray vulnerability reports are now reported promptly with the underlying error message (e.g. "Report limit reached: limit=100000, count reached=100213") surfaced in connector logs. Previously, failed reports were not recognized as a terminal state, so the connector continued polling until the configured report timeout (default 5 hours) elapsed. - Added a configurable Report Poll Interval in Seconds (pollInterval, default 5) that controls how long the connector waits before and between checks for report completion. Reports for most repositories complete almost instantly, so the previous fixed 5-second wait per repository dominated sync time on instances with many repositories. Lowering this value (e.g. to 1) can reduce sync duration substantially; it can be raised if the Xray server is slow to generate reports or rate-limited. - Removed the STATUS and STATUS_CATEGORY attributes from the Vulnerability model schema. These attributes are no longer required as of platform version 11.x and are no longer populated on emitted records; status semantics continue to be conveyed via PROVIDER_STATUS and SOURCE_STATUS. Bug Fixes - Sync no longer aborts when a single repository fails. A repository that times out or returns an error is now logged and skipped, and the remaining repositories continue to sync. The sync is reported as an overall failure only if every repository fails. - Vulnerability records that share an Xray issue ID across multiple impacted artifacts (common in Docker repositories with shared base layers) are now stored as distinct rows instead of producing duplicate-key database errors during ingestion. - Failed and timed-out Xray reports are now cleaned up on the JFrog server. Previously these reports were left as orphans, accumulating one per failed sync. - Incremental (delta) syncs no longer send malformed scan-date timestamps to Xray. The connector previously formatted the request's scan_date.end value using a 12-hour clock without an AM/PM marker, causing afternoon UTC timestamps to be sent as morning timestamps. The Xray API rejected these requests with HTTP 400 (scan start date must be earlier than scan end date) whenever a delta sync was triggered in the second half of a UTC day. The formatter now uses a 24-hour clock with an explicit UTC timezone.	• Vulnerability: The Open Source Finding UID format has changed from the bare Xray issue ID (e.g. XRAY-710560) to an MD5 hash of the repository, issue ID, artifact path, and component physical path. The new format ensures one row per (vulnerability × impacted artifact) occurrence and resolves the duplicate-key constraint violations on idx_u_JfrogXrayVulnerability_uid. Action: purge existing JfrogXrayVulnerability rows and re-sync after upgrading.
3.0.9	No changes in this release.	N/A
3.0.8	Improvements - Vulnerability findings now carry a populated Name based on the Xray issue ID, making individual findings easier to identify in the platform.	N/A
3.0.7	Improvements - Connector and Xray API errors now surface a clear, human-readable message (for example, the underlying Xray error text) instead of a generic failure, making sync issues easier to diagnose. Dependency Upgrades - Upgraded the connector platform and several third-party libraries (JSON processing and supporting libraries) to current, supported versions.	N/A
3.0.6	New Features - Added Include Repositories and Exclude Repositories configuration settings (comma-separated repository keys) so you can scope which repositories Xray scans during sync directly from the connector configuration. Improvements - The finding Type values that link an Open Source Finding to its Finding Definition are now prefixed with XRay- so they match the Finding Definition identifiers, ensuring findings correctly associate with their definitions.	• Vulnerability: The values that link findings to their Finding Definitions changed format (now prefixed with XRay-). Action: re-sync the Xray connector after upgrading so existing findings re-link to their definitions.
3.0.5	New Features - Added an Exclude Repositories option that lets you provide a comma-separated list of repository keys to skip during scanning, so unwanted or noisy repositories can be omitted from collection.	N/A
3.0.4	New Features - Added incremental (delta) scanning. Subsequent syncs now request only vulnerabilities scanned since the previous run, reducing sync time and load on the Xray server.	N/A
3.0.3	No changes in this release.	N/A
3.0.2	Improvements - Open Source Findings now populate status fields (provider status, source status, and status category) and the impacted artifact path, giving a more complete view of each finding. - Scan-time and published-date attributes are now emitted as proper date values rather than raw millisecond numbers, so they display and filter correctly as dates in the platform. - Findings and finding definitions are now categorized as Open Source Findings and Open Source Finding Definitions, aligning Xray data with the platform's standard finding model.	• VulnerabilityDefinition: The Finding Definition identifier format changed (definition IDs are now prefixed with XRay-). Action: purge existing JfrogXrayVulnerabilityDefinition rows and re-sync after upgrading.
3.0.1	Improvements - Finding definitions now capture the original Source severity reported by Xray alongside the normalized severity, preserving the vendor's severity rating.	N/A
3.0.0	Overview The JFrog Xray connector integrates with JFrog Xray to synchronize open-source vulnerability findings and their definitions discovered across scanned Artifactory repositories. Category: Application Security Models	N/A