Overview
Getting started
Vulcan RESTfull API supports various use cases and enables you to interact with various Vulcan functionality within your application.
How to use Vulcan API
Throughout this document, we will use https://your-domain.vulcancyber.com/api/v1 as the base URL.
A list of available functions, including the parameters needed and results, can be found in the URL:
https://your-domain.vulcancyber.com/#/app/api Generate an API Token in the Vulcan Platform
The first step in any API call is to perform authentication to the platform.
Click on your user name at the top right corner
Go to Account > API Tokens (OAuth2 Authentication)
Name the token, set the expiration date, and click Generate token to generate an OAuth 2 token.
Copy and paste the token into the appropriate location on your end.
You can revoke any of your tokens if needed by clicking Revoke.
Notes:
Keep the token secret, just like any other password.
For security reasons, it isn't possible to view the token after navigating from the authentication tab. If necessary, generate a new token.
Permissions
Most operations in this API require permissions. The calling user must have the required permissions for an operation to use it.
Permissions for users based on roles can be seen RBAC overview.
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 Information via API
Available Vulnerabilities information via API |
|
Available Assets information via API |
|
API methods, including optional/required parameters, can be specified in the request path, query, or body.
Parameters Examples
Path parameters
If a request has path parameters, the documentation shows them with curly brackets.
Example of a request:
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.
Example of the response:
{
"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 body of the request.
Example of a request which enables the user to create a new tag:
POST /tagsThe 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
]
}
}
}Example of the response:
{
"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 = 'your_domain.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}')