Using the latest JFrog products?
JFrog Platform User Guide
JFrog Xray 2.x Documentation
To get the latest version, go to the JFrog Unified Platform
Upgrading to version 2.4 and multiple resources
From version 2.4, a Watch can be defined on multiple resources (builds and repositories). When upgrading from a version below 2.4 to version 2.4 and above, all existing Watches with a specified target will be migrated to a new watch that includes the original Watch target as its only resource. Note that these can be then edited to add more resources.
All existing Watches specified on "Every Artifact" will be migrated to corresponding new Watches that specify All Repositories and All Builds as their resources.
How Do Watches Work?
When scanning an artifact, Xray completes the following steps for each resource added to a Watch:
- Check existence: Xray checks if the artifact exists in the resource
- Check filters: Xray then checks if the artifact matches all of the filters defined for that resource.
- Process Assigned Polices: Xray independently processes all of the policies in the Watch. For each assigned policy, Xray performs the following steps:
- Processes the rules according to priority.
- Checks the criteria of the rule.
- If the criteria are met, Xray generates a violation, the automatic actions are executed and the policy is considered as processed. There is no need to continue to the subsequent rules in the policy.
- If the criteria are not met, Xray continues to the next rule.
- In case none of the rules apply, the policy is considered as processed, and Xray continues to the next policy if one exists.
Creating a Watch
To create a new watch, click New Watch.
A Watch is created in three basic steps:
|A unique logical name for this watch.|
A general description of the Watch.
When checked, the watch is enabled.
|When selected, all the Watch recipients will receive email notifications in case a vulnerability is detected.|
The Resources are the set of repositories and builds in the connected Artifactory services that the Watch monitors. To specify resources for the Watch, click Manage Resources.
Managing resources for a Watch involves two steps:
- Specifying the repositories and builds to monitor
- Applying filters to focus only on those artifacts within those repositories and builds that you are interested in.
Move the resources you are interested in from the list of Available Resources on the left to the list of Selected Resources on the right by dragging them, or by selecting them and using the arrow icons.
You can only see resources in a Watch if they are indexed for scanning by Xray and you have "View" permission on the resource.
You can only add resources to a Watch or remove them if they are indexed for scanning by Xray and you have "Manage" permission on the resource.
Specifying All Repositories and Builds
Setting the All Repositories or All Builds checkboxes means that the Watch monitors all builds as well as all repositories that have been specified for indexing by Xray. Note that this setting will also apply to new repositories and builds that are created after the Watch is defined.
You may only specify All Repositories or All Builds if there is a permission defined providing you with global scope access (i.e., an All Resources permission) to all resources.
Scanning External Resources
From version 2.6, when scanning builds for supported package formats, external (transitive) dependencies that are not directly included in the build are also scanned and will trigger violations if the meet the criteria specified in a Watch. Currently, the supported package formats are: Maven, NuGet, npm and Gradle and scans external resources using SHA-256.
The filters you define for a watch determine which artifacts in the resources specified will generate violations and under what conditions. You can define any number of filters on each of the resources specified for the watch, and it will only trigger a violation on any of the resources if an artifact meets the conditions of all of the filters defined for that resource. The following content filters are available:
- Name: Generate a violation based on an artifact's name
- Path: Generate a violation based on an artifact's path in the repository
- Package Type: Generate a violation based on an artifact's package type
- Mime Type: Generate a violation based on an artifact's MIME type
- Property: Generate a violation if an artifact is annotated with the specified property
To specify filters, select the Filters tab.
For each resource you have added to the Watch, you can now specify the filters that apply to that resource.
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 resource, and only artifacts that pass through all of them will trigger a violation.
A Name 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.
For example, the filter above specifies that the watch should only trigger a violation for rpm files.
A Path filter uses a regular expression to specify the path of an artifact in the repository. The watch will only trigger a violation if an artifact's name matches the expression. Note that the filter does not consider the repository name to be a part of the path.
For example, the filter above specifies that the watch should only trigger a violation for artifacts that have the expressions "jfrog" in their path
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.
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.
For example, the filter above specifies that the watch should trigger a violation for any artifact with an "application/json" mime type.
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.
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".
To assign a policy to a watch, click on Assign Policies.
From the list of Available Policies on the left, select the policies you want to apply to the Watch and drag them, or use the arrows to move them to the list of Selected Policies on the right.
Click Assign to assign the policies to the Watch.
Editing a Policy
Edits made to a policy will automatically be applied to all watches the policy is assigned to. This will take affect only for newly scanned artifacts. You can manually apply the watch on existing artifacts.
Editing a Watch
To edit a Watch select it from the list of Watches and go to the Settings tab.
Examining a Watch
Click on a specific watch from the main Watch module page to examine all of its defined violations. You can filter the watch violations using the search mechanism, according to text, created date, type, severity and CVE ID.
To examine the details of a violation, click the violation from the list to display the Violation Details popup.
Ignoring Violations on a Watch
Introduced Enhanced Ignore Rule Functionality in Xray 2.11
From Xray 2.11, the Ignore Violations functionality has been enhanced to allow users to view and perform actions of violations tagged with Ignore Rules.
Users can choose to ignore violations detected on a watch in cases whereby a violation is low priority, or needs to be whitelisted or dealt with in future versions.
The following procedures are supported when Ignoring violations:
- Ignore a violation
- Search for violations tagged with ignore rules
- Restore an ignored violation on a watch
- Delete an ignore rule
- Get a list of violations with Ignored Rules via the REST API
Ignoring a Violation
- Select the required Watch and click the Violations tab.
- From the Violations list on the Watch, hover over the required violation in the list and click located on the rightmost side of the line.
The Ignore Violation dialog opens. Ignore Violation
- Choose one of the following methods to ignore the violation:
- Ignore Once: The violation will be tagged as an 'Ignored Violation', however it will reappear in the list the next time the violating artifact is scanned.
Ignore Permanently: The violation will be tagged as an "Ignored Violation' and an Ignore Rule will be created and will apply to future scans.
Ignore Rules from Component Details
You can also specify violations to ignore in the Violations tab of the Component Details page.
Under the Watch, you can view ignored rules in the Ignore Rules tab.
To view security or licence details of an ignored rule, select the Ignore rule in the Summary column.
Searching for Ignored Violations on a Watch
To view a list of ignored violations, from the Violations tab on the Watch select the Ignored Violations status from the Status filter and click Search.
Restoring an Ignored Violation on a Watch
- On the Violations page, select the violation and click Restore Violation.
- Click Restore Violation.
- Click Confirm. The violation will be added to the Active Violations list.
Deleting an Ignore Rule
You can delete an Ignore rule and select the Restore previous violations checkbox to restore previous violations tagged with this Ignore Rule.
- From the Ignore Rules tab, select the Ignore Rule and select the Delete icon.
- Click Delete.
Get a list of ignore violations on a Watch
To retrieve a list of ignored violations on a watch, run the following Get Ignored Violations command.
Apply On Existing Content
Once a Watch is created, it will scan artifacts in the specified resources when a scan-triggering event happens, and issue Violations 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 it and selecting Apply on Existing Content.
Not available for All Repositories or All Builds
You can only manually invoke a Watch on existing content if the Watch is defined on specific resources and not on All Repositories or All Builds
Clicking the button pops up a dialog that lets you specify which of the resources assigned to the watch should be scanned, and a date range which defines the amount of time an artifacts needs to have resided in the target in order to be scanned.
For example, selecting "Last 7 days" will only scan artifacts that have resided in the target for the last 7 days.