Cloud customer?
 Upgrade in MyJFrog >

Search





Overview

Once JFrog Xray is installed, administrators can set and update the following general configurations at any time:

Note: The Onboarding Wizard that is invoked automatically first time you login to the JFrog Platform, will also enable you to configure the Indexed Resources and Database Sync.

Additional advanced settings include:

Xray Configuration File

Xray's configuration parameters are stored in its configuration file which is located at <xray-compose-version>/.env for the Docker compose installation.

Xray Installation Files

The Xray installation files are available in the <xray-compose-version>/bin folder for the Docker compose installation.


Indexing Resources

To avoid a lengthy and intensive analysis processes, Xray does not automatically analyze all the resources in the system but allows you to manually select the repositories, builds and release bundles to be indexed.

To configure your indexed resources, in the Administration module, go to Xray Security and Compliance | General and click Indexed Resources.

From the Indexed Resources page:

  1. Select the resource type to index (Repositories | Builds | Release Bundles).
  2. Add Repositories/Builds/Release Bundles from the available resources in Artifactory.
    • For repositories, from the list of available repositories in Artifactory.
    • For builds and release Bundles, according to Name or Pattern
  3. Review the list of added resources.

Indexing All Builds

To index all current and any future builds, you can add an Include Pattern containing */**


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 primary feed that comes from the
global database server maintained by JFrog. 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 Administration module, select Xray | Database Sync

The Xray indexing process will only start after the initial DB sync process is completed.

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

For RPM installations the Updates folder is under the Data folder:

  • ${XRAY_HOME}/xray/data/updates/component
  • ${XRAY_HOME}/xray/data/updates/vulnerability


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.


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 configurable in the Administration module under Xray | Webhooks.

To add a webhook, click 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.

Use Proxy

Set the webhook to go through the predefined proxy. For more information, see Managing Proxies.

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.



Adding Custom Integrations

JFrog Xray is open for integration with any number of issue and vulnerability providers. This gives you the opportunity to add analyses from different providers with whom you may have an account, or even to create your own provider and display information such as performance issues, known defects or any other information offered by your provider. Xray integrations are configured in the Administration module in the Xray | Integrations page and displays the integrations you have configured and connected to.

To enable this, you'll need to build the following two REST endpoints and configure them in the Xray integrations page.

Building the Integration Endpoints

In order to enable your custom integration, you need to build and run two REST endpoints.

1. Check Authentication

Request an indication to whether a provided api key is valid. This API should be exposed by the feed provider.

Request header
apiKey: “some-api-key-which-is-unique-for-a-specific-customer”

GET /api/checkauth

Valid API Key Response Example (Status code: 200)
{
"valid" : true,
"error" : ""
}
Invalid API Key Response Example (Status code : 401)
{
"valid" : false,
"error" : "User api key is invalid"
}


2. Request for components information

This API will allow Xray to request for information about one or more components, each identified by a unique component id, from the feed provider. The API will be implemented by the feed provider.

Request

The request payload will contain unique identifiers of the components Xray would like to get information about.
In addition Xray will provide a context to the request, this can be a project id or another identifier. If the 3rd party service allows its users to define policies per project, this will allow to answer the request in the context of those policies. For example, if the 3rd party service allows creating policies for OSS license compliance per project, Xray may get a response with a license vulnerability if the queried component is violating the policy.

Request header
apiKey: "some-api-key-which-is-unique-for-a-specific-customer"
Request payload
{
	"components" : [
      {
 	 	"component_id": "gav://ant:ant:1.6.5",
		"blobs": [
			"97282a3b066de4ee4c9409979737f3911f95ceab"
		]
      }
	],
	"context" : "project_id"
}

Response

The response will contain a list of security vulnerabilities or other issues
{
	"components" : [
 	{"component_id" : "gav://ant:ant:1.6.5",
	"licenses" : ["Apache 2.0"],
     "provider" : "the feed provider",
	"vulnerabilities" : [
	{
  	"cve" : "CVE-2012-2098",
	"type" : "security",
	"source_id" : "unique id of the reported issue",
  	"summary" : "Algorithmic complexity vulnerability",
  	"description" : "Algorithmic complexity vulnerability in the sorting algorithms in bzip2 compressing stream",
  	"cvss_v2" : "7.9",
  	"url" : "http://more.info",
  	"publish_date" : "2015-11-03T07:30:51.991+00:00",
  	"references" : [	"http://archives.neohapsis.com/archives/bugtraq/2012-05/0130.html"
  	]
	}
	]}
 ]
}


Configuring the Integration Endpoints

To configure your endpoints, go to the Administration module in the Xray | Integrations page and click New Integration.

To add and connect to a custom provider, set the Enabled checkbox and enter the following parameters:

  • The Integration Vendor name
  • A Description for the vendor
  • The API Key you received from the provider
  • The URL Xray uses to check if a component it is scanning is registered with the provider.
    The URL should lead to the request for components information REST endpoint
  • The Test URL you can use to test your API key with the provider using the "Test" button.
    The Test URL should lead to the Check Authentication REST endpoint
  • The URL to an icon you can optionally display for the vendor

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

To configure these settings, in the Administration module, go to Xray Security and Compliance | Advanced and click Settings.

The following advanced configurations are available:

  • Basic Settings: allows enabling Xray, configuring the behaviour when it is unavailable and for blocked artifacts.
  • System Parameters: provides system settings.
  • Queue Workers: provides several parameters for tweaking Xray performance by changing the number of workers performing the different tasks.

Note: Adjusting these parameters may affect your system's performance, please contact JFrog Support for additional information.

Basic Settings

Xray Enabled

Indicates that Xray is enabled on the JFrog Platform and is set by default when Xray is installed.

Allow download and distribute when Xray is unavailable

Allows downloading artifacts from Artifactory and distributing Release Bundles to Edge Nodes when the Xray service is unavailable.

Allow downloads of blocked artifacts
Allows downloading all artifacts, including artifacts that have been blocked for download by Xray.
Block Unscanned Artifacts Download Timeout (Sec)

The max time a download request will be pending Xray to complete scanning the artifact.

When a repository is configured to block downloads of unscanned artifacts, this setting will make every download request connection remain open for the time configured (in seconds), allowing Xray sufficient time to scan the artifact and then return the artifact or block it based on scan results.

Important: make sure the client you are using to download artifacts from Artifactory is set with a high socket timeout value to ensure the connection will remain intact while Xray is scanning the artifacts. Example clients include: build CI server, package mangers, smart remote repository, cURL, etc.

This is also relevant when using a Smart Remote Repository, where Advanced → Socket Timeout (MS) should be set to a high value.

For Advanced Users:

The time interval for Artifactory to send scan requests to Xray can be configured using the following system property.

artifactory.xray.indexer.intervalSecs=60

This system property determines the interval between each artifact's events submission from Artifactory to Xray. When downloading a newly added artifact, an event is created in Artifactory, and this event is sent to Xray notifying it of a new artifact that needs to be scanned. In order for the block unscanned timeout to have enough time to get full scan results, Xray needs to be quickly notified that a new scan needs to be made, thus this system property needs to be changed to 10 seconds.

Note that an increase/tuning the Tomcat HTTP connection pool may be needed in order to support high load of connections while waiting for a scan to be completed.

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
Send Anonymous Statistics
Improves the Xray optimization by sending anonymous usage statistics.
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 Parameters

Index
The number of workers managing indexing of artifacts.
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.

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

Starting from Xray version 3.6, Xray prioritizes the scanning of new Artifacts/Builds/Release Bundles over events originating from a history scan or a full repository scan, and provides the capability to control the number of workers for new content versus history / full repository scan. To configure the number of workers, see Configuring the Workers Count REST API.

This requires Artifactory version 7.6 and above.




  • No labels
Copyright © 2020 JFrog Ltd.