About
The purpose of this section is to walk you through code examples of requested Use Cases using Python.
The format of the use case examples in this section is as follows:
Use case title
Request example: Demonstrates how to utilize the API endpoint.
Response example: Demonstrates the output received from the system.
Working with Vulcan API v1
Learn about Working with Vulcan API.
For Vulcan API v2, see here.
Use Cases Code Examples
Assign criticality to business Group tag
Assign criticality to business Group tag
Request Example
fetch("http://your-domain.vulcancyber.com/api/v1/tags/<TAG_ID>/", {
"headers": {
"accept": "application/json, text/plain, */*",
"accept-language": "en-US,en;q=0.9,he;q=0.8",
"biz-group-id": "null", // or the correct biz of the specific role
"content-type": "application/json",
"frontend-source": "true",
"sec-ch-ua-mobile": "?0",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
"timezone-offset": "180",
"x-csrftoken": "<x-csrftoken_value>",
"cookie": "<cookie_value>",
"Referer": "https://yourdomain.vulcancyber.com/",
"Referrer-Policy": "strict-origin-when-cross-origin"
},
"body": "{\"severity_score\": 0}",
"method": "PUT"
});Response Example
200 OK with the following response body:
{
"biz_group": true,
"id": 0,
"tag_join_method": "union",
"name": "string",
"native_impact_name": "string",
"native_severity_score": 0,
"saved_search": 0,
"severity_score": 0,
"tag_query": {},
"tag_type": "string"
}Assign metadata to vulnerabilities and assets
Assign metadata to vulnerabilities and assets
Request Example
import time
import requests
requests.urllib3.disable_warnings()
# Vulcan config
BEARER_TOKEN = "<NEED TO CREATE IN VULCAN>"
CONNECTOR_ID = 1 # Need to update report connector id, can be found in the URL
OUTPUT_FILE_PATH = "C:\\Users\\supam\\Downloads\\output.csv"
# Constant Vulcan config
BASE_URL = f"https://yourdomain.vulcancyber.com"
REPORTS_URL = f"{BASE_URL}/api/v1/vulcanreport/upload_report"
DEFAULT_HEADERS = {"Content-Type": "application/json", "Accept": "application/json",
"Authorization": f"Bearer {BEARER_TOKEN}", }
def main():
print("Uploading file")
_upload_report_to_vulcan()
print("Finished successfully")
def _upload_report_to_vulcan():
with open(OUTPUT_FILE_PATH, 'rb') as f:
files = {'upload_file': f}
response = requests.post(
url=f"{REPORTS_URL}/{CONNECTOR_ID}/", files=files, headers={
"Authorization": f"Bearer {BEARER_TOKEN}"
}, verify=False)
if response.ok:
print(f"Successfully uploaded the csv as vulcan report")
else:
print(
f"""Failed uploading the csv as vulcan report because of "{response.reason}"
with status code {response.status_code}""")
if __name__ == '__main__':
print("Starting tags script")
start_time = time.time()
main()
print(f"Elapsed time: {time.time() - start_time}")
Response Example
202 Accepted – no response body
Assign dynamic tags to vulnerabilities and assets
Assign dynamic tags to vulnerabilities and assets
Request Example
fetch("http://your-domain.vulcancyber.com/api/v1/tags/<TAG_ID>/", {
"headers": {
"accept": "application/json, text/plain, */*",
"accept-language": "en-US,en;q=0.9,he;q=0.8",
"biz-group-id": "null", // or the correct biz of the specific role
"content-type": "application/json",
"frontend-source": "true",
"sec-ch-ua-mobile": "?0",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
"timezone-offset": "180",
"x-csrftoken": "<x-csrftoken_value>",
"cookie": "<cookie_value>",
"Referer": "https://your-domain.vulcancyber.com/",
"Referrer-Policy": "strict-origin-when-cross-origin"
},
"body": "{\"tag_query\": {\"Specific Assets\": {\"hosts\": [0],\"code_projects\": [0],\"websites\": [0],\"repositories\": [0]\n }\n }\n}",
"method": "PUT"
});Response Example
200 OK with the following response body:
{
"biz_group": true,
"id": 0,
"tag_join_method": "union",
"name": "string",
"native_impact_name": "string",
"native_severity_score": 0,
"saved_search": 0,
"severity_score": 0,
"tag_query": {},
"tag_type": "string"
} Verify asset information
Verify asset information
Request Example
fetch("http://your-domain.vulcancyber.com/api/v1/assets/hosts/<ASSET_ID>/", {
"headers": {
"accept": "application/json, text/plain, */*",
"accept-language": "en-US,en;q=0.9,he;q=0.8",
"biz-group-id": "null", // or the correct biz of the specific role
"content-type": "application/json",
"frontend-source": "true",
"sec-ch-ua-mobile": "?0",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
"timezone-offset": "180",
"x-csrftoken": "<x-csrftoken_value>",
"cookie": "<cookie_value>",
"Referer": "https://your-domain.vulcancyber.com/",
"Referrer-Policy": "strict-origin-when-cross-origin"
},
"body": null,
"method": "GET",
"credentials": "include"
});
Note: To find the asset ID, either check the URL while clicking on the asset:
https://your-domain.vulcancyber.com/#/app/assets?type=hosts&id=926
;or call the list of assets via the API:
https://your-domain.vulcancyber.com/api/v1/assets/hosts/
Response Example
200 OK
{
"id": 927,
"priority": 4,
"vulnerabilities": [
{
"vuln_instance_id": 4514,
"vuln_id": 1596,
"asset_id": 927,
"title": "OpenSSH Privilege Escalation Vulnerability",
"cvss_score": 7,
"status": "vulnerable",
"qualitative_score": "HIGH",
"source": [
"qualys" ],
"priority": [
"3" ],
"rank_score": 32,
"vulcan_discovery_time": "2023-05-25T17:28:28.444961Z",
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"threats": [
"Broken Access Control",
"Local",
"OWASP Top 10" ],
"last_update": "2023-05-25T17:28:24.935376Z",
"atomic_risk_breakdown": {
"cvss": {
"score": 70,
"weight": 0.45 },
"tags": {
"score": 0,
"weight": 0.2 },
"custom": {
"score": 0,
"weight": 0 },
"threats": {
"score": 0,
"weight": 0.35 },
"mandiant": {
"score": 0,
"weight": 0 }
},
"manually_set_risk": false,
"orig_atomic_risk": 0,
"risk_edited_by": null,
"risk_edited_on": null,
"risk_edit_comment": null,
"time_to_sla": 138,
"start_check_sla_date": null,
"vuln_tags": {},
"additional_information": "{\"port\": \"\", \"results\": \"Vulnerable SSH-2.0-OpenSSH_7.4 detected on port 22 over TCP.\", \"protocol\": \"\", \"vuln_type\": \"Potential\"}" },
{
"vuln_instance_id": 2670,
"vuln_id": 1701,
"asset_id": 927,
"title": "SSL Certificate - Subject Common Name Does Not Match Server FQDN",
"cvss_score": 0,
"status": "vulnerable",
"qualitative_score": "INFO",
"source": [
"qualys" ],
"priority": [
"5" ],
"rank_score": 0,
"vulcan_discovery_time": "2023-05-25T17:28:27.806493Z",
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"threats": [
"Remote" ],
"last_update": "2023-05-25T17:28:25.088671Z",
"atomic_risk_breakdown": {
"cvss": {
"score": 0,
"weight": 0.7 },
"tags": {
"score": 0,
"weight": 0.3 },
"custom": {
"score": 0,
"weight": 0 },
"threats": {
"score": 0,
"weight": 0 },
"mandiant": {
"score": 0,
"weight": 0 }
},
"manually_set_risk": false,
"orig_atomic_risk": 0,
"risk_edited_by": null,
"risk_edited_on": null,
"risk_edit_comment": null,
"time_to_sla": 0,
"start_check_sla_date": null,
"vuln_tags": {},
"additional_information": "{\"port\": \"6443\", \"results\": \"Certificate 0 CN=kube-apiserver (dcr-dev-master-2) doesn't resolve\\n(dcr-dev-master-1) doesn't resolve\\n(dcr-dev-master-3) doesn't resolve\\n(localhost) doesn't resolve\\n(kubernetes) doesn't resolve\\n(kubernetes.default) doesn't resolve\\n(kubernetes.default.svc) doesn't resolve\\n(kubernetes.default.svc.cluster.local) doesn't resolve\\n(kube-apiserver) doesn't resolve\", \"protocol\": \"tcp\", \"vuln_type\": \"Confirmed\"}" },
{
"vuln_instance_id": 3329,
"vuln_id": 1838,
"asset_id": 927,
"title": "SSL Certificate - Signature Verification Failed Vulnerability",
"cvss_score": 0,
"status": "vulnerable",
"qualitative_score": "INFO",
"source": [
"qualys" ],
"priority": [
"5" ],
"rank_score": 0,
"vulcan_discovery_time": "2023-05-25T17:28:27.987390Z",
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"threats": [
"Remote",
"Unauthenticated" ],
"last_update": "2023-05-25T17:28:25.305090Z",
"atomic_risk_breakdown": {
"cvss": {
"score": 0,
"weight": 0.7 },
"tags": {
"score": 0,
"weight": 0.3 },
"custom": {
"score": 0,
"weight": 0 },
"threats": {
"score": 0,
"weight": 0 },
"mandiant": {
"score": 0,
"weight": 0 }
},
"manually_set_risk": false,
"orig_atomic_risk": 0,
"risk_edited_by": null,
"risk_edited_on": null,
"risk_edit_comment": null,
"time_to_sla": 0,
"start_check_sla_date": null,
"vuln_tags": {},
"additional_information": "{\"port\": \"6443\", \"results\": \"Certificate 0 CN=kube-apiserver unable to get local issuer certificate\", \"protocol\": \"tcp\", \"vuln_type\": \"Confirmed\"}" },
{
"vuln_instance_id": 4285,
"vuln_id": 1934,
"asset_id": 927,
"title": "Deprecated SSH Cryptographic Settings",
"cvss_score": 0,
"status": "vulnerable",
"qualitative_score": "INFO",
"source": [
"qualys" ],
"priority": [
"5" ],
"rank_score": 0,
"vulcan_discovery_time": "2023-05-25T17:28:28.310835Z",
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"threats": [
"Remote",
"Unauthenticated" ],
"last_update": "2023-05-25T17:28:25.480818Z",
"atomic_risk_breakdown": {
"cvss": {
"score": 0,
"weight": 0.7 },
"tags": {
"score": 0,
"weight": 0.3 },
"custom": {
"score": 0,
"weight": 0 },
"threats": {
"score": 0,
"weight": 0 },
"mandiant": {
"score": 0,
"weight": 0 }
},
"manually_set_risk": false,
"orig_atomic_risk": 0,
"risk_edited_by": null,
"risk_edited_on": null,
"risk_edit_comment": null,
"time_to_sla": 0,
"start_check_sla_date": null,
"vuln_tags": {},
"additional_information": "{\"port\": \"22\", \"results\": \"Type\\tName\\nkey exchange\\tdiffie-hellman-group1-sha1\", \"protocol\": \"tcp\", \"vuln_type\": \"Confirmed\"}" },
{
"vuln_instance_id": 3771,
"vuln_id": 2158,
"asset_id": 927,
"title": "SSL Certificate - Invalid Maximum Validity Date Detected",
"cvss_score": 0,
"status": "vulnerable",
"qualitative_score": "INFO",
"source": [
"qualys" ],
"priority": [
"5" ],
"rank_score": 0,
"vulcan_discovery_time": "2023-05-25T17:28:28.146681Z",
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"threats": [
"Remote",
"Unauthenticated" ],
"last_update": "2023-05-25T17:28:25.860997Z",
"atomic_risk_breakdown": {
"cvss": {
"score": 0,
"weight": 0.7 },
"tags": {
"score": 0,
"weight": 0.3 },
"custom": {
"score": 0,
"weight": 0 },
"threats": {
"score": 0,
"weight": 0 },
"mandiant": {
"score": 0,
"weight": 0 }
},
"manually_set_risk": false,
"orig_atomic_risk": 0,
"risk_edited_by": null,
"risk_edited_on": null,
"risk_edit_comment": null,
"time_to_sla": 0,
"start_check_sla_date": null,
"vuln_tags": {},
"additional_information": "{\"port\": \"6443\", \"results\": \"Certificate 0 CN=kube-apiserver is valid for more than 398 days\", \"protocol\": \"tcp\", \"vuln_type\": \"Confirmed\"}" }
],
"merge_history": [],
"detach_history": [],
"connectors": {
"qualys": {
"id": 2699,
"packages": [],
"vulcan_update_timestamp": "2023-06-12T21:14:28.530Z",
"scanned": null,
"native_raw_json": {
"ID": "555444",
"IP": "1.2.3.4",
"OS": "EulerOS / Ubuntu / Fedora / Tiny Core Linux / Linux 3.x / IBM / FortiSOAR",
"TAGS": null,
"TRACKING_METHOD": "IP",
"LAST_VM_SCANNED_DATE": "2023-05-02T21:53:40Z",
"LAST_VULN_SCAN_DATETIME": "2023-05-02T21:53:40Z",
"LAST_VM_SCANNED_DURATION": "1283" },
"vulcan_created_date": "2023-05-25T17:15:26.103Z",
"last_seen": "2023-05-02T21:53:40Z",
"first_seen": null,
"qualys_id": "559599626",
"hostname": "",
"fqdn": [],
"os": "EulerOS / Ubuntu / Fedora / Tiny Core Linux / Linux 3.x / IBM / FortiSOAR",
"ip": "10.100.29.153",
"tags": null,
"account_id": null,
"region": null,
"instance_id": null,
"image_id": null,
"mac_addresses": [],
"software_list_data": {},
"open_ports": [
[
{
"Port": "161",
"protocol": "UDP",
"Description": "SNMP",
"Service Detected": "snmp",
"IANA Assigned Ports/Services": "snmp" }
],
[
{
"Port": "22",
"protocol": "TCP",
"Description": "SSH Remote Login Protocol",
"Service Detected": "ssh ",
"OS On Redirected Port": " ",
"IANA Assigned Ports/Services": "ssh" },
{
"Port": "179",
"protocol": "TCP",
"Description": "Border Gateway Protocol",
"Service Detected": "unknown ",
"OS On Redirected Port": "Amazon Linux 2",
"IANA Assigned Ports/Services": "bgp" },
{
"Port": "6443",
"protocol": "TCP",
"Description": "unknown",
"Service Detected": "http over ssl",
"OS On Redirected Port": null,
"IANA Assigned Ports/Services": "unknown" }
]
],
"qg_host_id": "",
"tracking_method": "IP",
"server": 1,
"native_ips": [
"1.2.3.4" ]
}
},
"connectors_meta": [
"qualys" ],
"styled_os": "EulerOS / Ubuntu / Fedora / Tiny Core Linux / Linux 3.x / IBM / FortiSOAR",
"host_type": "host",
"vulcan_host_tags": [],
"severity": "32",
"sla_policy": {
"id": 1,
"bizgroups": [],
"is_global": true,
"priority_1_sla": 5,
"priority_2_sla": 14,
"priority_3_sla": 90,
"priority_4_sla": 180,
"priority_5_sla": 0,
"position": 1,
"name": "Global SLA Policy" },
"first_seen": "2023-05-02T21:53:40Z",
"last_seen": "2023-05-02T21:53:40Z",
"status": "active",
"active": true,
"risk_mass": 32,
"vulns_count": 5,
"technical_complexity": 0,
"connector_names": [
"Qualys" ],
"vuln_tag_ids": [],
"native_objects": {},
"scanned_by_scanner": true,
"additional_information": {
"qualys": {
"image_id": null,
"qualys_id": "559599626",
"account_id": null,
"qg_host_id": "",
"instance_id": null }
},
"vuln_breaching_sla_count": 0,
"asset_id": "",
"hostname": "10.100.29.153",
"fqdn": "",
"ip": "10.100.29.153",
"os": "EulerOS / Ubuntu / Fedora / Tiny Core Linux / Linux 3.x / IBM / FortiSOAR",
"os_version": "",
"platform_family": "Unknown",
"cloud_instance_id": "",
"ansible_valid_os": false,
"state": "running",
"mac_address": "",
"external_facing": {
"ip": false,
"elb": false,
"security_groups": false },
"ips": [
"10.100.29.153" ],
"mac_addresses": [],
"fqdns": [],
"eol_date": null,
"scan_methods": [],
"native_fields": [],
"generic_asset_scanner_slot": null,
"qualys_host": null,
"tenable_host": null,
"tenablesc_host": null,
"rapid7_host": null,
"chef_host": null,
"crowdstrike_host": null,
"servicenow_host": null,
"aws_host": null,
"aws_securityhub_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,
"vulcanreport_ai_host": null,
"nessusreport_host": null,
"prismacloud_host": null,
"sentinelone_host": null,
"microsofttvm_host": null,
"microsoftdfc_host": null,
"wiz_host": null,
"orca_host": null,
"jamf_host": null,
"tanium_host": null,
"outpost24_host": null,
"generic_host_slot1": null,
"generic_host_slot2": null,
"generic_host_slot3": null,
"generic_host_slot4": null,
"generic_host_slot5": null,
"search_connectors": [
1 ],
"search_connector_names": [
1 ]Verify vulnerability information
Verify vulnerability information
Request Example
fetch("http://your-domain.vulcancyber.com/api/v1/vulnerabilities/details/1/", {
"headers": {
"accept": "application/json, text/plain, */*",
"accept-language": "en-US,en;q=0.9,he;q=0.8",
"biz-group-id": "null", // or the correct biz of the specific role
"content-type": "application/json",
"frontend-source": "true",
"sec-ch-ua-mobile": "?0",
"sec-fetch-dest": "empty",
"sec-fetch-mode": "cors",
"sec-fetch-site": "same-origin",
"timezone-offset": "180",
"x-csrftoken": "<x-csrftoken_value>",
"cookie": "<cookie_value>",
"Referer": "https://your-domain.vulcancyber.com/",
"Referrer-Policy": "strict-origin-when-cross-origin"
},
"body": "{\"omit_assets\": <true/false>}",
"method": "POST",
"credentials": "include"
});Response Example
{
"added_json": {},
"assets": [
{}
],
"assets_count": 0,
"assets_count_by_category": {
"all": 0,
"fixed": 0,
"ignored": 0,
"vulnerable": 0
},
"assets_count_by_os": [
{}
],
"assets_count_by_os_by_category": {
"all": [
{
"os_type": "string",
"count": 0
}
],
"fixed": [
{
"os_type": "string",
"count": 0
}
],
"ignored": [
{
"os_type": "string",
"count": 0
}
],
"vulnerable": [
{
"os_type": "string",
"count": 0
}
]
},
"assets_os_versions": [
"string"
],
"assets_os_versions_by_category": {
"all": [
"string"
],
"fixed": [
"string"
],
"ignored": [
"string"
],
"vulnerable": [
"string"
]
},
"assets_sources": [
"string"
],
"assets_sources_by_category": {
"all": [
"string"
],
"fixed": [
"string"
],
"ignored": [
"string"
],
"vulnerable": [
"string"
]
},
"audit_data": [
{
"audit_type": "string",
"created_date": "string",
"text": "string",
"title": "string",
"id": 0,
"vulcan_host": {}
}
],
"code_projects": [
{}
],
"containers": [
{}
],
"cpes": [
"string"
],
"cves": [
"string"
],
"cvss_score": 0,
"cwe_labels": [
{}
],
"cwes": [
"string"
],
"description": "string",
"first_seen": "string",
"first_seen_by_category": {
"all": "string",
"fixed": "string",
"ignored": "string",
"vulnerable": "string"
},
"fixes": [
{}
],
"host_type": "string",
"hosts_count": 0,
"hosts_count_by_os": {
"os_type": "string",
"count": 0
},
"hosts_count_by_status": {},
"id": 0,
"ignored_status_until": {},
"impact": "string",
"last_seen": "string",
"last_seen_by_category": {
"all": "string",
"fixed": "string",
"ignored": "string",
"vulnerable": "string"
},
"last_update": "string",
"last_update_by_category": {
"all": "string",
"fixed": "string",
"ignored": "string",
"vulnerable": "string"
},
"min_sla": 0,
"modified_date": "string",
"note": {},
"priority": 0,
"published_date": "string",
"rank_score": 0,
"repositories": [
{}
],
"sla_breaching_count": 0,
"sla_breaching_count_by_category": {
"all": 0,
"fixed": 0,
"ignored": 0,
"vulnerable": 0
},
"solutions": [
{}
],
"sources": [
"string"
],
"status": "string",
"status_changed_by_user_action": true,
"status_date": "string",
"status_timestamp": "string",
"tags": [
0
],
"tags_by_category": {
"all": [
0
],
"fixed": [
0
],
"ignored": [
0
],
"vulnerable": [
0
]
},
"tags_count_by_severity_score": [
{
"severity_score": 0,
"count": 0,
"tag_ids": [
0
]
}
],
"threat_data": {},
"threats": {
"exploitablity": [
"string"
],
"attack_vector": [
"string"
]
},
"title": "string",
"total_assets_count_in_system": 0,
"vulcan_discovery_time": "string",
"vuln_packages": [
"string"
],
"vuln_sources": [
"string"
],
"vuln_vendor": [
"string"
],
"vv_id": "string",
"was_read": true,
"websites": [
{}
]
}