Using the latest JFrog products?
JFrog Platform User Guide
JFrog Xray 2.x Documentation
To get the latest version, go to the JFrog Unified Platform
- Created by Adi Atzmony, last modified by Lina Daher on Dec 23, 2020
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.
Base URL
New API Version
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.
V1: http://<xrayhost>:<port>/api/v1
V2: http://<xrayhost>:<port>/api/v2
Authentication
Most REST API calls need to be authenticated using your Xray user and password or through an authentication 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 Xray running on your local system, on port 8000.
You have configured a user in Xray named 'myUser', with password 'myP455w0rd!'.
- You have an authentication token with value 12345
To execute a call using basic authentication you would run:
curl -u myUser:myP455w0rd! -X DELETE http://localhost:8000/api/v2/watches/performance-watch
To execute a call authenticating with a token you would run:
curl X DELETE http://localhost:8000/api/v2/watches/performance-watch?token=12345
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 Type | Identifier | Example |
|---|---|---|
Maven | gav://group:artifact:version | gav://ant:ant:1.6.5 |
Docker | docker://Namespace/name:tag | docker://jfrog/artifactory-oss:latest |
RPM | rpm://dist(optional):arch:name:version | rpm://el6:i386:ImageMagick:6.7.2.7-4 |
Debian | deb://dist(optional):arch:name:version | deb://lucid:i386: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 | pip://package:version | pip://raven:5.13.0 |
| Composer | composer://package:version | composer://nunomaduro/collision:1.1 |
| Golang | go://package:version | go://github.com/ethereum/go-ethereum:1.8.2 |
REST Resources
AUTHENTICATION
Get Token
Description: Generates a temporary token that is valid for 2 hours
Security: Requires a valid user
Usage: POST /auth/token
Consumes: application/json
Sample Usage:
POST /auth/token
{
"name": "my_user",
"password": "my_password"
}
Sample Response:
{
"admin": true,
"email": "admin@mycompany.com",
"token": "12345",
"userName": "admin"
}
Response Codes:
200: Success
401: Bad credentials
500: Failed to marshal response
USER MANAGEMENT
Create User
Description: Creates a new Xray User
Security: Requires an admin user
Usage: POST /users
Consumes: application/json
Sample Usage:
{
"admin": false,
"email": "example_user@mycompany.com",
"name": "example_user",
"password": "example_password"
}
Sample Response:
{
"name": "example_user",
"password": "",
"email": "example_user@jfrog.com",
"admin": false,
"blocked": false
}
Response Codes:
200: Success - User created
400: Cannot create user with suffix _xray
409: User with name {name} already exists
415: Failed to parse request
500: Failed to check if user exists in the database
500: Failed to marshal response
Update User
Description: Updates an Xray User.
Security: Requires an admin user
Usage: PUT /users/{id}
Consumes: application/json
Sample Usage:
{
"password": "new_password",
"email": "example_user@jfrog.com",
"admin": false,
}
Response Codes:
200: Success - User updated
400: Failed to update a new user
400: Mail format is not valid
404: Failed to find user
415: Failed to parse request
Get Users
Description: Gets a list of all users in the system or a specific user
Security: Requires an admin user
Usage: GET /users
Produces: application/json
Sample Response:
[
{
"name": "admin",
"password": "",
"email": "admin@mycompany.com",
"admin": true,
"blocked": false
},
{
"name": "example_user",
"password": "",
"email": "example_user@jfrog.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
Security: Requires an admin user
Usage: GET /users/{id}
Produces: application/json
Sample Response:
{
"name": "example_user",
"password": "",
"email": "example_user@jfrog.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}
Delete User
Description: Deletes a user
Security: Requires an admin user
Usage: DELETE /users/{id}
Response Codes:
200: Success - user was deleted
403: User cannot delete itself {id}
404: Failed to retrieve user {id}
500: User "admin" cannot be deleted
ISSUES
Create Issue Event
Description: Allows adding a custom issue
Security: Requires a valid user with "Manage Components" permission
Usage: POST /events
Consumes: application/json
Sample Usage:
{
"type": "Security",
"provider": "Custom",
"package_type": "maven",
"severity": "High",
"components": [
{
"id": "aero:aero",
"vulnerable_versions": [
"[0.2.3]"
]
}
],
"cves": [
{
"cve": "CVE-2017-1000386", "cvss_v2" : "2.4"
}
],
"summary": "custom issue",
"description": "new custom issue",
"id": "Custom-787",
"sources": [
{
"source_id": "CVE-2017-1000386"
}
]
}
Update Issue Event
Description: Allows an issue vendor to update an issue event
Security: Requires a valid user with "Manage Components" permission
Usage: PUT /events/{id}
Consumes: application/json
Sample Usage:
{
"type": "Security",
"provider": "Custom",
"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",
"id": "Custom-787",
"sources": [
{
"source_id": "CVE-2017-1000386"
}
]
}
Get Issue Events
Description: Gets an issue created by a vendor
Security: Requires a valid user with "View Components" permission
Usage: GET /events/{id}
Produces: application/json
Sample Response:
{
"provider": "Custom",
"type": "security",
"source_id": "my_source_id",
"url": "my_source_id",
"created": (ISO8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"modified": (ISO8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"updated": (ISO8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZ),
"description": "This is a sample description",
"summary": "This is a sample summary",
"severity": "Low",
"components": [
{
"component_id": "deb://debian:stretch:lsb:9.20161125"
}
],
"properties": {
"cve": "CVE-001",
"cvss_v2": "3",
"cvss_v3": ""
}
}
WATCHES - v1 (DEPRECATED)
Create Watch - v1
DEPRECATED. From Xray version 2.4, please refer to Create Watch.
Description: Creates a new Watch
Security: Requires a valid user with "Manage Watches" permission
Usage: POST /watches
Consumes: application/json
Sample Usage - Watch a Repository:
{
"name": "watch_name",
"description": "This is an example watch",
"active": true,
"art_id": "artifactory_id",
"target_type": "repository",
"target_name": "repo-local",
"filters": [
{
"type": "regex",
"value": ".*"
},
{
"type": "package-type",
"value": "Docker"
},
{
"type": "mime-type",
"value": "application/deb"
},
{
"type": "property",
"value": {
"key": "prop_key",
"value": "prop_value"
}
}
]
}
Sample Usage - Watch a Build:
{
"name": "watch_name",
"description": "This is an example watch",
"active": true,
"art_id": "artifactory_id",
"target_type": "build",
"target_name": "build-name",
"filters": [
{
"type": "regex",
"value": ".*"
},
{
"type": "package-type",
"value": "Docker"
},
{
"type": "mime-type",
"value": "application/deb"
},
{
"type": "property",
"value": {
"key": "prop_key",
"value": "prop_value"
}
}
]
}
Response Codes:
200: Success - Watch created
415: Failed to parse request
400: Watch is not valid. Check mandatory fields
400: Binary manager doesn't exist
409: Watch with name {name} already exists
Update Watch - v1
DEPRECATED. From Xray version 2.4, please refer to Update Watch.
Description: Updates a Watch.
Security: valid user with "Manage Watches" permission
Usage: PUT /watches/{name}
Consumes: application/json
Sample Usage:
{
"name": "watch_name",
"description": "This is an example watch",
"active": true,
"art_id": "artifactory_id",
"target_type": "build",
"target_name": "build-name",
"filters": [
{
"type": "regex",
"value": ".*"
},
{
"type": "package-type",
"value": "Docker"
},
{
"type": "mime-type",
"value": "application/deb"
},
{
"type": "property",
"value": {
"key": "prop_key",
"value": "prop_value"
}
}
]
}
Response Codes:
200: Success. Watch was successfully updated
403: System watch is not editable for non-admin users
404: Failed to update watch. Watch was not found
415: Failed to parse watch
400: Failed to update watch
500: Failed to update watch
Get Watches - v1
DEPRECATED. From Xray version 2.4, please refer to Get Watches.
Description: Gets a list of all watches in the system or a named watch
Security: Requires a valid user with "View Watches" permission
Usage: GET /watches
Produces: application/json
Sample Response:
{
"id": "5b798cda5eaa3e77b3748449",
"name": "watch_name",
"description": "This is an example watch",
"active": true,
"art_id": "artifactory-id",
"target_type": "repository",
"target_name": "docker-local",
"filters": [
{
"type": "regex",
"value": ".*"
},
{
"type": "package-type",
"value": "Docker"
},
{
"type": "mime-type",
"value": "application/docker"
},
{
"type": "property",
"value": {
"key": "prop_key",
"value": "prop_value"
}
},
{
"type": "issue-severity",
"value": "Unknown"
}
]
}
Response Codes:
200: Success
500: Failed to get watches
Get Watch - v1
DEPRECATED. From Xray version 2.4, please refer to Get Watch.
Description: Gets a named watch
Security: Requires a valid user with "View Watches" permission
Usage: GET /watches/{name}
Produces: application/json
Sample Response:
[
{
"id": "5b798cda5eaa3e77b3748449",
"name": "watch_name",
"description": "This is an example watch",
"active": true,
"art_id": "artifactory-id",
"target_type": "repository",
"target_name": "docker-local",
"filters": [
{
"type": "regex",
"value": ".*"
},
{
"type": "package-type",
"value": "Docker"
},
{
"type": "mime-type",
"value": "application/docker"
},
{
"type": "property",
"value": {
"key": "prop_key",
"value": "prop_value"
}
},
{
"type": "issue-severity",
"value": "Unknown"
}
]
}
]
Response Codes:
200: Success
500: Failed to get watches
Delete Watch - v1
DEPRECATED. From Xray version 2.4, please refer to Delete Watch.
Description: Deletes a watch
Security: Requires a valid user with "Manage Watches" permission
Usage: DELETE /watches/{name}
Response Codes:
200: Success - watch(es) deleted
400: Failed to delete watches
WATCHES
Xray REST API v2
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 a valid user with "Manage Watches" permission
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"
}
]
}
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"
}
]
}
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"
}
]
}
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 a valid user with "Manage Watches" permission
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"
}
]
}
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 a valid user with "View Watches" permission
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"
}
]
}
]
Response Codes:
200: Success - Watches retrieved
500: Failed to get Watch
Get Watch
Description: Gets a named watch
API Version: v2
Security: Requires a valid user with "View Watches" permission
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"
}
]
}
Delete Watch
Description: Deletes a Watch
API Version: v2
Security: Requires a valid user with "Manage Watches" permissions
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.
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
API Version: v1
Security: Requires a valid user with "View Watches" permission.
Usage: GET /violations/ignored/ {watch_name}
Produces: application/json
Sample Response:
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
}
}
]
POLICIES
Create Policy
Description: Creates a new policy.
Security: Requires a user with Manage Policies permissions
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
}
}
]
}
Response Codes:
200: 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 a user with Manage Policies permissions
Usage: PUT /policies/{name}
Consumes: application/json
{
"name": "licensesPolicy",
"type": "license",
"description": "some description 2",
"rules": [
{
"name": "LicenseRule",
"priority": 1,
"criteria": {
"allowed_licenses": [
"0BSD",
"AAL"
],
"allow_unknown": true
}
}
]
}
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 a user with Manage Policies permissions
Usage: DELETE /policies/{name}
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 a user with "View Watches" permission
Usage: Get /policies | Get /policies/ {name}
Produces: application/json
[
{
"name": "some security policy",
"description": "some security policy description",
"type": "security",
"rules": [
{
"priority": 1,
"name": "Medium and above",
"criteria": {"min_severity":"Medium"},
"actions": {
"mails":["mail1@example.com","mail2@example.com"],
"fail_build":"true",
"block_download": {
"unscanned": true,
"active": true
}
}
},
{
"priority": 2,
"name": "All vulnerabilities",
"criteria": { "min_severity": "all severities"},
"actions": {
"webhooks": ["someWebhook1","someWebhook2"],
},
}
]
},
{
"name": "some license policy",
"description": "some license policy description",
"type": "license",
"rules": [
{
"priority": 1,
"name": "very dangerous",
"criteria": {"banned_licenses":["GPL-1, GPL-2, GPL-3, AGPL, LGPL"]},
"actions": {
"custom_severity""High",
"fail_build":true
},
},
{
"priority": 2,
"name": "semi dangerous",
"criteria": [{type: "banned_licenses", value: "EUPL, IPL, MPL"}],
"actions": {
"custom_severity": "Medium",
"mails": [
"mail1@gmail.com",
"mail2@gmail.com"
]
},
}
]
}
]
Assign Policies
Description: Assign a policy to watches
Security: Requires a valid user with "Manage Watches" permission
Usage: POST /api/v1/policies/{name}/assign
Consumes: application/json
Produces: application/json
{
"watches": ["<watch_name>", "<watch_name>"]
}
Response Codes:
200: Success - Policy assigned
400: Unsuccessful
SCANNING
Scan Artifact
Description: Invokes scanning of an artifact
Security: Requires a valid user with "Manage Components" permission
Usage: POST /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 an admin user
Usage: POST /scanBuild
Consumes: application/json
Produces: wild card
{
"artifactoryId": "artifactory-id",
"buildName": "build-name",
"buildNumber": "8"
}
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
BINARY MANAGERS
Add Binary Manager
Description: Configures a new connection to an Artifactory instance
Security: Requires an admin user
Usage: POST /binMgr
Consumes: application/json
Sample Usage:
{
"user": "admin",
"password": "password",
"binMgrUrl": "http://docker.artifactory/artifactory",
"binMgrId": "artifactory-xray",
"binMgrDesc": "This is Artifactory testing instance another",
"proxy_enabled": true
}
Response Codes:
200: Artifactory instance has been successfully added
400: Failed to create new instance of Artifactory, id is missing
400: Artifactory url cannot contain localhost
401: Bad Credentials
409: Artifactory already exists
409: Artifactory with Id {id} or url {url} already exists
415: Failed to parse request
415: Artifactory id must not contain /
500: Failed to obtain a response
500: Failed to set Artifactory Xray support information
500: Failed to upload Xray compatibility plugin
500: Incompatible version: {version}. This Xray version only supports integration with Artifactory {supportVersion} and above.
500: Failed to check Artifactory configuration
500: Artifactory instances older than version 4.11 must the Enterprise with a valid license
500: Failed to add Artifactory instance to database
500: Failed to create Xray configuration for Artifactory
500: Failed to validate Artifactory license
Get Binary Managers
Description: Gets the details of all connected Artifactory instances
Security: Requires a valid user
Usage: GET /binMgr
Sample usage:
[
{
"binMgrId": "artifactory-xray-US",
"binMgrDesc": "This is the US Artifactory instance",
"binMgrUrl": "http://docker.artifactory.us/artifactory",
"proxy_enabled": true
},
{
"binMgrId": "artifactory-xray-EU",
"binMgrDesc": "This is the EU Artifactory instance",
"binMgrUrl": "http://docker.artifactory.eu/artifactory",
"proxy_enabled": true
}
]
Response codes:
200: List of Artifactory instances
401: Bad Credentials
500: Failed to obtain response
Update Binary Manager
Description: Updates the details of a connected Artifactory instance
Security: Requires an admin user
Usage: PUT /binMgr/{id}
Consumes: application/json
{
"binMgrDesc": "",
"binMgrId": "",
"binMgrUrl": "",
"password": "",
"proxy_enabled": <true | false>,
"user": ""
}
Sample usage:
PUT /binMgr/Art2
{
"binMgrDesc": "For QA use",
"binMgrId": "Art2",
"binMgrUrl": "http://localhost:8081/artifactory",
"password": "password",
"proxy_enabled": false,
"user": "admin"
}
Response Codes:
200: BinMgr has been successfully updated
400: Path parameter is missing
400: Artifactory URL cannot contain localhost
401: Bad Credentials
500: Failed to obtain response
Get Binary Manager
Description: Gets the details of the specified connected Artifactory instance
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
Delete Binary Manager
Description: Deletes an Artifactory instance configuration
Security: Requires an admin user
Usage: POST /binMgr/delete
Consumes: application/json
{
"binMgrDesc": "",
"binMgrId": "",
"binMgrUrl": "",
"password": "",
"proxy_enabled": <true | false>,
"user": ""
}
Sample usage:
POST /binMgr/{id}
{
"binMgrDesc": "For QA",
"binMgrId": "arti2",
"binMgrUrl": "http://localhost:8081/artifactory",
"password": "password",
"proxy_enabled": true,
"user": "admin"
}
Response Codes:
200: BinMgr has been successfully updated
400: Path parameter is missing
400: Artifactory URL cannot contain localhost
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
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:
GET /api/v1/binMgr/${binMgrId}/repos
{
indexed_repos: [
{
"name": "some-repo1",
"type": "some-type",
"pkg_type": "some-pkgType"
},
{
"name": "some-repo2",
"type": "some-type",
"pkg_type": "some-pkgType"
}
],
non_indexed_repos: [
{
"name": "some-repo1",
"type": "some-type",
"pkg_type": "some-pkgType"
},
{
"name": "some-repo2",
"type": "some-type",
"pkg_type": "some-pkgType"
}
]
}
Get Builds Indexing Configuration
Description: Gets the indexed and not indexed builds in a given binary manger
Security: Requires an admin user
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:
GET /api/v1/binMgr/${binMgrId}/builds
{
"bin_mgr_id":"ArtifactoryID",
"indexed_builds":[
"some-build1",
"some-build2",
"some-build3"
],
"non_indexed_builds":[
"some-build4",
"some-build5",
"some-build6"
]
}
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: 2.16.0
Security: Requires a user with admin permissions
Usage: POST api/v1/binMgr/{binMgrId}/builds
Consumes: application/json
Produces: application/json
Sample Usage:
POST api/v1/binMgr/artId/builds
Sample Request:
{
"names": ["build1","build2","build1","build4","build4"]
}
Response Codes:
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
Usage: PUT /api/v1/binMgr/{id}/repos
Consumes: application/json
Response codes:
200: Success
Sample usage:
PUT /api/v1/binMgr/${binMgrId}/repos
{
indexed_repos: [
{
"name": "some-repo1",
"type": "some-type",
"pkg_type": "some-pkgType"
},
{
"name": "some-repo2",
"type": "some-type",
"pkg_type": "some-pkgType"
}
],
non_indexed_repos: [
{
"name": "some-repo1",
"type": "some-type",
"pkg_type": "some-pkgType"
},
{
"name": "some-repo2",
"type": "some-type",
"pkg_type": "some-pkgType"
}
]
}
Update Builds Indexing Configuration
Description: Updates the indexed and not indexed builds in a given binary manger
Security: Requires an admin user
Usage: PUT /api/v1/binMgr/{id}/builds
Consumes: application/json
Response codes:
200: Success
Sample usage:
PUT /api/v1/binMgr/${binMgrId}/builds
{
"bin_mgr_id":"ArtifactoryID",
"indexed_builds":[
"some-build1",
"some-build2",
"some-build3"
],
"non_indexed_builds":[
"some-build4",
"some-build5",
"some-build6"
]
}
Force Reindex
Description: Reindexes existing artifacts for missing components.
Notes: The following rules and guidelines apply when running the Reindex REST API Command.
- 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
1000for a single API call and is set as the default value. This value can be changed by setting themaxEntitiesToReindexparameter in the Xray configuration file located at${XRAY_DATA}/config/xray_config.yaml.There is no limit for the aggregated entities in multiple calls of the same API.
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 "View Component" permission
Usage: GET /component/{name}
Produces: application/json
Sample usage:
GET /component/Jinja2
{
"component": "Jinja2",
"package_type": "pip",
"name": "Jinja2",
"description": "A small but fast and easy to use stand-alone template engine written in pure python.",
"website_url": "http://jinja.pocoo.org/",
"downloads": 35536045,
"created": "2008-06-09T16:50:19Z",
"modified": "2016-12-30T06:03:21.705Z",
"sources": [
{
"name": "pypi",
"url": "https://pypi.python.org",
"updated": "2016-12-30T06:03:21.678Z"
}
],
"versions": [
{
"version": "2.8.1",
"released": "2016-12-29T13:16:20Z",
"licenses": [
"BSD"
],
"files": [
{
"name": "Jinja2-2.8.1-py2.py3-none-any.whl",
"sha256": "3997cf273f1424207c60d5895264f74483fce72702f15a7cd51a8551d43663ca",
"sha1": "805e865181e6bce2f2f6f74f7b54bd913fc54b27",
"md5": "7472b9df828747c2d44eb539558bbf7a"
},
{
"name": "Jinja2-2.8.1.tar.gz",
"sha256": "35341f3a97b46327b3ef1eb624aadea87a535b8f50863036e085e7c426ac5891",
"sha1": "6baee2df662bf193bb3669c2c5b475da6083e2aa",
"md5": "150a8f1c180272753cf46dd3cdd6decf"
}
]
}
]
}
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 whether directly or through one of its dependencies
Security: Requires a valid user with "View Component" permission
Usage: POST api/v1/component/searchByCves
Consumes: application/json
{
"cves": ["CVE ID",...]
}
Produces: application/json
[
{
"cve_details": "CVE ID",
"components": [
{
"name": "<Component name>",
"package_type": "<Package type>",
"version": "<Component version>",
"link": "<Link to component details page in Xray>"
}
]
}
]
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
Get Component List Per Watch
Description: Gets a list of components associated with a specific watch.
API Version: v2
Security: Requires an Admin
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"
}
]
Find CVEs by Component
Description: Search for CVEs by the infected components
Security: Requires a valid user with "View Component" permission
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 Artifact Dependency Graph
Description: Get the complete dependency graph for an artifact
Security: Requires a valid user with "View Components" permission
Usage: POST /dependencyGraph/artifact
Consumes: application/json
{
"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 "View Components" permission
Usage: POST /dependencyGraph/artifactDelta
Consumes: application/json
{
"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 "View Components" 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 "View Components" permission
Usage: POST /dependencyGraph/buildDelta
Consumes: application/json
{
"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 Components" permission
Usage: POST component/exportDetails
Consumes: application/json
Sample Request:
{
"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
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
LICENSE REPORTS
Generate License Report
Description: Generates licensed report
Security: Requires a valid user with "Generate Reports" permission
Usage: GET /licensesReport/generate
Produces: application/json
Sample usage:
{
"info": "License report was regenerated"
}
Response Codes:
200: License report was regenerated
500: Failed to regenerate license report
Get License Report
Description: Gets a report describing the distribution and compliance status of licenses in all indexed components
Security: Requires a valid user with "Generate Reports" permission
Usage: GET /licensesReport
Produces: application/json
Sample usage:
GET /licensesReport
{
"distribution": {
"Apache-2.0": 24,
"MIT": 10,
"Other": 1,
"Unknown": 333
},
"compliance": {
"banned": 25,
"unknown": 333,
"valid": 10
},
"lastUpdate": "2017-01-01T12:20:49.024397147Z"
}
Response Codes:
200: Successfully obtained license report
Get License Report Components
Description: Get license report. either `license` or `compliance` query parameter are required together with num_of_rows, order_by and page_num.
Security: Requires a valid user with "Generate Reports" permission
Usage: GET /licensesReport/components?[license=<license(BSD, GPL etc.)> | compliance=<unknown | valid | banned>]&num_of_rows=<rows>&order_by=<id | licenses>&page_num=<page to view>
Produces: application/json
Sample Usage - Compliance:
GET /licensesReport/components?compliance=valid&num_of_rows=20&order_by=id&page_num=1
{
"data": [
[...]
{
"component_id": "deb://debian:stretch:adduser:3.115",
"component_name": "debian:stretch:adduser",
"pkg_type": "Debian",
"is_root": false,
"licenses": [
"GPL-2.0"
]
},
[...]
],
"total_count": 1234
}
Sample Usage - License Type:
GET /licensesReport/components?license=GPL&num_of_rows=20&order_by=id&page_num=1
{
"data": [
[...]
{
"component_id": "deb://debian:stretch:debianutils:4.8.1.1",
"component_name": "debian:stretch:debianutils",
"pkg_type": "Debian",
"is_root": false
},
[...]
],
"total_count": 1234
}
Response Codes:
200: Successfully obtained license report components
400: Failed to get report components - check pagination query parameters.
500: Failed to obtain report components
SECURITY
Enable TLS Certificate for RabbitMQ
Description: Adds the TLS Certificate on RabbitMQ
Since: 2.8
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
}
SECURITY REPORTS
Generate Security Report
Description: Generates security report
Security: Requires a valid user with "Generate Reports" permission
Usage: GET /securityReport/generate
Produces: application/json
{
"info": "security report was regenerated"
}
Response Codes:
200: Security report was regenerated
500: Failed to regenerate security report
Get Security Report
Description: Get the security report
Security: Requires a valid user with "Generate Reports" permission
Usage: GET /securityReport
Produces: application/json
Sample Response:
{
"recent_vulnerabilities": {
"2018-12-09": 0,
"2018-12-16": 0,
"2018-12-23": 0,
"2018-12-30": 0,
"2019-01-06": 70
},
"recent_components": {
"2018-12-09": 0,
"2018-12-16": 0,
"2018-12-23": 0,
"2018-12-30": 0,
"2019-01-06": 53
},
"top_vulnerabilities": [
{
"summary": "RHSA-2006:0156: ethereal security update (Moderate)",
"total_affected_artifacts": 1
},
{
"summary": "RHSA-2006:0420: ethereal security update (Moderate)",
"total_affected_artifacts": 1
},
{
"summary": "RHSA-2005:809: ethereal security update (Moderate)",
"total_affected_artifacts": 1
},
{
"summary": "RHSA-2005:809: ethereal security update (Moderate)",
"total_affected_artifacts": 1
},
{
"summary": "Possible XML Injection",
"total_affected_artifacts": 2
}
],
"top_artifacts": [
{
"component_id": "generic://sha256:f43a9889ebfe59c2df9e0c60f08dbff2359072706d74c0df686bf/C1.zip",
"name": "C1.zip",
"version": "",
"package_type": "Generic",
"vulnerabilities_count": 53
},
{
"component_id": "gav://com.opensymphony:xwork:2.0.4",
"name": "com.opensymphony:xwork",
"version": "2.0.4",
"package_type": "Maven",
"vulnerabilities_count": 7
},
{
"component_id": "npm://abab:1.0.4",
"name": "abab",
"version": "1.0.4",
"package_type": "Npm",
"vulnerabilities_count": 6
},
{
"component_id": "rpm://ethereal:0.10.12.1mdk",
"name": "ethereal",
"version": "0.10.12.1mdk",
"package_type": "Rpm",
"vulnerabilities_count": 4
}
],
"lastUpdate": "2019-01-06T18:41:09.898+02:00"
}
Get Top Vulnerabilities Security Report
Description: Get the top vulnerabilities security report.
Security: Requires a valid user with "Generate Reports" permission.
Usage: GET /securityReport/topVulnerabilities.
Produces: application/json.
Sample Response:
[
{
"summary": "RHSA-2006:0156: ethereal security update (Moderate)",
"description": "Ethereal is a program for monitoring network traffic.Two denial of service bugs were found in Ethereal's IRC and GTP protocoldissectors. Ethereal could crash or stop
responding if it reads a malformedIRC or GTP packet off the network.",
"severity": "Low",
"created": "2016-12-27T13:18:41.868+02:00",
"cves": [
{
"cve": "CVE-2005-3313",
"cvss_v2": "5.0/CVSS:2.0/AV:N/AC:L/Au:N/C:N/I:N/A:P"
},
{
"cve": "CVE-2005-3651",
"cvss_v2": "7.5/CVSS:2.0/AV:N/AC:L/Au:N/C:P/I:P/A:P"
},
{
"cve": "CVE-2005-4585",
"cvss_v2": "7.8/CVSS:2.0/AV:N/AC:L/Au:N/C:N/I:N/A:C"
}
],
"affected_components": [
{
"id": "rpm://ethereal:0.10.12.1mdk",
"name": "ethereal",
"version": "0.10.12.1mdk",
"package_type": "Rpm"
}
]
},
GRAFEAS
Grafeas is an open source API that enables comprehensive auditing and governance for your software supply chain. The API uses a unified metadata exchange format that creates a uniform and consistent way to produce and consume metadata from software components. Having a standardized API for working with metadata is great because it simplifies your workflow by promoting automation.
By fully supporting the Grafeas API, Xray allows you to combine the publicly available metadata and your private metadata together to get a complete picture.
Grafeas defines two key entities:
- Notes: An item or condition that can be found via an analysis or is used multiple times in a process. For example, a CVE could be the result of a vulnerability analysis of a Linux package. In a build process, we would store information about our builder in a note. In Xray, notes represent security vulnerabilities but in the future additional note types will be supported.
Occurrences: Can be thought of as an instantiation of a note and describes how the note was found in a specific cloud resource or project (e.g., location, specific remediation steps, etc.), or what the results of a specific note were (e.g., the container images that resulted from a build). In Xray, occurrences represent concrete component issues.
Usage
The Xray Grafeas API uses the following syntax:
- Project: In Xray, the
project_idhas no significant meaning as the project scope does not exist. You can use any keyword, as we have used 'xray' in our examples. - Note: Each note is represented by a unique note ID. This ID is required when querying notes as displayed in the following example:
/projects/<project_id>/notes/<note_id>. - Occurrence: There are two ways to query occurrences either by a specific note or by a component (filter query).
The first option is to retrieve all occurrences for a specific note using the following syntax:/projects/<project_id>/notes/<note_id>/occurrences.
Another option is to retrieve all occurrences for a specific component using the following syntax:/projects/<project_id>/occurrences?filter=<url encoded component ID>.
Authentication
The Grafeas REST API authentication uses an access token as a bearer token in an authorization header (Authorization: Bearer) with your access token.
Get Note
Description: Gets a note using the note ID.
Security: Requires a valid user with “View Components” permission.
Usage: GET /api/v1/projects/<project_id>/notes/<note_id>
Consumes: application/json
Sample Usage:
GET /api/v1/projects/xrayScanner/notes/XRAY-G3
{
"shortDescription": "RHSA-2016:1776: java-1.6.0-openjdk security update (Important)",
"longDescription": "The java-1.6.0-openjdk packages provide the OpenJDK 6 Java Runtime Environment and the OpenJDK 6 Java Software...",
"kind": "PACKAGE_VULNERABILITY",
"attestationAuthority": {
"hint": {}
},
"vulnerabilityType": {
"severity": "Medium",
"details": [
{
"package": "7:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
}
]
},
"buildType": {
"signature": {}
},
"baseImage": {
"fingerprint": {}
},
"package": {},
"deployable": {},
"discovery": {},
"relatedUrl": [
{
"url": "https://rhn.redhat.com/errata/RHSA-2016-1776.html"
}
],
"createTime": "2016-11-27T09:14:08+02:00",
"updateTime": "2016-11-27T09:14:08+02:00"
}
400: Notes associated with project_id do not exist.
Update Note
Description: Updates a note.
Security: Requires a valid user with “Manage Components” permission.
Usage: PUT /api/v1/projects/<project_id>/notes/<note_id>
Produces: application/json
Sample Usage:
PUT /api/v1/projects/xrayScanner/notes/XRAY-G3
{
"name": "XRAY-G3",
"shortDescription": "UPDATED - RHSA-2016:1776: java-1.6.0-openjdk security update (Important)",
"longDescription": "The java-1.6.0-openjdk packages provide the OpenJDK 6 Java Runtime Environment and the OpenJDK 6 Java Software Development
Kit.Security Fix(es):* An insufficient bytecode verification flaw was discovered in the Hotspot component in OpenJDK. An untrusted
Java application or applet could use this flaw to completely bypass Java sandbox restrictions. (CVE-2016-3606)* Multiple denial of
service flaws were found in the JAXP component in OpenJDK. A specially crafted XML file could cause a Java application using JAXP
to consume an excessive amount of CPU and memory when parsed. (CVE-2016-3500, CVE-2016-3508)* Multiple flaws were found in the
CORBA and Hotsport components in OpenJDK. An untrusted Java application or applet could use these flaws to bypass certain Java
sandbox restrictions. (CVE-2016-3458, CVE-2016-3550) - update",
"kind": "PACKAGE_VULNERABILITY",
"attestationAuthority": {
"hint": {}
},
"vulnerabilityType": {
"severity": "Medium",
"details": [
{
"package": "7:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "6:java-1.6.0-openjdk-src",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.6.el6_8",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "7:java-1.6.0-openjdk-demo",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "High",
"fixedLocation": {
"version": {}
}
},
{
"package": "5:java-1.6.0-openjdk-src",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.4.el5_11",
"kind": "MAXIMUM"
},
"severityName": "High",
"fixedLocation": {
"version": {}
}
},
{
"package": "5:java-1.6.0-openjdk-demo",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.4.el5_11",
"kind": "MAXIMUM"
},
"severityName": "High",
"fixedLocation": {
"version": {}
}
},
{
"package": "6:java-1.6.0-openjdk-javadoc",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.6.el6_8",
"kind": "MAXIMUM"
},
"severityName": "High",
"fixedLocation": {
"version": {}
}
},
{
"package": "7:java-1.6.0-openjdk-javadoc",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "5:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.4.el5_11",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "6:java-1.6.0-openjdk",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.6.el6_8",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "6:java-1.6.0-openjdk-demo",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.6.el6_8",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "7:java-1.6.0-openjdk",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "5:java-1.6.0-openjdk-javadoc",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.4.el5_11",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "7:java-1.6.0-openjdk-src",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "6:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.6.el6_8",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
},
{
"package": "5:java-1.6.0-openjdk",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.4.el5_11",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
}
]
},
"buildType": {
"signature": {}
},
"baseImage": {
"fingerprint": {}
},
"package": {},
"deployable": {},
"discovery": {},
"relatedUrl": [
{
"url": "https://rhn.redhat.com/errata/RHSA-2016-1776.html"
},
{
"url": "https://access.redhat.com/security/cve/CVE-2016-3458"
},
{
"url": "https://access.redhat.com/security/cve/CVE-2016-3500"
},
{
"url": "https://access.redhat.com/security/cve/CVE-2016-3508"
},
{
"url": "https://access.redhat.com/security/cve/CVE-2016-3550"
},
{
"url": "https://access.redhat.com/security/cve/CVE-2016-3606"
}
],
"createTime": "2016-11-27T09:14:08+02:00",
"updateTime": "2016-11-27T09:14:08+02:00"
}
Response code:
400: Failed to update note.
Create Note
Description: Creates a new note.
Security: Requires a valid user with “Manage Components” permission.
Usage: POST /api/v1/projects/project_id>/notes/<note_id>
Consumes: application/json
Response: 201
Sample Usage:
POST /api/v1/projects/xrayScanner/notes
{
"shortDescription": "RHSA-2016:1776: java-1.6.0-openjdk security update (Important)",
"longDescription": "The java-1.6.0-openjdk packages provide the OpenJDK 6 Java Runtime Environment and the OpenJDK 6 Java Software...",
"kind": "PACKAGE_VULNERABILITY",
"attestationAuthority": {
"hint": {}
},
"vulnerabilityType": {
"severity": "Medium",
"details": [
{
"package": "7:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
}
]
},
"buildType": {
"signature": {}
},
"baseImage": {
"fingerprint": {}
},
"package": {},
"deployable": {},
"discovery": {},
"relatedUrl": [
{
"url": "https://rhn.redhat.com/errata/RHSA-2016-1776.html"
}
],
"createTime": "2016-11-27T09:14:08+02:00",
"updateTime": "2016-11-27T09:14:08+02:00"
}
Delete Note
Description: Deletes a note.
Security: Requires a valid user with “Manage Components” permission.
Usage: DELETE /api/v1/projects/<project_id>/notes/<note_id>
Produces: application/json
Sample Usage:
DELETE /api/v1/projects/xrayScanner/notes/XRAY-G2
Response Code:
200: Note was deleted.
400: Failed to delete notes with project_id.
Get Occurrences by Note ID
Description: Gets all occurrences based on a Note ID.
Security: Requires a valid user with “View Components” permission.
Usage: GET /api/v1/projects/<project_id>/notes/<note_id>/occurrences
Consumes: application/json
Sample Usage:
GET /api/v1/v1alpha1/projects/xrayScanner/notes/XRAY-G3
{
"shortDescription": "RHSA-2016:1776: java-1.6.0-openjdk security update (Important)",
"longDescription": "The java-1.6.0-openjdk packages provide the OpenJDK 6 Java Runtime Environment and the OpenJDK 6 Java Software...",
"kind": "PACKAGE_VULNERABILITY",
"attestationAuthority": {
"hint": {}
},
"vulnerabilityType": {
"severity": "Medium",
"details": [
{
"package": "7:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
}
]
},
"buildType": {
"signature": {}
},
"baseImage": {
"fingerprint": {}
},
"package": {},
"deployable": {},
"discovery": {},
"relatedUrl": [
{
"url": "https://rhn.redhat.com/errata/RHSA-2016-1776.html"
}
],
"createTime": "2016-11-27T09:14:08+02:00",
"updateTime": "2016-11-27T09:14:08+02:00"
Get Occurrences by Component ID
Description: Gets all occurrences based on a URL encoded component ID.
Security: Requires a valid user with “View Components” permission.
Usage: GET /api/v1/projects/<project_id>/occurrences?filter=<url encoded component id>
Consumes: application/json
Sample Usage:
GET /api/v1/v1alpha1/projects/xrayScanner/occurrences?filter=aHR0cDovL2tva286ODA4MC9jb21tb25zOmNvbW1vbnM6NC42OUAxMjM%3D
{
"shortDescription": "RHSA-2016:1776: java-1.6.0-openjdk security update (Important)",
"longDescription": "The java-1.6.0-openjdk packages provide the OpenJDK 6 Java Runtime Environment and the OpenJDK 6 Java Software...",
"kind": "PACKAGE_VULNERABILITY",
"attestationAuthority": {
"hint": {}
},
"vulnerabilityType": {
"severity": "Medium",
"details": [
{
"package": "7:java-1.6.0-openjdk-devel",
"minAffectedVersion": {
"kind": "MINIMUM"
},
"maxAffectedVersion": {
"name": " 1:1.6.0.40-1.13.12.5.el7_2",
"kind": "MAXIMUM"
},
"severityName": "Medium",
"fixedLocation": {
"version": {}
}
}
]
},
"buildType": {
"signature": {}
},
"baseImage": {
"fingerprint": {}
},
"package": {},
"deployable": {},
"discovery": {},
"relatedUrl": [
{
"url": "https://rhn.redhat.com/errata/RHSA-2016-1776.html"
}
],
"createTime": "2016-11-27T09:14:08+02:00",
"updateTime": "2016-11-27T09:14:08+02:00"
}
Response Code:
400: Failed to get notes for project_ID.
SUMMARY
Build Summary
Description: Provides details about any build specified by build identifier (name + number)
Security: Requires a valid user with "View Components" 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 "View Components" permission.
Usage: POST /summary/artifact
Consumes: application/json
{
"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
Create Bundle
Description: Create support bundle
Security: Requires an admin user
Usage: POST /system/support/bundle
Consume: application/json
Produce: application/json
Sample Usage:
Request + Payload
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
}
}
}
Response
{
"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"
}
}
Response codes:
201: Support bundle Created successfully
401: Bad Credentials
400: status bad request
500: Failed to create support bundle
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 /system/ping
Produces: application/json
Sample usage:
GET /system/ping
{"status":"pong"}
Response Codes:
200: Ping successful
External Ping Request
Description: Sends a ping request to external sources (Global Database, Bintray, etc.)
Security: Requires a valid user
Usage: GET /system/external/ping
Response Codes:
200: Ping successful to external source
404: Page not found
Get Version
Description: Gets the Xray version and revision you are running
Security: Requires a valid user
Usage: GET /system/version
Produces: application/json
{
"xray_version":"<version number>",
"xray_revision":"<revision number>"
}
Sample Usage:
GET /system/version
{
"xray_version":"1.4",
"xray_revision":"b3034"
}
Response Codes:
200: Got version info successfully
VIOLATIONS
Get Violations
Description: Gets the Xray violations based on a set of search criteria
Security: Requires a "View Watches" permission
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",
"arti1/generic-local/jfrog-artifactory-pro-5.9.0.zip",
"arti1/libs-release-local/jfrog-artifactory-check-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",
"arti1/generic-local/jfrog-artifactory-pro-5.9.0.zip",
"arti1/libs-release-local/jfrog-artifactory-check-pro-5.9.0.zip"
]
}
]
}
PERMISSIONS
Get Permissions
Description: Gets a list of all permissions in the system
Security: Requires an admin user
Usage: GET /api/v1/permissions
Sample response:
[
{
"name": "Admins"
"uri" : "http://<server>:<port>/api/v1/security/permissions/Admins"
}, {
"name": "Developers"
"uri" : "http://<server>:<port>/api/v1/security/permissions/Developers"
}
]
Get Permission Details
Description: Gets the details of a specific permission
Security: Requires an admin user
Usage: GET /api/v1/permissions/{id}
Sample response (permission on specific resources):
{
"name": "MyProject",
"scope" : "resources",
"resources" : [
{
artifactory_id: "art1",
type: "build",
name: "my-build",
},
{
artifactory_id: "art2",
type: "local",
name: "my-repo",
},
{
artifactory_id: "art2",
type: "remote",
name: "my-other-repo",
}
],
"users" :[
{
"name":"bob",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component",
"admin",
"view_reports"
]
},
{
"name":"alice"
"roles":[
"view_watch",
"view_component"
]
}
],
"groups" :[
{
"name":"dev-leads",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component"
]
},
{
"name":"readers",
"roles":[
"View_watch",
"View_component"
]
}
]
}
Sample response (permission on all resources):
{
"name": "GlobalPermission",
"scope" : "global",
"resources" : [],
"users" : [
{
"name":"bob",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component",
"admin",
"view_reports"
]
},
{
"name":"alice",
"roles" : [
"view_watch",
"view_component"
]
}
],
"groups" : [
{
"name":"dev-leads",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component"
]
},
{
"name":readers",
"roles":[
"view_watch",
"View_component"
]
}
]
}
Create Permission
Description: Creates a new permission
Security: Requires an admin user
Usage: POST /api/v1/permissions
Consumes: application/json
{
"name": "permission name",
"scope" : <"resources" | "global">,
"resources" : [
{
"artifactory_id": "artifactory id",
"type": <"local" | "remote" | "build">,
"name": "name of repository or build"
}
],
"users" :[
{
"name":"user name",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component",
"manage_policies", // available for "global" scope only
"admin", // available for "global" scope only
"view_reports" // available for "global" scope only
]
}
],
"groups" :[
{
"name":"group name",
"roles":[
"view_watch",
"manage_watch",
"view_component",
"manage_component",
"manage_policies", // available for "global" scope only
"admin", // available for "global" scope only
"view_reports" // available for "global" scope only
]
}
]
}
Response Codes:
201: Permission added successfully
415: "Failed to parse request"
400: "Got invalid permission name"
400: "Got invalid permission resource type"
400: "Failed to validate permissions roles"
500: "Failed to create permissions"
Delete Permission
Description: Deletes a permission
Security: Requires an admin user
Usage: DELETE /api/v1/permissions/{id}
Sample Usage:
DELETE /api/v1/permissions/some-permission
Response Code:
200: Permission deleted successfully
400: Failed to delete permission with provided id.
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.
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"
}
200: Success.Response Codes:
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.
Page Contents
Overview
Content Tools
JFrog.com | Documentation | Featured | Have a question? Want to report an issue? Contact JFrog support