Overview


Getting started

Vulcan RESTfull API supports various use cases and enables you to interact with various Vulcan functionality within your application.

API Limit

The limit is defined as follows:

  • 1 call per minute

  • 500 calls per hour

  • 5000 calls per day

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:

  1. Go to Settings > Vulcan API.

  2. 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:

  1. Assets

  2. Authentications

  3. Campaigns

  4. Checkmarks Connectors

  5. Packages Clusters

  6. SLA Policy

  7. Solutions

  8. Tags

  9. Vulcan Report Connector

  10. Vulnerability Tags

  11. Vulnerabilities

Available Information via API

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.

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 ​/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
]
}
}
}

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

Did this answer your question?