Vectra API Integrations

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.

Getting Started

Installation

To install the library using pip run:

pip install vectra_api_tools
pip install develop branch from github:

pip install git+https://github.com/vectranetworks/vectra_api_tools.git@develop
To install from source code, run the following command from the root directory:

python setup.py install
Once installed, VAT can be imported into any python code using the following:

import vat
or scripts can be run by changing the script directory and running

python <script></script>
Help is available for all scripts using the -h or --help flag

To get started with the STIX_TAXII module, you will first want to instantiate an instance of the TaxiClient. General concept should be the same for other threat feeds. This module is built on cabby, so please leverage their documentation as an additional resource.

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)

Detection methods

Get detections:

This method has a page_size limit of 5000 objects and should be used when response does not exceed this limit. If response exceeds 5000objects, use get_all_detections(). Use of parameters is recommended.

vc.get_detections()
All parameters are optional

  • 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
  • category: detection category - will be removed with deprecation of v1 of api
  • certainty: certainty score (int)
  • certainty_gte: certainty score greater than or equal to (int)
  • detection:
  • detection_type: detection type
  • detection_category: detection category
  • fields: comma separated string of fields to be filtered and returned
  • host_id: detection id (int)
  • is_targeting_key_asset: detection is targeting key asset (bool)
  • is_triaged: detection is triaged
  • ordering: field used to sort response
  • src_ip: source ip address of host attributed to detection
  • state: state of detection (active/inactive)
  • t_score: threat score (int) - will be removed with deprecation of v1 of api
  • t_score_gte: threat score is greater than or equal to (int) - will be removed with deprecation of v1 of api
  • tags: tags assigned to detection
  • targets_key_asset: detection targets key asset (bool) - will be removed with deprecation of v1 of api
  • threat: threat score (int)
  • threat_gte threat score is greater than or equal to (int)

Get all detections:

This method is a generator and should be used when the response exceeds the limit of 5000 objects. When using this method, you must instantiate the generator and then call next, or iterate over the generator.

detection_generator = vc.get_all_detections()
next(detection_generator)
or
for page in detection_generator:
    print page
Parameters used with get_detections() can be used and are optional

Get detections by id:

vc.get_detections_by_id(detection_id=1)
Parameters

  • det_id: detection id - required
  • fields: comma separated string of fields to be filtered and returned

Get detection tags:

vc.get_detection_tags(detection_id=1)
Parameters

  • detection_id: id of host to retrieve tags

Set detection tags:

vc.set_detection_tags(detection_id=1, tags=[], append=False)
Parameters

  • detection_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)

Proxy methods

Get proxies:

vc.get_proxies()
Parameters

  • proxy_id: id of proxy

Add proxy:

vc.add_proxy(address="192.168.72.27", enable=True)
Parameters

  • address: ip address of proxy
  • enable: enable proxy

Update proxy:

vc.update_proxy(proxy_id=1, enable=False)
Parameters

  • proxy_id: id of proxy
  • address: ip address of proxy
  • enable: enable proxy

Delete proxy:

vc.delete_proxy(proxy_id=1)
Parameters

  • proxy_id: id of proxy

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

Advanced search

vc.advanced_search(stype='detections', page_size=50, query="detection.certainty:>=50")
Parameters

Access custom endpoint

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

  • path: path of the api endpoint

STIX/TAXII module reference:

import vat.stix_taxii as tc

tc = TaxiClient(url='otx.alienvalut.com', use_https=True, discovery_path='/taxii/discovery', username=<token>)
Parameters

  • url: url of service (do not include http(s)://)
  • discovery_path: discover advertised services
  • https: use https transport (boolean)
  • username
  • password
  • cert
  • key

Once an instance of the TaxiiClient has been instantiated, the following methods can be used:

  • discovery
  • set_discovery_path
  • collections
  • poll
  • write_stix_file

Discovery
Discover advertised services

tc.discovery()
Parameters

  • uri: uri of the discovery service (optional if discovery_path is defined in TaxiiClient)

Set Discovery Path
Set discovery path for tc

tc.set_discovery_path(uri='/taxii/discovery')
Parameters

  • uri: uri of discovery service

Collections
Fetch contents of Collection Management Service

tc.collections(uri='/taxii/collections')
Parameters

  • uri

Poll
Poll for contents of a collection and generate STIX package

tc.poll(feed='user_AlienVAult', duration=7)
Parameters

  • feed: name of the collection to retrieve
  • discovery_path (not required if defined in tc)
  • duration: number of days to retrieve

Write STIX file
Convert package generated by tc.poll() to STIX file

tc.write_stix_file(stix_package)
Parameters

  • stix_package: package generated by poll()

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.