Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

To set up your initial Xray configuration, we recommend that you go through the Onboarding Wizard which will be invoked automatically first time you run Xray. 

Once you have completed the Onboarding Wizard you may go through the following steps as needed at any time to update and add to your configuration.

  1. Connect to additional Artifactory instances and specify repositories that should be analyzed

  2. Manage Users

  3. Configure a mail server

  4. Configure webhooks

  5. Define watches

  6. Indexing artifacts 

  7. Synchronizing the database  


Xray Configuration File

Xray's configuration parameters are stored in its configuration file which is located in:

/opt/jfrog/xray/data/config/xray_config.yaml when running on Red Had Linux, and in:

$XRAY_HOME/config/xray_config.yaml when running on other supported flavors of Linux.

Connecting to Artifactory

You may connect Xray to several instances of JFrog Artifactory. When a connection between Xray and Artifactory is established, a user with "admin" privileges called xray is created in Artifactory which allows Xray to access the data it needs to perform its different analyses and functions.

To view the list of Artifactory instances connected, in the Admin module, select Artifactory.

Artifactory instances

Page Contents

 

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

ID
The Artifactory ID you provided when registering the instance.
Artifactory URL
The URL of the registered Artifactory instance, including the "/artifactory" path (as in the screenshot).
License
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.

Artifactory ID
A logical identifier for this Artifactory instance.
Description
A description of this instance.
Artifactory URL
The URL by which this instance will be accessed.
Proxy Enabled
When set, Xray will connect to this Artifactory instance through the HTTP proxy defined in the Admin module.
Admin User
A user with admin privileges in this instance.
Admin Password
The admin password.
Test Connection
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.

Selecting repositories for indexing

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

Indexed Repositories

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. 

Configure Indexed Builds

Want all builds scanned?

If you do want Xray to scan all builds, in the $XRAY_HOME/config/xray_config.yaml, set indexAllBuilds: true and restart Xray.

 


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

Users

User Name
The user name with which the user should log on to Xray
Email
The user's email. This is the default email to which notifications will be sent for this user's watchers.
Admin
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.

Creating and Editing a User

User Name
The user name that this user should log in with, or use to run REST API calls
Email
The user's email
Admin
When set, this user will have admin privileges and therefore have access to a wider range of features and REST API calls
Password

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.

SaaS users

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.

Mail Configuration

Host
The host name of the mail server.
Port
The port of the mail server.
Username
The username for authentication with the mail server.
Password
The password for authentication with the mail server.
From (optional)

The "from" address header to use in all outgoing mails.

Subject Prefix
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.

Use SSL/TLS

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.

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.

Webhooks

Click on a webhook to edit its details, or on New Webhook to define a new one.

New webhook

General
Webhook Name
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
URL
The URL that this webhook invokes. For details of the payload provided by Xray to the webhook, please refer to Webhook Payload.
Description
A free text description
 
Basic Auth
User Name/Password
A username and password as required by the webhook
 
Custom Headers
Any custom headers that may need to be added to invoke the webhook

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.

Indexed repositories

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.

Resource intensive

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:

1. https://dl.bintray.com
2. https://akamai.bintray.com
3. https://jxray.jfrog.io

To test the ability to sync, run the following REST API endpoint:

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.

Database Sync

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.

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.

 

Offline Synch

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

To skip having to validating a site's self-signed SSL certificate, you may add the sslInsecure parameter in Xray's xray_config.yaml configuration file, and set it to "true" (default, false) as follows: 

---
    ver:                   	1.0
    XrayServerPort:       	8000
    mqBaseUrl:            	amqp://guest:guest@rabbitmq:5672/
    mongoUrl:             	mongodb://xray:password@mongodb:27017/?authSource=xray&authMechanism=SCRAM-SHA-1
    webFolder:            	/opt/jfrog/xray
    postgresqlUrl:        	postgres://xray:xray@postgres:5432/xraydb?sslmode=disable`
	sslInsecure:			true

From version 2.0, the sslnsecure parameter was removed from the xray_config.yaml 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). 

In the Admin module, under HTTP Settings configure the HTTPs settings and click Save.

Use SSL
When set, Xray will be accessible via HTTPS at the corresponding port that is set.
HTTPS Port
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. When reaching the specified value, Xray will NOT download packages for indexing.
SSL Certificate Path
The full path to the certificate file for access via HTTPS.

 

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


 


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.

Configuring a 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.

General Settings

Basic Configuration

Xray Base URL

The base URL through which Xray can be accessed. The base URL uses the following format: PROTOCOL://IP_OR_HOST:8000

For example, http://10.120.12.123:8000 or http://XRAY_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: http://127.0.0.1:8000, http://10.120.12.123:8000/web/#/home

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

System Parameters

SSL Insecure
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
Job Interval
Interval for running node specific jobs

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.

Index
The number of workers managing indexing of artifacts.
Binary Manager
The number of workers managing communication with Artifactory.
Event
The number of workers handling events issued by Artifactory to Xray.
Persist
The number of workers managing persistent storage needed to build the artifact relationship graph.
Alert
The number of workers managing alerts.
Analysis
The number of workers involved in scanning analysis.
Impact Analysis
The number of workers involved in impact analysis to determine how a component with a reported issue impacts others in the system.
Notification
The number of workers managing notifications.

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 and change the password as follows:

# Access MongoDB as the Xray user
$ mongo --port 27017 -u "xray" -p "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>

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.


 

 

 

  • No labels