API Use Case Code Examples

Code example use cases usig Python

Updated over a week ago

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:

  1. Use case title

  2. Request example: Demonstrates how to utilize the API endpoint.

  3. Response example: Demonstrates the output received from the system.

Working with Vulcan API

Use Cases Code Examples

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

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

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

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

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": [
{}
]
}

Did this answer your question?