Subscription Information
This feature is supported with Enterprise X and Enterprise+ licenses.
As a Release Bundle v2 is promoted through different environments towards production and eventual distribution to Edge nodes, it is crucial to ensure that the Release Bundle does not contain potential security risks.
JFrog Xray enables you to validate the security risk of a Release Bundle v2 and optionally prevent its promotion and distribution when a risk is detected.
Note
The ability to scan Release Bundles v2 requires Artifactory version 7.68.6 or later and Xray version 3.82.6 or later.
The workflow for scanning Release Bundles v2 is described below.
One-time setup procedures performed by a Security Admin:
Step 1 – Index Resources
For Xray to scan the Release Bundle v2, the Release Bundle must first be added as an indexed resource in Xray. For more information, see Indexing Xray Resources.
Step 2 – Create Security Policies
An Xray administrator can create policies with specific rules, that if violated, can trigger actions including blocking the Release Bundle from being promoted and/or distributed.
For more information about policies, see Creating Xray Policies and Rules.
Step 3 – Attach Policies to Watches
Watches apply a defined policy to specific indexed resources. Use Watches to ensure that Release Bundles are scanned by the appropriate policy. For more information, see Configuring Xray Watches.
Procedures performed during the software development process:
Step 4 – Scan Release Bundles
Xray scans the Release Bundle as soon as it exists as an indexed resource. Any vulnerabilities discovered in the artifacts that comprise the Release Bundle can be viewed in the Xray tab of the dashboard.
When you act to promote or distribute a Release Bundle, the status of the scan is retrieved from Xray. If Xray detects that the Release Bundle violates one of the rules in the policy defined by the Watch, Xray performs the action defined by the policy. These actions can include blocking the promotion or distribution operation.
Note
The status of the promotion or distribution action remains PROCESSING until the scan is complete.
If the policy blocks the Release Bundle from being promoted or distributed, you can view a list of violations discovered by Xray.
Step 5 – View and Evaluate Scan Results
You can view the scan results in the Xray tab of the timeline.
The scan results include the number of policy violations detected by Xray and the number of security issues that were uncovered.
Tip
You can also collect scan results using REST APIs:
Scans List - Get Release Bundle v2 Versions: Returns a list of Release Bundle v2 versions that have been scanned by Xray.
Release Bundle v2 Details: Returns security, license, and operational risk violations found in a specific Release Bundle v2.
Step 6 – Resolve Security Issues
Resolve the security issues as necessary to proceed with promotion and distribution. For more information about the different scans provided by Xray and how to resolve issues, see Xray Scan Results.
Xray Evidence
Enterprise+ users can view the evidence related to Xray scans during Release Bundle v2 creation, promotion, and distribution. Evidence can be viewed in the evidence graph as well as on the timeline of the Release Bundle version.
When a Release Bundle v2 is created and scanned by Xray, two pieces of evidence are created ⎻ an SBOM that lists all the artifacts that comprise the Release Bundle and a second file containing a list of any known vulnerabilities. Both files follow the CycloneDX standard by default.
Note
To use the SPDX (Software Package Data Exchange) standard instead, change the value of the evidenceSbomFormat property in the Xray system YAML from cyclone to spdx.
Understanding the Blocking Process
A Release Bundle v2 is blocked by Xray from being promoted and/or distributed when all of the following conditions are met:
Xray 3.82.6 or higher is installed, enabled, and available.
Note
There is an optional Xray setting that allows promotion and distribution without scanning if Xray is enabled but unavailable. For more information, see the section, Advanced Settings in Configuring Xray.
The Release Bundle has been indexed as a resource.
There is a Watch defined that ties together this Release Bundle with a policy that triggers an action (for example, blocking promotion and/or distribution) if the criteria defined by the policy are met. For example, if a direct vulnerability of a certain severity is discovered in one of the scanned artifacts that comprise the Release Bundle, promotion and distribution of the Release Bundle are blocked.
Note
In certain circumstances, the indexing process might take a long time to complete. There is a defined timeout setting, which if exceeded, causes the promotion or distribution action to fail if indexing is still in progress or otherwise stuck.