Need help with other JFrog products?

JFrog Platform
JFrog Artifactory
JFrog Xray
JFrog Mission Control
JFrog Distribution
[JFrog Pipelines]
JFrog Access


Page tree
Skip to end of metadata
Go to start of metadata

Overview

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

Read more about JFrog CLI here.

Syntax

When used with JFrog Artifactory, JFrog CLI uses the following syntax:

$ jfrog xr command-name arguments options


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 optionDescription 
--urlJFrog Xray API endpoint URL. It usually ends with /xray
--userJFrog username
--passwordJFrog 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 optionDescription 
--urlJFrog Xray API endpoint URL. It usually ends with /xray
--access-tokenJFrog 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

curl

Abbreviation
cl
Command options


--server-id

[Optional]

Server ID configured using the jfrog rt 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:

  1. The full Xray URL should not be passed. Instead, the REST endpoint URI should be sent.
  2. 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.

jfrog 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.

jfrog 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

offline-update

Abbreviation
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 command scans files on the local file-system with Xray. 

This command requires version 3.29.0 or above of Xray and also 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 rt 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 which files should be uploaded to Artifactory. You can specify multiple files by using wildcards.

Examples

Example 1

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

jfrog xr 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.

jfrog xr 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. 

jfrog xr 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.

jfrog xr 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.

jfrog xr 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.

jfrog xr s "*.tgz"

Dependencies Scan

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 rt 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. 

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. 

jfrog xr an --watches "watch1"

Example 2

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

jfrog xr an --watches "watch1,watch2"

Example 3

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

jfrog xr 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.

jfrog xr 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 xr 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.29.0 or above of Xray and also 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 rt 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. 

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. 

jfrog xr am --watches "watch1"

Example 2

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

jfrog xr am --watches "watch1,watch2"

Example 3

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

jfrog xr 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.

jfrog xr 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.

jfrog xr 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 rt 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. 

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. 

jfrog xr ag --watches "watch1"

Example 2

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

jfrog xr ag --watches "watch1,watch2"

Example 3

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

jfrog xr 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.

jfrog xr 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.

jfrog xr 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 rt 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. 

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. 

jfrog xr ap --watches "watch1"

Example 2

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

jfrog xr ap --watches "watch1,watch2"

Example 3

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

jfrog xr 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.

jfrog xr 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.

jfrog xr 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 rt 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. 

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. 

jfrog xr ago --watches "watch1"

Example 2

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

jfrog xr ago --watches "watch1,watch2"

Example 3

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

jfrog xr 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.

jfrog xr 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 xr ago
  • No labels