Xray plugin

6 minute readExtensibilityDeveloper productivity

JFrog Xray identifies security vulnerabilities and license violations as early as the dependency declaration stage and blocks builds with security issues from development. This plugin integrates CloudBees CD/RO with JFrog Xray via the JFrog CLI.

Plugin version 1.0.0

Revised on November 29, 2022

Overview

JFrog Xray identifies security vulnerabilities and license violations as early as the dependency declaration stage and helps block builds with security issues from development. This plugin integrates CloudBees CD/RO with JFrog Xray via the JFrog CLI.

Supported versions

The plugin has been tested with the following versions:

  • JFrog CLI 2.25.2

Prerequisites

You have the Xray service available on the JFrog Platform.

Plugin configurations

Plugin configurations are sets of parameters that can be applied across some, or all, of the plugin procedures. They can reduce the repetition of common values, create predefined parameter sets, and securely store credentials. Each configuration is given a unique name that is entered in the designated parameter for the plugin procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD/RO, complete the following steps:

  1. Navigate to DevOps Essentials  Plugin Management  Plugin configurations.

  2. Select Add plugin configuration to create a new configuration.

  3. In the New Configuration window, specify a Name for the configuration.

  4. Select the Project that the configuration belongs to.

  5. Optionally, add a Description for the configuration.

  6. Select the appropriate Plugin for the configuration.

  7. Configure the parameters per the descriptions below.

Configuration procedure parameters

Parameter Description

Configuration Name

Required. The name for the created configuration.

Description

The description for the configuration.

Endpoint

JFrog Platform endpoint URL. For example, https://<your-instance>.jfrog.io.

Xray URL path

JFrog Xray API URL path. Usually it is /xray.

JFrog CLI executable path

An absolute or relative path to JFrog CLI executable.

Auth type

The type of authorization to use.

Basic Auth

Authenticating with Username and Password.

Access Token

Authenticating with an Access Token.

Server ID

Server ID configured using the jfrog c add command.

Check configuration resource

A resource that is used for the checking configuration. JFrog CLI must be installed on the resource.

Check Connection?

If selected, the connection endpoint and credentials entered as part of the configuration are tested and the configuration is not saved if the test fails.

Debug level

This option sets the debug level for logs. If Info is selected, only a summary is displayed. If Debug is selected, any debug information is displayed. If Trace is selected, all requests and responses are displayed.

Plugin procedures

Dependencies Scan

Provides the capability to scan your sources dependencies using the JFrog CLI for vulnerabilities.

Dependencies Scan parameters

Parameter Description

Configuration Name

The previously defined configuration for the plugin.

Working directory

The target directory containing the source files.

Project type

Choose the target project type.

Use Gradle wrapper?

Enable if you would like to use the Gradle wrapper.

JFrog project

The JFrog project key, to enable Xray to determine security violations accordingly.

Repo path

Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly.

Watches

A comma-separated list of Xray watches, to enable Xray to determine violations accordingly.

Additional options

Specify additional options to be provided to the jf audit command. Use spaces or newlines to separate options.

Success criteria

A desired status of the scan. The procedure fails if the criteria is not reached. If ANY is selected, the procedure completes successfully, regardless of whether issues were found or not.

On-Demand Binary Scan

The on-demand binary scanning enables you to point to a binary in your local file system and receive a report that contains a list of vulnerabilities, licenses, and policy violations for that binary, prior to uploading the binary or build to Artifactory.

On-Demand Binary Scan parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Path

Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards. Examples:

  • ` /path/to/files/`

Path

Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards. For example:

  • /path/to/files/

  • path/to/files/, relative to the path in the working directory.

  • path/to/files/*.zip scans all .zip files located at the path/to/files/ file-system directory.

  • *.tgz scans all .tgz files located in the working directory.

Recursive

Uncheck if you do not wish to collect artifacts in sub-folders to be scanned by Xray.

JFrog project

The JFrog project key, to enable Xray to determine security violations accordingly. This parameter is used if the Repo path and Watches parameters are not provided. If none of the three parameters are provided, the scan shows all known vulnerabilities.

Repo path

The JFrog Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The procedure accepts this parameter only if the JFrog project and Watches parameters are not provided. If none of the three parameters are provided, the scan shows all known vulnerabilities.

Watches

A comma-separated list of Xray watches, to enable Xray to determine violations accordingly. The procedure accepts this parameter only if the JFrog project and Repo path parameters are not provided. If none of the three parameters are provided, the command shows all known vulnerabilities.

Success criteria

A desired status of the scan. The procedure fails if the criteria is not reached. If ANY is selected, the procedure completes successfully, regardless of whether issues were found or not.

Table output

Enables the table output format.

Extended table output

Add extended fields such as CVSS and Xray Issue Id to the table output.

On-Demand Docker Image Scan

Scans Docker containers located on the local file-system using the Docker client. The containers do not need to be deployed to Artifactory or any other container registry before they can be scanned.

On-Demand Docker Image Scan parameters

Parameter Description

Configuration name

Required. The unique name for the configuration.

Docker Image

Specifies the local Docker image with tag to be scanned. For example, electricflow/efagent:latest.

JFrog project

The JFrog project key, to enable Xray to determine security violations accordingly. This parameter is used if the Repo path and Watches parameters are not provided. If none of the three parameters are provided, the scan shows all known vulnerabilities.

Repo path

The JFrog Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The procedure accepts this parameter only if the JFrog project and Watches parameters are not provided. If none of the three parameters are provided, the scan shows all known vulnerabilities.

Watches

A comma-separated list of Xray watches, to enable Xray to determine violations accordingly. The procedure accepts this parameter only if the JFrog project and Repo path parameters are not provided. If none of the three parameters are provided, the command shows all known vulnerabilities.

Success criteria

A desired status of the scan. The procedure fails if the criteria is not reached. If ANY is selected, the procedure completes successfully, regardless of whether issues were found or not.

Timeout

Time (in seconds) to wait for the scan to complete.

Use cases

Performing on-demand binary scans

Within pipelines, you can use the Xray plugin to perform on-demand binary scans on project binary artifacts.

You must have a plugin configuration to add for the pipeline on-demand binary scan task.

To perform an on-demand binary scan:

  1. After checking out a binary in a project pipeline step, select Add.

  2. Give the New Task a name and select Select Task Type.

  3. From the Plugins list, select Xray and On-Demand Binary Scan.

  4. Select Define and then Input parameters.

  5. Fill in the required parameters:

    1. In the Configuration Name field, add the Xray plugin configuration.

    2. In the Path field, add the path to the binary you want scanned.

  6. Fill in the other fields as needed for your project. For more information, you can select the ? icon to display additional dialogs.

    The Success criteria field can be set for both positive and negative reporting.
  7. Select OK to save the task configuration.

  8. Select Assign a Resource or Resource Pool and add the resource you configured for the plugin configuration, and select OK.

  9. Select OK to save the task.

You can now run the pipeline, and this Scan task returns the findings of the vulnurabilites scan.

Using JFrog Xray watches in pipelines

Within pipelines, you can use JFrog Platform Xray Watches configured with basic or custom policies as scanning criteria for your artifacts.

To perform the following steps, you must have a Watch configured in JFrog. For more information on how to configure watches, refer to JFrog’s Configuring watches and policies documentation.

To implement your JFrog Watches within the plugin:

  1. After checking out a binary in a project pipeline step, select Add.

  2. Give the New Task a name and select Select Task Type.

  3. From the Plugins list, select Xray and the type of scan you want to perform.

  4. Select Define and then Input parameters.

  5. Fill in the required parameters:

    1. In the Configuration Name field, add the Xray plugin configuration.

    2. In the Path field, add the path to the binary you want scanned.

  6. To configure your JFrog Xray Watch to be used as the scanning parameter, enter the name of a watch you have configured in JFrog in the Watches field.

  7. Fill in the other fields as needed for your project. For more information, you can select the ? icon to display additional dialogs.

    The Success criteria field can be set for both positive and negative reporting.
  8. Select OK to save the task configuration.

  9. Select Assign a Resource or Resource Pool and add the resource you configured for the plugin configuration, and select OK.

  10. Select OK to save the task.

You can now run the pipeline and this Scan task uses your JFrog Watch as the scanning criteria.

Release notes

Xray 1.0.0

  • First release.