Overview

Xray provides a convenient and up-to-date self-descriptive API that can be used by various tools/frameworks to automate the creation of REST calls. 

Usage

Xray REST API endpoints can be invoked in any of the standard ways to invoke a RESTful API. This section describes how to use the Xray REST API using cURL as an example.

You can download cURL here. Learn how to use and configure cURL here.

Base URL

From version 2.4, JFrog Xray is introducing a new REST API version. The different endpoints specified in this page will be upgraded gradually over progressive version upgrades, while maintaining backward compatibility to previous API versions. Where new endpoints are available, the API Version will be listed. In these cases, you should make sure to use corresponding Base URL as specified below. If the API version is not specified, it means the endpoint is part of the V1 REST API and you should use the V1 base URL.

The Platform REST URL is constructed of: 

<JFrog URL>/<Service Context>/api/<API-Version>

For example

# Using your JFrog URL 
http://myjfrog.acme.org/xray/api/v1

# Using your Artifactory server hostname and the Artifactory router port
http://ARTIFACTORY_SERVER_HOSTNAME:8082/xray/api/v1

Working with JFrog Platform Cloud

JFrog Platform Cloud offers the same extensive functionality and capabilities for automation as an on-prem installation, including authentication and the REST API endpoints.

As a Cloud service, the URL is different from an on-prem installation and the REST API endpoints can be reached at:

https://<Server Name>.jfrog.io/xray/

Authentication

Most REST API calls need to be authenticated using your user and password or using an access token. A few calls (such as SYSTEM calls) do not require authentication.

Example - Deleting a Watch

The example below demonstrates how to invoke the Delete Watch REST API with the following assumptions:

  • You are using cURL from the unix command line, and are presently working from the home (~) directory of the user 'myUser':

  • You wish to delete the watch called performance-watch.

  • You have configured a user in Xray named 'myUser', with password 'myP455w0rd!'.

To execute a call using basic authentication you would run:

curl -u myUser:myP455w0rd! -X DELETE http://SERVER_HOSTNAME:8082/xray/api/v2/watches/performance-watch

To execute a call using basic authentication using your username and API Key

curl -uadmin:APIkey <Xray url>/xray/api/v2/watches

Component Identifiers

Several endpoints require the use of a component identifier which must be formatted, according to its package type, using the convention described in the following table:

Package TypeIdentifierExample

Maven

gav://group:artifact:version

gav://ant:ant:1.6.5

Docker

docker://Namespace/name:tag

docker://jfrog/artifactory-oss:latest

RPM

rpm://os-version:package:epoch-version:versionrpm://7:rpm-python:7:4.11.3-43.el7

Debian

deb://vendor:dist:package:version

deb://ubuntu:trustee:acl:2.2.49-2

NuGet

nuget://module:version

nuget://log4net:9.0.1

Generic file

generic://sha256:<Checksum>/name

generic://sha256:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b/foo.jar

NPM

npm://package:version

npm://mocha:2.4.5

Python

pypi://package:version

pypi://raven:5.13.0

Composercomposer://package:versioncomposer://nunomaduro/collision:1.1
Golanggo://package:versiongo://github.com/ethereum/go-ethereum:1.8.2
Alpinealpine://branch:package:versionalpine://3.7:htop:2.0.2-r0

Deprecated APIs from Artifactory 7.x

To fully support the integration of JFrog Xray into the JFrog Platform, a set of Xray API commands have been deprecated. For a full list of deprecated commands, see Deprecated REST APIs.


REST Resources

GENERAL SETTINGS

Ignore Xray Alert

Description: Sets an alert to be ignored until next time the repository hosting the artifact about which the alert was issued, is scanned. Note that this endpoint does not affect artifacts that are blocked because they have not been scanned at all.
Since: 3.0
Security: Requires an admin user
Usage: POST /api/xray/setAlertIgnored?path={artifact path}


Allow Download of Blocked Artifacts

Description: When a repository is configured to block downloads of artifacts, you may override that configuration (and allow download of blocked artifacts). Note that this setting cannot override the blocking of unscanned artifacts.
Since: 3.0
Security: Requires an admin user
Usage
: POST /api/xray/allowBlockedArtifactsDownload?allow={true | false}


Allow Download when Xray is Unavailable

Description: You may configure Artifactory to block downloads of artifacts when the connected Xray instance is unavailable. This endpoint lets you override that configuration (and allow download of artifacts).
Since: 3.0
Security: Requires an admin user
Usage
: POST /api/xray/allowDownloadWhenUnavailable?allow={true | false}


Configuring the Workers Count

Description: Configure the number of workers which enables you to control the number of workers for new content and existing content.
Since: 3.6
Security: Requires an admin user
UsagePUT /api/v1/configuration/workersCount

You must restart Xray to apply the changes. 

Sample Usage:

{
    "index": {
        "new_content": 8,
        "existing_content": 4
    },
    "persist": {
        "new_content": 8,
        "existing_content": 4
    },
    "analysis": {
        "new_content": 8,
        "existing_content": 4
    },
    "alert": {
        "new_content": 8,
        "existing_content": 4
    },
    "impact_analysis": {
        "new_content": 4
    },
    "notification": {
        "new_content": 8
    }
}

Response Codes: 
200: Success
400: Invalid input: error
400: Failed to parse workers count
500: Failed to update workers count
415: Unsupported media type
403: Forbidden
401: Unauthorized


Get the Workers Count

Description: Get the number of workers for new content and existing content.
Since: 3.6
Security: Requires an admin user
Usage: GET /api/v1/configuration/workersCount
Sample Response:

{
    "index": {
        "new_content": 8,
        "existing_content": 4
    },
    "persist": {
        "new_content": 8,
        "existing_content": 4
    },
    "analysis": {
        "new_content": 8,
        "existing_content": 4
    },
    "alert": {
        "new_content": 8,
        "existing_content": 4
    },
    "impact_analysis": {
        "new_content": 4
    },
    "notification": {
        "new_content": 8
    }
}

Response Codes: 
200: Success
500: Failed to get worker settings
403: Forbidden
401: Unauthorized


Update DB Sync Daily Update Time 

Description: Update the time of the DB sync daily update job.
Since: 3.6
Security:  Requires a user with admin permissions
Usage: PUT api/v1/configuration/dbsync/time
Produces : application/json

Sample Usage:


{
   "db_sync_updates_time": "18:40"
}


Sample Response:

{

   "info": "Successfully updated db sync daily updates time to *"

}

Response Codes: 

403: Forbidden

401: Unauthorized

400: Bad value

400: Bad type

500: Failed to get configuration from db

500: Failed to update, db sync updates job is not running


Get DB Sync Daily Update Time

Description: Get the DB sync daily update time.
Since: 3.6
Security:  Requires a user with admin permissions
Usage
GET api/v1/configuration/dbsync/time
Produces : application/json
Sample Response:

{
   "db_sync_updates_time": "18:40"
}

Response Codes: 

403: Forbidden

401: Unauthorized

500: Failed to get configuration from DB


USER MANAGEMENT

Get Users 

Description: Gets a list of all users in the system or a specific user
API Version: v1
Security: Requires an admin user
Usage: GET /users
Produces: application/json

Sample Response:

[
    {
        "name": "user1",
        "password": "",
        "email": "user1@company.com",
        "admin": true,
        "blocked": false
    },
    {
        "name": "user2",
        "password": "",
        "email": "user2@company.com",
        "admin": false,
        "blocked": false
    }
]

Response Codes: 
200: Success
404: Use with id {id} does not exist
500: Failed to serialize user data
500: Failed to retrieve user 
500: Failed to retrieve user {id}


Get User

Description: Gets a specific user
API Version: v1
Security: Requires an admin user
Produces: application/json

Sample Response:

{
    "name": "user1",
    "password": "",
    "email": "user1@company.com",
    "admin": true,
    "blocked": false
}

Response Codes: 
200: Success
404: Use with id {id} does not exist
500: Failed to serialize user data
500: Failed to retrieve user 
500: Failed to retrieve user {id}


ISSUES

Create Issue Event

Description: Allows adding a custom issue 
API Version:  v1
Security: Requires a valid user with the "Manage Xray Metadata" permission
Usage: POST /events
Producesapplication/json
Consumes: application/json

Sample Payload: 

{
    "id": "XRAY-787",
    "type": "Security",
    "provider": "JFrog",
    "package_type": "maven",
    "severity": "High",
    "components": [
        {
            "id": "aero:aero",
            "vulnerable_versions": [
                "[0.2.3]"
            ]
        }
    ],
    "cves": [
        {
            "cve": "CVE-2017-1000386",
            "cvss_v2": "2.4"
        }
    ],
    "summary": "A very important custom issue",
    "description": "A very important custom issue",
    "sources": [
        {
            "source_id": "CVE-2017-1000386"
        }
    ]
}

Sample Response:

{
    "id": "XRAY-787",
    "package_type": "maven",
    "type": "security",
    "provider": "JFrog",
    "summary": "A very important custom issue",
    "description": "A very important custom issue",
    "severity": "High",
    "created": "2019-12-17T15:29:31.95835098Z",
    "cves": [
        {
            "cve": "CVE-2017-1000386",
            "cvss_v2": "2.4"
        }
    ],
    "sources": [
        {
            "source_id": "CVE-2017-1000386"
        }
    ],
    "components": [
        {
            "id": "aero:aero",
            "vulnerable_versions": [
                "[0.2.3]"
            ],
            "fixed_versions": null
        }
    ],
    "modified": "2019-12-17T15:29:31.95835098Z",
    "edited": "2019-12-17T15:29:31.972920491Z"
}

Update Issue Event

Description: Allows an issue vendor to update an issue event 
Security: Requires a valid user with the "Manage Xray Metadata" permission
Usage: PUT /events/{id}
Consumes: application/json

Sample Payload: 

{
    "id": "XRAY-787",
    "type": "Security",
    "provider": "JFrog",
    "package_type": "maven",
    "severity": "High",
    "components": [
        {
            "id": "aero:aero",
            "vulnerable_versions": [
                "[0.2.3]"
            ]
        }
    ],
    "cves": [
        {
            "cve": "CVE-2017-1000386",
            "cvss_v2": "2.4"
        }
    ],
    "summary": "new summary",
    "description": "updated description",
    "sources": [
        {
            "source_id": "CVE-2017-1000386"
        }
    ]
}

Response:
Should return updated object.


Get Issue Events

Description: Gets an issue created by a vendor
Security: Requires a valid user with the "Read" permission 
Usage: GET /events/{id}
Produces: application/json

Sample Response: 

{
    "id": "XRAY-787",
    "type": "security",
    "source_id": "CVE-2017-1000386",
    "severity": "High",
    "provider": "JFrog",
    "created": "2019-12-17T15:36:33.654Z",
    "modified": "2019-12-17T15:36:33.654Z",
    "updated": "2019-12-17T15:36:33.654Z",
    "description": "updated description",
    "summary": "new summary",
    "components": [
        {
            "component_id": "gav://aero:aero:0.2.3"
        }
    ],
    "properties": {
        "cve": "CVE-2017-1000386",
        "cvss_v2": "2.4",
        "cvss_v3": ""
    }
}

Garbage Collector (GC)

Garbage Collector Status

Description: Returns the current status of the Garbage Collector.
Security: Requires an admin user.
Usage: GET /api/v1/gc/status
Produces: application/json

{
"is_running" : true/false,
“last_time_started” : Date,
“last_time_ended” : Date,
"last_successful_run" : Date,
“Last_state”:  “running”/“succeeded”/”failed”/”aborted”
"last_error": "cause error if there is"
}

Response Codes:

200: ok
500: failed to retrieve current settings
401: unauthorized
403: forbidden


Get GC Configuration

Description: Returns the current configurations of the Garbage Collector.
Security: Requires an admin user.
Usage: GET /api/v1/configuration/gc
Produces: application/json

{
   "scheduler_enabled": true/false,
   "scheduler_period_minutes" : int,
   "max_duration_seconds" : int,
   "max_retry_count" : int,
   "Idle_listener_enabled" : true/false,
   "Idle_listener_gc_duration_seconds" : int,
   "Idle_listener_sampling_rate_seconds" : int
}

Response Codes:

200: ok
500: failed to retrieve current settings
401: unauthorized
403: forbidden


Set GC Configuration

Description: Sets the Garbage Collector configuration.
Security: Requires an admin user.
Usage: PUT /api/v1/gc/configuration
Produces: application/json

{
   "scheduler_enabled": true/false,
   "scheduler_period_minutes" : int,
   "max_duration_seconds" : int,
   "max_retry_count" : int,
   "Idle_listener_enabled" : true/false,
   "Idle_listener_gc_duration_seconds" : int,
   "Idle_listener_sampling_rate_seconds" : int
}
{
	"info" : "Garbage collector configurations successfully updated" 
}

Response Codes:

200: ok
500: failed to update Garbage Collector configuration
400: parsing error/max_duration is below 60; period is below 60; max_retry_count is below 3
401: unauthorized
403: forbidden


Force GC to Run

Description: Forces the Garbage Collector to run.
Security: Requires an admin user.
Usage: POST /api/v1/gc/start
Produces: application/json

{
	"max_duration_seconds" : int
}
{
	"info" : "Garbage collector successfully triggered" 
}

Response Codes:

200: ok
500: failed to trigger Garbage Collector
400: parsing error/max_duration is below 60
409: system YAML parameter deleteMode is not set to 'gc'
401: unauthorized
403: forbidden


Abort GC

Description: Forces the Garbage Collector to stop if running.
Security: Requires an admin user.
Usage: POST /api/v1/gc/abort
Produces: application/json

{
	"info" : "Garbage collector stop signal was triggered" 
}

Response Codes:

200: ok
500: failed to trigger Garbage Collector
401: unauthorized
403: forbidden


WATCHES

The following endpoints related to Watches use the JFrog Xray REST API v2 introduced in Xray version 2.4. If you are using an older version of Xray, please refer to the corresponding endpoints under WATCHES-v1.

Create Watch

Description: Creates a new Watch
API Version: v2
Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can create a Watch using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies.
Usage: POST /watches
Consumes: application/json
Produces: application/json 

Response Codes: 
201: Success - Watch has been successfully created
415: Failed to parse request
400: invalid watch
403: No permissions for watch
409: Watch with name {name} already exists 
500: Failed to create watch

Sample Usage: 
Sample 1 - Watch a Repository

POST api/v2/watches

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "repository",
                "bin_mgr_id": "art-prod-eu",
                "name": "libs-release-local",
                "filters": [
                    {
                        "type": "regex",
                        "value": ".*"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
   },  
    "watch_recipients":["galba@myemail.com","umac@youremail.com"]
}


Sample 2 - Watch All Repositories

POST api/v2/watches

{
    "general_data": {
        "name": "all-repositories",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-repos",
                "filters": [
                    {
                        "type": "package-type",
                        "value": "Docker"
                    },
                    {
                        "type": "package-type",
                        "value": "Debian"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "critial_issues",
            "type": "security"
        }
    ]
 },  
   "watch_recipients":["name@myemail.com","umac@youremail.com"]
}


Sample 3 - Watch a Build

POST api/v2/watches

{
    "general_data": {
        "name": "specific-build-watch",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "build",
                "bin_mgr_id": "art-prod-eu",
                "name": "release-pipeline"
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "critial_issues",
            "type": "security"
        },
        {
            "name": "block_policy",
            "type": "security"
        }
    ]
 },  
   "watch_recipients":["name@myemail.com","umac@youremail.com"]
}

Sample 4 - Create a Watch in Projects

POST api/v2/watches?projectKey=<project_key>

Sample 5- Watch Projects by Project Key 

POST api/v2/watches

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "project",
                "bin_mgr_id":default",
                "name": "<project-key#1>"
            }
        ]
     }
  ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
   },  
    "watch_recipients":["galba@myemail.com","umac@youremail.com"]
}

Sample 6 - Watch All Projects

POST api/v2/watches

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-projects",
                "bin_mgr_id": "art-prod-eu",
            }
        ]
     }
  ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
   },  
    "watch_recipients":["galba@myemail.com","umac@youremail.com"]
}

Sample 7 - Watch Projects with Include/Exclude Patterns on Project Key

POST api/v2/watches

{
    "general_data": {
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "project",
                "bin_mgr_id":default",
                "filters": [
                   {
                     "type": "ant-patterns",
                     "value": {
                       "ExcludePatterns": ["a*","b*"],
                       "IncludePatterns": ["ab*"]
            }
        ]
     }
  ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
   },  
    "watch_recipients":["galba@myemail.com","umac@youremail.com"]
}



Update Watch

Description: Updates a Watch.
Note: This will overwrite the previous Watch configurations and replace them with the updated parameters.
API Version: v2
Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can update a Watch using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies.
Usage: PUT /watches/{name}
Consumes: application/json 
Produces: application/json 
Sample usage: 

PUT api/v2/watches/{watch_name}

{
    "general_data": {
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "all-repos",
                "filters": [
                    {
                        "type": "package-type",
                        "value": "Docker"
                    },
                    {
                        "type": "package-type",
                        "value": "Debian"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "critial_issues",
            "type": "security"
        }
    ]
},  
   "watch_recipients":["name@myemail.com","umac@youremail.com"]
}
PUT api/v2/watches/proj-wath?projectKey=<project_key>

Response Codes:
200: Success. Watch was successfully updated 
400: Failed to update watch: Watch name is empty
403: Failed to update watch: no permissions 
404: Failed to update watch. Watch not found
415: Failed to parse request
500: Failed to update watch 
500: Failed to reload block download cache


Get Watches

Description: Gets a list of all watches in the system
API Version: v2
Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a list of Watches using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies. You can not update the project_key parameter. 
Usage: GET /watches
Produces: application/json

Sample Response:

GET api/v2/watches

[
    {
        "general_data": {
			"id": "5bbe364b0fe4dc29f64c25aa",
            "name": "specific-build-watch",
            "description": "This is a new watch created using API V2",
            "active": true
        },
        "project_resources": {
            "resources": [
                {
                    "type": "build",
                    "bin_mgr_id": "art-prod-eu",
                    "name": "release-pipeline"
                }
            ]
        },
        "assigned_policies": [
            {
                "name": "critial_issues",
                "type": "security"
            },
            {
                "name": "block_policy",
                "type": "security"
            }
        ]
    },
    {
        "general_data": {
			"id": "6f2s864b0fe4dc29f64r5z9m",
            "name": "all-repositories",
            "description": "This is a new watch created using API V2",
            "active": true
        },
        "project_resources": {
            "resources": [
                {
                    "type": "all-repos",
                    "filters": [
                        {
                            "type": "package-type",
                            "value": "Docker"
                        },
                        {
                            "type": "package-type",
                            "value": "Debian"
                        }
                    ]
                }
            ]
        },
        "assigned_policies": [
            {
                "name": "critial_issues",
                "type": "security"
            }
        ]
    },
    {
        "general_data": {
			"id": "56sdf564b0fe4dc29f64cdfs564",
			"name": "vuln-prod",
            "description": "This is a new watch created using API V2",
            "active": true
        },
        "project_resources": {
            "resources": [
                {
                    "type": "repository",
                    "bin_mgr_id": "art-prod-eu",
                    "name": "libs-release-local",
                    "filters": [
                        {
                            "type": "regex",
                            "value": ".*"
                        }
                    ]
                }
            ]
        },
        "assigned_policies": [
            {
                "name": "medium_policy",
                "type": "security"
            }
        ]
    }
]
GET api/v2/watches?projectKey=<project_key>
[
    {
        "general_data": {
            "id": "5bbe364b0fe4dc29f64c25aa",
            "name": "specific-build-watch",
            "description": "This is a new watch created using API V2",
            "active": true,
            "project_key": "myproj"
        },
        "project_resources": {
            "resources": [
                {
                    "type": "build",
                    "bin_mgr_id": "art-prod-eu",
                    "name": "release-pipeline"
                }
            ]
        },
        "assigned_policies": [
            {
                "name": "critial_issues",
                "type": "security"
            },
            {
                "name": "block_policy",
                "type": "security"
            }
        ]
    }
]

Response Codes:
200: Success - Watches retrieved
500: Failed to get Watch


Get Watch

Description: Gets a named watch
API Version: v2
Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a list of Watches using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies. 
Usage: GET /watches/{name}
Produces: application/json
Sample Response:

GET api/v2/watches/vuln-prod

{
    "general_data": {
		"id": "56sdf564b0fe4dc29f64cdfs564",
        "name": "vuln-prod",
        "description": "This is a new watch created using API V2",
        "active": true
    },
    "project_resources": {
        "resources": [
            {
                "type": "repository",
                "bin_mgr_id": "art-prod-eu",
                "name": "libs-release-local",
                "filters": [
                    {
                        "type": "regex",
                        "value": ".*"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
}
GET api/v2/watches/proj-watch?projectKey=<project_key>
{
    "general_data": {
        "id": "56sdf564b0fe4dc29f64cdfs564",
        "name": "proj-watch",
        "description": "This is a new watch created using API V2",
        "active": true,
        "project_key": "myproj"
    },
    "project_resources": {
        "resources": [
            {
                "type": "repository",
                "bin_mgr_id": "art-prod-eu",
                "name": "libs-release-local",
                "filters": [
                    {
                        "type": "regex",
                        "value": ".*"
                    }
                ]
            }
        ]
    },
    "assigned_policies": [
        {
            "name": "medium_policy",
            "type": "security"
        }
    ]
}

Delete Watch

Description: Deletes a Watch 
API Version: v2
Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can delete Watches using this REST API in the scope of a project, by using the additional query parameter projectKey. A Watch can include both Global and Project Policies. 
Produces: application/json
Usage: DELETE /watches/{name}

Response Codes:
200: Success - Watch deleted
403: Failed to delete Watch
404: Watch not found
500: Failed to get Watch for delete
500: Failed to update block download cache



Get Ignored Violations

Description: Gets a list of all Ignored violations on a watch.
API Version: v1 
Notes: Setting pagination parameters are optional. You can get the list sorted using order_by according to severity or updated.  
The default values are:

  • limit = 500 
  • offset = 1
  • order_by = updated

Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can gets a list of all Ignored violations on a Watch using this REST API in the scope of a project, by using the additional query parameter projectKey. 
Usage: GET /violations/ignored/ {watch_name}
Produces: application/json

Get api/v1/violations/ignored/{watch_name}?limit={limit}&order_by={order_by}&offset={offset}

{
    "violations_count": 1,
    "violations": [
        {
            "violation_id": "5ddd31eb9c0a3c25fe242bdd",
            "description": "The Apache Software License, Version 2.0",
            "severity": "High",
            "type": "License",
            "infected_components": [
                "gav://commons-lang:commons-lang:2.4",
                "gav://commons-io:commons-io:1.2",
                "gav://commons-collections:commons-collections:3.2",
                "gav://org.apache.wicket:wicket:1.3.7"
            ],
            "created": "2019-11-26T18:03:37+02:00",
            "watch_name": "watch_all",
            "matched_policies": [
                {
                    "policy": "hgh",
                    "rule": "hi",
                    "is_blocking": false
                }
            ],
            "issue_id": "Apache-2.0",
            "ignore_rule_info": {
                "ignore_rule_type": "Ignore Permanently",
                "author": "admin",
                "created": 1574846905
            }
        }
    ]

Get api/v1/violations/ignored/proj-watch?projectKey=<project_key>&?limit={limit}&order_by={order_by}&offset={offset}

POLICIES - v2

Create Policy

Description: Creates a new policy. 
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Notes
For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can create a policy using this REST API in the scope of a project, by using the additional query parameter projectKey.
API Version: V.2
Usage: POST api/v2/policies
Consumes: application/json
Produces : application/json

Security Example 1: Setting a 'min_severity' criteria
{
    "name": "sec_policy",
    "description": "This is a security policy",
    "type": "security",
    "rules": [
        {
            "name": "sec_rule",
            "criteria": {
                "min_severity": "medium"
            },
            "actions": {
                "webhooks": [
                    "sec_webhook"
                ],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true,
                "notify_deployer": true,
                "notify_watch_recipients": true
            },
            "priority": 1
        }
    ]
}
Security Example 2 -  Setting a 'cvss_range' criteria
{
    "name": "sec_policy",
    "description": "",
    "type": "security",
    "rules": [
        {
            "name": "sec_rule",
            "criteria": {
                "cvss_range": {
                    "from": 2.7,
                    "to": 7.1
                }
            },
            "actions": {
                "webhooks": [
                    "sec_webhook"
                ],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true
            },
            "priority": 1
        }
    ]
}
License Example 1 - Setting an 'allowed_licenses' criteria
{
    "name": "lic_policy",
    "description": "License policy",
    "type": "license",
    "rules": [
        {
            "name": "lic_rule",
            "criteria": {
                "allowed_licenses": [
                    "Apache-1.0",
                    "Apache-2.0"
                ],
                "allow_unknown": true
            },
            "actions": {
                "webhooks": [],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true,
                "custom_severity": "high"
            },
            "priority": 1
        }
    ]
}
License Example 2 - Setting 'banned_licenses' criteria
{
    "name": "lic_policy",
    "description": "License policy",
    "type": "license",
    "rules": [
        {
            "name": "lic_rule",
            "criteria": {
                "banned_licenses": [
                    "Apache-1.0",
                    "Apache-2.0"
                ],
                "allow_unknown": true
            },
            "actions": {
                "webhooks": [],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true,
                "custom_severity": "high"
            },
            "priority": 1
        }
    ]
}

License Example 3 - Setting ‘multi permissive licenses’ criteria
{
    “name”: “lic_policy”,
    “description”: “License policy”,
    “type”: “license”,
    “rules”: [
         {
            “name”: “lic_rule”,
            “criteria”: {
                “banned_licenses”: [
                    “Apache-1.0",
                    “Apache-2.0”
                ],
                “allow_unknown”: true,
                “multi_license_permissive”: true
            },
            “actions”: {
                 “webhooks”: [],
                 “block_download”: {
                     “active”: true
                     “unscanned”: true
                 },
                 “block_release_bundle_distribution”: true,
                 “fail_build”: true,
                 “custom_severity”: “high”
             },
             “priority”: 1
         }
    ]
}


Example 4 -  Projects Sample Usage
POST api/v2/policies?projectKey=<project_key>

Response Codes:
200: Success - Policy created

{
    "info": "Policy {pName} has been created successfully"
}

400 - One or more fields are missing/invalid
409 - Policy {pName} already exists
500 - Failed to create policy


Update Policy

Description: Updates an existing policy. 
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Notes
For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can update a Policy using this REST API in the scope of a project, by using the additional query parameter projectKey. A project_key can not be updated. 
Usage: PUT api/v2/policies/{policy_name}
Consumes: application/json

{
    "name": "sec_policy",
    "description": "Security policy",
    "type": "security",
    "rules": [
        {
            "name": "sec_rule",
            "criteria": {
                "min_severity": "medium"
            },
            "actions": {
                "webhooks": [
                    "sec_webhook"
                ],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true,
               "notify_deployer": true
            },
            "priority": 1
        }
    ]
}
PUT api/v2/policies/{policy_name}?projectKey=<project_key>


Response Codes:
200: Success - Policy updated

{
    "info": "Policy {pName} has been edited successfully"
}

400 - One or more fields are missing/invalid.
404 - Policy {pName} does not exist.
500 - Failed to update policy.


Delete Policy

Description: Deletes an existing policy. 
Security:  Requires the "Manage Watches" role to be set on the User or Group level.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can delete a Policy using this REST API in the scope of a project, by using the additional query parameter projectKey
Usage: DELETE api/v2/policies/{policy_name}

{
   "Policy {policy_name} was deleted successfully"
}
DELETE api/v2/policies/{policy_name}?projectKey=<project_key>

Get Policies

Description: Gets a list of all policies in the system or a specific policy
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a list of Global and Project Policies using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage:
GET api/v2/policies
Produces: application/json

[
    {
        "name": "sec-policy",
        "type": "security",
        "description": "edited",
        "author": "admin",
        "rules": [
            {
                "name": "sec_rule",
                "priority": 1,
                "actions": {
                    "webhooks": [
                        "sec_webhook"
                    ],
                    "fail_build": true,
                    "block_download": {
                        "unscanned": true,
                        "active": true
                    },
                    "block_release_bundle_distribution": true
                },
                "criteria": {
                    "min_severity": "all severities"
                }
            }
        ],
        "created": "2019-12-19T09:17:09.562Z",
        "modified": "0001-01-01T00:00:00Z"
    }
]

GET api/v2/policies?projectKey=<project_key>
[
    {
        "name": "sec-policy",
        "type": "security",
        "description": "edited",
        "author": "admin",
        "project_key": "myproj",
        "rules": [
            {
                "name": "sec_rule",
                "priority": 1,
                "actions": {
                    "webhooks": [
                        "sec_webhook"
                    ],
                    "fail_build": true,
                    "block_download": {
                        "unscanned": true,
                        "active": true
                    },
                    "block_release_bundle_distribution": true
                },
                "criteria": {
                    "min_severity": "all severities"
                }
            }
        ],
        "created": "2019-12-19T09:17:09.562Z",
        "modified": "0001-01-01T00:00:00Z"
    }
]

Response Codes:
200: Success 
500: Failed to get policies.


Get Policy

Description: Gets a list of all policies in the system or a specific policy
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a list of Global and Project Policies using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage:
GET api/v2/policies/{policy_name}
Produces: application/json

{
    "name": "sec-policy",
    "type": "security",
    "description": "edited",
    "author": "admin",
    "rules": [
        {
            "name": "sec_rule",
            "priority": 1,
            "actions": {
                "webhooks": [
                    "sec_webhook"
                ],
                "fail_build": true,
                "block_download": {
                    "unscanned": true,
                    "active": true
                },
                "block_release_bundle_distribution": true
            },
            "criteria": {RE
                "min_severity": "all severities"
            }
        }
    ],
    "created": "2019-12-19T09:17:09.562Z",
    "modified": "0001-01-01T00:00:00Z"
}
GET api/v2/policies/{policy_name}?projectKey=<project_key>
{
   "name": "sec-policy",
   "type": "security",
   "description": "edited",
   "author": "admin",
   "project_key": "myproj",

   "rules": [
       {
           "name": "sec_rule",
           "priority": 1,
           "actions": {
               "webhooks": [
                   "sec_webhook"
               ],
               "fail_build": true,
               "block_download": {
                   "unscanned": true,
                   "active": true
               },
               "block_release_bundle_distribution": true
           },
           "criteria": {
               "min_severity": "all severities"
           }
       }
   ],
   "created": "2019-12-19T09:17:09.562Z",
   "modified": "0001-01-01T00:00:00Z"
}

Response Codes:

200 - Success
400 - One or more fields are missing or invalid.
404  - Policy {pName} does not exist.
500  - Failed to get policy with name  {pName} 


POLICIES - v1

Create Policy

Description: Creates a new policy. 
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Usage: POST /policies
Consumes: application/json

Produces : application/json

-- Example 1
{
  "name": "securityPolicy",
  "type": "security",
  "description": "some description",
  "rules": [
    {
      "name": "securityRule",
      "priority": 1,
      "criteria": {
        "min_severity": "High"
      },
      "actions": {
        "mails": [
          "mail1@example.com",
          "mail2@example.com"
        ],
        "fail_build": true,
        "block_download": {
          "unscanned": true,
          "active": true
        }
      }
    }
  ]
}

-- Example 2

{
  "name": "licensesPolicy",
  "type": "license",
  "description": "some description",
  "rules": [
    {
      "name": "LicenseRule",
      "priority": 1,
      "criteria": {
        "allowed_licenses": [
          "0BSD",
          "AAL"
        ],
        "allow_unknown": true
      }
    }
  ]
}
-- Example 3
{
  "name": "securityPolicy",
  "type": "security",
  "description": "some description",
  "rules": [
       {
         "name": "SLA_ rule",
          "criteria": { … },
          "actions": {
          "webhooks": [],
          "mails": [],
          "block_download": { … },
          "block_release_bundle_distribution": false,
          "notify_watch_recipients": false,
          "notify_deployer": true
          "fail_build": true,
          "build_failure_grace_period_in_days": 5
        }
      }
    }
  ]
}

Response Codes:

201: Success - Policy created
415: Failed to parse the request
400: Policy is not valid. Check mandatory fields
409: Policy with name {name} already exists


Update Policy

Description: Updates an existing policy. 
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Usage: PUT /policies/{policy_name}
Consumes: application/json

{
    "name": "sec_policy",
    "description": "Security policy",
    "type": "security",
    "rules": [
        {
            "name": "sec_rule",
            "criteria": {
                "min_severity": "medium"
            },
            "actions": {
                "webhooks": [
                    "sec_webhook"
                ],
                "block_download": {
                    "active": true,
                    "unscanned": true
                },
                "block_release_bundle_distribution": true,
                "fail_build": true
            },
            "priority": 1
        }
    ]
}
{
    "info": "Policy edited successfully"
}

Response Codes:

200: Success - Policy updated
415: Failed to parse the request
400: Policy is not valid. Check mandatory fields
404: Policy not found


Delete Policy

Description: Deletes an existing policy. 

Security:  Requires the "Manage Watches" role to be set on the User or Group level. 
Usage: DELETE /policies/{policy_name}

{
    "info": "Policy policy_name was deleted successfully"
}

Response Codes:
200: Success - policy deleted
404: Policy not found
500: Failed to delete policy


Get Policies

Description: Gets a list of all policies in the system or a specific policy
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Usage: Get /policies
Produces: application/json

[
    {
        "name": "sec-policy",
        "type": "security",
        "description": "edited",
        "author": "admin",
        "rules": [
            {
                "name": "sec_rule",
                "priority": 1,
                "actions": {
                    "webhooks": [
                        "sec_webhook"
                    ],
                    "fail_build": true,
                    "block_download": {
                        "unscanned": true,
                        "active": true
                    },
                    "block_release_bundle_distribution": true
                },
                "criteria": {
                    "min_severity": "all severities"
                }
            }
        ],
        "created": "2019-12-19T09:17:09.562Z",
        "modified": "0001-01-01T00:00:00Z"
    }
]

Get Policy

Description: Gets a list of all policies in the system or a specific policy
Security: Requires the "Manage Policies" role to be set on the User or Group level. 
Usage: Get /policies/{policy_name}
Produces: application/json

[
    {
        "name": "sec-policy",
        "type": "security",
        "description": "edited",
        "author": "admin",
        "rules": [
            {
                "name": "sec_rule",
                "priority": 1,
                "actions": {
                    "webhooks": [
                        "sec_webhook"
                    ],
                    "fail_build": true,
                    "block_download": {
                        "unscanned": true,
                        "active": true
                    },
                    "block_release_bundle_distribution": true
                },
                "criteria": {
                    "min_severity": "all severities"
                }
            }
        ],
        "created": "2019-12-19T09:17:09.562Z",
        "modified": "0001-01-01T00:00:00Z"
    }
]


Assign Policy to Watches

 Description: Assign a policy to watches
 Security: Requires the "Manage Watches" role to be set on the User or Group level. 
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can assign a Policy to Watches using this REST API in the scope of a project, by using the additional query parameter projectKey.
 Usage: POST /api/v1/policies/{policy_name}/assign
 Consumes: application/json
 Produces: application/json

{
    "watches": [
        "watch_name"
    ]
}
POST /api/v1/policies/{policy_name}/assign?projectKey=<project_key>


Response Codes: 

200: Success - Policy assigned
400: Unsuccessful


SCANNING

Scan Artifact

Description: Invokes scanning of an artifact
Security:  Requires a valid user with the "Manage Xray Metadata" permission
Usage: POST /api/v1/scanArtifact"
Consumes: application/json

Sample Request:

{
 "componentID": "docker://image_name:image_tag"
}

Sample Response:

{
 "info": "Scan of artifact is in progress"
}

Response Codes:

200: Scan of artifact is in progress
415: Failed to parse artifact
500: Failed to write message to the queue


Scan Build

Description: Invokes scanning of a build that was uploaded to Artifactory as requested by a CI server
Security: Requires the "Manage Xray Metadata" role to be set on the User or Group level. 
Usage: POST /api/v1/scanBuild
Consumes: application/json
Produces: wild card 

{
 "artifactory_Id": "artifactory-id",
 "buildName": "build-name",
 "buildNumber": "8",
 "rescan": true,   //this is for scanning the artifact even if it was already scanned - scanned will be performed only if there is no other scan of this build  name and number in progress
  "filters": {
   "includeLicenses": true //in order to get also the licenses
   }
}
{
  "artifactory_Id": "artifactory-id",
  "buildName": "build-name",
  "buildNumber": "8",
  "project": "<project_key>"
}


Produces: application/json

{
  "summary": {
    "fail_build": <true | false>,
    "message": <message with more information regarding the fail/success>,
    "more_details_url": <link to all created Alerts in Xray>,
    "total_alerts": <number of alerts generated from the scan>
  },
  "alerts": [  <alert details>
    {
      "created": <creation time of the Alert>,
      "issues": [ <the issues the Alert includes>
        {
          "created": <creation time of the issue>,
          "cve": "",
          "description": <issue description>,
          "impacted_artifacts": [
            {
              "depth": "int",
              "display_name": "",
              "infected_files": [
                {
                  "component_id": "",
                  "depth": "int",
                  "details": [
                    {
                      "banned_licenses": [
                        {
                          "alert_type": "",
                          "description": "",
                          "id": {},
                          "severity": "",
                          "summary": ""
                        }
                      ],
                      "child": "ImpactedFile",
                      "vulnerabilities": [
                        {
                          "alert_type": "",
                          "description": "",
                          "id": {},
                          "severity": "",
                          "summary": ""
                        }
                      ]
                    }
                  ],
                  "display_name": "",
                  "name": "",
                  "parent_sha": "",
                  "path": "",
                  "pkg_type": "",
                  "sha1": "",
                  "sha256": ""
                }
              ],
              "name": "",
              "parent_sha": "",
              "path": "",
              "pkg_type": "",
              "sha1": "",
              "sha256": ""
            }
          ],
          "provider": <issue provider>,
          "severity": <issue severity>,
          "summary": <issue summary>,
          "type": <issue type>
        }
      ],
      "top_severity": <Alert's top severity>,
      "watch_name": <name of the Watch which caused the Alert>
    }
  ],
  "licenses": [
    {
      "name": <license name>
      "components": [<names of build components with this license>],
      "full_name": <license full name>,
      "more_info_url": [<links to more information about this license>],
    }
  ]
}

Response Codes: 
200: Build scanned
415: Failed to parse scan build request
400: Request is missing mandatory fields
403: No valid license was found
500: Failed to get Artifactory instance data
500: Failed to check watches
500: Failed to send build to scan


Release Bundle Details

Description: Returns license and security violations found in a Release Bundle. 
Security: Requires an Admin user.
Usage: GET /api/v1/details/release_bundle/{name}/{version}?include_violations={boolean}
Parameters: “include_violations” (default - true)

{
   status: "ALLOWED"/"BLOCKED"/"IN_PROGRESS"/"NOT_INDEXED"/"NOT_MARKED_FOR_INDEX","NOT_FOUND_IN_ARTIFACTORY"

   violations: {
     license:  [{...}],
     security: [{...}]
   }
}

Response Codes:

200- Ok
400-
Bad request
500-
Internal server error


REPORTS

Generate Vulnerabilities Report

Description: Generates a Vulnerabilities report with data defined by scope and filters. This request starts the report generation process which runs in the background. The returned report ID is used in other requests that require it such as Get Report Content, Delete Report, etc.
Since: 3.8
Security: Requires a user with the Manage Reports role.
Notes
For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can generate a Vulnerabilities report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST api/v1/reports/vulnerabilities


{

    "name": "report1",
    "resources": {
        "repositories": [
            {
                "name": "libs-release-local"
            },

            {
                "name": "plugins-release-local",
                "include_path_patterns": [
                    "*folder1/*path"
                ]
            },

            {
                "name": "ext-release-local",
                "include_path_patterns": [
                    "folder1/path/*",
                    "folder2/path*"
                ],
                "exclude_path_patterns": [
                    "folder1/path2/*",
                    "folder2/path2*"
                ]
            }
        ],
        "builds": {
            "names": [
                "art-docker-test",
                "art-docker-prod"
            ],
            "include_patterns": [
                "release*",
                "feat*ure"
            ],
            "exclude_patterns": [
                "snapshots*",
                "test*"
            ],
            "number_of_latest_versions": 5
        },
        "release_bundles": {
            "names": [
                "art-pkg",
                "xray_pkg"
            ],
            "include_patterns": [
                "release*",
                "feat*ure"
            ],
            "exclude_patterns": [
                "snapshots*",
                "test*"
            ],
            "number_of_latest_versions": 5
        },
        "projects": {
            "names": [
                "test1",
                "test2"
            ],
            "include_key_patterns": [
                "test*",
            ],
            "number_of_latest_versions": 5
       }
    },
    "filters": {
        "vulnerable_component": "*vulnerable:component*",
        "impacted_artifact": "some://impacted*artifact",
        "has_remediation": false,
        "cve": "CVE-1234-1234",
        "issue_id": "XRAY-1234",
        "severities": [
            "High",
            "Medium"
        ],
        "cvss_score": {
            "min_score": 6.3,
            "max_score": 9
        },
        "published": {
            "start": "2020-06-29T12:22:16Z",
            "end": "2020-06-29T12:22:16Z"
        },
        "scan_date": {
            "start": "2020-06-29T12:22:16Z",
            "end": "2020-06-29T12:22:16Z"
 }

    }

}
{
   "report_id": 23,
   "status": "pending"
}
POST /api/v1/reports/vulnerabilities?projectKey=<project_key>

Generate Due Diligence Report

Description: Generates a Due Diligence report with data defined by scope and filters. This request starts the report generation process which runs in the background. The returned report ID is used in other requests that require it such as Get Report Content, Delete Report, etc.
Since: 3.9
Security: Requires a user with the Manage Reports role.
NotesFor Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can generate a Due Diligence report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST api/v1/reports/licenses


{
    "name": "report1",
    "resources": {
        "repositories": [
            {
                "name": "libs-release-local"
            },
            {
                "name": "plugins-release-local",
                "include_path_patterns": [
                    "*folder1/*path"
                ]
            },
            {
                "name": "ext-release-local",
                "include_path_patterns": [
                    "folder1/path/*",
                    "folder2/path*"
                ],
                "exclude_path_patterns": [
                    "folder1/path2/*",
                    "folder2/path2*"
                ]
            }
        ],
        "builds": {
            "names": [
                "art-docker-test",
                "art-docker-prod"
            ],
            "include_patterns": [
                "release*",
                "feat*ure"
            ],
            "exclude_patterns": [
                "snapshots*",
                "test*"
            ],
            "number_of_latest_versions": 5
        },
        "release_bundles": {
            "names": [
                "art-pkg",
                "xray_pkg"
            ],
            "include_patterns": [
                "release*",
                "feat*ure"
            ],
            "exclude_patterns": [
                "snapshots*",
                "test*"
            ],
            "number_of_latest_versions": 5
        },
        "projects": {
            "names": [
                "test1",
                "test2"
            ],
            "include_key_patterns": [
                "test*",
            ],
            "number_of_latest_versions": 5
       }
    },
    "filters": {
        "component": "*gav:component*",
        "artifact": "some://impacted*artifact",
        "unknown": false,

        "unrecognized": true,

       

        "license_names": [

            "Apache",
            "MIT"

            "AFL"
        ],

        "license_patterns": [

            "*Apache*",
            "The Apache*"

            "AFL*"
        ],

        "scan_date": {
            "start": "2020-06-29T12:22:16Z",
            "end": "2020-06-29T12:22:16Z"
        }
    }
}




{
    "report_id": 43,
    "status": "pending"
}
POST api/v1/reports/licenses?projectKey=<project_key>

Generate Violations Report

Description: Generates a Violations report with data defined by scope and filters. This request starts the report generation process which runs in the background. The returned report ID is used in other requests that require it such as Get Report Content, Delete Report, etc.
Since: 3.11
Security: Requires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can generate a Violations report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST /api/v1/reports/violations
Parameters: All filter parameters are optional


{
  "name": "ViolationsReport",
  "resources": {
    "repositories": [
      {
        "name": "libs-release-local"
      },
      {
        "name": "plugins-release-local",
        "include_path_patterns": [
          "*folder1/*path"
        ]
      },
      {
        "name": "ext-release-local",
        "include_path_patterns": [
          "folder1/path/*",
          "folder2/path*"
        ],
        "exclude_path_patterns": [
          "folder1/path2/*",
          "folder2/path2*"
        ]
      }
    ],
    "builds": {
      "names": [
        "art-docker-test",
        "art-docker-prod"
      ],
      "include_patterns": [
        "release*",
        "feat*ure"
      ],
      "exclude_patterns": [
        "snapshots*",
        "test*"
      ],
      "number_of_latest_versions": 5
    },
    "release_bundles": {
      "names": [
        "art-pkg",
        "xray_pkg"
      ],
      "include_patterns": [
        "release*",
        "feat*ure"
      ],
      "exclude_patterns": [
        "snapshots*",
        "test*"
      ],
      "number_of_latest_versions": 5
    },
    "projects": {
      "names": [
        "test1",
        "test2"
     ],
     "include_key_patterns": [
       "test*",

     ],
      "number_of_latest_versions": 5
    }
  },
  "filters": {
    "type": "security|license",
    "watch_names": [
      "NameOfWatch1",
      "NameOfWatch2"
    ],
    "watch_patterns": [
      "WildcardWatch*"
    ],
    "component": "*vulnerable:component*",
    "artifact": "some://impacted*artifact",
    "policy_names": [
      "NameOfPolicy"
    ],
    "severities": [
      "High",
      "Medium"
    ],
    "updated": {
      "start": "2020-01-02T15:00:00Z",
      "end": "2020-12-15T00:00:00Z"
    },
    "security_filters": {
      "cve": "CVE-2020-10693",
      "issue_id": "XRAY-87343",
      "cvss_score": {
        "min_score": 6.3,
        "max_score": 9
      },
      "summary_contains": "kernel",
      "has_remediation": false
    },
    "license_filters": {
      "unknown": false,
      "unrecognized": true,
      "license_names": [
        "Apache",
        "MIT",
        "AFL"
      ],
      "license_patterns": [
        "*Apache*",
        "AFL*"
      ]
    }
  }
}        



{
    "report_id": 43,
    "status": "pending"
}
POST /api/v1/reports/violations?projectKey=<project_key>


Get Reports List

Description: Get a list of reports that were generated.
Since: 3.8
Security: Requires a user with the Manage Reports role.
Notes
For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a list of reports using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST api/v1/reports
Usage Note: Setting pagination parameters are optional. The list of parameters include: 

  • Direction: asc/desc
  • Page_num: Starting from 1 to any number of pages.
  • Num_of_rows: Starting from 1 to any number of rows that are included in a page.
  • Order_by: name, type, author, start_time, and status.
POST .../api/v1/reports?direction=asc&page_num=2&num_of_rows=10&order_by=name
{
"filters" : {
      "name" : "admin",  //substring
      "status" : ["completed"],
      "report_type":  ["license | vulnerability"],
      "author" : "admin",    //substring
      "start_time_range" :  {
        "start": "2020-06-29T12:22:16Z",
        "end": "2020-06-29T12:22:16Z"
    },
      "end_time_range" : {
        "start": "2020-06-29T12:22:16Z",
        "end": "2020-06-29T12:22:16Z"
    }

  }

}     
{
    "total_reports": 100,
    "reports": [
        {
            "id": 1234,
            "name": "vul_report_1",
            "status": "completed", //running, pending, complete, aborted, failed
            "total_artifacts": 1000,
            "num_of_processed_artifacts": 10,
            "progress": 1,
            "number_of_rows": 10,
            "start_time": "1970-01-01T02:00:00+02:00",
            "end_time": "1970-01-01T03:00:00+02:00",
            "error": "error message in case of failure",
            "author": "user who initiated the report",
            "report_type": "license | vulnerability"
        }

    ]

}
POST /api/v1/reports?direction=asc&page_num=2&num_of_rows=10&order_by=name&projectKey=<project_key
{
    "total_reports": 100,
    "reports": [
        {
            "id": 1234,
            "name": "vul_report_1",
            "status": "completed", //running, pending, complete, aborted, failed
            "total_artifacts": 1000,
            "num_of_processed_artifacts": 10,
            "progress": 1,
            "number_of_rows": 10,
            "start_time": "1970-01-01T02:00:00+02:00",
            "end_time": "1970-01-01T03:00:00+02:00",
            "error": "error message in case of failure",
            "author": "user who initiated the report",
            "report_type": "license | vulnerability",
            "project_key": "myproj"
        }
    ]
}


Get Vulnerabilities Report Content

Description: Get specific content in a Vulnerabilities report.
Since: 3.8
Security: Requires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get specific content in a Vulnerabilities report. using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST api/v1/reports/vulnerabilities/{id}}
Mandatory Pagination Parameters: You can order by

  • severity
  • published
  • cve
  • vulnerable_component
  • impacted_artifact
  • path
  • fixed_versions
  • package_type
  • provider
  • cvss2 
  • cvss3 
  • summary 
POST .../api/v1/reports/vulnerabilities/21?direction=asc&page_num=2&num_of_rows=10&order_by=summary
{

"total_rows": 100,
"rows" :[
    {
        "cves" : [ 

        {
            "cve" : "CVE-2015-8902",
            "cvss_v2" : "4.3/CVSS:2.0/AV:N/AC:M/Au:N/C:N/I:N/A:P",
            "cvss_v3" : "5.5/CVSS:3.0/AV:L/AC:L/PR:N/UI:R/S:U/C:N/I:N/A:H"

        },

        {
            "cve" : "CVE-2016-8902",
            "cvss_v2" : "5.3/CVSS:2.0/AV:N/AC:M/Au:N/C:N/I:N/A:P",
            "cvss_v3" : "6.5/CVSS:3.0/AV:L/AC:L/PR:N/UI:R/S:U/C:N/I:N/A:H"
        }        
    ],
        "summary": "Algorithmic complexity vulnerability",
        "severity": "High",
        "vulnerable_component": "source",
        "impacted_artifact": "artifact",
        "path": "repo1/folder1/artifact",
        "fixed_versions": [
            "2.3",
            "2.4",            "2.5"

        ],
        "published": "1970-01-01T03:00:00+02:00",
        "issue_id": "XRAY-1234",
        "package_type": "maven",
        "provider": "JFrog",
        "description": "Algorithmic complexity vulnerability",
        "references": [
            "github.com",
            "nvd.com"
        ]

    }

]

}
POST /api/v1/reports/vulnerabilities/21?direction=asc&page_num=2&num_of_rows=10&order_by=summary?projectKey=<project_key>

Get Due Diligence Report Content

Description: Get specific content in a Due Diligence report.
Since: 3.9
Security: Requires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get specific content in a Due Diligence report. using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST /api/v1/reports/licenses/{id}
Mandatory Pagination Parameters: You can order by

  • license
  • artifact
  • component
  • unknown_license
  • path
  • unrecognized
  • artifact_scan_time
  • custom, license_name


POST .../api/v1/reports/licenses?direction=asc&page_num=2&num_of_rows=10&order_by=license
{

"total_rows": 100,

"rows" :[
    {
        
        "license": "MIT",

        "license_name" : "The MIT License",
        "component": "deb://debian:buster:glibc:2.28-10,
        "artifact": "docker://redis:latest-07142020122937",
        "path": "repo1/folder1/artifact",

        "artifact_scan_time": "2020-07-14T09:32:00Z",

        "unknown" : false,

        "unrecognized" : false,

        "custom" : false,

        "references": [
            "https://spdx.org/licenses/AFL-1.1.html",
            "https://spdx.org/licenses/AFL-1.1"
        ]
    }
]

}
POST /api/v1/reports/licenses?direction=asc&page_num=2&num_of_rows=10&order_by=license?projectKey=<project_key>

Get Violations Report Content

Description: Get specific content in a Violations report.
Since: 3.11
Security: Requires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get specific content in a Violations report. using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST /api/v1/reports/violations/{id}
Mandatory Pagination Parameters: You can order by

  • type

  • summary

  • severity

  • updated

  • impacted_artifact

  • path

  • vulnerable_component

  • cves

  • cvss2_max_score

  • cvss3_max_score

POST /api/v1/reports/violations?page_num=2&num_of_rows=10&order_by=field1&direction=asc
{
    "total_rows": 6,
    "rows": [
        {
            "type": "security",
            "vulnerable_component": "lodash",
            "impacted_artifact": "docker://docker-violations:latest",
            "path": "docker-local/docker-violations/latest/",
            "watch_id": "45b397d9097293612f5c037e",
            "watch_name": "HighVulnWatch",
            "summary": "Lodash Package for Node.js lodash.js baseSet() Function Prototype Pollution DoS",
            "policy_names": ["HighVuln"],
            "severity": "High",
            "package_type": "npm",
            "issue_id": "XRAY-121295",
            "updated": "2020-08-31T16:01:42.64+03:00",
            "published": "2020-01-01T00:00:00+03:00",
            "artifact_scan_time": "2020-01-01T00:00:00+03:00",
            "references": [],
            "cves": [
                {
                    "cvss_v2_score": 7.1,
                    "cvss_v2_vector": "CVSS:2.0/AV:N/AC:M/Au:N/C:N/I:N/A:C"
                }
            ],
            "cvss2_max_score": 7.1,
            ]
        },
        {
           "type": "license",
           "vulnerable_component": "gav://io.netty:netty-handler-proxy:4.1.48.Final",
           "impacted_artifact": "generic://sha256:06bde4ed74044d133fce9d596258ec57c7e42023df5e3e542209a488347eb340/jfrog-artifactory-oss-7.7.3-linux.tar.gz",
           "path": "generic-local/jfrog-artifactory-oss-7.7.3-linux.tar.gz",
           "watch_id": "4db8cec50cd846fd4de117c7",
           "watch_name": "AnyWatchLicense",
           "summary": "The Apache Software License, Version 2.0",
           "policy_names": ["BanApacheLicense2","BanApacheLicense"],
           "severity": "High",
           "package_type": "maven",
           "updated": "2020-09-03T22:11:09.865+03:00",
           "published": null,
           "artifact_scan_time": "1970-01-01T02:00:00+02:00",
           "references": [],
           "license_name": "Apache-2.0"
       },
    ]
}
POST /api/v1/reports/violations?page_num=2&num_of_rows=10&order_by=field1&direction=asc?projectKey=<project_key>

Get Report Details By ID

Description: Get a report's details by using a specific report ID.
Since: 3.8
Security: Requires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can get a report's details by using a specific report ID using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: GET api/v1/reports/{id}

{
  "id": 1234,
  "name": "vul_report_1",
  "status": "completed", //running, pending, complete, aborted, failed
  "total_artifacts": 1000,
  "num_of_processed_artifacts": 10,
  "progress": 1,
  "number_of_rows": 10,
  "start_time": "1970-01-01T02:00:00+02:00",
  "end_time_estimation": "1970-01-01T03:00:00+02:00",
  "error": "error message in case of failure",
  "Author": "user who initiated the report",
  "report_type": "license | vulnerability"
}
GET api/v1/reports/7?projectKey=<project_key>

{
  "id": 1234,
  "name": "vul_report_1",
  "status": "completed", //running, pending, complete, aborted, failed
  "total_artifacts": 1000,
  "num_of_processed_artifacts": 10,
  "progress": 1,
  "number_of_rows": 10,
  "start_time": "1970-01-01T02:00:00+02:00",
  "end_time_estimation": "1970-01-01T03:00:00+02:00",
  "error": "error message in case of failure",
  "Author": "user who initiated the report",
  "report_type": "license | vulnerability",
  "project_key": "myproj"
}

Export

Description: Export a report and it's data to a PDF, JSON, or CSV file.
Since: 3.8
SecurityRequires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can export a report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: GET /api/v1/reports/export/{id:.*}
Usage Note: There are two mandatory query parameters that need to be provided:

  • File_name: The desired file name for download (without a suffix)
  • Format: pdf| json | csv
GET api/v1/reports/export/{15}?file_name=vuln_report_1&format=pdf
GET api/v1/reports/export/15?file_name=vuln_report_1&format=pdf?projectKey=<project_key>


Response
A downloaded file named <file-name>.zip; this file would contain the file <file-name>.<format>.


Delete

Description: Delete report.
Since: 3.8
SecurityRequires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can delete a report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: DELETE /api/v1/reports/{id:.*}

DELETE /api/v1/reports/{10}
DELETE /api/v1/reports/10?projectKey=<project_key>
"report deleted successfully"

Abort

Description: Abort report generation.
Since: 3.8
SecurityRequires a user with the Manage Reports role.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Manage Security Assets privilege can abort a report using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST /api/v1/reports/abort/{id:.*}

POST /api/v1/reports/abort/{21}
POST /api/v1/reports/abort/21?projectKey=<project_key>


BINARY MANAGERS

Get Binary Manager

Description: Gets the details of the specified connected Artifactory instance
NotesThis API is deprecated from version 3.x.
Security:  Requires a valid user
Usage: GET /binMgr/{id}

Sample usage:

GET /binMgr/###art12
{
  "binMgrUrl": "http://localhost:8081/artifactory",
  "binMgrId": "###art12",
  "binMgrDesc": "",
  "version": "4.x-SNAPSHOT",
  "proxy_enabled": false
}


Response Codes:

200: Artifactory model
400: Path parameter is missing
401: Bad Credentials
500: Failed to obtain response


Get Repos Indexing Configuration

Description: Gets the indexed and not indexed repositories in a given binary manger
Security: Requires an admin user
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Index Resources privilege can get the indexed and not indexed repositories in a given binary manger using  this REST API in the scope of a project, by using the additional query parameter projectKey. 
Usage: GET /api/v1/binMgr/{id}/repos
Consumes: application/json

Response codes:

200: List of Artifactory repositories
401: Bad Credentials
500: Failed to obtain response

Sample usage: 

{
    "bin_mgr_id": "default",
    "indexed_repos": [
        {
            "name": "docker-local",
            "type": "local",
            "pkg_type": "Docker"
        }
    ],
    "non_indexed_repos": [
        {
            "name": "debian-local",
            "type": "local",
            "pkg_type": "Debian"
        }
    ]
}

Get Builds Indexing Configuration

Description: Gets the indexed and not indexed builds in a given binary manager.
Security: Requires an admin user
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Index Resources privilege can get the indexed and not indexed builds in a given binary manger using this REST API in the scope of a project, by using the additional query parameter projectKey
Usage: GET /api/v1/binMgr/{id}/builds
Consumes: application/json

Response codes:

200: List of Artifactory builds
401: Bad Credentials
500: Failed to obtain response

Sample usage: 

{
    "bin_mgr_id": "default",
    "indexed_builds": [
        "build1",
        "build2"
    ],
    "non_indexed_builds": [
        "build3",
        "build4"
    ]
}

Add Builds to Indexing Configuration

Description: Adds new builds to the list of builds selected for indexing by only providing the new build names. 
Since: 3.8.2
Security:  Requires a user with admin permissions
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Index Resources privilege can add new builds to the list of builds selected for indexing using this REST API in the scope of a project, by using the additional query parameter projectKey
Usage:
 POST api/v1/binMgr/builds
Consumes: application/json
Produces: application/json
Sample Usage:

POST api/v1/binMgr/builds
Sample Request:
{
  "names": ["build1","build2","build1","build4","build4"]
}


Response Codes:Sample Request:

401 - Unauthorized

403 - Forbidden

400 - Failed to set build names to index : Got invalid request

500 - Failed to set build names to index


Update Repos Indexing Configuration

Description: Update the indexed and not indexed repositories in a given binary manger
Security: Requires an admin user
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Index Resources privilege can update the indexed and not indexed repositories in a given binary manger using this REST API in the scope of a project, by using the additional query parameter projectKey
Usage: PUT /api/v1/binMgr/{id}/repos
Consumes: application/json

Response codes:

200: Success

Sample usage: 

{
    "indexed_repos": [
        {
            "name": "docker-local",
            "type": "local",
            "pkg_type": "Docker"
        }
    ],
    "non_indexed_repos": [
        {
            "name": "debian-local",
            "type": "local",
            "pkg_type": "Debian"
        }
    ]
}

Response:

{
  "info": "Repositories list has been successfully sent to Artifactory"
}

Update Builds Indexing Configuration

Description: Updates the indexed and not indexed builds in a given binary manager
Security: Requires an admin user
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with Index Resources privilege can update the indexed and not indexed builds in a given binary manger using this REST API in the scope of a project, by using the additional query parameter projectKey
Usage: PUT /api/v1/binMgr/{id}/builds
Consumes: application/json

Response codes:

200: Success

Sample usage: 

{
    "indexed_builds": [
        "build1",
        "build2"
    ]
}

Response:

{
  "info": "Repositories list has been successfully sent to Artifactory"
}

Force Reindex

Description: Reindexes existing artifacts for missing components.
Notes: The repositories and builds need to be configured for indexing in Xray prior to running the command.
The reindexing process only adds missing files or components and does not remove existing ones.
The number of max entities that can be reindexed is limited to 1000 and is set as the default value. This value can be changed by setting the maxEntitiesToReindex parameter in the Xray configuration file  located at ${XRAY_DATA}/config/xray_config.yaml.

Security:  Requires an admin user
Usage: POST  /api/v1/forceReindex
Consumes: application/json

{
    "artifactory_id": "art1AWS",
    "artifacts": [
        {
            "repository": "myDebian", // repository is a mandatory parameter, either path or sha256 or both should be provided - if both are provided we compare the given sha256 to the actual sha256 and fail if they are incompatible 
            "path": "/aaa/bb/ccc.deb", 
            "sha256": "aa146bx"
        }
    ],
    "builds": [
        {
            "name": "myb",  // both build name and build number must be provided
            "number": "12"
        }
    ]
}

Sample response

{
  "sent_to_reindex": {
    "artifacts": [
      {
        "repository": "myDebian",  
        "path": "aaa/bb/ccc",
        "sha256": "aa146bx"
      }
    ],
    "builds": [
      {
        "name": "myb",
        "number": "12"
      }
    ]
  },
}

COMPONENTS

Find Component by Name

Description: Search for a component by name - applicable only for components synced from the JFrog Global database to Xray 
Security: Requires a valid user with the "Read" permission
Usage: GET /component/{component_name}
Produces: application/json
Sample Response

{
    "component": "4:kdegames-devel",
    "package_type": "rpm",
    "name": "kdegames-devel",
    "description": "Development files for the KDE gaming libraries.Install kdegames-devel if you wish to develop or compile games for the KDE desktop.",
    "created": "2017-11-19T09:24:12.065Z",
    "modified": "2017-11-19T10:13:19.946Z",
    "sources": [
        {
            "name": "archive-centos",
            "url": "http://vault.centos.org/",
            "updated": "2017-11-19T09:24:11.995Z"
        }
    ],
    "versions": [
        {
            "version": "6:3.3.1-2",
            "released": "0001-01-01T00:00:00Z",
            "licenses": [
                "GPL-3.0"
            ],
            "files": [
                {
                    "name": "kdegames-devel-3.3.1-2.i386.rpm",
                    "sha256": "f256373977e2705e521e06c85f6f49cefcd6c74c8a0fa18dec2eb1bcefe7e4b4",
                    "sha1": "d184ba4bd8e205fda0ba29b7f1db39b91174b1ef",
                    "md5": "7b246aeef791ad549e78cda2c3c72a40"
                }
            ]
        }
    ]
}


Response Codes:

200: Component found

400: Failed to resolve component mapping

500: Failed to get component by name


Find Component by CVE

Description: Search for a component by the CVEs it contains directly
Security: Requires a valid user with "Admin" permissions. For Xray 3.8 and above, this only requires a valid user with the "Manage Reports" role.
Usage: POST api/v1/component/searchByCves
Consumes: application/json

{
    "cves": [
        "CVE-2018-1999002"
    ]
}


Produces: application/json

[
    {
        "cve_details": "CVE-2018-1999002",
        "components": [
            {
                "name": "org.jenkins-ci.main:jenkins-core",
                "package_type": "Maven",
                "version": "2.60.3",
                "link": "http://localhost:8046/xray/web/#/component/details/gav:~2F~2Forg.jenkins-ci.main:jenkins-core/2.60.3"
            }
        ]
    }
]


Sample usage: 

POST api/v1/component/searchByCves
{
	"cves": ["CVE-2017-15708","CVE-2017-15709"]
}

Sample Response:

[
    {
        "cve_details": "CVE-2017-15708",
        "components": [
            {
                "name": "commons-collections:commons-collections",
                "package_type": "Maven",
                "version": "3.2.1",
                "link": "http://10.1.16.130:8000/web/#/component/details/gav:~2F~2Fcommons-collections:commons-collections/3.2.1"
            }
        ]
    },
    {
        "cve_details": "CVE-2017-15709",
        "components": []
    }
]

Response Codes

200: valid response
415: Failed to parse request
400: Got invalid CVE
500:  Failed to search components by cves


Find CVEs by Component

Description: Search for CVEs by the infected components
Security:  Requires a valid user with "Admin" permissions. For Xray 3.8 and above, this only requires a valid user with the "Manage Reports" role.
Usage: POST api/v1/component/searchCvesByComponents
Consumes: application/json

{
	"components_id": ["<component ID>"]
}

Produces: application/json

[
    {
        "component": "<Component ID>",
        "cves": [
            "<CVE ID>"
        ]
    },
    {
        "component": "c2",
        "error": "Failed to get component",
        "cves": []
    }
]

Sample Usage:

POST api/v1/component/searchCvesByComponents

{
	"components_id": ["gav://commons-collections:commons-collections:3.2.1","c2"]
}

Sample Response:

[
    {
        "component": "gav://commons-collections:commons-collections:3.2.1",
        "cves": [
            "CVE-2017-15708"
        ]
    },
    {
        "component": "c2",
        "error": "Failed to get component",
        "cves": []
    }
]

Response Codes

200: Valid response
415: Failed to parse request
500: Failed to search CVEs of components


Get Component List Per Watch 

Description: Gets a list of components associated with a specific watch.
API Version: v2
Security: Requires a valid user with "Admin" permissions. For Xray 3.8 and above, this only requires a valid user with the "Manage Reports" role.
Usage: GET api/v2/component/data/{watch_name}?limit=(?)offset=(?)from=(?)to=(?)
Produces: application/json
Sample Response: 

Get/api/v2/component/data/w1?limit=8&offset=0&from=2017-06-10T12:44:00&to=2020-06-10T12:44:00
[
    {
        "checksum": "cf7274c79120c6420e2563292e4c54ee3abf1a7924a22cd3ff29ec686dc97ed0",
        "repo": "generic-local",
        "path": "/",
        "package_name": "generic://sha256:cf7274c79120c6420e2563292e4c54ee3abf1a7924a22cd3ff29ec686dc97ed0/cli.zip"
    },
    {
        "checksum": "cec571c6f2578e3388339c97cf6706d64e877742d040f315206d2f5c09f68c0b",
        "repo": "python-local",
        "path": "/",
        "package_name": "pypi://getversion",
        "version": "0.5.7"
    }
]

Get Artifact Dependency Graph

Description: Get the complete dependency graph for an artifact
Security:  Requires a valid user with the "Read" permission
Usage: POST /dependencyGraph/artifact
Consumes: application/json

The artifactory_id parameter is no longer required in Xray version 3.x, this parameter (also within a path) will be ignored.

{
  "path": "<artifactory-name/repo-name/path>"
}

Produces: application/json

{
  "artifact":{
    "name": "<The name of the artifact who's graph we are obtaining>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
    "component_id": "<The component ID>"
  },
  "components":[ 
    {
      "component_name":"<Dependency component name>",
      "component_id":"<Dependency Component ID>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "components":[<Next level dependencies of the dependency component>] 
    }]
}

Sample Usage:

POST /dependencyGraph/artifact
{
  "path": "/Artifactory/pnnl/goss/goss-core-client/0.1.7/goss-core-client-0.1.7-sources.jar"
}
 
{
  "artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": "",
    "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  "components":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[]
    },
    {
      "component_name":"some-component-1.2",
      "component_id":"pip://some-component:1.2",
      "package_type":"pip",
      "version":"1.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[
        {
          "component_name":"Jinja2.7.2",
          "component_id":"pip://Jinja2:2.7.2",
          "package_type":"pip",
          "version":"2.7.2",
          "created":"2008-06-09T16:50:19Z",
          "modified":"2015-07-26T17:49:47Z",
          "components":[]
        }
      ]
    }
  ]
}

Response Codes:
200: Success
400: Artifact '<PATH>' doesn't exist or isn't indexed in Xray
401: Bad credentials
415: Failed to parse request


Compare Artifacts

Description: Compares two artifacts and produces the difference between them
Security:  Requires a valid user with the "Read" permission
Usage: POST /dependencyGraph/artifactDelta
Consumes: application/json

The artifactory_id parameter is no longer required in Xray version 3.x, this parameter (also within a path) will be ignored.

{
 "source_artifact_path":"<artifactory/repo/path>",
 "target_artifact_path":"<artifactory/repo/path>"
}

Produces:

{
  "source_artifact":{
    "name": "<The name of the source artifact we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
  },
  "target_artifact":{
    "name": "<The name of the target artifact we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "sha1": "<Artifact's SHA1 checksum>",
  },
  "removed":[
    {
      "component_name":"<Component name only found in source artifact>",
      "component_id":"<Dependency Component ID only found in source artifact>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>"
    }
  ],
  "added":[
    {
      "component_name":"<Component name only found in target artifact>",
      "component_id":"<Dependency Component ID only found in target artifact>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ],
 "unchanged":[
    {
      "component_name":"<Component name only found in both artifacts>",
      "component_id":"<Dependency Component ID only found in both artifacts>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ]
}

Sample Usage:

POST /dependencyGraph/artifactDelta
{
 "source_artifact_path":"/pnnl/goss/goss-core-client/0.1.7/goss-core-client-0.1.7-sources.jar",
 "target_artifact_path":"/pnnl/goss/goss-core-client/0.1.8/goss-core-client-0.1.8-sources.jar",
}
 
{
  "source_artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": ""
  },
  "target_artifact":{
    "name": "artifactory-pro.zip",
    "path": "art2/ext-release-local/",
    "pkg_type": "Generic",
    "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
    "sha1": ""
  },
  "removed":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
  "added":[
    {
      "component_name":"Jinja2.7.2",
      "component_id":"pip://Jinja2:2.7.2",
      "package_type":"pip",
      "version":"2.7.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
 "unchanged":[
    {
      "component_name":"Apache1.4",
      "component_id":"gav://apache:1.4",
      "package_type":"maven",
      "version":"1.4",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ]
}

Response Codes:
200: Success
400: Artifact '<PATH>' doesn't exist or isn't indexed in Xray
401: Bad Credentials
415: Failed to parse request


Get Build Dependency Graph

Description: Get the complete dependency graph for a build
Security:  Requires a valid user with the "Read" permission
Usage: POST /dependencyGraph/build
Consumes: application/json

{
 "artifactory_id":"<Artifactory instance name>",
 "build_name":"<Build name>",
 "build_number":"<Build number>"
}

Produces: application/json

{
  "build":{
    "name": "<The name of the build who's graph we are obtaining>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Artifact's SHA256 checksum>",
    "component_id": "<The component ID>"
  },
  "components":[ 
    {
      "component_name":"<Dependency component name>",
      "component_id":"<Dependency Component ID>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "components":[] 
    }]
}

Sample Usage:

POST /dependencyGraph/build
{
 "artifactory_instance":"myInstance",
 "build_name":"someBuild",
 "build_number":"someNumber"
}
 
{
  "build": {
      "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
    },
  "components":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[]
    },
    {
      "component_name":"some-component-1.2",
      "component_id":"pip://some-component:1.2",
      "package_type":"pip",
      "version":"1.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z",
      "components":[
        {
          "component_name":"Jinja2.7.2",
          "component_id":"pip://Jinja2:2.7.2",
          "package_type":"pip",
          "version":"2.7.2",
          "created":"2008-06-09T16:50:19Z",
          "modified":"2015-07-26T17:49:47Z",
          "components":[]
        }
      ]
    }
  ]
}

Response Codes:
200: Success
400: Build '<PATH>' doesn't exist or isn't indexed in Xray
400: Missing build name
400: Missing build number
400: Missing Artifactory ID
401: Bad credentials
415: Failed to parse request 


Compare Builds

Description: Compares two builds and produces the difference between them
Security:  Requires a valid user with the "Read" permission
Usage: POST /dependencyGraph/buildDelta
Consumes: application/json

The artifactory_id parameter is no longer required in Xray version 3.x, this parameter (also within a path) will be ignored.

{
 "source_artifactory_id":"<First instance name>",
 "source_build_name":"<First build name>",
 "source_build_number":"<First build number>",
 "target_artifactory_id":"<Second instance name>",
 "target_build_name":"<Second build name>",
 "target_build_number":"<Second build number>"
}

Produces: application/json

{
  "source_build":{
    "name": "<The name of the source build we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Build's SHA256 checksum>",
    "component_id": "<Build's component ID>",
  },
  "target_build":{
    "name": "<The name of the target build we are comparing>",
    "path": "<artifactory-name/repo-name/path>",
    "pkg_type": "<Package type>",
    "sha256": "<Build's SHA256 checksum>",
    "component_id": "<Build's component ID>",
  },
  "removed":[
    {
      "component_name":"<Component name only found in source build>",
      "component_id":"<Dependency Component ID only found in source build>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>"
    }
  ],
  "added":[
    {
      "component_name":"<Component name only found in target build>",
      "component_id":"<Dependency Component ID only found in target build>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ],
 "unchanged":[
    {
      "component_name":"<Component name only found in both builds>",
      "component_id":"<Dependency Component ID only found in both builds>",
      "package_type":"<Dependency component package type>",
      "version":"<Dependency component version>",
      "created":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
      "modified":"<ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    }
  ]
}

Sample Usage:

POST /dependencyGraph/buildDelta
{
 "origin_build_artifactory_instance":"my-instance",
 "origin_build_name":"someOriginBuild",
 "origin_build_number":"111",
 "target_build_artifactory_instance":"my-instance",
 "target_build_name":"someTargetBuild",
 "target_build_number":"222",
}
 
{
  "source_build":{
    "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  "target_build":{
    "name": "my-build",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
  },
  " removed":[
    {
      "component_name":"some-component-1.1",
      "component_id":"pip://some-component:1.1",
      "package_type":"pip",
      "version":"1.1",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
  "added":[
    {
      "component_name":"Jinja2.7.2",
      "component_id":"pip://Jinja2:2.7.2",
      "package_type":"pip",
      "version":"2.7.2",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ],
 "unchanged":[
    {
      "component_name":"Apache1.4",
      "component_id":"gav://apache:1.4",
      "package_type":"maven",
      "version":"1.4",
      "created":"2008-06-09T16:50:19Z",
      "modified":"2015-07-26T17:49:47Z"
    }
  ]
}

Response Codes:
200: Success
400: The build with the provided identifier doesn't exist or isn't indexed in Xray
401: Bad credentials
415: Failed to parse request


Export Component Details

Description: Export component details.
Security:  Requires a valid user with "Read" permission
Usage: POST component/exportDetails
Consumes: application/json

Sample Request:

{
    "violations": true | false,
    "include_ignored_violations": true | false,            
    "license": true | false,
    "security": true | false,
    "exclude_unknown": true | false,
    "component_name": "abrade:abrade:0.0.1",
    "package_type": "maven",
    "output_format": "pdf | csv | json",
    "sha_256" : "1314223523643634"
}

Response: []byte stream to file

Response Codes:

200: Success 
400: Invalid request payload
403: No Permission to component
500: Failed to export component details


SECURITY

Enable TLS Certificate for RabbitMQ

Description: Adds the TLS Certificate on RabbitMQ
Security: Requires an admin user 
Usage: PUT /api/v1/configuration/systemParameters
Consumes: application/json
Sample Output

PUT /api/v1/configuration/systemParameters

{
    "sslInsecure": false,
    "maxDiskDataUsage": 80,
    "monitorSamplingInterval": 300,
    "mailNoSsl": false,
    "messageMaxTTL": 7,
    "jobInterval": 86400,
    "allowSendingAnalytics": true,
    "httpsPort": 443,
    "enableTlsConnectionToRabbitMQ": true,
	"httpClientMaxConnections": 50,
    "httpClientMaxIdleConnections": 20,
    "jsFilesBatch": 20
}

INTEGRATIONS

Get Integration Configuration

Description: Retrieves integrations configured into the system
Security:  Requires an admin user
Usage: GET /integration

Produces: application/json

Sample usage:

GET /integration
 
 [
  {
    "vendor": "whitesource",
    "api_key": "4a547ccd-fdf0-4ac4-8ec2-259ce91c1633",
    "enabled": <true|false>,
    "context": "project_id",
    "url": "https://saas.whitesourcesoftware.com/xray",
    "description": "WhiteSource provides a simple yet powerful open source security and licenses management solution. More details at http://www.whitesourcesoftware.com.",
    "test_url": "https://saas.whitesourcesoftware.com/xray/api/checkauth"
  }
]

Response Codes:

200: Integration data retrieved successfully

500: Failed to retrieve integration data


Add Integration Configuration

Description: Add an integration configuration
Security:  Requires an admin user
Usage: POST /integration

Consumes: application/json


 {
  "vendor": ""
  "api_key": "",
  "enabled": <true|false>,
  "context": "",
  "url": "",
  "description": "",
  "test_url": ""
}

Sample usage:

POST /integration
 
{
  "vendor": "whitesource",
  "api_key": "12345",
  "enabled": true,
  "context": "project_id",
  "url": "https://saas.whitesourcesoftware.com/xray",
  "description": "WhiteSource provides a simple yet powerful open source security and licenses management solution. More details at http://www.whitesourcesoftware.com.",
  "test_url": "https://saas.whitesourcesoftware.com/xray/api/checkauth"
}

Response Codes:

200: Integration data successfully added

500: Failed to register integration data


Update Integration Configuration

Description: Updates the integration configuration
Security:  Requires an admin user
Usage: PUT /integration/{name}
Consumes: application/json


 {
  "vendor": "",
  "api_key": "",
  "enabled": <true|false>,
  "context": "",
  "url": "",
  "description": "",
  "test_url": ""
}

Response Codes:

200: Integration data successfully Updated

500: Failed to register integration data


Delete Integration Configuration

Description: Delete integration configuration
Security:  Requires an admin user
Usage: DELETE /integration/{name}
Produces: application/json

Sample usage:

 DELETE /integration/whitesource

Response Codes:

200: Integration deleted successfully

400: Vendor name is missing

500: Failed to delete integration


SUMMARY

Build Summary

Description: Provides details about any build specified by build identifier (name + number)
Security:  Requires a valid user with "Read" permission
Usage: GET /summary/build?build_name=<build name>&build_number=<build number>
Produces: application/json

{
  "artifacts": [
    {
      "general": {
        "component_id": "",
        "name": "",
        "path": "",
        "pkg_type": "",
        "sha256": ""
      },
      "issues": [
        {
          "created": "",
          "description": "",
          "impact_path": [
            {}
          ],
          "issue_type": "",
          "provider": "",
          "severity": "",
          "summary": ""
        }
      ],
      "licenses": [
        {
          "components": [
            "sets.SetInterface"
          ],
          "full_name": "",
          "more_info_url": [
            ""
          ],
          "name": ""
        }
      ]
    }
  ],
  "errors": [
    {
      "error": "",
      "identifier": ""
    }
  ]
}

Response Codes: 

200: Obtained artifact build summary

400: Missing build name or build number


Artifact Summary

Description: Provides details about any artifact specified by path identifiers or checksum.
Note: Supported checksums are SHA-256 and SHA-1.
Security: Requires a valid user with "Read" permission.
Usage: POST /summary/artifact
Consumes: application/json

The artifactory_id parameter is no longer required in Xray version 3.x, this parameter (also within a path) will be ignored.

{
  "checksums": [
    ""
  ],
  "paths": [
    ""
  ]
}

Produces: application/json

{
  "artifacts": [
    {
      "general": {
        "component_id": "",
        "name": "",
        "path": "",
        "pkg_type": "",
        "sha256": ""
      },
      "issues": [
        {
          "created": "",
          "description": "",
          "impact_path": [
            {}
          ],
          "issue_type": "",
          "provider": "",
          "severity": "",
          "summary": ""
        }
      ],
      "licenses": [
        {
          "components": [
            "sets.SetInterface"
          ],
          "full_name": "",
          "more_info_url": [
            ""
          ],
          "name": ""
        }
      ]
    }
  ],
  "errors": [
    {
      "error": "",
      "identifier": ""
    }
  ]
}

Sample Usage:

POST /summary/artifact
{
    "checksums":["d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2"]
}
  
Response
{
  artifacts: [
    "general": {
      "name": "artifactory-pro.zip",
      "path": "art2/ext-release-local/",
      "pkg_type": "Generic",
      "sha256": "d160c68ed8879ae42756e159daec1dd7ecfd53b6192321656b72715e20d46dd2",
      "component_id": "gav://org.artifactory.pro:artifactory-pro-war:4.14.0"
    },
    "issues":[
      {
        "summary":"FileSystemBytecodeCache in Jinja2 2.7.2 does not properly create temporary directories",
        "description":"this is the description of the issue",
        "issue_type":"security",
        "severity":"Medium",
        "provider":"JFrog",
        "created":"2016-10-26T11:15:51.17Z",
        "impact_path": [
          "xray-artifactory/maven-1000/com/atlassian/aui/auiplugin/0.0.5-9-0-snapshot-035-do-not-use/Jinja2-2.7.2"
        ]
      }
    ],
    "licenses":[
      {
        "name":"MIT",
        "full_name":"The MIT License",
        "more_info_url":"https://opensource.org/licenses/MIT",
        "components":[
          "some-component-1",
          "some-component-2",
          "some-component-3"
        ]
      },
      {
        "name":"AGPL-3.0",
        "full_name":"GNU AFFERO GENERAL PUBLIC LICENSE, Version 3",
        "more_info_url":"https://opensource.org/licenses/AGPL-3.0",
        "components":[
          "some-component-4",
          "some-component-5"
        ]
      },
      {
        "name":"unknown",
        "components":[
          "some-component-6",
          "some-component-7"
        ]
      }
  ],
  errors: [
    {
      identifier: "4e39f19212597312ee02db873847bcb12c17cc639898bd2fd9b6a4aff16690e5",
      error: "Artifact doesn't exist or not indexed in Xray"
    }
  ]
}

Response Codes:

200: Obtained artifact summary

415: Failed to parse JSON


SYSTEM

Resend Artifacts Metadata 

Description: Resend artifact metadata to the Metadata Server
Since: 3.10.3
Security: Requires an admin user
UsagePOST api/v1/mds/migration
Note: Requires the following two parameters

  • repo: Name of the repository, has to be an existing repo marked for scanning.
  • path: Repository path
curl http://10.70.30.82:8082/xray/api/v1/mds/migration -H "Content-Type: application/json" -d '{"repo":"npm-local", "path":"/1/"}
{"info":"Migration has been started"}

Create Bundle 

Description: Create support bundle
Security: Requires an admin user
Usage: POST /system/support/bundle
Consume: application/json
Produce: application/json

Sample Usage:

POST /system/support/bundle
{
   "name":"support_bundle_issue1",
   "description":"support bundle for issue 1",
   "parameters":{
      "configuration":true,
      "system":true,
      "logs":{
         "end_date":"2019-05-15T16:32:04+03:00",
         "include":true,
         "start_date":"2019-05-15T16:32:04+03:00"
      },
      "thread_dump":{
         "count":1,
         "interval":1000
      }
   }
}
{
    "id": "01DT79NXGJBM4G0KMTEEMZ9FN0",
    "artifactory": {
        "service_id": "jfrt@01dsqzccvew5dr0j75eq6b1tnv",
        "bundle_url": "http://<host>:<port>/artifactory/api/archive/download/jfrog-support-bundle/01DT79NXGJBM4G0KMTEEMZ9FN0/jfxr/jfxr@01dsr2hbsef4c1et00cj2mnzkn?archiveType=zip"
    }
}



Get System Monitoring Status

Description: Gets system monitoring status
Security:  Requires an admin user
Usage: GET /monitor
Produces: application/json

Sample usage:

GET /monitor
 
{
 "problems": [
   {
     "severity": "warning",
     "services": [
       "analysis",
       "event",
       "indexer",
       "xray_server"
     ],
     "problem": "No connection to Artifactory instance ###art12"
   }
 ]
}

Response Codes:

200: System monitoring status was sent

500: Failed to marshal object to json


Ping Request

Description: Sends a ping request
Security: Requires a valid user
Usage: GET /api/v1/system/ping
Produces: application/json
Sample usage:

GET /api/v1/system/ping
{"status":"pong"}

Response Codes:

200: Ping successful


Get Version

Description: Gets the Xray version and revision you are running
Security: Requires a valid user
Usage: GET /api/v1/system/version
Produces: application/json

{
    "xray_version":"<version number>",
    "xray_revision":"<revision number>"
}

Sample Usage:

GET /api/v1/system/version
  
{
    "xray_version":"1.4",
    "xray_revision":"b3034"
}

Response Codes:

200: Got version info successfully


Metrics

Description: Get system metrics data.
Since: 3.8
Security: Requires an admin user. Available only for on-prem customers.
Usage
GET api/v1/metrics


# HELP app_disk_used_bytes Used bytes for app home directory disk device
# TYPE app_disk_used_bytes gauge
app_disk_used_bytes 3.47563655168e+11 1594190659312
# HELP app_disk_free_bytes Free bytes for app home directory disk device
# TYPE app_disk_free_bytes gauge
app_disk_free_bytes 1.38795900928e+11 1594190659312
# HELP app_self_metrics_calc_seconds Total time to collect all metrics
# TYPE app_self_metrics_calc_seconds gauge
app_self_metrics_calc_seconds 0.052461418 1594190659312
# HELP app_self_metrics_total Count of collected metrics
# TYPE app_self_metrics_total gauge
app_self_metrics_total 17 1594190659312
# HELP db_connection_pool_in_use_total The number of connections currently in use
# TYPE db_connection_pool_in_use_total gauge
db_connection_pool_in_use_total 0 1594190659312
# HELP db_connection_pool_idle_total The number of idle connections
# TYPE db_connection_pool_idle_total gauge
db_connection_pool_idle_total 5 1594190659312
# HELP go_memstats_heap_in_use_bytes Process go heap bytes in use
# TYPE go_memstats_heap_in_use_bytes gauge
go_memstats_heap_in_use_bytes 5.7597952e+07 1594190659312
# HELP go_memstats_heap_allocated_bytes Process go heap allocated bytes
# TYPE go_memstats_heap_allocated_bytes gauge
go_memstats_heap_allocated_bytes 5.3492992e+07 1594190659312
# HELP go_memstats_heap_idle_bytes Process go heap idle bytes
# TYPE go_memstats_heap_idle_bytes gauge
go_memstats_heap_idle_bytes 7.4129408e+07 1594190659312
# HELP go_memstats_heap_objects_total Process go heap number of objects
# TYPE go_memstats_heap_objects_total gauge
go_memstats_heap_objects_total 426224 1594190659312
# HELP go_memstats_heap_reserved_bytes Process go heap reserved bytes
# TYPE go_memstats_heap_reserved_bytes gauge
go_memstats_heap_reserved_bytes 1.3172736e+08 1594190659312
# HELP go_memstats_gc_cpu_fraction_ratio Process go cpu used by gc. value is between 0 and 1
# TYPE go_memstats_gc_cpu_fraction_ratio gauge
go_memstats_gc_cpu_fraction_ratio 2.103941598027732e-05 1594190659312
# TYPE sys_cpu_ratio gauge
sys_cpu_ratio 0.2537313432835821 1594190659312
# HELP sys_load_1 Host load average in the last minute
sys_load_1 2.91 1594190659312
# HELP sys_load_5 Host load average in the last 5 minutes
sys_load_5 4.22 1594190659312
# HELP sys_load_15 Host load average in the last 15 minutes
sys_load_15 3.9 1594190659312
# HELP sys_memory_used_bytes Host used virtual memory
# TYPE sys_memory_used_bytes gauge
sys_memory_used_bytes 1.0906873856e+10 1594190659312
# HELP sys_memory_free_bytes Host free virtual memory
# TYPE sys_memory_free_bytes gauge
sys_memory_free_bytes 2.051506176e+09 1594190659312 
# HELP jfxr_db_sync_started_before_seconds Seconds that passed since the last Xray DB sync started running
jfxr_db_sync_started_before_seconds 1730.505649843 1612187458132
# HELP jfxr_db_sync_running_total DB sync total running time
jfxr_db_sync_running_total 0 1623046336551
# HELP jfxr_db_sync_ended_analyze_before_seconds Seconds that passed since DB sync completed sending all impact analysis messages
jfxr_db_sync_ended_analyze_before_seconds 140274.549095 1623046336551
# HELP jfxr_db_sync_ended_persist_before_seconds Seconds that passed since completed persisting new updates to the database
jfxr_db_sync_ended_persist_before_seconds 140274.549095 1623046336551
# HELP jfxr_data_artifacts_total{package_type="deb"} Total number of Xray scanned artifacts by package type
jfxr_data_artifacts_total{package_type="deb"} 1 1612187458132
# HELP jfxr_data_components_total{package_type="go"} Total number of Xray scanned components by package type
jfxr_data_components_total{package_type="go"} 1 1612187458132
# HELP jfxr_performance_server_up_time_seconds Seconds that passed since Xray server has started on the particular node
jfxr_performance_server_up_time_seconds 1730.505649843 1612187458132

IGNORE RULES

Get Ignore Rules

Description: Returns all Ignore Rules by specific filters.
Since: 3.11
Security: Requires a valid user with the "Manage Watches" permission.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with the Manage Assets privilege can get a list of Ignore Rules using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: GET /api/v1/ignore_rules
Parameters: 

"vulnerability"/"license"/"policy"/"watch"/"component_name"/"component_version"/

"artifact_name"/"artifact_version"/"build_name"/"build_version"/

"release_bundle_name"/"release_bundle_version"/"docker_layer"

Pagination Parameters:

  • "order_by"
  • "direction"
  • "page_num"
  • "num_of_rows"
  • "expires_before"
  • "expires_after"
  • "project_key"
http://10.70.30.82:8082/xray/api/v1/ignore_rules?artifact_name=artifact&artifact_version=2&artifact_path=/myRepo
{
 "data":
	[
	 {
	  "id": string,
 	  "created": Date,
 	  "author": string,
  	  "notes": string,
      "expires_at": Date,
  	  "ignore_filters": {
  	     "vulnerabilities": [
     	   "Vuln1",
    	   "Vuln2"
     	 ],
     	 "licenses": [
     	 ],
     	 "watches": [
     	   "Watch1",
      	   "Watch2"
      	],
        "components": [
          {name:"docker://redis"},
          {name:"Comp2", version: "2.6"},
          {name:"Comp3", version: "1.03"}
      ]
   }
  ],
 "total_count": 1
}
GET /api/v1/ignore_rules?expires_before=2021-01-03T00:00:00Z
GET /api/v1/ignore_rules?expires_after=2021-01-01T00:00:00Z
GET /api/v1/ignore_rules?expires_after=2021-01-01T00:00:00Z&expires_before=2021-01-03T00:00:00Z
GET api/v1/ignore_rules?artifact_name=artifact&artifact_version=2&artifact_path=/myRepo&project=<project_key>
GET api/v1/ignore_rules?projectKey=<project_key>

Response Codes:

500 - Failed to get ignore rules

401 - Unauthorized

403 - Forbidden


Get Ignore Rule

Description: Returns a single Ignore Rule by its ID.
Since: 3.11
Security: Requires a valid user with the "Manage Watches" permission.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with the Manage Assets privilege can get an Ignore Rule using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: GET /api/v1/ignore_rules/{id}

{
   "id": string,
   "created": Date,
   "author": string,
   "notes": string,
   "expires_at": Date,
   "ignore_filters": {
      "vulnerabilities": [
        "Vuln1",
        "Vuln2"
      ],
      "licenses": [
      ],
      "watches": [
        "Watch1",
        "Watch2"
      ],
      "components": [
        {name:"docker://redis"},
        {name:"Comp2", version: "2.6"},
        {name:"Comp3", version: "1.03"}
      ]
   }
 }
GET /api/v1/ignore_rules/{id}?projectKey=<project_key>
{
   "id": string,
   "created": Date,
   "author": string,
   "notes": string,
   "expires_at": Date,
   "project_key":"myproj",
   "ignore_filters": {
      "vulnerabilities": [
        "Vuln1",
        "Vuln2"
      ],
      "licenses": [
      ],
      "watches": [
        "Watch1",
        "Watch2"
      ],
      "components": [
        {name:"docker://redis"},
        {name:"Comp2", version: "2.6"},
        {name:"Comp3", version: "1.03"}
      ],
      "projects": [
        "myproj"
      ],
   }
 }

Response Codes:

200 - OK

500 - Failed to get ignore rules

401 - Unauthorized

403 - Forbidden


Create Ignore Rule

Description: Create an Ignore Rule.
Since: 3.11
Security: Requires a valid user with the "Manage Watches" permission.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with the Manage Assets privilege can create Ignore Rules using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: POST /api/v1/ignore_rules
Parameters 

“vulnerabilities”/“licenses”/“cves”/“policies”/“watches”/“docker-layers”  - []string 

["Value 1", "Value 2", ...]


“release-bundles”/“builds”/“components” - []{name(string), version(string)} (name - must)

[{"name": test, "version": number},...]


“artifacts” - []{name(string), version(string), path(string)} (name - must)

[{"name": test, "version": number, "path": path},...]

Functionality level

Objective

Scope

Source

Filters

“vulnerabilities”

“licenses”

“cves”

“policies”

“watches”

“builds”

“release-bundles”

“docker-layers” 

“artifacts”

“components”

Ignore filters:


{
    "notes": "ignore any license for any version of alpine for the base layer within all 'myApp' builds",
    "ignore_filters": {
        "licenses":[
            "any"
        ],
        "builds": [
            {
                "name":"myApp"
            }
        ],
        "components": [
            {
                "name":"docker://alpine"
            }
        ],
        "docker-layers": [
            "0503825856099e6adb39c8297af09547f69684b7016b7f3680ed801aa310baaa"
        ]
    }
}
{
    "notes": "ignore 'CVE-2016-2168' when watch is 'tstWatch'",
    "ignore_filters": {
        "cves":[
            "CVE-2016-2168"
        ],
        "watches":[
            "tstWatch"
        ]
    }
}
{
    "notes": "ignore 'CVE-2016-2168' until the expiration date set'",
    "expires_at": "2020-06-29T00:00:00Z",
    "ignore_filters": {
        "cves":[
            "CVE-2016-2168"
        ],
        "watches":[
            "tstWatch"
        ]
    }
}
{
    "notes": "ignore 'XRAY-12345' for component 'rpm://juice' of version '6.0.0",
    "ignore_filters": {
        "vulnerabilities":[
            "XRAY-12345"
        ],
        "components":[
            {
                "name":"rpm://juice",
                "version":"6.0.0"
            }
        ]
    }
}
{
    "notes": "ignore any violation for 'tstRB' release-bundle",
    "ignore_filters": {
        "vulnerabilities":[
            "any"
        ],
        "licenses":[
            "any"
        ],
        "release-bundles":[
            {
                "name":"tstRB"
            }
        ]
    }
}
{
    "notes": "ignore any violation for 'gav://dev' artifact only under repo 'devRepo' when violation sources are any version of 'go://gosu' or 'rpm://juice'",
    "ignore_filters": {
        "vulnerabilities":[
            "any"
        ],
        "licenses":[
            "any"
        ],
        "artifacts":[
            {
                "name":"gav://dev",
                "path":"devRepo/"
            }
        ],
        "components":[
            {
                "name":"go://gosu"
            },
            {
                "name":"rpm://juice"
            }
        ]
    }
}
{
 "notes": string,
 "ignore_filters": {
    "vulnerabilities": [
      "any"
    ],
    "licenses": [
      "any"
    ],
    "artifacts": [
      {name:"docker://redis", version: "any", path: "/testRepo"}
    ]
  }
}

successfully added ignore rule with id: {id}

Projects Filter:

Note: Add project field to Builds filter, a Build without a project is referred to as a Global Build.


{
    "notes": "ignore any license for any version of alpine for the base layer within all 'myApp' builds",
    "ignore_filters": {
        "licenses":[
            "any"
        ],
        "builds": [
            {
                "name":"myApp", "project":"projA"
            }
        ],
        "components": [
            {
                "name":"docker://alpine"
            }
        ],
        "projects": [
            "projA",
            "projB"
        ]
    }
}

Response Codes:

201 - successfully created ignore rule id: {ignore_rule_id}

500 - Failed to create ignore rule

400 - Parsing/validation error

401 - Unauthorized

403 - Forbidden

415 - Unsupported media type


Delete Ignore Rule

Description: Delete an Ignore Rule and restore violations associated with this rule. Since Xray  3.13 the "restore_violations" parameter has been deprecated.
Since: 3.11
Security: Requires a valid user with the "Manage Watches" permission.
Notes: For Xray version 3.21.2 and above with Projects, a Project Admin with the Manage Assets privilege can delete Ignore Rules using this REST API in the scope of a project, by using the additional query parameter projectKey.
Usage: DELETE /api/v1/ignore_rules/{id}

http://10.70.30.82:8082/xray/api/v1/ignore_rules/d6192775-9320-42ec-7a98-4a860f01f02b?restore_violations=true


Response Codes:

204 - No content

500 - Failed to delete ignore rule

404 - Ignore rule not found

401 - Unauthorized

403 - Forbidden



VIOLATIONS

Get Violations

Description: Gets the Xray violations based on a set of search criteria

Security:  Requires the "Manage Watches" role to be set on the User or Group level. 
Usage: POST /api/v1/violations
Consumes: application/json

Sample usage (all of the filter fields are optional): 

POST /api/v1/violations
{
	"filters": {
		"name_contains": "Denial of service attack",
		"violation_type": "Security",
		"watch_name": "watch",
		"min_severity": "Medium",
		"created_from": "2018-06-06T12:22:16+03:00"
	},
	"pagination": {
		"order_by": "updated",
		"limit": 25,
		"offset": 1
	}
}

Sample response: 

{
  "total_violations": 295,
  "violations": [
    {
      "description": "Amazon Digital Services License",
      "severity": "High",
      "type": "License",
      "infected_component": [
        "generic://sha256:72daef35b54f95a97e7da5ae2dd7cccecc71183788656083f35fdf6e0ca5a24f/opkg-4.3.54.jar"
      ],
      "created": "2018-05-29T17:30:49+03:00",
      "watch_name": "watch_license",
      "issue_id": "ADSL",
      "violation_details_url": "localhost:8000/api/v1/violations?watch_id=5b163b41ab1bdddbb2e16492&issue_id=XRAY-60763",
      "impacted_artifacts": [
        "arti1/libs-release-local/jfrog-artifactory-pro-5.9.0.zip"
      ]
    },
    {
      "description": "If a user of Commons-Email (typically an application programmer) passes unvalidated input as the so-called \"Bounce Address\", and that input contains line-breaks, then the email details (recipients, contents, etc.) might be manipulated.",
      "severity": "Low",
      "type": "Security",
      "infected_component": [
        "gav://org.apache.commons:commons-email:1.1"
      ],
      "created": "2018-06-06T12:21:18+03:00",
      "watch_name": "all",
      "issue_id": "XRAY-60829",
      "violation_details_url": "localhost:8000/api/v1/violations?watch_id=5b163b41ab1bdddbb2e16492&issue_id=XRAY-60829",
      "impacted_artifacts": [
        "arti1/libs-release-local/jfrog-artifactory-pro-5.9.0.zip"
      ]
    }
  ]
}

List Ignored Violations 

Description: Returns ignored violations by filters.
Since: 3.11
Security: Requires a valid user with the "Manage Watches" permission.
Usage: POST /api/v1/violations/ignored
Parameters 

“vulnerabilities”/“licenses”/“cves”/“policies”/“watches”/“docker-layers”  - []string

“release-bundles”/“builds”/“components” - []{name(string), version(string)} (name - must)

“artifacts” - []{name(string), version(string), path(string)} (name - must)

Pagination:
"order_by","offset", "limit"

Ignore filters:

Functionality level

Objective

Scope

Source

Filters

“vulnerabilities”

“licenses”

“cves”

“policies”

“watches”

“builds”

“release-bundles”

“docker-layers” 

“artifacts”

“components”

{
  "vulnerabilities":[
    "vuln1",
    "vuln2"
  ],
  "artifacts": [
    { 
      "name": "docker://redis"
    }
  ],
  "docker-layers":[
    "4c5fa3a86e3b1d07979ff011af3b58481e519faa6ee27eb23622a6fe0"
  ]
 }

{
   "data": [
       {
           "violation_id": "1323291645094375424",
           "issue_id": "AGPL-3.0",
           "type": "License",
           "created": "2020-11-02T17:51:28+02:00",
           "watch_name": "w",
           "description": "GNU AFFERO GENERAL PUBLIC LICENSE v3",
           "severity": "High",
           "impacted_artifact": {
               "name":       "generic://sha256:4c5fa3a86e3b1d07979ff011af3b58481e519faa6ee27eb23622a6fe00d89935/jfrog-artifactory-pro-6.0.0.zip",
               "path": "example-repo-local/jfrog-artifactory-pro-6.0.0.zip"
           },
           "matched_policies": [
               {
                   "policy": "pl",
                   "rule": "l",
                   "is_blocking": false
               }
           ],
           "ignore_rule_details": {
               "id": "a11b59c0-a94e-4d99-4135-74dda0e0c354",
               "author": "admin",
               "created": "2020-11-02T17:53:41+02:00",
               "notes": "license"
               "expires_at": "2020-12-29T00:00:00Z",
               "deleted_by": "admin",
               "deleted_at": "2020-12-28T00:00:00Z"
           }
       },
       {
           "violation_id": "1323291688811606016",
           "issue_id": "XRAY-100646",
           "type": "Security",
           "created": "2020-11-02T17:51:38+02:00",
           "watch_name": "w",
           "provider": "JFrog",
           "description": "FasterXML jackson-databind 2.x before 2.9.10.5 mishandles the interaction between serialization gadgets and typing, related to com.sun.org.apache.xalan.internal.lib.sql.JNDIConnectionPool (aka xalan2).",
           "severity": "Medium",
           "properties": [
               {
                   "Cve": "CVE-2020-14062",
                   "Cwe": [
                       "CWE-502"
                   ],
                   "CvssV2": "6.8/CVSS:2.0/AV:N/AC:M/Au:N/C:P/I:P/A:P",
                   "CvssV3": "8.1/CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H"
               }
           ],
           "impacted_artifact": {
               "name": "generic://sha256:4c5fa3a86e3b1d07979ff011af3b58481e519faa6ee27eb23622a6fe00d89935/jfrog-artifactory-pro-6.0.0.zip",
               "path": "example-repo-local/jfrog-artifactory-pro-6.0.0.zip"
           },
           "matched_policies": [
               {
                   "policy": "ps",
                   "rule": "s",
                   "is_blocking": false
               }
           ],
           "ignore_rule_details": {
               "id": "d33d30d1-a775-41f2-6e0d-c2955d496ab1",
               "author": "admin",
               "created": "2020-11-02T17:53:57+02:00",
               "notes": "sec1"
           }
       }
   ],
   "total_count": 2
}


Response Codes:

200 - OK

500 - Failed to get ignored violations

400 - Parsing/validation error

401 - Unauthorized

403 - Forbidden


Restore Ignored Violations

Description: Restores violations that were ignored by an Ignore Rule by ID.
Since: 3.16
Security: Requires a valid user with the "Manage Watches" permission.
Usage: POST /api/v1/violations/restore

{
"ids:" ["id1", "id2"]
}
200:Success



IMPORT & EXPORT

Export Xray Settings

Description: Exports user-defined settings to zip file under the following path: <XRAY_HOME>/backup/config/<SERVICE_ID>_xray_exported_config_<TIMESTAMP>.zip.
Notes: It is mandatory to specify the source Binary management (instance_id) when exporting watches, ignore rules, and indexed resources. This REST API supported from Xray version 2.11.0.
Related Dependencies:
- Exporting watches requires exporting policies.
- Exporting ignored rules requires exporting watches.
API Version: v1
Security: Requires an admin user
Usage: POST configuration/export
Consumes: application/json
Produces : application/json

Sample Usage: 

POST api/v1/configuration/export

{ 
    "policies" : true,
    "watches" : true,
    "ignore_rules" : true,
    "custom_licenses" : true,
    "custom_issues" : true,
    "webhooks" : true,
    "mail_server" : true,
    "proxy_config": true,
    "indexed_resources" : true,
    "instance_id" : <instance_id>
}

Sample Response:

{
 "info": "Successfully exported config to file <SERVICE_ID>_xray_exported_config_<TIMESTAMP>.zip under {XRAY_HOME}/backup/config"

}

Response Codes:

200: Success.
400: Got an invalid request
500: Failed to export config file.


Import Xray Configurations 

Description: Imports user-defined configurations from the exported zip file.
Notes: When importing configuration settings, you must specify the new Artifactory instance that the new Xray instance will work with.
Related Dependencies:

-Importing watches requires importing policies.
-Importing ignored rules requires importing watches.

API Version: v1
Security: Requires an admin user
Usage: POST /configuration/import
Sample Usage: 

POST api/v1/configuration/import
{ 
    "instance_id" : <the new instance id connected to Xray>,
    "src_path" : <directory or zip file path under /backup/config>
}

Sample Response:

{
 "info": "Successfully imported config from path <directory or zip file path under /backup/config>"
}

Response Codes:

200: Success - settings imported.
400: Got an invalid request.
500: Failed to import configuration.

Deprecated REST APIs

The following APIs have been deprecated in Artifactory 7.X. Click the link to view the supported command in Artifactory 6.x.



    

Back to Top