How Do Watches Work?
Xray completes the following steps when scanning an artifact:
- Checks Target Resources: Checks if the artifact exists in a watch target resource.
- Checks Filters: Checks if the artifact matches all of the filters in the found watches.
- Processes Assigned Polices: Xray independently processes all of the policies in the found watches. For each assigned policy in a watch, Xray performs the following steps:
- Processes the rules according to priority.
- Checks the criteria of the rule.
- If the criteria is 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 next rules in the policy.
- If the criteria is not met, Xray continues to the next rule.
- In case none of the rules are met, the policy is considered as processed, and Xray continues to the next policy if exists.
Creating and Editing a Watch
To create a new watch, click New Watch and fill in the fields that define the watch.
|A logical name for this watch.|
A general description of the Watch.
When checked, the watch is enabled
Repository: The watch monitors the repository specified in the Repository Name field.
Build: The watch monitors the build specified in the Build Name field.
All Builds: The watch monitors all builds in all Artifactory instances connected to this instance of Xray.
Every Artifact: The watch monitors all artifacts in all repositories indexed by Xray.
|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.|
|The build or repository to watch based on the Target Type|
|Specifies which Artifact Filters to apply. Only artifacts matching all filters will trigger a violation.|
|The policies assigned to this watch.|
You can edit an existing Watch by clicking its name in the Watches table and editing its parameters in the form displayed.
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
To add a filter to your watch, select the filter type and click "Add".
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.
A 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.
For example, the filter above specifies that the watch should only trigger a violation for rpm files.
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.
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.
Examining a Watch
Click on a specific watch from the main Watch module page to examine all of its defined violations. 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.
The Ignore Rules tab displays violations which you have chosen to ignore in the Component Details display.
Apply On Existing Content
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.