Uptycs APIs to get the list of vulnerabilities for a Host, CVE or Package

Uptycs APIs to get the list of vulnerabilities for a Host, CVE or Package


This document outlines the APIs required to retrieve the vulnerability data for a given host / CVE / package.

Sample python scripts attached to this document (vulnerabilities_api_sample.zip):  The attached package contains a list of sample python scripts to call the Uptycs APIs to get vulnerabilities for host, CVE or package.
The python scripts demonstrates how to use the APIs, please refer README file for the prerequisites and commands to run these scripts.

About the python files in this package:

1) utils.py: This is the common library file used by host_vulners.py, cve_vulners.py, package_vulners_cves.py, package_vulners_hosts.py.
2) host_vulners.py: Sample script to use "VLN_DETAILS_SPECIFIC_HOST" API to get the list of vulnerabilities for a given hostname
3) cve_vulners.py: Sample script to use "VLN_SUMMARY_HOSTS" API to get the list of vulnerabilities for a given CVE
4) package_vulners_cves.py: Sample script to use "VLN_PACKAGE_VULNERABILITY_DETAILS" API to get the CVE list for a given package name and package version
5) package_vulners_hosts.py: Sample script to use "VLN_PACKAGE_ASSET_DETAILS" API to get the asset list for a given package name and package version

To run these samples, download the api key file from Uptycs web UI for a user, rename the file to apikey.json and keep it in the same directory where the python scripts are.

Generating API Key + Customer ID: (apikey.json)

  1. Go to your environment’s page, click configuration
  2. In that page, click Users
  3. Find your User and click Edit
  4. Under Use API Key, hit create. Save these values as these will not be visible again
  5. To get the .json file hit download on this window. The file will contain the API key, API secret and Customer ID.
  6. Rename the downloaded filename to apikey.json and move it to the same directory where the python scripts are.


Uptycs APIs to get vulnerabilities for a given Host:

1) Get AssetID for a given Hostname:

All the Vulnerabilities APIs that take host filter requires AssetID, hence, we need to call the following API to get the AssetID from Hostname.
domain: your domain. (ex. tvz.uptycs.io, domain would be tvz)
hostName: your host. (ex. jenkins-master)
customerId: Is in the apikey.json file

#API:
https://{{domain}}.uptycs.dev/public/api/customers/{{customerId}}/assets?filters={"hostName":{"equals": "jenkins-master"}}

#Method:
GET

#Payload:
Query string parameter
filters={"hostName":{"equals": "jenkins-master"}}

Sample Output:


{
    "items": [
        {
            "hostName": "jenkins-master",
            "id": "b532244b-2f5e-4350-81b6-4f05483f6395",
            "os": "Alpine Linux",
            "osFlavor": "debian",
            "osqueryVersion": "5.7.0.23-Uptycs",
            "osVersion": " v3.17",
            "status": "active",
            "live": true
         }
      ]
}


(Note: API returns a lot many attributes, showing only limited in above list for clarity).

The items json array would contain zero rows if host is not found, one entry if host is found. So read output['items'][0]['id'] to get the assetId to be used in subsequent and relevant API calls.

2) Using the AssetID to get the list of vulnerabilities:

  1. Step1: This API is asynchronous, once submitted it returns a “QueryJobId” indicating that query is submitted to the cloud. Then keeps calling “QueryJob” API (Step2) periodically (say every second) to figure out the status of the Job. When the status of the job is finished, it calls the “QueryJobResults” API (Step3) to fetch the results, the list of vulnerabilities in a host.
API:
https://{{domain}}.uptycs.io/public/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details

Method:
POST

Payload:
{
  "name": ""VLN_DETAILS_SPECIFIC_HOST"",
  "assetId": "b532244b-2f5e-4350-81b6-4f05483f6395"
}
API Response:


{
    "id": "abc96dd7-893a-4594-a12c-6e0c374571a0",
    "name": "78353296ca08c120a5369eef28233a96",
    "status": "QUEUED",
    "links": [
        {
            "rel": "self",
            "title": "Query job information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details/abc96dd7-893a-4594-a12c-6e0c374571a0"
        },
        {
            "rel": "parent",
            "title": "Query jobs information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details"
        }
    ],
    "startTime": null,
    "endTime": null,
    "error": null
}


  1. Step2: QueryJob API, to get the status of the above asynchronous API
API:
https://{{domain}}.uptycs.io/public/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details?queryJobId=abc96dd7-893a-4594-a12c-6e0c374571a0

Method:
GET

Payload:
Query String Parameters
queryJobId:  abc96dd7-893a-4594-a12c-6e0c374571a0

QueryJobId GET API response:


{
  "items":[],
  "links":[
  { "rel":"self",
    "title":"Query job results information",
    "href":"/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details"},
    {
      "rel":"parent",
      "title":"Query job information",
      "href":"/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities"}
      ],"status":"RUNNING",
      "id":"abc96dd7-893a-4594-a12c-6e0c374571a0",
      "error":null,
      "endTime":null,
      "startTime":"2023-03-15T09:26:18.468Z",
      "rowCount":null,
      "offset":0,
      "limit":50000
}


  1. Step3: QueryJobResults API, to get the results from QueryJobId that is in finished state
API:
https://{{domain}}.uptycs.io/public/api/customers/{{customerId}}/queryjobs/abc96dd7-893a-4594-a12c-6e0c374571a0/results

Method:
GET

Payload:
Query String Parameters
queryJobId:  abc96dd7-893a-4594-a12c-6e0c374571a0

Sample output for host vulnerability details:


{
    "items": [
        {
            "createdAt": "2023-03-15",
            "rowDataHash": "3ac0e533-78ed-351d-8e72-2588dc2b3cca",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "severity": "critical",
                "affectedPackageCount": 7,
                "fixAvailable": true,
                "advisoryAttackVector": null,
                "isCustomVulnerability": false,
                "os": "Ubuntu",
                "affectedPackages": "[\"linux-headers-4.15.0-142\",\"linux-modules-4.15.0-142-generic\",\"linux-headers-4.15.0-142-generic\",\"linux-modules-extra-4.15.0-142-generic\",\"linux-headers-4.15.0-140-generic\",\"linux-headers-4.15.0-140\",\"linux-libc-dev\"]",
                "references": "",
                "os_version": "16.04",
                "indicator_type": "Uptycs",
                "package_type": "deb",
                "fixVersion": "4.4.0-236.270",
                "maxCvssScore": "10.0",
                "cve_list": "CVE-2022-3643",
                "indicator_version": "4.4.0-236.270",
                "package_version": "4.4.0-210.242",
                "exploitTitle": "",
                "system_type": "host",
                "indicator_operator": "lt",
                "nvdAttackVector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
                "package_name": "linux-modules-extra-4.15.0-142-generic",
                "package_arch": "amd64",
                "exploitAvailable": false,
                "uptycs_score": "10.0"
            },
            "rowNumber": 1,
            "queryJobId": "abc96dd7-893a-4594-a12c-6e0c374571a0"
        }
      ],
    "name": "a40277a2359df0bd9acecf61d95d07ad",
    "endTime": "2023-03-15T09:41:12.596Z",
    "startTime": "2023-03-15T09:41:10.120Z",
    "error": null,
    "rowCount": 2559,
    "resultStore": "cache",
    "offset": null,
    "limit": null
}


Uptycs APIs to get the list of hosts affected by a given CVE:

1) Using the CVE to get the list of hosts affected:

  1. Step1: This API is asynchronous, once submitted it returns a “QueryJobId” indicating that query is submitted to the cloud. Then keeps calling “QueryJob” API (Step2) periodically (say every second) to figure out the status of the Job. When the status of the job is finished, it calls the “QueryJobResults” API (Step3) to fetch the results, the list of hosts affected by a given CVE.

#API:
https://{{domain}}.uptycs.dev/public/api/customers/{{customerId}}/vulnerabilities/details

#Method:
POST

#Payload:
{
  "name": "VLN_SUMMARY_HOSTS",
  "cveCode" : "CVE-2020-14343"
}

  1. Follow Step2, “QueryJob” API to get the status of asynchronous API and Step3, “QueryJobResults” API to fetch the results, the list of hosts affected by a given CVE.

Sample output for the list of hosts affected by a given CVE:


{
    "items": [
    {
            "createdAt": "2023-03-10",
            "rowDataHash": "ef5f1f1e-2b94-3a6f-b398-53969f9063bf",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "high": 0,
                "lastSeen": "2023-03-10 13:37:00.0",
                "critical": 2,
                "upt_hostname": "vul-docker-repo",
                "low": 0,
                "firstSeen": "2023-03-10 13:37:00.0",
                "agentless": false,
                "medium": 0,
                "upt_asset_id": "1b146a2a-36f3-45a0-9f8b-75b65b2a4d19",
                "packagesAffected": 1,
                "maxCvss_score": "9.8"
                 },
            "rowNumber": 1,
            "queryJobId": "a6246a03-bcdf-4ada-a2df-4ddc06ed8747"
        }
      ]
}


Uptycs APIs to get the list of CVEs for a given Package_Name and Package_Version:

1) Using the Package_Name and Package_Version to get the list of CVEs:

  1. Step1: This API is asynchronous, once submitted it returns a “QueryJobId” indicating that query is submitted to the cloud. Then keeps calling “QueryJob” API (Step2) periodically (say every second) to figure out the status of the Job. When the status of the job is finished, it calls the “QueryJobResults” API (Step3) to fetch the results, the list of CVEs for a given Package_Name and Package_Version.
#API:
https://{{domain}}.uptycs.dev/public/api/customers/{{customerId}}/vulnerabilities/details

#Method:
POST

#Payload:
{
  "name": "VLN_PACKAGE_VULNERABILITY_DETAILS",
  "packageName": "systemd",
  "packageVersion": "237-3ubuntu10.56"
}

Sample Response for QueryJobId:


{
    "id": "5549f040-0769-484b-9735-3d2fd2fa0387",
    "name": "e778b1b2e8242105a9cdc4178fd8d8eb",
    "status": "RUNNING",
    "links": [
        {
            "rel": "self",
            "title": "Query job information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details/5549f040-0769-484b-9735-3d2fd2fa0387"
        },
        {
            "rel": "parent",
            "title": "Query jobs information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details"
        }
    ],
    "startTime": "2023-03-10T15:16:56.949Z",
    "endTime": null,
    "error": null
}


  1. Follow Step2, “QueryJob” API to get the status of asynchronous API and Step3, “QueryJobResults” API to fetch the results, the list of CVEs for a given Package_Name and Package_Version.

Sample output for the list of CVEs for a given Package_Name and Package_Version:


{
    "items": [
        {
            "createdAt": "2023-03-10",
            "rowDataHash": "9e61f6bf-bd0e-3e87-ae44-976dfe863cd7",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "severity": "medium",
                "cve_list": "CVE-2022-3821",
                "fixAvailable": true,
                "reliable": true,
                "isCustomVulnerability": false,
                "end_of_life": false,
                "advisory_severity": "medium",
                "confidence": true,
                "exploitAvailable": false,
                "uptycs_score": "5.5",
                "maxCvssScore": "5.5"
            },
            "rowNumber": 1,
            "queryJobId": "5549f040-0769-484b-9735-3d2fd2fa0387"
        },
        {
            "createdAt": "2023-03-10",
            "rowDataHash": "5ed1784c-df9b-36ca-a230-1211f3998ad5",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "severity": "unknown",
                "cve_list": "CVE-2023-26604",
                "fixAvailable": false,
                "reliable": true,
                "isCustomVulnerability": false,
                "end_of_life": false,
                "advisory_severity": "medium",
                "confidence": true,
                "exploitAvailable": true,
                "uptycs_score": "6",
                "maxCvssScore": null
            },
            "rowNumber": 2,
            "queryJobId": "5549f040-0769-484b-9735-3d2fd2fa0387"
        }
    ]
}


Uptycs APIs to get the list of hosts affected for a given Package_Name and Package_Version:

1) Using the Package_Name and Package_Version to get the list of hosts affected:

  1. Step1: This API  is asynchronous, once submitted it returns a “QueryJobId” indicating that query is submitted to the cloud. Then keeps calling “QueryJob” API (Step2) periodically (say every second) to figure out the status of the Job. When the status of the job is finished, it calls the “QueryJobResults” API (Step3) to fetch the results, the list of hosts affected for a given Package_Name and Package_Version.

#API:
https://{{domain}}.uptycs.dev/public/api/customers/{{customerId}}/vulnerabilities/details

#Method:
POST

#Payload:
{
  "name": "VLN_PACKAGE_ASSET_DETAILS",
  "packageName": "systemd",
  "packageVersion": "237-3ubuntu10.56"
}

Sample Response with QueryJobId:


{
    "id": "13796585-8dae-4c5a-99f3-f04af6d2bcb6",
    "name": "49fab4442ad00109c5559d8181cbd326",
    "status": "QUEUED",
    "links": [
        {
            "rel": "self",
            "title": "Query job information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details/13796585-8dae-4c5a-99f3-f04af6d2bcb6"
        },
        {
            "rel": "parent",
            "title": "Query jobs information",
            "href": "/api/customers/6dedb183-57df-47bb-aec2-2fc338553d71/vulnerabilities/details"
        }
    ],
    "startTime": null,
    "endTime": null,
    "error": null
}


  1. Follow Step2, “QueryJob” API to get the status of asynchronous API and Step3, “QueryJobResults” API to fetch the results, the list of hosts affected for a given Package_Name and Package_Version.

Sample output for the list of hosts affected for a given Package_Name and Package_Version:


{
    "items": [
        {
            "createdAt": "2023-03-10",
            "rowDataHash": "6d5b7fc5-6e5b-33b3-94b0-93bc14bdec48",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "hostName": "local",
                "package_version": "237-3ubuntu10.56",
                "firstSeen": "2023-03-08 09:09:41.0",
                "agentless": false,
                "package_name": "systemd",
                "upt_asset_id": "3e350c8f-4b04-4ec2-b487-c4c62fc5cf89"
            },
            "rowNumber": 1,
            "queryJobId": "13796585-8dae-4c5a-99f3-f04af6d2bcb6"
        },
        {
            "createdAt": "2023-03-10",
            "rowDataHash": "204f9a3e-d46f-34fe-a995-511123676b20",
            "customerId": "6dedb183-57df-47bb-aec2-2fc338553d71",
            "rowData": {
                "hostName": "jenkins-master",
                "package_version": "237-3ubuntu10.56",
                "firstSeen": "2023-03-08 04:20:25.0",
                "agentless": false,
                "package_name": "systemd",
                "upt_asset_id": "b532244b-2f5e-4350-81b6-4f05483f6395"
            },
            "rowNumber": 2,
            "queryJobId": "13796585-8dae-4c5a-99f3-f04af6d2bcb6"
        }
  ]
}



    • Related Articles

    • API calling via Swagger

      Go To the "Account Settings". Click the "CREATE" button to generate API keys, which will be downloaded in JSON format. The downloaded JSON will contain information such as customerId, API key, API Secret, Domain, DomainSuffix, and other relevant ...

    • How to Retrieve Software Bill of Materials (SBOM) Using the Uptycs API: A Step-by-Step Guide

      To get SBOM(Software Bill of Material) information for your resource through Uptycs API, follow below step → Obtain Access Keys: • Login to the Uptycs console • Go to Account Settings • Create an API Key • Download the API Key in JSON format. For ...

    • Uptycs Alert Triggers API Call

      This python module can be run to trigger Uptycs API calls from Uptycs alerts.  Example: An alert is configured to fire when asset location is not in USA (possible GDPR issue). This python can then be run to automatically make an API call to disable ...

    • Python helper module for Uptycs API

      The attached helper module (uptapi.py) and demo program (uptdemo.py) show how to access Uptycs API from Python 3. 

    • How to configure Query job API in service now

      Steps : Submit query job with POST /queryJobs , get the job id in response Poll query job with GET /queryJobs/{job_id} , if status received is “FINISHED“, go to next step. Get query job results with GET /queryjobs/${job_id}/results. Add A REST ...