CLI for JFrog Xray

Overview

This page describes how to use JFrog CLI with JFrog Xray.

Authentication

When used with Xray, JFrog CLI offers several means of authentication: JFrog CLI does not support accessing Xray without authentication.

Authenticating with Username and Password

To authenticate yourself using your Xray login credentials, either configure your credentials once using the jfrog c add command or provide the following option to each command.

Command option	Description
--url	JFrog Xray API endpoint URL. It usually ends with /xray
--user	JFrog username
--password	JFrog password

Authenticating with an Access Token

To authenticate yourself using an Xray Access Token, either configure your Access Token once using the jfrog c add command or provide the following option to each command.

Command option	Description
--url	JFrog Xray API endpoint URL. It usually ends with /xray
--access-token	JFrog access token

Page Contents

General Commands

Running cUrl

Execute a cUrl command, using the configured Xray details. The command expects the cUrl client to be included in the PATH.

Command name	xr curl
Abbreviation	xr cl
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
Command arguments
cUrl arguments and flags	The same list of arguments and flags passed to cUrl, except for the following changes: The full Xray URL should not be passed. Instead, the REST endpoint URI should be sent. The login credentials should not be passed. Instead, the --server-id should be used.

Examples

Example 1

Execute the cUrl client, to sent a GET request to the /api/system/version endpoint to the default configured Xray server.

jf xr curl -XGET /api/v1/system/version

Example 2

Execute the cUrl client, to send a GET request to the /api/v1/system/version endpoint to the configured my-xr-server server ID.

jf rt curl -XGET /api/v1/system/version --server-id my-xr-server

Downloading updates for Xray's database

The offline-update command downloads updates to the for Xray's vulnerabilities database. The Xray UI allows building the command structure for you.

Command name	xr offline-update
Abbreviation	xr ou
Command options
--license-id	[Mandatory] Xray license ID
--from	[Optional] From update date in YYYY-MM-DD format.
--to	[Optional] To update date in YYYY-MM-DD format.
--versio	[Optional] Xray API version.
--target	[Default: ./] Path for downloaded update files.
Command arguments	The command accepts no arguments.

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.

Scanning Files on the Local File System

This jf scan command scans files on the local file-system with Xray.

This command requires:

Version 3.29.0 or above of Xray
Version 2.1.0 or above of JFrog CLI

Command name	scan
Abbreviation	s
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--spec	[Optional] Path to a file specifying the files to scan. If the pattern argument is provided to the command, this option should not be provided.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--licenses	[Default: false] Set if you also require the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
Command arguments
Pattern	Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards.

Output Example

Examples

Example 1

Scans all the files located at the path/ti/files/ file-system directory using the watch1 watch defined in Xray.

jf s "path/to/files/" --watches "watch1"

Example 2
Scans all the files located at the path/ti/files/ file-system directory using the watch1 and watch2 Watches defined in Xray.

jf s "path/to/files/" --watches "watch1,watch2"

Example 3

Scans all the zip files located at the path/ti/files/ file-system directory using the watch1 and watch2 Watches defined in Xray.

jf s "path/to/files/*.zip" --watches "watch1,watch2"

Example 4

Scans all the tgz files located at the path/ti/files/ file-system directory using the policies defined for project-1.

jf s "path/to/files/*.tgz" --project "project-1"

Example 5
Scans all the tgz files located in the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf s "*.tgz" --repo-path "libs-local/release-artifacts/"

Example 6
Scans all the tgz files located at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jf s "*.tgz"

Scanning Docker Containers on the Local File System

This jf docker scan command scans docker containers located on the local file-system using the docker client and JFrog Xray. The containers doesn't need to be deployed to Artifactory or any other container registry before it can be scanned.

This command requires:

Version 3.40.0 or above of Xray
Version 2.11.0 or above of JFrog CLI

Command name	docker scan
Abbreviation
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities.
--licenses	[Default: false] Set if you also require the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
Command arguments
Pattern	Specifies the local file system path to artifacts to be scanned. You can specify multiple files by using wildcards.

Examples

Example 1

Scan the local reg1/repo1/img1:1.0.0 container and show all known vulnerabilities, regardless of the policies defined in Xray.

$ docker images
REPOSITORY           TAG       IMAGE ID       CREATED         SIZE
reg1/repo1/img1   1.0.0     6446ea57df7b   19 months ago   5.57MB
$ 
$ jf docker scan reg1/repo1/img1:1.0.0

Example 2

Scan the local reg1/repo1/img1:1.0.0 container and show all violations according to the policy associated with my-project JFrog project.

$ docker images
REPOSITORY           TAG       IMAGE ID       CREATED         SIZE
reg1/repo1/img1   1.0.0     6446ea57df7b   19 months ago   5.57MB
$ 
$ jf docker scan reg1/repo1/img1:1.0.0 --project my-project

Example 3

Scan the local reg1/repo1/img1:1.0.0 container and show all violations according to the policy associated with my-watch Xray Watch.

$ docker images
REPOSITORY           TAG       IMAGE ID       CREATED         SIZE
reg1/repo1/img1   1.0.0     6446ea57df7b   19 months ago   5.57MB
$ 
$ jf docker scan reg1/repo1/img1:1.0.0 --watches my-watch

Example 4

Scan the local reg1/repo1/img1:1.0.0 container and show all violations according to the policy associated with releases-local/app1/ path in Artifactpry.

$ docker images
REPOSITORY           TAG       IMAGE ID       CREATED         SIZE
reg1/repo1/img1   1.0.0     6446ea57df7b   19 months ago   5.57MB
$ 
$ jf docker scan reg1/repo1/img1:1.0.0 --repo-path releases-local/app1/

Scanning Project Dependencies

The Xray Dependencies Scan feature enables you to scan your source code dependencies to find security vulnerabilities and licenses violations, with the ability to scan against your Xray policies.

Auditing Npm Projects

The audit-npm command audits an npm project, by generating a dependency tree for the sources, and scans it with Xray. The command should be executed while inside the root directory of the project.

This command requires version 3.29.0 or above of Xray and also version 2.1.0 or above of JFrog CLI.

Command name	audit-npm
Abbreviation	an
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--licenses	[Default: false] Set if you'd also like the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
--fail	[Default: true] Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray.
Command arguments	The command accepts no arguments

Examples

Example 1

Audit the npm project at the current directory using the watch1 watch defined in Xray.

jf an --watches "watch1"

Example 2

Audit the npm project at the current directory using the watch1 and watch2 watches defined in Xray.

jf an --watches "watch1,watch2"

Example 3

Audit the npm project at the current directory using the policies defined for project-1.

jf an --project "project-1"

Example 4

Audit the npm project at the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf an --repo-path "libs-local/release-artifacts/"

Example 5

Audit the npm project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jfrog an

Auditing Maven Projects

The audit-mvn command audits Maven projects, by generating a dependency tree for the sources, and scans it with Xray. The command should be executed while inside the root directory of the project.

This command requires:

Version 3.1.0 or above of Maven
Version 3.29.0 or above of Xray
Version 2.1.0 or above of JFrog CLI

Command name	audit-mvn
Abbreviation	am
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--exclude-test-deps	[Default: false] Set if you'd like to exclude test dependencies from Xray scanning.
--licenses	[Default: false] Set if you'd also like the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
--fail	[Default: true] Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray.
Command arguments	The command accepts no arguments

Examples

Example 1

Audit the Maven project at the current directory using the watch1 watch defined in Xray.

jf am --watches "watch1"

Example 2

Audit the Maven project at the current directory using the watch1 and watch2 watches defined in Xray.

jf am --watches "watch1,watch2"

Example 3

Audit the Maven project at the current directory using the policies defined for project-1.

jf am --project "project-1"

Example 4

Audit the Maven project at the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf am --repo-path "libs-local/release-artifacts/"

Example 5

Audit the Maven project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jf am

Auditing Gradle Projects

The audit-gradle command audits Gradle projects, by generating a dependency tree for the sources, and scans it with Xray. The command should be executed while inside the root directory of the project.

This command requires version 3.29.0 or above of Xray and also version 2.1.0 or above of JFrog CLI.

Command name	audit-gradle
Abbreviation	ag
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--use-wrapper	[Default: false] Set if you'd like to use the Gradle wrapper.
--exclude-test-deps	[Default: false] Set if you'd like to exclude test dependencies from Xray scanning.
--licenses	[Default: false] Set if you'd also like the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
--fail	[Default: true] Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray.
Command arguments	The command accepts no arguments

Examples

Example 1

Audit the Gradle project at the current directory using the watch1 watch defined in Xray.

jf ag --watches "watch1"

Example 2

Audit the Gradle project at the current directory using the watch1 and watch2 watches defined in Xray.

jf ag --watches "watch1,watch2"

Example 3

Audit the Gradle project at the current directory using the policies defined for project-1.

jf ag --project "project-1"

Example 4

Audit the Gradle project at the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf ag --repo-path "libs-local/release-artifacts/"

Example 5

Audit the Gradle project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jf ag

Auditing Pip Projects

The audit-pip command audits python projects using the pip client, by generating a dependency tree for the sources, and scans it with Xray. The command should be executed while inside the root directory of the project.

This command requires version 3.29.0 or above of Xray and also version 2.4.0 or above of JFrog CLI.

Command name	audit-pip
Abbreviation	ap
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--licenses	[Default: false] Set if you'd also like the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
--fail	[Default: true] Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray.
Command arguments	The command accepts no arguments

Examples

Example 1

Audit the Pip project at the current directory using the watch1 watch defined in Xray.

jf ap --watches "watch1"

Example 2

Audit the Pip project at the current directory using the watch1 and watch2 watches defined in Xray.

jf ap --watches "watch1,watch2"

Example 3

Audit the Pip project at the current directory using the policies defined for project-1.

jf ap --project "project-1"

Example 4

Audit the Pip project at the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf ap --repo-path "libs-local/release-artifacts/"

Example 5

Audit the Pip project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jf ap

Auditing Go Projects

The audit-go command audits Go projects using the Go client, by generating a dependency tree for the sources, and scans it with Xray. The command should be executed while inside the root directory of the project.

This command requires version 3.29.0 or above of Xray and also version 2.4.0 or above of JFrog CLI.

Command name	audit-go
Abbreviation	ago
Command options
--server-id	[Optional] Server ID configured using the jfrog c add command. If not specified, the default configured server is used.
--project	[Optional] JFrog project key, to enable Xray to determine security violations accordingly. The command accepts this option only if the --repo-path and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--repo-path	[Optional] Artifactory repository path in the form of <repository>/<path in the repository>, to enable Xray to determine violations accordingly. The command accepts this option only if the --project and --watches options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--watches	[Optional] A comma separated list of Xray watches, to enable Xray to determine violations accordingly. The command accepts this option only if the --repo-path and --repo-path options are not provided. If none of the three options are provided, the command will show all known vulnerabilities
--licenses	[Default: false] Set if you'd also like the list of licenses to be displayed.
--format=json	[Optional] Produces a JSON file containing the scan results.
--fail	[Default: true] Set to false if you do not wish the command to return exit code 3, even if the 'Fail Build' rule is matched by Xray.
Command arguments	The command accepts no arguments

Examples

Example 1

Audit the Go project at the current directory using the watch1 watch defined in Xray.

jf ago --watches "watch1"

Example 2

Audit the Go project at the current directory using the watch1 and watch2 watches defined in Xray.

jf ago --watches "watch1,watch2"

Example 3

Audit the Go project at the current directory using the policies defined for project-1.

jf ago --project "project-1"

Example 4

Audit the Go project at the current directory using the policies defined for the libs-local/release-artifacts/ path in Artifactory.

jf ago --repo-path "libs-local/release-artifacts/"

Example 5

Audit the Go project at the current directory. Show all known vulnerabilities, regardless of the policies defined in Xray.

jfrog ago

Scanning Published Builds

JFrog CLI is integrated with JFrog Xray and JFrog Artifactory, allowing you to have your build artifacts and dependencies scanned for vulnerabilities and license violations. This command allows scanning a build, which had already been published to Artifactory using the build-publish command.

Command name	build-scan
Abbreviation	bs
Command options
--server-id	[Optional] Server ID configured by the jfrog c add command. If not specified, the default configured server is used.
--vuln	[Optional] Set if you'd like to receive all vulnerabilities, regardless of the policy configured in Xray.
--fail	[Default: true] When set, the command returns exit code 3 if a 'Fail Build' rule is matched by Xray. Set to false if you do not wish the command to return exit code 3 in such case, and an exit code 0 will be returned.
--format	[Default: table] Defines the output format of the command. The accepted values are: *table* and json.
--project	[Optional] JFrog project key
Command arguments	The command accepts two arguments.
Build name	Build name to be scanned.
Build number	Build number to be scanned.

Example

jf bs my-build-name 18

Page tree

CLI for JFrog Xray

Overview

Authentication

Authenticating with Username and Password

Authenticating with an Access Token

General Commands

Running cUrl

Command name

Abbreviation

Command options

Command arguments

Examples

Downloading updates for Xray's database

Command name

Abbreviation

Command options

Command arguments

On-Demand Binary Scan

Scanning Files on the Local File System

Command name

Abbreviation

Command options

Command arguments

Pattern

Scanning Docker Containers on the Local File System

Command name

Abbreviation

Command options

Command arguments

Pattern

Scanning Project Dependencies

Auditing Npm Projects

Command name

Abbreviation

Command options

Command arguments

Examples

Auditing Maven Projects

Command name

Abbreviation

Command options

Command arguments

Examples

Auditing Gradle Projects

Command name

Abbreviation

Command options

Command arguments

Examples

Auditing Pip Projects

Command name

Abbreviation

Command options

Command arguments

Examples

Auditing Go Projects

Command name

Abbreviation

Command options

Command arguments

Examples

Scanning Published Builds

Command name

Abbreviation

Command options

Command arguments

Example