Vectra API Integrations

Vectra offers comprehensive API and API tools for developers and security practitioners who wish to integrate the Vectra Cognito platform into their existing workflows.  

Vectra API Tools is set of resources that is designed to save time and repetitive work by providing a python library that simplifies interaction with the Vectra API, scripts that can be run from the command-line, and additional resources that can help with the Vectra API. These API tools were built to be a project to allow not only Vectra, but the Vectra community to contribute to the success of its customers. 

The Vectra STIX/TAXII module works with the STIX and TAXII standards to improve prevention and mitigation of cyber-attacks. STIX states the what of threat intelligence, while TAXII defines how that information is relayed. 

We also offer a CLI module and a collection of some sampleScripts that can be used to interact with the Vectra api from the command line.These scripts can also be used as a reference on how to leverage the VAT library. 

The project is maintained at Github and is free to use under the APACHE 2 license.

Host methods

Get hosts:

This method has a page_size limit of 5000 objects and should be used when response does not exceed this limit. If response exceeds 5000 objects, use get_all_hosts(). Use of parameters is recommended.
‍
vc.get_hosts()All parameters are optional

• active_traffic: host has active traffic (bool)
• c_score: certainty score (int) - will be removed with deprecation of v1 of api
• c_score_gte: certainty score greater than or equal to (int) - will be removed with deprecation of v1 of api
• certainty: certainty score (int)
• certainty_gte: certainty score greater than or equal to (int) - will be removed with deprecation of v1 of api
• fields: comma separated string of fields to be filtered and returned
• has_active_traffic: host has active traffic (bool)
• include_detection_summaries: include detection summary in response (bool)
• is_key_asset: host is key asset (bool)
• is_targeting_key_asset: host is targeting key asset (bool)
• key_asset: host is key asset (bool) - will be removed with deprecation of v1 of api
• last_source: registered ip address of host
• mac_address: registered mac address of host
• name: registered name of host
• ordering: field to use to order response
• page: page number to return (int)
• page_size: number of object to return in response (int)
• state: state of host (active/inactive)
• t_score: threat score (int) - will be removed with deprecation of v1 of api
• t_score_gte: threat score greater than or equal to (int) - will be removed with deprecation of v1 of api
• tags: tags assigned to host
• targets_key_asset: host is targeting key asset (bool)
• threat: threat score (int)
• threat_gte: threat score greater than or equal to (int)

Get all hosts:

This method has a page_size limit of 5000 objects and should be used when response does not exceed this limit. If response exceeds 5000 objects, use get_all_hosts(). Use of parameters is recommended.
‍
host_generator = vc.get_all_hosts()
next(host_generator)
or
‍
for page in host_generator:
    print page
Parameters used with get_detections() can be used and are optional

Get host by id:

vc.get_host_by_id(host_id=1)
Parameters

• host_id: host id - required
• fields: comma separated string of fields to be filtered and returned - optional

Set host as key asset:

vc.set_key_asset(host_id=1)
Parameters

• id: id of host needing to be set - required
• set: set flag to False if unsetting host as key asset (bool)

Get host tags:

vc.get_host_tags(host_id=1)
Parameters

• host_id: id of host to retrieve tags

Set host tags:

vc.set_host_tags(host_id=1, tags=[], append=False)
Parameters

• host_id: id of host to retrieve tags
• tags: list of tags to apply to host
• append: overwrites existing list if set to False, appends to existing tags if set to True. Set to empty list to clear all tags (default: False)

Triage rule methods

Get triage rules:

vc.get_rules()
Parameters

• name: name of triage rule
• rule_id: id of triage rule

Create triage rule:

vc.create_rule(detection_category="reconnaissance",detection_type="port sweep", triage_category="misconfiguration", description="scanner", is_whitelist=False, ip=["192.168.72.58"])
Parameters

• detection_category: detection category to triage [botnet activity, command & control, reconnaissance, lateral movement, exfiltration]
• detection_type: detection type to triage
• triage_category: name that will be used for triaged detection
• description: name of the triage rule
• is_whitelist: set to True if rule is to whitelist; opposed to tracking detections without scores (boolean)
• ip: list of ip addresses to apply to triage rule
• host: list of host ids to apply to triage rule
• sensor_luid: list of sensor luids to triage
• all_hosts: apply triage rule to all hosts (boolean)
• remote1_ip: destination ip addresses to triage
• remote1_dns: destination hostnames to triage
• remote1_port: destination ports to triage

Update triage rule:

vc.update_rule(rule_id=1, append=False)
Parameters

• rule_id: id of rule to update
• name: name of rule to update
• append: set to True if appending to existing list (boolean)
• ip: list of ip addresses to apply to triage rule
• host: list of host ids to apply to triage rule
• sensor_luid: list of sensor luids to triage
• remote1_ip: destination ip addresses to triage
• remote1_dns: destination hostnames to triage
• remote1_port: destination ports to triage

Delete triage rule:

vc.delete_rule(rule_id=1, restore_detections=True)
Paramaters

• rule_id: id of rule to delete
• restore_detections: restore previously triaged detections (bool)

Threat feed methods

Create threat feed:

vc.create_feed(name='sample', category='exfil', certainty='Medium', itype='Exfiltration', duration=14)
Parameters

• name: name of threat feed
• category: category that detection will register. supported values are lateral, exfil, and cnc
• certainty: certainty applied to detection. Supported values are Low, Medium, High
• itype: indicator type - supported values are Anonymize, Exfiltration, Malware Artifacts, and Watchlist
• duration: days that the threat feed will be applied
• Values for category, itype, and certainty are case sensitive

Delete threat feed:

vc.delete_feed(feed_id=1)
Parameters

• feed_id: id of threat feed (returned by get_feed_by_name())

List threat feeds:

vc.get_feeds()
No parameters

Get threat feed by name:

vc.get_feed_by_name(name='sample')
Parameters

• name: name of threat feed

Post STIX file:

vc.post_stix_file(feed_id=1, stix_file='stix.xml')
Parameters

• feed_id: id of threat feed (returned by get_feed_by_name())
• stix_file: stix filename

Access custom endpoint

vc.custom_endpoint(path='/health')
Parameters

• path: path of the api endpoint

CLI/SCRIPTS reference:

The scripts directory is a collection of scripts used to interact with the Vectra api from the command line. These scripts can also be used as a reference on how to leverage the VAT library.

• dest_dns.py provides a list of destination domains sorted by total number of detections
• dest_ip.py provides a list of destination IPs sorted by total number of detections or on a per detection basis
• dest_ports.py provides a list of ports sorted based on number of detections
• detection_counts.py provides a list of detection types sorted based on count
• detections.py retrieves, filter, and sort detections from the command line
• hosts.py retrieves, filters, and sorts detections from the command line
• key_assets.py (un)sets key assets using hostname, ip, id, or a list provided by the user (list file requires one hostname or ip per line and needs to be one type)
• src_ip.py provides a list of source IPs sorted by total number of detections
• subnet_count.py provides a list of host counts per subnet
• threat_feed.py provides a programatic way of managing threat feeds via the api.

To get started with the scripts, it is recommended that you run python <script> -h to see what options are available. Most scripts are written in a hierarchy to help ensure proper execution. As an example, if we run </script>detection\counts.py we get the following:
‍
$ python detection_counts.py -h
usage: detection_counts.py [-h] {host,file} ... 

positional arguments:
 {host,file}
   host      retrieve data from Vectra brain
   file      Load data from file 
‍
optional arguments:
  -h, --help  show this help message and exit
What this is telling us is that the first parameter that needs to be defined is if you will be running this against a Vectra brain or will be providing input via a file. Once you have determined this, you will run the script again with the appropriate argument to get any additional help.

We will take the previous example and assume we are running it against a Vectra brain. This will result in us running the following command:

$ python detection_counts.pyhost -h
usage: detection_counts.py host[-h] --url URL (--token TOKEN | --user USER)
                               [--page PAGE][--size PAGE_SIZE]
                               [--state{active,inactive}] [--fields FIELDS]
                               [--order ORDER] 

optional arguments:
 -h, --help            show this help message and exit
 --url URL             IP or FQDN for Vectra brain(http://www.example.com)
 --token TOKEN         api token
 --user USER           username for basic auth
 --page PAGE           page number to when returning multiple pages
 --size PAGE_SIZE      number of results to return per page(default: 5000)
 --state {active,inactive}
                       state of object (default:active)
 --fields FIELDS       fields to return
 --order ORDER         field to use for ordering
The result of this tells us that we will have to provide a url (required) a token or username (one of which is required) and the remaining fields are optional and can be used to filter the response.

Another example key_assets.py would result in the following:

python key_assets.py -h
usage: key_assets.py [-h] {hostname,ip,id} ... 

positional arguments:
 {hostname,ip,id}
   hostname        Set key asset flag based on hostname
   ip              Set key asset flag based on ip address
   id              Set key asset based on id 

optional arguments:
 -h, --help        show this help message and exit
This particular script will (un)set host as key assets based on hostname, IP address, or id. If we dig into one of these options, we will learn more about what addition parameters are required.

$ python key_assets.py hostname -h
usage: key_assets.py hostname[-h] --url URL --token TOKEN [--file] [--unset]
                             target 

positional arguments:
 target        hostname or file name with list of hostnames 

optional arguments:
 -h, --help    show this help message and exit
 --url URL     IP or FQDN for Vectra brain (http://www.example.com)
 --token TOKEN api token
 --file        set target to file
 --unset       set flag to unset host as key asset
This tells us that we have to provide a url, token, and a target. Setting the hosts as key assets is the default value. By providing the --unset flag, we will be unsetting the defined host as key assets. Finally, we can provide a hostname as a target or we can use the flag option to tell the script that the target will be a file with a list of hostnames.