SafeDep Documentation

The SafeDep JFrog Xray integration is available with the Threat Intel Feed add-on. To enable the add-on, see the pricing page.

The JFrog Xray integration runs as a daemon. It polls SafeDep for verified malicious packages and pushes them to JFrog Xray as Custom Issues. With a blocking policy in place, Xray blocks those packages for every developer on that instance.

To preview the feed without JFrog credentials, run it with --dry-run first.

Prerequisites

SafeDep CLI installed (install)
JFrog instance with Xray enabled
JFrog Xray scoped Access Token
Optional, for blocking malicious packages on developer machines or CIs
- JFrog Xray Malware security policy and repository watch with a block action configured

How It Works

Authenticate with SafeDep

# Option 1: API key login (--api-key is a flag; pass the value with --api-key-value)
safedep auth login --tenant your-tenant.safedep.io --api-key --api-key-value YOUR_API_KEY

# Option 2: Environment variables (read directly by safedep; no login command needed)
export SAFEDEP_TENANT_ID=your-tenant.safedep.io
export SAFEDEP_API_KEY=YOUR_API_KEY

Start the integration daemon

safedep integration jfrog run \
  --instance-url https://yourcompany.jfrog.io \
  --instance-access-token YOUR_JFROG_TOKEN

# or pass token via environment variable (see Environment Variables below)

The daemon polls SafeDep continuously (default: every 5 minutes) and pushes any newly verified malicious packages to Xray.On the first run the daemon starts from the current time and does not pull older reports. To seed history, pass --backfill with a duration: --backfill 168h covers the last 7 days. Later runs resume from the saved cursor, so --backfill is ignored after the first run.

Output

i Validating JFrog connectivity
✓ JFrog connectivity OK (URL + token verified)
i Starting JFrog Syncing with SafeDep Threat Intel Feed
i No saved cursor: starting fresh from now
✓ Pushed: @hideliar/9router (npm) versions: 0.4.25
i   JFrog: SD-01KR3WJYFTSNZFFS5CFNYVGZFH [201]
✓ Pushed: @sheason/d-pi (npm) versions: 0.4.3
i   JFrog: SD-01KR3XSCZ0WNAEYY6CNMD4CQH3 [201]
i Feed cycle complete at 2026-08-25T10:15:04Z, next in 5m0s
...
..
.

Verify Blocking via JFrog

Assumes a Malicious Package blocking policy and watch configured for the target repository (e.g. npm-remote).

jf npm install <Malicious Ingested Package>

jf npm install triggers Xray to index <Malicious Ingested Package>. Xray raises a policy violation and blocks the download.

Install Output

  npm ERR! 403 on a server you do not have access to.
  {
    "error": {
      "code": "E403",
      "summary": "403 Forbidden - GET https://yourcompany.jfrog.io/artifactory/api/npm/npm-virtual/<Malicious Ingested Package>",
      "detail": "In most cases, you or one of your dependencies are requesting\na package version that is forbidden by your security policy, or\non a server you do not have access to."
    }
  }

Limitations

Malicious Packages Blocking

npm and other package managers cache packages locally on developer machines. If a developer installs a package before SafeDep flags it, the cached copy remains accessible even after the integration pushes it to Xray. Running npm cache clean --force removes the cached copy, but it clears the entire local cache and forces a full re-download of all packages.

npm cache clean --force

Configuration

CLI Flags

Flag	Required	Default	Description
`--instance-url`	Yes*	None	JFrog instance base URL. Must use `https://`.
`--instance-access-token`	Yes*	None	JFrog access token scoped to Xray.
`--poll-interval`	No	`5m`	Duration between poll cycles (`30s`, `5m`, `1h`).
`--backfill`	No	`0`	First-run window to seed history (e.g. `24h`, `168h`). `0` starts from now.
`--dry-run`	No	`false`	Preview the feed and print what would be pushed, without sending to JFrog. See Dry run.
`--profile`	No	`"default"`	SafeDep credential profile (inherited from root).

*Required unless the corresponding environment variable is set.

Environment Variables

For server deployments or CI pipelines, use environment variables to avoid passing secrets as CLI flags. When both are set, flags take precedence.

Variable	Corresponding Flag
`SAFEDEP_INTEGRATION_JFROG_ARTIFACTORY_URL`	`--instance-url`
`SAFEDEP_INTEGRATION_JFROG_ARTIFACTORY_ACCESS_TOKEN`	`--instance-access-token`

Example: environment variable setup

export SAFEDEP_INTEGRATION_JFROG_ARTIFACTORY_URL=https://yourcompany.jfrog.io
export SAFEDEP_INTEGRATION_JFROG_ARTIFACTORY_ACCESS_TOKEN=***
safedep integration jfrog run

Dry run

Use --dry-run to test the feed without a JFrog connection.

--dry-run previews the feed and prints each finding as a Would push: line, without sending to JFrog. It needs no JFrog credentials, so you can check the feed before you connect an instance.

# Preview the last 24 hours, then clear the cursor before a real run
safedep integration jfrog run --dry-run --backfill 24h
safedep integration jfrog cursor remove

A dry-run does everything a real run does, except the final step: it prints each finding instead of sending it to JFrog.

Dry-run advances the same saved cursor. Run cursor remove before the first real run, or that run skips what the preview consumed.

Manage the feed cursor

The run command saves a cursor so it resumes where it stopped. The cursor is per SafeDep profile, so a change affects only the profile you select with --profile.

Move the cursor

Set the cursor to an RFC3339 timestamp. The next run processes reports updated after this time.

safedep integration jfrog cursor set 2026-08-01T00:00:00Z

Clear the cursor

Remove the saved cursor. The next run starts fresh from the current time, or from the --backfill window.

safedep integration jfrog cursor remove

Getting Started

Consuming the Feed

Integrations

Reference

JFrog Xray Integration

Prerequisites

How It Works

Limitations

Malicious Packages Blocking

Configuration

CLI Flags

Environment Variables

Dry run

Manage the feed cursor

Move the cursor

Clear the cursor

​Prerequisites

​How It Works

​ Limitations

​Malicious Packages Blocking

​Configuration

​CLI Flags

​Environment Variables

​Dry run

​Manage the feed cursor

​Move the cursor

​Clear the cursor

Prerequisites

How It Works

Limitations

Malicious Packages Blocking

Configuration

CLI Flags

Environment Variables

Dry run

Manage the feed cursor

Move the cursor

Clear the cursor