Try JFrog
Guides
Contact SupportTry JFrog
  1. xray
  2. How-Tos

Find Why an Artifact Download Is Blocked

Use jf xr status to see which JFrog Xray policy blocked an artifact download, including the CVE or other violation.

A download from JFrog Artifactory can fail because a JFrog Xray policy is set to block downloads. The client, such as Maven, npm, pip, or Docker, reports a blocked or forbidden download and doesn't name the policy. The block usually comes from a JFrog Xray watch on that repository. A security policy can match a CVE, a severity threshold, or a malicious package. License and operational-risk policies can block the download the same way.

The JFrog CLI command jf xr status prints the Artifact Download Status and the policy violations that produced it. The artifact must already exist in JFrog Artifactory, and you need the same read permission on the repository that a download requires. For command options, Docker image references, and JSON output, see Check Artifact Download Status.

Find the Blocking Policy

To find why an artifact download is blocked:

  1. Copy the repository path of the artifact the client tried to download. Use the path from the failed request, for example libs-release-local/com/acme/foo-1.2.jar. The path is the artifact JFrog Xray checks.

  2. Check the download status. This command reads the current Artifact Download Status for that artifact:

    jf xr status <REPOSITORY>/<PATH>

    Where:

    • <REPOSITORY>: The JFrog Artifactory repository key.
    • <PATH>: The artifact path inside the repository.

    For example:

    jf xr status libs-release-local/com/acme/foo-1.2.jar

    The command prints the artifact path, the Artifact Download Status, the reason, and a link to the artifact in the JFrog Xray Scans List. For a Docker image, use the same reference you use with docker pull. For more information, see Check Artifact Download Status.

  3. Read the Artifact Download Status and the reason.

    When a policy blocks the download, the Artifact Download Status looks like this.

    Expected output:

    Download Status:  BLOCKED
Reason:           one or more matched policies are configured to block downloads

    BLOCKED means at least one matched policy that hasn't been ignored is configured to block downloads. ALLOWED means violation scanning is complete and no matched policy blocks the download. UNKNOWN means scanning hasn't finished, failed, or is partial, or the checksum indexed by JFrog Xray doesn't match the artifact. A watch that blocks unscanned artifacts can still block the download while the Artifact Download Status is UNKNOWN.

  4. Read the violations table that follows the Artifact Download Status. JFrog Xray lists blocking violations first, then sorts by severity.

    ColumnWhat it shows
    BlockingWhether this violation blocks the download.
    SeverityHow severe the finding is.
    DetailThe CVE or other finding that matched.
    PolicyThe policy that matched.
    RuleThe rule inside that policy, such as a CVE severity rule.
    WatchThe watch that applied the policy to this repository.

    A row marked as blocking is what stopped the download. Detail names the CVE or other finding. Policy and Rule name the block-download rule. Watch names who applied that policy to the repository.

  5. Open the result. The Results line is the artifact in the JFrog Xray Scans List. When the terminal supports clickable links, the last column of the table opens that violation in JFrog Xray.

📘

Note

Terminals that support clickable links include iTerm2, Visual Studio Code, Windows Terminal, kitty, WezTerm, Hyper, Ghostty, Tabby, and Warp. Terminal.app on macOS omits the link column. The Results URL is still printed.

The Artifact Download Status and the blocking row show which policy stopped the download and which finding it matched. Upgrading or replacing the component, or asking the watch owner to review an ignore rule, depends on that finding. For more information, see Violations Handling and Notifications.

Frequently Asked Questions

This section provides answers to frequently asked questions.

plusFAQs
Q: What do I need before I run jf xr status?

A: The artifact must already exist in JFrog Artifactory, and you need the same read permission on the repository that a download requires. For the check itself, see Find the Blocking Policy.

Q: How do I find which policy blocked an artifact download?

A: Run jf xr status with the repository path from the failed request. An Artifact Download Status of BLOCKED means a matched policy that hasn't been ignored is set to block downloads, and the violations table names the CVE or other finding, the policy, the rule, and the watch. For the steps, see Find the Blocking Policy.

Q: What is the difference between the Artifact Download Status values BLOCKED, ALLOWED, and UNKNOWN?

A: BLOCKED means a matched policy blocks the download, ALLOWED means violation scanning is complete and no matched policy blocks the download, and UNKNOWN means scanning hasn't finished, failed, or is partial, or the indexed checksum doesn't match the artifact. For where each Artifact Download Status is printed, see Find the Blocking Policy.

Q: What happens if I check the wrong artifact path?

A: JFrog Xray reports the Artifact Download Status for the path you pass, so a wrong path checks a different artifact. Use the repository path from the failed request, such as libs-release-local/com/acme/foo-1.2.jar. For how to copy that path, see Find the Blocking Policy.

Q: Can I check a Docker image with jf xr status?

A: Use the same image reference you use with docker pull. The command still prints the Artifact Download Status, the reason, and the violations that matched. For the Docker example, see Find the Blocking Policy.

Related Topics

Updated 9 days ago

Did this page help you?