Using the latest JFrog products?
JFrog Platform User Guide
JFrog Xray 2.x Documentation
To get the latest version, go to the JFrog Unified Platform
The screen displays the list of Artifactory instances you have added to Xray showing:
|The Artifactory ID you provided when registering the instance.|
|The URL of the registered Artifactory instance, including the "/artifactory" path (as in the screenshot).|
|Indicates if the Xray license in the selected Artifactory instance is valid or not.|
Number of Indexed Files
|Indicates the number of files has indexed for the Artifactory instance according to the repositories specified for analysis in Artifactory|
Adding a New Instance
To add a new instance, click the New instance link and fill in the form displayed.
|A logical identifier for this Artifactory instance.|
|A description of this instance.|
|The URL by which this instance will be accessed.|
|When set, Xray will connect to this Artifactory instance through the HTTP proxy defined in the Admin module.|
|A user with admin privileges in this instance.|
|The admin password.|
|Tests the connection between Xray and Artifactory (in both directions) to ensure you have configured it correctly.|
Specifying Repositories for Analysis
To avoid a lengthy and intensive analysis processes, Xray does not analyze all repositories in the connected Artifactory instance. Instead, after you create a new Artifactory instance, Xray will display the repositories in that instance so you can select which ones should be indexed for analysis.
Once you have specified repositories for analysis in Artifactory, they will appear in the Repositories tab under Indexed Resources in the Artifactory Instance page (in the Admin module under Artifactory).
You may now index artifacts in the selected repositories for analysis as described in Indexing Artifacts.
Specifying Builds for Analysis
To avoid a lengthy and intensive analysis processes, Xray does not analyze all builds in the connected Artifactory instance. Instead, after you create a new Artifactory instance, in the Builds tab of the Indexed Resources panel, you can select which builds should be indexed for analysis.
Want all builds scanned?
If you do want Xray to scan all builds, in the
indexAllBuilds: true and restart Xray.
Xray supports two ways to manage users:
- Through an Authentication Provider
- Defining Users Internally
Managing Users Through an Authentication Provider
From version 1.9, you can set one of the connected Artifactory instances as an Authentication Provider. In this case, Artifactory will first try to authenticate users through the means set for that instance (whether LDAP/Crowd or SAML).
For details, please refer to Authentication.
Managing Users Internally
Using an Authentication Provider is not mandatory, and you can always define users internally within Xray.
You can view the list of users registered with Xray under the Admin module under Users.
|The user name with which the user should log on to Xray|
|The user's email. This is the default email to which notifications will be sent for this user's watchers.|
|Indicates if this user has admin privileges|
Creating and Editing a User
To add a new user, click New user, or click an existing user in the table displayed to edit their details.
|The user name that this user should log in with, or use to run REST API calls|
|The user's email|
|When set, this user will have admin privileges and therefore have access to a wider range of features and REST API calls|
The user's password. The user will need this to log in or run REST API calls.
Configuring a Mail Server
Xray sends email notifications to users for different events that occur.
This configuration is not available for SaaS users where a default mail server is automatically configured.
Some examples are:
- Watchers can send alerts by email.
- Users may be notified about changes in their account information
To enable mail notifications, you need to configure Xray with your mail server details under Admin | Mail as described below.
|The host name of the mail server.|
|The port of the mail server.|
|The username for authentication with the mail server.|
|The password for authentication with the mail server.|
The "from" address header to use in all outgoing mails.
|A prefix to use for the subject of all outgoing mails.|
Artifactory URL (optional)
The Artifactory URL to use in all outgoing mails to denote links to Artifactory.
When set, uses Transport Layer Security when connecting to the mail server.
Send Test Mail
|Click to send a test message to the specified email address.|
One of the options when configuring Watches is to have them invoke webhooks which are proprietary URLs you can define to perform custom actions as a result of a violation being issued.
Webhooks are displayed in the Admin module under Webhooks.
Click on a webhook to edit its details, or on New Webhook to define a new one.
|An identifier for the webhook. This is the name that will be used by any Watches that want to invoke the webhook in case of a violation|
|The URL that this webhook invokes. For details of the payload provided by Xray to the webhook, please refer to Webhook Payload.|
|A free text description|
|A username and password as required by the webhook|
|Any custom headers that may need to be added to invoke the webhook|
JFrog Xray provides information on issues and vulnerabilities in components it has indexed. During normal operation, the database of components is continuously updated and reindexed when changes are made to components in repositories marked for analysis, however, to set up the initial database you need to manually invoke indexing for the repositories that were marked for analysis.
In the Admin module, under Artifactory, you can view the list of connected Artifactory instances. Click the instance whose repositories you want to index. The details page for that instance shows the list of repositories marked for indexing.
This Index Status column will indicate for which repositories indexing is up-to-date, and which need to be indexed. You may click Calculate to initiate indexing of a single repository, or check several repositories and click Index Now to initiate indexing for multiple repositories at a time.
Depending on the size of the repository, indexing be a resource intensive operation, so we recommend invoking indexing on repositories separately to avoid excessive loads on your system.
Synchronizing the Database
Using a firewall?
If you are using a firewall, to allow the database sync to complete successfully, you need to add the following URLs to your firewall's whitelist:
To test the ability to sync, run the following REST API endpoint:
For Xray to scan your indexed artifacts it must ingest data on issues and vulnerabilities from the various feeds it is connected to. The primary feed comes from the global database server maintained by JFrog (additional feeds include direct connections you may have through Xray's integrations with external providers). There are two ways to synchronize Xray with the global database server:
- Online: In online mode, Xray synchronizes with the global database server automatically on a daily basis through an internet connection
- Offline: In offline mode, you manually download files from the global database server and then upload them to Xray
To configure synchronization with the global database server, in the Admin module, select Database Sync.
To get started right away so Xray can scan your artifacts, you may invoke the initial synchronization manually by selecting Start Sync in the Status panel. From then on, Xray will synchronize issues and vulnerabilities regularly and automatically, once a day.
If, for any reason, you do not want to maintain a live internet connection to the global database server, select Offline in the Sync Mode panel to get detailed instructions on how to get the latest data available.
Version compatibility with JFrog CLI
An offline database synchronization requires the use of JFrog CLI.
From Xray version 2.1.2, to do an offline synchronization, you must have JFrog CLI version 1.16.2 or higher.
Pausing and Resuming Synchronization
Updating Xray with the latest data from the global database server may be a resource intensive operation. During an update, you may click the corresponding link in the Status panel to pause the operation at any time to free up resources, and then resume it later.
Working with SSL Using Self-Signed Certificates
Xray is able to work over a secure connection when connecting to other applications and services. For example, it connects to Artifactory through HTTPS. As part of the HTTPS protocol, Xray is able to verify the site's identity by validating its SSL certificate, however, in cases of a trusted connection, a site may use a self-signed certificate which cannot be validated (which may be the case in an Artifactory/Xray connection).
From version 2.0, the
sslInsecure parameter was removed from the
file. This configuration has moved to the General Settings in the Xray UI.
Configuring HTTPS Settings
You can configure access to Xray via HTTP, HTTPS or both (at least one is required).
To configure access to Xray with HTTPS, paste your SSL key and SSL certification files in the following directory:
Then go to Admin module > HTTP Settings, click Refresh to see the added SSL files, and click save.
|When set, Xray will be accessible via HTTPS at the corresponding port that is set.|
|Sets the port for the HTTPS server. The default value is 8000 and is configured in the xray_config.yaml file.|
SSL Key Path
|The full path to the key file for access via HTTPS.|
(Note: this can only be configured by inserting your certificates in the
SSL Certificate Path
|The full path to the certificate file for access via HTTPS. (Supported formats: .cer, .crt, .csr, .pem)|
(Note: this can only be configured by inserting your certificates in the
For a Docker-based installation, copy the certificates to your xray-server container using the following command:
In case self signed certificates are used, enable ‘SSL Insecure’ in the Admin module, under General Settings. Then, import the certificates to Artifactory.
After setting up the certificates, update the ‘Xray Base URL’ to HTTPS and restart Xray.
When changing the default port to use a port below 1024, for example, to run a server listening on port 80, use the following command:
setcap cap_net_bind_service=ep /opt/jfrog/xray/bin/server
For Docker installations, exec into the xray-server container as root and run the following command:
setcap cap_net_bind_service=ep /opt/jfrog/xray-server/server
Configuring a Proxy
Depending on your organization's policies, you may need to configure Xray to access external resources through a proxy which may be configured in the Admin module under Proxy.
Xray is built on a set of microservices that perform its actions in the realm of indexing artifacts, communicating with Artifactory, managing events and notifications and so on.
Xray Base URL
The base URL through which Xray can be accessed. The base URL uses the following format: PROTOCOL://IP_OR_HOST:8000
Note that the Xray Base URL should not be defined as "localhost", or "127.0.0.1", and should not include the "/web" element. For example, the following base URLs would NOT work:
Xray access URL is not its base URL
Be careful not to confuse Xray's access URL with its base URL.
Xray's access URL is: <XRAY_BASE_URL>/web/#/home
If you set the access URL in the Xray Base URL field, connected Artifactory instances will not be able to communicate with Xray
Queue Workers offers several parameters you may configure to tweak the performance of Xray by changing the number of workers performing the different tasks.
|The number of workers managing indexing of artifacts.|
|The number of workers managing communication with Artifactory.|
|The number of workers handling events issued by Artifactory to Xray.|
|The number of workers managing persistent storage needed to build the artifact relationship graph.|
|The number of workers managing alerts.|
|The number of workers involved in scanning analysis.|
|The number of workers involved in impact analysis to determine how a component with a reported issue impacts others in the system.|
|The number of workers managing notifications.|
|Toggles enablement of skipping Xray's self-signed certificate validation|
Mail Without SSL
|Toggles usage of Transport Layer Security when connecting to the mail server|
Max Disk Usage
|Percentage of disk usage tolerated by Xray. When reaching the specified value, Xray will NOT download packages for indexing|
Monitor Sampling Interval
|Interval for executing monitoring jobs on CPU, Disk Usage, restarts, etc.|
Queue Message Max TTL
|Number of retries to be accepted in the Message Queue system|
|Interval for running node specific jobs|
For more details on how adjusting these parameters may affect your system's performance, please contact JFrog Support.
Changing Third Party Service Credentials
Xray works with a number of third party services, such as various databases, which come pre-configured with default credentials for access by Xray. The following sections show how to change these default credentials.
To change the default credentials used by Xray to access its internal MongoDB database, you need to log into the database as the "xray" user, with the password that was established at the time Xray was installed.
If the version of Xray that was initially installed was release 2.8.8 or older, the default password is "password".
If the version of Xray initially installed was release 2.8.9 or newer, the default password is a random string that was generated by the install procedure, then encrypted by the Xray master.key. The generated password is stored under the /root folder as a text file called
MongoDB_Admin_pass.txt. Depending on how Xray was installed, it might be in the local user's home directory:
You can log into the MongoDB database and change the password as follows:
To change the default credentials used by Xray to access its internal PostgreSQL database, you need to log into the database as the "xray" user and change the password as follows:
Xray comes pre-installed with RabbitMQ using its default credentials of: User: guest, Password: guest
To change the default credentials, follow the steps below:
Hardening Security for Secrets
Xray uses a set of encrypted parameters (secrets) used to connect to external resources such as the different databases it uses. While these secrets may be stored in the Xray configuration file, this poses a risk of their being exposed.
To keep secrets safe from exposure, from version 2.5, on Xray installations running in Kubernetes, you may pre-load secrets from a temporary file first time you startup Xray. Once Xray has read and successfully used the secrets, the file is deleted.
The snippet below shows an example of the parameters you could include in this temporary file. These are the connection strings with which Xray connects to the different databases it uses.
While we recommend only including sensitive information such as encrypted connection strings, this file may contain any of the Xray configuration parameters, and any parameters specified (including environment variables and system properties) will override the corresponding ones in the Xray configuration file.
Once file is ready, create a Kubernetes secret from it. For example:
- Using an init container, pre-load the secret as a volume to each of your Xray services to a temporary path.
You also need to mount
- In the init container, copy temporary file to
- Start Xray. During startup, if the temporary configuration file exists, Xray will read all parameters from it, and then delete the file. If Xray fails to delete the file, Xray will not start and will issue an error.
A full pod restart is required
Since the temporary file is deleted when Xray starts, a full pod restart is required if the Xray service container crashes and restarts.
This is a known limitation of the pod lifecycle. The automated pod restart on container crash is currently not supported.
Watch the Screencast
Watch this screencast and learn how to troubleshoot your Xray installation for problems related to proxy connections, database, network and compute resources.
Configuring PostgreSQL Connection Pools
You can configure the following PostgreSQL parameters in the xray_config.yml file for heightened system performance.