---
title: "Vectra 365 collector"
canonical: "https://docs.devo.com/space/latest/609517608/Vectra%20365%20collector"
format: markdown
---
> Macro (toc)

## Overview

Vectra REST API is available for administrators and developers to integrate Vectra’s breach detection data into their applications. Vectra RESTful API provides access to security event data, platform configuration, and health information via URI paths.

## Devo collector features

| **Feature** | **Details** |
| --- | --- |
| Allow parallel downloading (`multipod`) | `not allowed` |
| Running environments | - `collector server`
- `on-premise` |

## Data sources

| **Data source** | **Description** | **Devo table** |
| --- | --- | --- |
| Detections | Detection objects contain all the information related to security events detected in the environment | `ndr.vectra.platform.detection` |

For more information on how the events are parsed, [visit our page](https://devodocs.atlassian.net/wiki/spaces/latest/pages/405078017).

## Flattening preprocessing

| **Data source** | **Collector service** | **Optional** | **Flattening details** |
| --- | --- | --- | --- |
| Source | Service | - `yes`
- `no` | Flattening steps |

## Vendor setup

### API Clients

Getting access to the Vectra Platform API is done through the creation of an API Client. Creation of an API Client will provide a set of OAuth 2.0 credentials that will be used to gain authorization to the Vectra Platform API. Please note that management of API Clients is restricted to Detect users with the role Super Admin. To create an API client, log in to your Detect portal and navigate to** Manage → API Clients**.

![a66b962d-133b-4a1c-8dbc-a07198b920cd.png](media://707659da-3c35-40b5-9c7f-cf982bb154f0)

### Creating a new API Client

From the API Clients page, select **Add API Client **to create a new client.

![image-20240425-195648.png](media://c44b170c-bf32-4d98-a598-794e9aefdb28)

Creating a new API Client has one required parameter:

- **Role** – the role maps the API Client to a set of permissions, similar to the way a Detect UI user  
would be assigned a role. The role must be the following:
  - Read-Only

Creating a new API Client has two optional parameters:

- **Name** – a user-friendly name to identify the client (up to 256 characters)
- **Description** – a brief description to aid in identifying the client (up to 2048 characters)

Once you have entered the API Client information, select **Generate Credentials** to get your client credentials.

![image-20240425-195952.png](media://17963681-9e14-4663-806d-b357d710160e)

Be sure to record your **Client ID **and **Secret Key** for safekeeping. You will need these two credentials to authenticate as an API Client in the Vectra Platform API.

## Run the collector

Once the data source is configured, you can either send us the required information if you want us to host and manage the collector for you (<u>Cloud collector</u>), or deploy and host the collector in your own machine using a Docker image (<u>On-premise collector</u>).

> Macro (rw-ui-tabs-macro)
> 
> > Macro (rw-tab)
> 
> The collector runs on the Devo Collector Server. To enable the collector for a customer:
> 
> 1. In the **Collector Server** **GUI**, access the **domain** where you want this instance to be created, click on **Add Collector** and search for “**Vectra 3655 - Integrations Factory**”, then click on the result.
> 2. In the **Version** field, select the latest value.
> 3. In the **Collector Name** field, set the value you prefer (this name must be unique inside the same Collector Server domain).
> 4. In the **Parameters** section, establish the **Collector Parameters** as follows below:
> 
> ```
> {
>   "global_overrides": {
>     "debug": false
>   },
>   "inputs": {
>     "vectra_365": {
>       "id": "<short_unique_id>",
>       "enabled": true,
>       "credentials": {
>         "vectra_portal_url": "<vectra_portal_url>",
>         "client_id": "<client_id>",
>         "secret_key": "<secret_key>"
>       },
>       "environment": "prod",
>       "services": {
>         "detection": {
>           "request_period_in_seconds": <request_period_in_seconds>,
>           "start_time": "<start_time>"
>         }
>       }
>     }
>   }
> }
> ```
> 
> Replace the placeholders with your required values following the description table below:
> 
> |  |  |  |  |  |
> | --- | --- | --- | --- | --- |
> | **Parameter** | **Data type** | **Type** | **Value range / Format** | **Details** |
> | `input_id` | `int` | `Mandatory` | Minimum length: 1  
> Maximum length: 50 | Use this param to give an unique id to this input service. |
> | `enabled` | `bool` | `Mandatory` | false / true | If the value is true, the input definition will be executed. If the value is false, the service will be ignored. |
> | `vectra_portal_url` | `str` | `Mandatory` | Any | URL to the Vectra 365 portal. This parameter is required to connect to the service. |
> | `client_id` | `str` | `Mandatory` | Any | Client ID used to authenticate to the Vectra service. |
> | `secret_key` | `str` | `Mandatory` | Any | Secret key used alongside the client ID for authentication purposes. |
> | `request_period_in_seconds` | `int` | `Mandatory` | Minimum value: 1 | This parameter allows you to customize this behavior for each service. |
> | `start_time` | `int` | `Mandatory` | Following [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339): `%Y-%m-%dT%H:%M:%S.%f%z`<br>Example: `2024-04-04T05:50:00.000-0500` | Initial time period used when fetching data from the endpoint.<br>> ⚠️ Due to the large amount of data produced by this service, using this parameter is discouraged except in special cases.<br>> 📝 This parameter can be left blank, removed or commented. |
> 
> > Macro (rw-tab)
> 
> This data collector can be run in any machine that has the Docker service available because it should be executed as a docker container. The following sections explain how to prepare all the required setup for having the data collector running.
> 
> ### Structure
> 
> The following directory structure should be created for being used when running the collector:
> 
> ```
> <any_directory>
> └── devo-collectors/
>     └── <product_name>/
>         ├── certs/
>         │   ├── chain.crt
>         │   ├── <your_domain>.key
>         │   └── <your_domain>.crt
>         ├── state/
>         └── config/ 
>             └── config.yaml 
> ```
> 
> > ⚠️ Replace `<product_name>` with the proper value.
> 
> ### Devo credentials
> 
> In Devo, go to **Administration → Credentials → X.509 Certificates**, download the **Certificate**, **Private key** and **Chain CA** and save them in `<product_name>/certs/`. Learn more about security credentials in Devo [here](#).
> 
> ![image-20240506-121539.png](media://5793ae22-09d6-4b74-81d8-cf2b6e38a7db)
> 
> > ⚠️ Replace `<product_name>` with the proper value.
> 
> ### Editing the config.yaml file
> 
> ```
> globals:
>   debug: false
>   id: not_used
>   name: vectra-365
>   persistence:
>     type: filesystem
>     config:
>       directory_name: state
> 
> outputs:
>   devo_1:
>     type: devo_platform
>     config:
>       address: collector-us.devo.io
>       port: 443
>       type: SSL
>       chain: chain.crt
>       cert: <devo_domain>.crt
>       key: <devo_domain>.key
> 
> inputs:
>   vectra_365:
>     id: <unique_id>
>     enabled: true
>     credentials:
>       vectra_portal_url: <vectra_portal_url>
>       client_id: <client_id>
>       secret_key: <secret_key>
>     environment: prod
>     services:
>       detection:
>         request_period_in_seconds: <request_period_in_seconds>
>         start_time: <start_time>
> ```
> 
> > ℹ️ All defined service entities will be executed by the collector. If you do not want to run any of them, just remove the entity from the `services` object.
> 
> Replace the placeholders with your required values following the description table below:
> 
> |  |  |  |  |  |
> | --- | --- | --- | --- | --- |
> | **Parameter** | **Data type** | **Type** | **Value range** | **Details** |
> | `collector_id` | `str` | `Mandatory` | Minimum length: 1  
> Maximum length: 5 | Use this param to give an unique id to this collector. |
> | `collector_name` | `str` | `Mandatory` | Minimum length: 1  
> Maximum length: 10 | Use this param to give a valid name to this collector. |
> | `multiprocessing_mode` | `bool` | `Mandatory` | false / true | If the value is true, the collector will run using a multiprocessing architecture. If the value is false, the collector will use only one CPU. |
> | `devo_address` | `str` | `Mandatory` | `collector-us.devo.io`  
> `collector-eu.devo.io` | Use this param to identify the Devo Cloud where the events will be sent. |
> | `chain_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the chain.cert  file downloaded from your Devo domain. Usually this file's name is: `chain.crt` |
> | `cert_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the `file.cert` downloaded from your Devo domain. |
> | `key_filename` | `str` | `Mandatory` | Minimum length: 4  
> Maximum length: 20 | Use this param to identify the `file.key` downloaded from your Devo domain. |
> | `input_id` | `int` | `Mandatory` | Minimum length: 1  
> Maximum length: 5 | Use this param to give an unique id to this input service. |
> | `vectra_portal_url` | `str` | `Mandatory` | Any | URL to the Vectra 365 portal. This parameter is required to connect to the service. |
> | `client_id` | `str` | `Mandatory` | Any | Client ID used to authenticate to the Vectra service. |
> | `secret_key` | `str` | `Mandatory` | Any | Secret key used alongside the client ID for authentication purposes. |
> | `request_period_in_seconds` | `int` | `Mandatory` | Minimum length: 1<br>Recommended value: 60 | This parameter allows you to customize this behavior for each service. As this collector uses websockets, this is the period elapsed between reconnections. |
> | `start_time` | `int` | `Mandatory` | Following [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339): `%Y-%m-%dT%H:%M:%S.%f%z`<br>Example: `2024-04-04T05:50:00.000-0500` | Initial time period used when fetching data from the endpoint. |
> 
> ### Download the Docker image
> 
> The collector should be deployed as a Docker container. Download the Docker image of the collector as a .tgz file by clicking the link in the following table:
> 
> | **Collector Docker image** | **SHA-256 hash** |
> | --- | --- |
> | [collector-vectra365_if-docker-image-1.0.0](https://drive.google.com/file/d/1OvjbD7GdAw6zxuz1TCszDAPrmJX-P3hB/view?usp=drive_link) | `5388714853656516b16437c5bcb263551a107e0b7467cc9011efedbf82969f33` |
> 
> Use the following command to add the Docker image to the system:
> 
> ```
> gunzip -c <image_file>-<version>.tgz | docker load
> ```
> 
> > ⚠️ Once the Docker image is imported, it will show the real name of the Docker image (including version info). Replace `<image_file>` and `<version>` with a proper value.
> 
> The Docker image can be deployed on the following services:
> 
> #### Docker
> 
> Execute the following command on the root directory `<any_directory>/devo-collectors/<product_name>/`
> 
> ```
> docker run 
> --name collector-<product_name> 
> --volume $PWD/certs:/devo-collector/certs 
> --volume $PWD/config:/devo-collector/config 
> --volume $PWD/state:/devo-collector/state 
> --env CONFIG_FILE=config.yaml 
> --rm 
> --interactive 
> --tty 
> <image_name>:<version>
> ```
> 
> > ⚠️ Replace `<product_name>`, `<image_name>` and `<version>` with the proper values.
> 
> #### Docker Compose
> 
> The following Docker Compose file can be used to execute the Docker container. It must be created in the `<any_directory>/devo-collectors/<product_name>/` directory.
> 
> ```
> version: '3'
> services:
>   collector-<product_name>:
>     image: <image_name>:${IMAGE_VERSION:-latest}
>     container_name: collector-<product_name>
>     volumes:
>       - ./certs:/devo-collector/certs
>       - ./config:/devo-collector/config
>       - ./credentials:/devo-collector/credentials
>       - ./state:/devo-collector/state
>     environment:
>       - CONFIG_FILE=${CONFIG_FILE:-config.yaml}
> ```
> 
> To run the container using docker-compose, execute the following command from the `<any_directory>/devo-collectors/<product_name>/` directory:
> 
> ```
> IMAGE_VERSION=<version> docker-compose up -d
> ```
> 
> > ⚠️ Replace `<product_name>`, `<image_name>` and `<version>` with the proper values.

## Change log

| **Release** | **Released on** | **Release type** | **Details** | **Recommendations** |
| --- | --- | --- | --- | --- |
| `v1.0.0` | 4/24/2024 | [NEW FEATURE] | **New features:**<br>- Used DCSDK v1.11.1
- Created services:
  - detection
- Created modules:
  - initializer
  - requester
  - paginator
  - processing
  - puller
  - puller_setup
- Tests with 93% coverage | `-` |