Configuring Xray

The screen displays the list of Artifactory instances you have added to Xray showing:

Adding a New Instance

To add a new instance, click the New instance link and fill in the form displayed.

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. 

Managing Users

Xray supports two ways to manage users:

1. Through an Authentication Provider
2. 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. 

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.

Configuring a Mail Server

Xray sends email notifications to users for different events that occur.

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.

Configuring Webhooks

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.

Indexing Artifacts

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.

Synchronizing the Database

https://jxray.jfrog.io/api/v1/system/ping

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. 

Online Synchronization

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.

Offline Synchronization

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.

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

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: $XRAY_HOME/data/ssl/serverCerts

Then go to Admin module > HTTP Settings, click Refresh to see the added SSL files, and click save.

For a Docker-based installation, copy the certificates to your xray-server container using the following command:

docker cp <PATH_TO_CERTIFICATES> <XRAY_SERVER_CONTAINER>:/var/opt/jfrog/xray/data/ssl/serverCerts

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.

setcap cap_net_bind_service=ep /opt/jfrog/xray/bin/server

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.

General Settings

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.

Basic Configuration

Queue Workers

Queue Workers offers several parameters you may configure to tweak the performance of Xray by changing the number of workers performing the different tasks.

System Parameters

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.

MongoDB

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: ~/MongoDB_Admin_pass.txt

You can log into the MongoDB database and change the password as follows:

# Access MongoDB as the Xray user
$ mongo --port 27017 -u "xray" -p "<current_password>" --authenticationDatabase "xray"
 
# Switch to the xray database
$ use xray
 
# Update the credentials
$ db.updateUser("xray",{pwd: "<new_password>"})
 
# Verify the update was successful by logging in with the new credentials
$ mongo --port 27017 -u "xray" -p "<new_password>" --authenticationDatabase "xray"

PostgreSQL

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:

# Access PostgreSQL as the Xray user adding the optional -W flag to invoke the password prompt
$ psql -d xraydb -U xray -W
 
# Securely change the password for user "xray". Enter and then retype the password at the prompt.
\password xray
 
# Verify the update was successful by logging in with the new credentials
$ psql -d xraydb -U xray -W

RabbitMQ

Xray comes pre-installed with RabbitMQ using its default credentials of: User:  guest, Password: guest

To change the default credentials, follow the steps below:

# Change the default password
$ rabbitmqctl change_password guest <new_password>
 
# Verify the update was successful
$ rabbitmqctl authenticate_user guest <new_password>

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.

	mqBaseUrl:            amqp://<user>:<password>@rabbitmq:5672/
    mongoUrl:             mongodb://<user>:<password>@mongodb:27017/?authSource=xray&authMechanism=SCRAM-SHA-1
    postgresqlUrl:        postgres://<user>:<password>@postgres:5432/xraydb?sslmode=disable

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.

1. Once file is ready, create a Kubernetes secret from it. For example:

   kubectl create secret generic <SECRET_NAME> --from-file=<PATH/TO/TEMP/YAML>/temp.xray_config.yml

2. 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 xray data-volume to /var/opt/jfrog/xray/data


3. In the init container, copy temporary file to /var/opt/jfrog/xray/data/.secrets/.temp.xray_config.yml


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

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. 

maxOpenConnServer: 30
maxIdleConnServer: 15
maxOpenConnPersist: 30
maxIdleConnPersist: 15
maxOpenConnAnalysis: 30
maxIdleConnAnalysis: 15
maxOpenConnIndexer: 30
maxIdleConnIndexer: 15