In this article you will find:

  1. Overview
  2. How to get started
  3. Authentication
  4. Permissions
  5. Vulcan API Swagger
    • Example of a request with path parameter
    • Example of a request with body parameter
  6. Python example of API usage

Overview

This guide documents about Vulcan RESTfull API. It supports a wide variety of 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  

API Token

The first step in any API call is to perform authentication to the platform.

OAuth2 Authentication:

  1. Generate an API token:
    • You can do it from your Vulcan account -
    Go to the Account screen (press on your avatar icon in the upper right corner) and navigate to the API token:

Name the token

Choose an expiration date (1 year from creation by default)

Click “Generate token” to generate an OAuth 2 token.

Copy and paste the token in the appropriate location on your end.

Note - you can revoke any of your tokens if needed by clicking on the "Revoke" button

• You can do it using Session Authentication -

Create a POST call to the URL:

https://your-domain.vulcancyber.com/api/authentication/login/

With the request body:

{"username": your_user_name , "password": your_password}

and save the output to a cookie.

Use it in the authentication/token/ call:

curl --location --request POST

'https://your-domain.vulcancyber.com/api/authentication/token/' \

--header 'Content-Type: application/json' \

--header 'Content-Type: text/plain' \

--header 'Cookie: sessionid=your_sessionid';

csrftoken=your_csrftoken' \

--data-raw '{"expiration_date":"2021-05-25"}'

You might need to add also --"header 'X-csrftoken: your_csrftoken'

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

For every request, add an authorization with the value :

'Bearer your_token_here'

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 Page

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

  • Assets
  • Dashboard
  • Reports
  • Solutions
  • Tags
  • Vulcan report connector
  • Vulnerabilities

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

You can find the relevant documentation for each supported call in the Vulcan API page. For example:

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 the request body.

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?