About Vulcan Cyber ExposureOS API v1

The Vulcan Cyber ExposureOS platform provides a comprehensive set of APIs, allowing developers to integrate and extend the platform's capabilities.

For API v2, see here.

Scope

This article details the available APIs, their endpoints, request/response formats, authentication mechanisms, and a selection of use case examples.

Version information	Version : v1
Base URL	`https://api.vulcancyber.com/v1`
URI scheme	Host : {tenant}.vulcancyber.com BasePath : /api/v1 Schemes : HTTPS
Consumes	application/json
Produces	application/json
Security	Basic
Default API call limit	Limit per Minute: 60 calls Limit per Hour: 1000 calls Limit per Day: 10,000 calls Note: The API call limit is configurable. To configure the API call limit, contact your Customer Success Manager at Vulcan.

Access and Permissions

Authentication and Role-Base Access Control

For authentication, generate an API Token in the Vulcan Cyber ExposureOS platform. All API requests require authentication using an API token. To authenticate, include an Authorization header in the request with the value Bearer {API_TOKEN}.

You can obtain an API token from the Vulcan Cyber ExposureOS Platform administration.

Endpoint Permission

Most operations in this API require permissions. The calling user must have the required permissions for an operation to use it. Each endpoint has corresponding permissions that match it. For example, an endpoint that gets assets will work only if the user requesting (i.e., the user that created the user/pass or token) has access to assets, as indicated in their role. Permissions for users based on roles can be set and managed through the Vulcan Cyber ExposureOS platform UI under Settings > Roles.

Working with Vulcan Cyber ExposureOS API

Base URL

Throughout this document, we will use the following URL as the base URL:

https://{tenant}.vulcancyber.com/api/v1

A list of available functions, including the parameters needed and results, can be found in the URL:

https://{tenant}.vulcancyber.com/#/app/api

Vulcan Cyber ExposureOS API Swagger

To access the Vulcan Cyber ExposureOS API v1 page and documentation on each call, Go to Help & Support > Vulcan API v1.

Click the drop-down next to each call for more info.

The calls are divided into groups to make tracking down the calls you would like to invoke easier. The groups are:

Assets
Authentications
Campaigns
Checkmarks Connectors
Packages Clusters
SLA Policy
Solutions
Tags
Vulcan Report Connector
Vulnerability Tags
Vulnerabilities

Available Asset and Vulnerability Information

Available Vulnerabilities information via API	Risk level Vulnerability source OS version Threats CVEs CVSSS score Discovery time SLA status Tags Vulnerability status Business groups
Available Assets information via API	OS OS version Coverage status Risk level IP Cloud instance ID Source Tags Business Groups

API methods, including optional/required parameters, can be specified in the request path, query, or body.

API Paths and Endpoints

Learn about the various paths that can be used to access cloud security information and vulnerability data through the Vulcan Cyber ExposureOS API v1 at API Paths and Endpoints.

API Use Case Code Examples

Review this walk-through code examples of requested Use Cases using Python.

Parameter Examples

Path Parameters

If a request has path parameters, the documentation shows them with curly brackets.

Request Example

GET /assets/hosts/{host_id}/

The {host_id} path parameter should be replaced with the relevant host ID in this example. The brackets should not be included.

Required Parameter: host_id (string), let's say it's 12345.

Response Example

{
    "id": 12345,
    "vulnerabilities": [
        {
            "vuln_id": 1000,
            "asset_id": 12345,
            "title": "TLS Version 1.0 Protocol Detection",
            "cvss_score": 6.1,
            "status": "vulnerable",
            "qualitative_score": "MEDIUM",
            "source": [
                "tenable"
            ],
            "priority": [
                "3"
            ],
            "rank_score": 59
        },
    ],
    "connectors": {
        "tenable": {
            "id": 1363740,
            "found_in_last_scan": true,
            "tracking_method": "IP",
            "last_seen": "2020-05-21T10:39:58.533000Z",
            "first_seen": "2019-03-28T11:42:59.672000Z",
            "state": "running",
            "uuid": "1111111-2222-3333-4444-555555555555",
            "hostname": [],
            "fqdn": [
                "example.vulcancyber.com"
            ],
            "ip": [
                "12.345.67.890"
            ],
            "os": [
                "Linux Kernel 2.4",
                "Linux Kernel 2.6",
                "Linux Kernel 2.2"
            ],
            "groups": [],
            "tags": [
                "example_tag: 123"
            ],
            "agent_uuid": null,
            "server": 5,
            "snowflake_server": null
        }
    },
    "connectors_meta": [
        "tenable"
    ],
    "styled_os": "Linux",
    "host_type": "host",
    "priority": 3,
    "vulcan_host_tags": [
        {
            "id": 1,
            "name": "External Facing",
            "biz_group": true,
            "tag_type": "external_facing"
        },
        {
            "id": 2,
            "name": "Tenable",
            "biz_group": true,
            "tag_type": "vulcan_tag"
        },
    ],
    "status": "active",
    "active": true,
    "vulns_count": 2,
    "severity": "medium",
    "technical_complexity": 0,
    "native_objects": {},
    "asset_id": "tenable|1111111-2222-3333-4444-555555555555",
    "hostname": "35.161.64.203",
    "fqdn": "example.vulcancyber.com",
    "ip": "35.161.64.203",
    "os": "Linux",
    "os_version": "",
    "platform_family": "Linux",
    "created": "2020-04-30T00:06:00.126403Z",
    "scanned_by_scanner": true,
    "last_seen": "2020-05-21T10:39:58.533000Z",
    "first_seen": "2019-03-28T11:42:59.672000Z",
    "state": "running",
    "native_fields": [
        "fqdn",
        "ip",
        "os",
        "platform_family"
    ],
    "qualys_host": null,
    "tenable_host": 1234567,
    "rapid7_host": null,
    "chef_host": null,
    "servicenow_host": null,
    "aws_host": null,
    "gcp_host": null,
    "paloalto_host": null,
    "intsights_host": null,
    "opswat_host": null,
    "azure_host": null,
    "sccm_host": null,
    "intune_host": null,
    "ivanti_host": null,
    "vulcanreport_host": null
}

Body Parameters

If an endpoint has body parameters, the documentation shows them in the body of the request.

Request Example

Example of a request which enables the user to create a new tag:

POST /tags

The body:

{
  "biz_group": true,
  "name": "New_API_tag",
  "severity_score": 0,
  "tag_query": {
    "freeInput": [
      "Prod"
    ],
    "subnet": [
      "127.12.12.32/1"
    ],
    "Tags": [
      "External Facing"
    ],
    "saved_search_id": [
      4
    ],
    "Specific Assets": {
      "hosts": [
        535332
      ],
      "code_projects": [
        0
      ],
      "websites": [
        0
      ],
      "repositories": [
        0
      ]
    }
  }
}

Response Example

{
    "id": 26045307,
    "name": "New_API_tag",
    "biz_group": true,
    "tag_type": "vulcan_tag",
    "tag_query": {
        "freeInput": [
            "Prod"
        ],
        "subnet": [
            "127.12.12.32/1"
        ],
        "Tags": [
            "External Facing"
        ],
        "saved_search_id": [
            4
        ],
        "Specific Assets": {
            "hosts": [
                535332
            ],
            "code_projects": [
                0
            ],
            "websites": [
                0
            ],
            "repositories": [
                0
            ]
        }
    },
    "severity_score": 0,
    "native_impact_name": null,
    "native_severity_score": 0,
    "saved_search": null
}

Python Example of API Usage

import requests
import json
## CONFIG ###
login_url = '{tenant}.vulcancyber.com'
token = 'TOKEN_GENERATED_IN_VULCAN'
client.headers = {'Content-Type': 'application/json', 'Authorization': f'Bearer {token}'}
### get the list of vulnerabilities
r = client.get(f'https://{login_url}/api/v1/vulnerabilities/risk?connector_type=qualys')
print(r.text)
vulnerabilities = json.loads(r.text)
def calculate_severities_sum(vulnerabilities):
    qualys_severity_sum, vulcan_severity_sum = 0, 0
    for vulnerability in vulnerabilities:
        qualys_severity_sum += vulnerability['qualys_risk']
        vulcan_severity_sum += vulnerability['vulcan_risk']
    return qualys_severity_sum, vulcan_severity_sum
qualys_severity_sum, vulcan_severity_sum = calculate_severities_sum(vulnerabilities)
print (f'The qualys severity sum is: {qualys_severity_sum}, the vulcan severity sum is: {vulcan_severity_sum}')