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

Skip to end of metadata
Go to start of metadata

Overview

Watches monitor artifacts for issues, and trigger alerts if any are found based on two types of analysis which Xray performs

Scanning

Xray monitors builds or repositories in Artifactory for issues. Each time a monitored build is updated, or an artifact is deployed to a monitored repository, Xray will scan its dependencies and trigger a violation if any dependency with issues is found.

Impact Analysis

Xray listens to all providers currently streaming feeds regarding issues. If any provider notifies Xray of a new issue with an artifact, Xray looks up the artifact in its database. If the artifact is already in the database, Xray will perform an impact analysis to determine all the artifacts in Artifactory that are ultimately affected by the issue by virtue of their including the problematic artifact. The results are displayed in an impact analysis graph.

Focusing on Specific Components (Filters)

An active Artifactory instance may cause Xray to trigger many alerts on artifacts which are not interesting to you. To focus on artifacts you want to monitor, you can fine-tune Xray to trigger violations only for artifacts that pass through Filters you define based on the following parameters:

The specific filters available depend on the Target Type on which the watch is defined.

In addition, you need to define a Severity Filter to specify the minimum severity for which you want Xray to register a violation.

A watch in Xray will only register a violation for components that:

  • have been identified by one of Xray's providers to have some kind of vulnerability
  • meet all the criteria (i.e. Artifact Filters and/or Severity Filters) you defined for it. 

All the Watches defined in your system are displayed in the Watches module.

Watches

Page Contents

Ignore Rules

The Ignore Rules tab displays violations which you have chosen to ignore in the Component Details display.

Ignore Rules

Archived Alerts

From version 1.12, Xray introduced the concept of Violations which replaces Alerts, and Alerts are not generated any more.

The Archived Alerts tab displays all the alerts that Xray generated prior to being upgraded to version 1.12.

Archived Alerts


Creating and Editing a Watch

To create a new watch, click New Watch and fill in the fields that define the watch.

New Watch

General
 
Name
A logical name for this watch.
Target Type

Repository: The watch monitors the repository specified in the Repository Name field.

Every Artifact: The watch monitors all artifacts in all repositories indexed by Xray.

All Builds: The watch monitors all builds in all Artifactory instances connected to this instance of Xray.

Artifactory Instance
The Artifactory instance to which this watch should be applied. The watch will only take effect if Xray is currently connected to the specified instance.
Repository Name
The build or repository to watch based on the Target Type
Description
A general description of the Watch.
Enabled
When checked, the watch is enabled
 
Artifact Filters
Specifies which Artifact Filters to apply. Only artifacts matching all filters will trigger a violation.
  
Severity Filters

Specifies which Severity Filters to apply. Only artifacts detected to have violations that meet the Minimal Severity set or greater will trigger a violation.

  
Actions
Specifies what additional actions to take once aviolation has been triggered.

You can edit an existing Watch by clicking its name in the Watches table and editing its parameters in the form displayed.

Artifact Filters

The filters you define for a watch determine which components in the currently observed Artifactory instance will generate alerts and under what conditions. You can define any number of filters, and the watch will only trigger a violation if an artifact meets the condition of all of the filters defined. The following content filters are available:

  • Regex: Generate a violation based on a component's name
  • Package Type: Generate a violation based on a component's package type
  • Mime Type: Generate a violation based on a component's MIME type
  • Property: Generate a violation if a component is annotated with the specified property
  • Allowed/Banned Licenses: Generate a violation if a component uses a license that is not allowed

To add a filter to your watch, select the filter type and click "Add".

Artifact Filters

Xray will display the filter for you to specify the parameter to trigger a violation.

Pass through ALL filters

You can define any number of filters for a watch, and only artifacts that pass through all of them will trigger a violation.

Regex

Regex filter uses a regular expression to specify the name of an artifact. The watch will only trigger a violation if an artifact's name matches the expression.

Regex Filter

For example, the filter above specifies that the watch should only trigger a violation for rpm files.

Package Type

A Package Type filter specifies an artifact's package type. The watch will only trigger a violation if an artifact has the specified package type.

Package Type Filter

Mime Type

A Mime Type filter specifies an artifact's mime type. The watch will only trigger a violation if an artifact has the specified mime type.

Mime Type Filter

For example, the filter above specifies that the watch should trigger a violation for any artifact with an "application/json" mime type.

Property

A Property filter specifies a property annotating an artifact and its value. The watch will only trigger a violation if the property has the specified value.

Property Filter

For example, the filter above specifies that the watch should trigger a violation if an artifact with a property named "performance" has the value "false".

Allowed and Banned Licenses

An Allowed Licenses filter specifies a whitelist of OSS licenses that may be attached to an artifact. The watch will only trigger a violation if an artifact has an OSS license other than the ones specified. You may include "Unknown" in the list of allowed licenses to allow components with an unknown license to reside in your repositories without triggering a violation

A Banned Licenses filter specifies a blacklist of OSS licenses that may not be attached to an artifact. The watch will only trigger a violation if an artifact has any of OSS licenses specified. You may include "Unknown" in the list of banned licenses so that components whose license cannot be determined will trigger a violation.

You may specify either an Allowed License filter or a Banned licenses filter for a violation, but not both together. Once you have specified Allowed Licenses or Banned Licenses, use the Select Licenses link to specify the licenses to allow or ban.

Banned Licenses filter

Severity Filter

A Severity filter specifies the minimum severity of an issue associated with an artifact. If an artifact has an issue with an equal or higher severity, a violation is generated.

Severity filter is required

It is compulsory to define a Severity Filter for all watches.

Severity Filter

Actions

The Actions panel lets you specify additional actions that Xray should take once a violation has been triggered by watch in which the action is defined. You can specify multiple actions for a violation. To add an action, click Add Action.

Adding an Action

Notify Email

This action lets you specify email addresses to which Xray should send an email message about a violation when one is triggered. For this to work, you need to have a mail server configured in Xray. 

Notify Email Action

Trigger Webhook

This action lets you specify webhooks you have configured in Xray that should be invoked when a violation is triggered. 

Webhook Action

Webhook Payload

The payload provided to any triggered webhook is a JSON object describing a list of Alerts with the following format:

Alerts are being deprecated

From version 1.12, Alerts are in the process of being deprecated. Currently, the webhook payload still references alerts, however, this will be changed in forthcoming releases

{
  "alert_id": "<Alert ID>",
  "created": "<Alert creation time stamp in ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
  "top_severity": "<Top severity of any issue in the alert>",
  "watch_name": "<Logical name for the watch>",
  "issues": [
	{
		"severity": "<Issue severity>",
    	"type": "<Issue type>",
    	"provider": "<Issue provider>",
    	"created": "<Issue creation time stamp in ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    	"summary": "<Issue summary>",
      	"description": "<Issue description>",
      	"impacted_artifacts": [
			{
	      		"name": "<Artifact name>",
          		"display_name": "<Artifact dispalay name>",
          		"path": "<Artifact path in Artifactory>",
          		"pkg_type": "<Package type>",
          		"sha256": "<Artifact SHA 256 checksum>",
          		"sha1": "<Artifact SHA 1 checksum>",
          		"depth": <Artifact depth in its hierarchy>,
         		"parent_sha": "<Parent artifact SHA 1 checksum>",
  				"infected_files": [
            		{
              			"name": "<File name>",
              			"path": "<File path>",
              			"sha256": "<File SHA 256 checksum>",
              			"depth": <File depth in hierarchy>,
              			"parent_sha": "<File's parent SHA 1 checksum>",
              			"display_name": "<File's display name>",
              			"pkg_type": "File's package type"
            		}
				]	
			}
		]
	}
  ]
}

The following shows an example payload for a webhook

{
  "alert_id": "5aa6d687db80740001ac83b4",
  "created": "0001-01-01T00:00:00Z",
  "top_severity": "Critical",
  "watch_name": "no-Apache-2.0-builds",
  "issues": [
    {
      "severity": "Critical",
      "type": "security",
      "provider": "Custom",
      "created": "2018-03-12T19:12:06.702Z",
      "summary": "custom-glassfish",
      "description": "custom-glassfish",
      "impacted_artifacts": [
        {
          "name": "test",
          "display_name": "test:6639",
          "path": "artifactory-xray/builds/",
          "pkg_type": "Build",
          "sha256": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "sha1": "737145943754ac99a678d366269dcafc205233ba",
          "depth": 0,
          "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "infected_files": [
            {
              "name": "ant-1.9.4.jar",
              "path": "",
              "sha256": "649ae0730251de07b8913f49286d46bba7b92d47c5f332610aa426c4f02161d8",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "ant-1.9.4.jar",
              "pkg_type": "Generic"
            },
            {
              "name": "aopalliance-repackaged-2.4.0-b09.jar",
              "path": "",
              "sha256": "a97667a617fa5d427c2e95ce6f3eab5cf2d21d00c69ad2a7524ff6d9a9144f58",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "org.glassfish.hk2.external:aopalliance-repackaged:2.4.0-b09",
              "pkg_type": "Maven"
            }
          ]
        }
      ]
    },
    {
      "severity": "Critical",
      "type": "License",
      "summary": "Apache-2.0",
      "description": "Apache License 2.0",
      "impacted_artifacts": [
        {
          "name": "test",
          "display_name": "test:6639",
          "path": "artifactory-xray/builds/",
          "pkg_type": "Build",
          "sha256": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "sha1": "737145943754ac99a678d366269dcafc205233ba",
          "depth": 0,
          "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "infected_files": [
            {
              "name": "ant-1.9.4.jar",
              "path": "",
              "sha256": "649ae0730251de07b8913f49286d46bba7b92d47c5f332610aa426c4f02161d8",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "ant-1.9.4.jar",
              "pkg_type": "Generic"
            },
            {
              "name": "aopalliance-repackaged-2.4.0-b09.jar",
              "path": "",
              "sha256": "a97667a617fa5d427c2e95ce6f3eab5cf2d21d00c69ad2a7524ff6d9a9144f58",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "org.glassfish.hk2.external:aopalliance-repackaged:2.4.0-b09",
              "pkg_type": "Maven"
            }
          ]
        }
      ]
    }
  ]
}

 

CI Integration

This action lets you specify that if a CI server requests a build to be scanned, and the Watch triggers a violation, Xray will respond with an indication that the build job should fail.

This action is only available if the Watch is defined with an All Builds target type.

CI Integration Action

No Fail Build Job Actions defined?

 If a request to scan a build is received by Xray, but there are no Watches with a CI Integration action defined, Xray will always respond with an indication that the build job should indeed fail, whether build artifacts or dependencies are found to have vulnerabilities or not.

Block Download

This action lets you specify that artifacts should be blocked for download from Artifactory

Block Download Action

Block Download
When set, Artifactory will block download of artifacts that meet the Artifact Filter and Severity Filter specifications for this watch.
Block Unscanned
When set, Artifactory will block download of artifacts that meet the Artifact Filter specifications for this watch, but have not been scanned yet.

Examining Violations

Click on a specific watch from the main Watch module page to examine all of its defined violations.


Manually Invoking a Scan

Temporarily Disabled

This feature has been temporarily disabled and is not available from version 1.9. The feature will be enabled again in one of the forthcoming releases.

You may still initiate a scan on a specific component from the Actions Menu in its Details Panel.

 This is how it will look when enabled...

Once a Watch is created, it will scan artifacts in the specified Target Type when a scan-triggering event happens, and issue alerts accordingly. However, until a scan-triggering event happens, artifacts already existing in the system will not be scanned by the watch. So, to make sure a watch is immediately applied to the relevant artifacts, you can invoke it manually by hovering over the relevant watch.

Clicking the button pops up a dialog that lets you specify a date range which defines which artifacts in the specified target type should be scanned according to the amount of time they have resided in the target.

For example, selecting "Last 7 days" will only scan artifacts that have resided in the target for the last 7 days.

Manual Scan Details

 


Download Blocking

Previously, blocking download of artifacts was defined in Artifactory and managed as special "system watches" in Xray. From JFrog Artifactory version 5.10 and Xray version 1.12, the integration between these two applications has changed, and download blocking is now fully managed in Xray through watches that use a Block Download action.

 

  • No labels