5. Scripts

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 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.py host -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 returnining 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.