Vectra API Client (Under Development)

Vectra API Client

• Free software: MIT license
• Documentation: https://vectra-api-client.readthedocs.io.

Overview

This project is a Vectra Detect API Client written with a focus on python. It uses https://swagger.io in order to automatically generate the low-level api objects. From there, it aims to provide a thin convenience wrapper around those apis.

Since this project uses swagger, a client library in any language should be possible to generate. I hope this helps helps increase accessibility and ease of use.

Usage

Detect v2

Get Detections (v2):: python

>>> from vectra_api_client import clients
>>> token = 'TokenFromProfilePage'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v2(host, token)
>>> query_params = {
...     'src_ip': '172.16.106.116',
...     'threat_gte': 50,
... }
>>> detections = client.detections_get(**query_params)

Get Hosts (v2):: python

>>> from vectra_api_client import clients
>>> token = 'TokenFromProfilePage'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v2(host, username, password)
>>> query_params = {
...     'state': 'active',
...     'name': 'tb5-7',
... }
>>> client.hosts_get(**query_params)

Search (v2):: python

>>> from vectra_api_client import clients
>>> token = 'TokenFromProfilePage'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v2(host, username, password)
>>> query_string = 'host.threat:>=50 and host.certainty:>=50'
>>> hosts = client.search_hosts_get(query_string=query_string)

Detect v1

Get Detections (v1):: python

>>> from vectra_api_client import clients
>>> username = 'vectra'
>>> password = 'password'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v1(host, username, password)
>>> query_params = {
...     'type_vname': 'data smuggler',
...     'src_ip': '172.16.106.116',
... }
>>> detections = client.detections_get(**query_params)

Get Hosts (v1):: python

>>> from vectra_api_client import clients
>>> username = 'vectra'
>>> `password = 'password'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v1(host, username, password)
>>> query_params = {
...     'state': 'active',
...     'name': 'tb5-7',
... }
>>> client.hosts_get(**query_params)

System Info (v1):: python

>>> from vectra_api_client import clients
>>> username = 'vectra'
>>> password = 'password'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v1(host, username, password)
>>> system_info = client.system_info_get()

Other Endpoints

The api objects returned from clients.(v1|v2) have a .session attribute that allow you to hit any endpoint under their respective base url api routes. (eg. v1 will use /api as the base url and v2 will use /api/v2 as the base url.) This .session attribute is from http://docs.python-requests.org/en/master/user/advanced/#session-objects

v1:: python

>>> from vectra_api_client import clients
>>> username = 'vectra'
>>> password = 'password'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v1(host, username, password)
>>> client.session.get('endpoint/under/development')  # GET {host}/api/endpoint/under/development
>>> client.session.post('endpoint/under/development')  # POST {host}/api/endpoint/under/development

v2:: python

>>> from vectra_api_client import clients
>>> token = 'TokenFromProfilePage'
>>> host = 'https://vectra-ip-or-hostname.com'
>>> client = clients.v1(host, username, password)
>>> client.session.get('endpoint/under/development')  # GET {host}/api/v2/endpoint/under/development
>>> client.session.post('endpoint/under/development')  # POST {host}/api/v2/endpoint/under/development

Installation

pip install vectra-api-client

Other Languages

GENERATOR_NAME=$lang OUTPUT_DIR=output make swagger

Contributing

All contributions to the project are welcome! Fork the repo and make a PR. Making github issues is also completely fine as well.

Developing

• docker is required. It is used to run openapi/openapi-generator-cli

pip install -r requirements.txt
pip install -r requirements_dev.txt
make swagger
make test
make test-all

TODO

API v1

• [] /settings
• [] /rules
• [x] /detections
• [x] /hosts
• [] /health
• [] /sensors
• [x] /system/info

API v2

• [] /rules
• [x] /detections
• [] /hosts
• [x] /search
• [x] /threatFeeds
• [x] /proxies
• [] /tagging

This project uses https://swagger.io/ in order to generate its low-level http api classes.

Resources

• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

Credits

Thanks to @leroux for his early contributions.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.