JFrog Xray — Policies, Watches, Impact Analysis, Errors and Mistakes

How Xray turns vulnerabilities into violations through watches and policies, and finds every stored artifact that contains a CVE. Covers blocked downloads, indexing gaps, ignore rules, mistakes, and proving after the fact what reached production.

Overview

JFrog Xray is the software composition analysis service of the JFrog Platform. It scans what you store in Artifactory (repositories, builds, Release Bundles) and builds a dependency graph of every component inside. When a new CVE is published, Xray re-checks that graph instead of rescanning every binary, so it can tell you which stored artifacts contain the vulnerable component.

Most production trouble with Xray comes from three places.

Coverage gaps. A repository was never added to indexing, a watch does not include it, or the scan data aged out of the retention period. Xray then reports nothing, and nothing looks the same as safe.
Enforcement surprises. A policy with Block Download or Block Unscanned starts returning 403 to a build or a production deployment, often during an incident or right after a policy change.
Questions Xray alone cannot answer. Xray knows what an artifact contains. It does not know whether that artifact ran in production. Proving that needs promotion records, logs and the deployment system.

> [!IMPORTANT] > Xray scan data is not kept forever. Since Xray 3.41.4 the default retention is 90 days for indexed repositories and 15 days for indexed builds, and garbage collection removes the artifact data and its related violations. Plan any retroactive investigation around that.

Which subscription gives you what

JFrog Xray, Impact analysis — Pro X, Enterprise X, Enterprise+ (self-managed feature matrix; not in Non-commercial)
Xray high availability — Enterprise X (included) or Enterprise+ (built-in); not Pro X
JFrog Advanced Security: Contextual Analysis, SAST, secrets, misconfiguration (IaC) — Add-on available with Enterprise X or Enterprise+
Policy criteria Skip not applicable CVEs and Skip if not in Runtime — JFrog Advanced Security; Skip if not in Runtime also needs a connected Runtime controller and applies to Docker images only
Exposures reports — Advanced Security customers only
Curation (block packages at the remote repository) — Enterprise X or Enterprise+, plus JFrog Catalog; Artifactory 7.63.5 and Xray 3.78.2 minimum (3.82.11 behind a proxy)
JFrog Runtime — Not listed in the self-managed feature matrix; confirm with JFrog
Release Bundle v2: create and promote / scan with Xray / Xray policies controlling promotion or distribution / distribute — Pro or above / Pro X or above / Enterprise X or above / Enterprise+ (Release Lifecycle Management page)

Symptom to first command

Client gets 403 with download blocking policy configured in Xray — POST /xray/api/v1/violations filtered to the artifact — Blocked downloads
Downloads hang, then time out, after enabling Block Unscanned — Block Unscanned Artifacts Download Timeout (Sec) (default 60) and the artifact scan status — Blocked downloads
Every download fails while Xray is down — Allow download and distribute when Xray is unavailable — Blocked downloads
A repository has artifacts but no scan results — Administration, Xray, Indexed Resources, index status — Indexing gaps
Repository missing from the watch picker, or Watch is not valid — Is the repository indexed yet; RabbitMQ cluster health on HA — Indexing gaps
Scans stay PENDING, nothing new is indexed — System messages, disk usage limit (default 80%), RabbitMQ queues — Stuck scans
A new watch shows no violations on old artifacts — Run Apply on Existing Content — Policies and watches
Security asks which artifacts contain CVE-X — Impact Search or GET /xray/api/v2/search/impactedResources — Impact analysis
Security asks whether CVE-X ever reached prod — Impact search plus promotion and deployment records — Retroactive proof

What you will be able to do

Explain indexing, the component graph, Impact Analysis, and the difference between a vulnerability and a violation.
Design watches and policies whose rule order, actions and grace periods do what you intend.
Find every stored artifact, build and Release Bundle that contains a CVE, from the UI, the API or the CLI.
Diagnose blocked downloads, indexing gaps and stuck scans, and pick the narrowest safe unblock.
Spot and prevent the common mistakes: uncovered repositories, ignore rules without expiry, wide ignores, outage-time toggles.
Build a defensible, evidence-based answer to whether a vulnerable artifact was ever deployed to production, and say exactly what Xray can and cannot prove.

Key concepts

Indexed resource: A repository, build or Release Bundle selected under Indexed Resources. Xray scans and keeps graphs only for indexed resources.
Vulnerability: A finding that a component version has a known issue such as a CVE. It exists without any watch or policy.
Violation: A vulnerability, license or operational risk issue that matched a rule of a policy assigned to a watch covering the resource. Only violations trigger actions.
Watch: Binds resources (repositories, builds, Release Bundles, projects) to policies, with optional filters and recipients.
Policy rule: Criteria plus actions inside a security, license or operational risk policy. The first matching rule decides the actions.
Impact Analysis: Re-evaluates stored dependency graphs when the vulnerability database changes, about hourly, for resources still within retention.
Apply on Existing Content: Runs a watch over content that existed before the watch, for a date range. Not available for All Repositories or All Builds.
Ignore rule: Suppresses matching violations with required notes, optional expiry and scope filters. Applies to future scans only.
Block unscanned: Holds a download until the artifact is scanned, up to the Block Unscanned Artifacts Download Timeout (default 60 seconds).
Retention period: How long Xray keeps scan data: 90 days for indexed repositories and 15 days for indexed builds by default, up to 1000 days.

When to use it

Use this page when a new CVE is disclosed and you must list every artifact, build and Release Bundle that contains the affected component.
Use it when a build or production deployment starts receiving 403 responses from Artifactory that mention an Xray download blocking policy.
Use it when designing watches and policies, so that rule order, grace periods and coverage behave as intended.
Use it when a repository or build shows no scan results and you need to know whether that means clean or not covered.
Use it when an auditor or security team asks for retroactive evidence of what reached production.
Use it when reviewing ignore rules and global bypass settings for drift and risk.

Interview questions

Your security team wants to retroactively prove that no artifact affected by a newly disclosed CVE was ever deployed to prod over the last few months. How do you actually answer that, given Xray policies only started blocking new builds going forward.
Xray started blocking downloads of an artifact that production deployments depend on during an incident. What are your options, and what do you check before you unblock anything?
What is the difference between a vulnerability and a violation in Xray, and why does it matter operationally?
A CVE was published today. How does Xray flag artifacts uploaded months ago, and when would it miss them?
You created a new watch for your production repositories, but artifacts that clearly contain critical CVEs show no violations. Why, and how do you fix it?
Builds with critical vulnerabilities keep passing CI even though you have a policy with Fail Build. What do you check?
How do you handle false positives without creating blind spots?
After enabling Block Unscanned Artifacts, pip installs start timing out. What is happening and what are your options?
Xray stopped indexing new artifacts, but every service reports healthy. How do you troubleshoot?
An auditor asks for an SBOM and license evidence for a release. What can Xray produce and in which formats?
Which JFrog subscription do you need for Xray, Advanced Security and Curation, and what does each add?
Someone created an ignore rule months ago for a critical CVE with no expiry and no scope. How do you find and fix this class of problem?