XRAY: Xray 3.X Quickstart

Raphael Zaafrani
2022-08-31 11:22

Xray 3.X Quickstart guide:

The first thing to know is that Xray is quite resourced intensive, as such you will need to meet the following system requirements to ensure proper performance.

User-added image
User-added image

Once you have a machine meeting the specified requirements follow this guide to install Xray.

Now that Xray is installed and connected to your Artifactory instance you're ready to get started!

1. Database Sync:

The first thing to do when setting up your Xray instance is to trigger the Database Sync. JFrog engineers have aggregated information from internal vulnerability research, as well as private and public databases, into one database. This is the basis of all of Xray's findings, as such until the Database Sync is successfully completed Xray will not provide valid results to scans.

You can manually trigger the Database Sync from your Artifactory UI under Administration → Xray → Settings → General → Database Sync 

User-added image

From that menu, you can check on the status of your DB Sync, if it has not started yet you can trigger it by pressing the following button.

User-added image
Please note that while the first sync will be quite intensive and take a long time, all subsequent synchronizations will be fast and almost unnoticeable.

2. Indexed Resources:

In order to add repositories or builds to a watch, you will first need to add them to the Indexed Resources. You can reach the Indexed Resources from your Artifactory UI under Administration → Xray → Settings → General → Indexed Resources

User-added image
From that menu, simply press "Add a Repository" in the top right corner and, from the pop-up menu shown in the screenshot below, select which repositories you would like Xray to have access to.

User-added image
If you would like to index builds, the approach is the same under the Build tab in the top left corner. But in the Build Indexing menu, you will have the option to index builds by pattern. You can learn how to index all builds in this article.

3. Policies and Watches:

Below I will give a simple overview of Policies and Watches. You can find more detailed information in this article: "Creating Xray Policies and Rules".

Policies are contextless sets of security or license compliance rules. They decide what to flag in a scan. 
To get started and create a new policy, in the UI navigate to Administration → Xray → Watches & Policies  and select New Policy

User-added image
There you will have the choice between three types of policies. 
User-added image

Each type of policy will have its own specific set of rules:

1. Security:

Set of rules relating to vulnerability analysis. 

  • Minimal Severity (Minor, Major, Critical, All): The minimal security vulnerability severity as it is in the JFrog vulnerabilities database. If the artifact or build contains a vulnerability with the selected severity or higher, the rule will meet the criteria, the automatic actions will be executed, and the policy will stop processing.
  • CVSS Score (1-10): The CVSS score range to apply to the rule. This is used for a fine-grained control, rather than using the predefined severities. The score range is based on CVSS v3 scoring, and CVSS v2 score if CVSS v3 score is not available.
  • Generate violations only when fixed versions are available: Xray will not generate violations for issues that do not contain a fixed version. If a fixed version is available later, the violation will be generated. 

2. License:

Set of rules letting you decide what type of license you allow or ban in your builds.

  • Allowed Licenses: Specifies an Allow List of OSS licenses that may be attached to a component. If a component has an OSS license outside the specified Allow List, The rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing.
  • Banned Licenses: Specifies a Block List of OSS licenses that may not be attached to a component. If a component has any of the OSS licenses specified, the rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing.
  • Disallow Unknown License: Specifies the wanted behavior for components whose license cannot be determined. A violation will be triggered if a component with an unknown license is found.

3. Operational Risk:

Components Operational Risk is the risk of using outdated or inactive open source software components in your projects.

  • Minimal Risk (High, Medium, Low): Preset risk values. Learn more about it here.
  • Custom Condition:
    • Use between (AND/OR): Boolean operator between the following rules.  
    • Is End-Of-Life: Did the developer of the OSS package declare that development has stopped or the package is obsolete.
    • Release age greater than (in months): If the package has been released for at least X months.
    • Number of releases since greater than: If the OSS package has seen at least X since the current version.
    • Release cadence less than (per year): If fewer than X releases have been published per year.
    • Number of commits less than (per year): If the package has had fewer than X commits per year.
    • Number of committers less than (per year): If the package has had contributions from fewer than X developers.
    • Risk Severity (Low, Medium, High):  At least matching the calculated risk value.

Each of those rules can have automatic actions when triggered.

User-added image
User-added image
Refer to this article for more information on automatic actions.

Now that your policies are set up, you can create watches to scan your artifacts and enforce the rules we've just set. 

To create a watch, in the same UI menu as the policies, navigate to Watches and select New watch. 
User-added image

Here simply select an option under "Manage Resources". There you will see only the repositories and builds indexed in step 2 so revert back to that step if you do not see the resource you're looking for.

Once you have selected the desired resources, assign the previously created policies by selecting "Manage Policies"
There you will be able to select one or more policies for your watch to use when scanning artifacts.

User-added image
And you are done! Now that your watch has been successfully set up, every upload to the selected resources will be automatically scanned and flagged as described in the policies assigned to the watch. 

If you'd like to scan data that was already present in the resources before the watch was set up, simply click "Apply on Existing Content" to run a historic scan on the Watch's targets.

User-added image