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.
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.
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
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
Set host as key asset:
vc.set_key_asset(host_id=1)
Parameters
Get host tags:
vc.get_host_tags(host_id=1)
Parameters
Set host tags:
vc.set_host_tags(host_id=1, tags=[], append=False)
Parameters
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
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 pageParameters used with get_detections() can be used and are optional
Get detections by id:
vc.get_detections_by_id(detection_id=1)
Parameters
Get detection tags:
vc.get_detection_tags(detection_id=1)
Parameters
Set detection tags:
vc.set_detection_tags(detection_id=1, tags=[], append=False)
Parameters
Get triage rules:
vc.get_rules()
Parameters
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
Update triage rule:
vc.update_rule(rule_id=1, append=False)
Parameters
Delete triage rule:
vc.delete_rule(rule_id=1, restore_detections=True)
Paramaters
Get proxies:
vc.get_proxies()
Parameters
Add proxy:
vc.add_proxy(address="192.168.72.27", enable=True)
Parameters
Update proxy:
vc.update_proxy(proxy_id=1, enable=False)
Parameters
Delete proxy:
vc.delete_proxy(proxy_id=1)
Parameters
Create threat feed:
vc.create_feed(name='sample', category='exfil', certainty='Medium', itype='Exfiltration', duration=14)
Parameters
Delete threat feed:
vc.delete_feed(feed_id=1)
Parameters
List threat feeds:
vc.get_feeds()
No parameters
Get threat feed by name:
vc.get_feed_by_name(name='sample')
Parameters
Post STIX file:
vc.post_stix_file(feed_id=1, stix_file='stix.xml')
Parameters
vc.advanced_search(stype='detections', page_size=50, query="detection.certainty:>=50")
Parameters
vc.custom_endpoint(path='/health')
Parameters
import vat.stix_taxii as tc
tc = TaxiClient(url='otx.alienvalut.com', use_https=True, discovery_path='/taxii/discovery', username=<token>)Parameters
Once an instance of the TaxiiClient has been instantiated, the following methods can be used:
Discovery
Discover advertised services
tc.discovery()
Parameters
Set Discovery Path
Set discovery path for tc
tc.set_discovery_path(uri='/taxii/discovery')
Parameters
Collections
Fetch contents of Collection Management Service
tc.collections(uri='/taxii/collections')
Parameters
Poll
Poll for contents of a collection and generate STIX package
tc.poll(feed='user_AlienVAult', duration=7)
Parameters
Write STIX file
Convert package generated by tc.poll() to STIX file
tc.write_stix_file(stix_package)
Parameters
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.
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.