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 |
|
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 |
|
vailable Assets information via API |
|
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
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
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
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}')