Search Resources by Vulnerability and Package

Description: Search all resources (Artifacts, Builds, Release Bundles, etc.) that include a specific package or are impacted by a specific vulnerability (CVE or XRAY ID). Supports three search modes: by vulnerability, by package version, or by package name & type.

Since: Xray 3.131

Notes:

SBOM Requirement: This capability depends on the SBOM Service. Self-Hosted users must enable the SBOM feature and complete the SBOM migration. If SBOM is disabled, the API returns 403 – "SBOM is disabled".
Pagination: Use last_key from the response to fetch subsequent pages; an empty last_key indicates no further results.
Limit: Defaults to 1000; maximum 10000; 0 means 1000.

ID Formats: CVE format CVE-YYYY-NNNN; XRAY format XRAY-N.

Applicable Environment: JFrog SaaS, JFrog Self-Hosted

Security: Requires a valid user with Reports Manager permission.

Usage: GET /xray/api/v2/search/impactedResources

Consumes: N/A (GET with query parameters)

Produces: application/json

Query parameters:

Name	Type	Required/Optional	Description
`limit`	integer	optional	Maximum number of resources to return. Default: 1000; Maximum: 10000; If set to 0, defaults to 1000.
`last_key`	string	optional	Pagination cursor from the previous response. Include this value to retrieve the next page.
`vulnerability`	string	optional*	Vulnerability ID in CVE format (`CVE-YYYY-NNNN`) or XRAY format (`XRAY-N`). Required when searching by vulnerability.
`name`	string	optional*	Package name. Required when searching by package (with or without version).
`type`	string	optional*	Package type (e.g., `npm`, `maven`, `pypi`, etc.). Required when searching by package (with or without version).
`version`	string	optional	Package version. When provided with `name` and `type`, searches for a specific package version; when omitted, searches across all versions.
`namespace`	string	optional	Package namespace. Default: `public`.
`ecosystem`	string	optional	Package ecosystem. Default: `generic`.

*Search Mode Requirements:

Mode 1 — By Vulnerability: vulnerability is required.
Mode 2 — By Package Version: name and type are required; version is optional (recommended for exact version search).
Mode 3 — By Package (all versions): name and type are required; omit version.

Response body:

Name	Type	Description
`result`	`Resource[]`	Array of resources that match the search criteria.
`last_key`	string	Pagination cursor. If empty, no further results are available.

Resource

Name	Type	Description
`type`	string	Resource type. Valid values: `Artifact`, `Build`, `ReleaseBundle`, `ReleaseBundleV2`, `AppVersion`, `Component`.
`name`	string	Name of the resource.
`path`	string	Artifact path in the repository. Present for artifact-type resources.
`repo`	string	Repository name.
`version`	string	Version of the resource (for aggregated resources such as builds or release bundles).
`artifact_name`	string	Name of the artifact within an aggregation. Present on aggregated resources.
`artifact_pkg_version`	`PackageVersionKey`	Package version info for the artifact containing the impacted package.
`scan_date`	string	ISO 8601 timestamp indicating when the resource was last scanned.
`impacted_pkg_version`	`PackageVersionKey`	Package version info for the impacted package matching the search.

PackageVersionKey

Name	Type	Description
`type`	string	Package type (e.g., `npm`, `maven`, `pypi`, `docker`, etc.).
`name`	string	Package name.
`namespace`	string	Package namespace. Default: `public`.
`version`	string	Package version.
`ecosystem`	string	Package ecosystem. Default: `generic`.

Response Codes:

Status Code	Description
200	OK — Search completed successfully.
400	Bad request — Invalid request parameters (e.g., missing required parameters, invalid vulnerability ID format, invalid limit).
403	Permission denied — Missing Reports Manager permission, or SBOM feature disabled.
500	Internal server error — Error while processing the request.

Sample Requests & Responses:

Search by Vulnerability (CVE)

GET /xray/api/v2/search/impactedResources?vulnerability=CVE-2021-44228&limit=100
Accept: application/json

curl -u <user>:<password> ^
  -G "https://<xray-host>/xray/api/v2/search/impactedResources" ^
  --data-urlencode "vulnerability=CVE-2021-44228" ^
  --data-urlencode "limit=100" ^
  -H "Accept: application/json"

Sample Response (200 OK)

{
  "result": [
    {
      "type": "Artifact",
      "name": "app.jar",
      "path": "libs-release-local/com/example/app/1.0.0/app-1.0.0.jar",
      "repo": "libs-release-local",
      "scan_date": "2024-01-15T10:30:00Z",
      "artifact_pkg_version": {
        "type": "maven",
        "name": "app",
        "namespace": "com.example",
        "version": "1.0.0",
        "ecosystem": "generic"
      },
      "impacted_pkg_version": {
        "type": "maven",
        "name": "log4j-core",
        "namespace": "org.apache.logging.log4j",
        "version": "2.14.1",
        "ecosystem": "generic"
      }
    }
  ],
  "last_key": "eyJwcmltYXJ5IjoiMTIzNDU2Nzg5MCIsInNlY29uZGFyeSI6ImFiY2RlZjEyMzQ1Njc4OTAifQ=="
}

Search by Vulnerability (XRAY ID)

curl -u <user>:<password> ^
  -G "https://<xray-host>/xray/api/v2/search/impactedResources" ^
  --data-urlencode "vulnerability=XRAY-123456" ^
  --data-urlencode "limit=50" ^
  -H "Accept: application/json"

Search by Package Version

GET /xray/api/v2/search/impactedResources?type=npm&name=express&version=4.17.1&limit=100
Accept: application/json

curl -u <user>:<password> ^
  -G "https://<xray-host>/xray/api/v2/search/impactedResources" ^
  --data-urlencode "type=npm" ^
  --data-urlencode "name=express" ^
  --data-urlencode "version=4.17.1" ^
  --data-urlencode "limit=100" ^
  -H "Accept: application/json"

Sample Response (200 OK)

{
  "result": [
    {
      "type": "Artifact",
      "name": "my-app.tar.gz",
      "path": "npm-release-local/my-app/my-app-1.0.0.tgz",
      "repo": "npm-release-local",
      "scan_date": "2024-01-20T14:15:00Z",
      "artifact_pkg_version": {
        "type": "npm",
        "name": "my-app",
        "namespace": "public",
        "version": "1.0.0",
        "ecosystem": "generic"
      },
      "impacted_pkg_version": {
        "type": "npm",
        "name": "express",
        "namespace": "public",
        "version": "4.17.1",
        "ecosystem": "generic"
      }
    }
  ],
  "last_key": ""
}

Search by Package (All Versions)

GET /xray/api/v2/search/impactedResources?type=npm&name=express&limit=100
Accept: application/json

curl -u <user>:<password> ^
  -G "https://<xray-host>/xray/api/v2/search/impactedResources" ^
  --data-urlencode "type=npm" ^
  --data-urlencode "name=express" ^
  --data-urlencode "limit=100" ^
  -H "Accept: application/json"

Pagination Example

# First request
curl -u <user>:<password> -G "https://<xray-host>/xray/api/v2/search/impactedResources" \
  --data-urlencode "vulnerability=CVE-2021-44228" \
  --data-urlencode "limit=100" \
  -H "Accept: application/json"

# Response (includes "last_key")
{
  "result": [...],
  "last_key": "eyJwcmltYXJ5IjoiMTIzNDU2Nzg5MCIsInNlY29uZGFyeSI6ImFiY2RlZjEyMzQ1Njc4OTAifQ=="
}

# Next request (continue with last_key)
curl -u <user>:<password> -G "https://<xray-host>/xray/api/v2/search/impactedResources" \
  --data-urlencode "vulnerability=CVE-2021-44228" \
  --data-urlencode "limit=100" \
  --data-urlencode "last_key=eyJwcmltYXJ5IjoiMTIzNDU2Nzg5MCIsInNlY29uZGFyeSI6ImFiY2RlZjEyMzQ1Njc4OTAifQ==" \
  -H "Accept: application/json"

Error Response Examples

400 Bad Request - Missing Required Parameters
{
  "error": "Mandatory parameters: \"vulnerability\" OR (\"type\", \"name\", \"version\")"
}

400 Bad Request - Invalid Vulnerability ID
{
  "error": "invalid vulnerability id: INVALID-ID"
}

400 Bad Request - Invalid Limit
{
  "error": "invalid should be between 0 and 10000"
}

403 Forbidden - SBOM Disabled
{
  "error": "SBOM is disabled"
}

403 Forbidden - Permission Denied
{
  "error": "Permission denied"
}