Working with Vulcan API

Learn about using Vulcan RESTfull API

Updated over a week ago

About Vulcan API

The Vulcan Cyber Platform provides a comprehensive set of APIs that allow developers to integrate with and extend the capabilities of the Vulcan Cyber Platform.

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 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}.

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 Platform UI under Setting > Role-Based Access Control.

Working with Vulcan 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 API Swagger

To access the Vulcan API Page and documentation on each call, Go to Settings > Vulcan API.

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

The calls are divided into groups to make it easier to track down the calls you would like to invoke. 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

vailable 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 API at: API Paths and Endpoints

API Use Case Code Examples


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}')

Did this answer your question?