JFrog Xray

JFrog Xray is a binary-level SCA tool that scans the actual artifacts stored in JFrog Artifactory. The Sonatype 2024 State of Software Supply Chain report found that one in eight open-source downloads contains a known vulnerability, making artifact-level scanning before deployment a critical control. Instead of analyzing source code or manifest files, Xray examines compiled binaries, Docker images, and packaged artifacts to find vulnerabilities, license violations, and malicious components.

The tool recursively scans every layer and dependency within an artifact. For a Docker image, that means the base image, every build layer, and all installed packages. For a Java application, it traces through nested JARs and their transitive dependencies. This catches vulnerabilities that source-level scanners miss because it analyzes what actually gets deployed.

What is JFrog Xray?

Xray scans artifacts in Artifactory against vulnerability databases including the NVD, GitHub Advisories, and JFrog’s own security research. It maintains a database of over 4 million known malicious packages and supports virtually every package type: Docker, npm, Maven, PyPI, NuGet, Go, Cargo, and more.

Key features

Supported artifact types

Deep recursive scanning

Xray analyzes the complete dependency graph of every artifact. For Docker images, it examines the base image, every layer added during build, and all packages installed at each stage. For Java applications, it traces through nested JARs and their transitive dependencies.

A common scenario: a direct dependency that itself depends on a vulnerable library. Without recursive scanning, this stays hidden until someone exploits it.

Impact analysis

When a new vulnerability is disclosed, Xray’s impact analysis shows every affected artifact along with all builds, releases, and deployments that depend on those artifacts. This turns incident response from digging through build logs into an instant query across your entire repository.

Policy-based security gates

Xray policies enforce security standards automatically. Rules can be based on CVE severity thresholds, specific CVE IDs (e.g., always block Log4Shell), license types (e.g., no GPL in commercial products), CVSS scores, or component age. When an artifact violates a policy, Xray can block downloads, fail builds, trigger alerts, or fire webhooks.

License compliance

Xray identifies licenses on all components in your software, helping legal and compliance teams understand obligations from open-source dependencies. Policies prevent accidental inclusion of components with incompatible licenses.

Installation

JFrog Xray runs as part of the JFrog Platform and requires JFrog Artifactory.

Deployment options include:

Cloud (JFrog SaaS)

The fastest path to getting started.

JFrog manages infrastructure, updates, and scaling.

# No installation required - configure via UI or API
# Access at https://your-instance.jfrog.io

Self-Hosted (Docker)

# Pull the Xray Docker images
docker pull releases-docker.jfrog.io/jfrog/xray-server:latest
docker pull releases-docker.jfrog.io/jfrog/xray-indexer:latest
docker pull releases-docker.jfrog.io/jfrog/xray-analysis:latest
docker pull releases-docker.jfrog.io/jfrog/xray-persist:latest

# Run using Docker Compose (recommended)
# Download docker-compose.yaml from JFrog documentation
docker-compose -f docker-compose.yaml up -d

Helm (Kubernetes)

# Add JFrog Helm repository
helm repo add jfrog https://charts.jfrog.io
helm repo update

# Install Xray (requires existing Artifactory)
helm upgrade --install xray jfrog/xray \
  --namespace jfrog \
  --set xray.joinKey=<your-join-key> \
  --set xray.jfrogUrl=https://artifactory.example.com

Integration

GitHub Actions

name: Build and Scan
on: [push, pull_request]

jobs:
  build-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup JFrog CLI
        uses: jfrog/setup-jfrog-cli@v4
        with:
          version: latest
        env:
          JF_URL: ${{ secrets.JF_URL }}
          JF_ACCESS_TOKEN: ${{ secrets.JF_ACCESS_TOKEN }}

      - name: Build and publish
        run: |
          jf rt build-add-dependencies my-build 1 "target/*.jar"
          jf rt upload "target/*.jar" libs-release-local/
          jf rt build-publish my-build 1

      - name: Scan for vulnerabilities
        run: |
          jf audit --watches "prod-security-policy"

      - name: Scan Docker image
        run: |
          jf docker scan myapp:${{ github.sha }}

GitLab CI

stages:
  - build
  - scan
  - deploy

variables:
  JFROG_CLI_BUILD_NAME: "my-app"
  JFROG_CLI_BUILD_NUMBER: "$CI_PIPELINE_ID"

scan:
  stage: scan
  image: releases-docker.jfrog.io/jfrog/jfrog-cli-v2:latest
  script:
    - jf config add --url=$JF_URL --access-token=$JF_ACCESS_TOKEN
    - jf rt download "libs-snapshot-local/*.jar" ./target/
    - jf audit --fail=true --min-severity=High
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Jenkins Pipeline

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                rtServer (
                    id: "ARTIFACTORY_SERVER",
                    url: "${ARTIFACTORY_URL}",
                    credentialsId: "artifactory-credentials"
                )
                rtMavenDeployer (
                    id: "MAVEN_DEPLOYER",
                    serverId: "ARTIFACTORY_SERVER",
                    releaseRepo: "libs-release-local",
                    snapshotRepo: "libs-snapshot-local"
                )
                rtMavenRun (
                    pom: 'pom.xml',
                    goals: 'clean install',
                    deployerId: "MAVEN_DEPLOYER"
                )
            }
        }

        stage('Xray Scan') {
            steps {
                xrayScan (
                    serverId: "ARTIFACTORY_SERVER",
                    buildName: "${JOB_NAME}",
                    buildNumber: "${BUILD_NUMBER}",
                    failBuild: true
                )
            }
        }
    }
}

Setup

When to use JFrog Xray

Xray is the right choice when you already use Artifactory and want security scanning tightly integrated with your artifact management. It scans what actually gets deployed, not just what’s in source code.

Strengths:

• Binary-level analysis of actual deployment artifacts
• 4M+ malicious package detection database
• Impact analysis across your entire artifact repository
• Policy gates that block vulnerable downloads
• Supports virtually every package type

Limitations:

• Requires JFrog Artifactory (not standalone)
• Commercial only, no free tier
• Heavier setup compared to CLI-based scanners

How it compares:

Learn more in our guides on What is SCA? and software supply chain security.

Frequently Asked Questions