# Devo

This document describes how to integrate Devo with
Google Security Operations.

## Product Permission

Devo provides several authentication methods described in the [Security
credentials](https://docs.devo.com/space/latest/94763701/Security+credentials)
document available within the Devo documentation.

Google Security Operations integration supports either authentication tokens or
access keys for authentication.

It is recommended to configure token-based authentication:

1. Go to the [Authentication
   tokens](https://docs.devo.com/space/latest/94763821) document available within the Devo documentation.
2. Follow steps on how to create a token, on step 3 select **Query data using
   REST API**.
3. On step 4, for the target table, specify "siem.logtrust.alert.info".

> [!NOTE]
> **Note:** "Siem.logtrust.alert.info" is a table that stores alerts generated by Devo, if you are using authentication tokens and planning to query other tables with integration query actions, configure the target table accordingly. If "siem.logtrust.alert.info" is not granted for the generated access token, the Ping action fails even if the token is valid.

Finish the creation process according to the documentation to get a token.

## API

For more information on API, see the [API
reference](https://docs.devo.com/space/latest/95128251/API+reference) document
available within the Devo documentation.

## Configure Devo integration in Google SecOps

For detailed instructions on how to configure an integration in
Google SecOps, see [Configure
integrations](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/configure-integrations).

### Integration parameters

Use the following parameters to configure the integration:

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| API URL | String | https://apiv2-us.devo.com | Yes | Specify API root for the target Devo instance. |
| API Token | Password | N/A | No | If a token-based authentication is used, specify the API token for the target Devo instance. If both Token and Access Keys are provided, integration works on API token and ignores Access Keys. |
| API Key | Password | N/A | No | If an access keys authentication is used, specify the API key for the target Devo instance. |
| API Secret | Password | N/A | No | If an access keys authentication is used, specify the API secret for the target Devo instance. |
| Verify SSL | Checkbox | Checked | No | If enabled, the Google SecOps server checks the certificate configured for API root. |

> [!NOTE]
> **Note:** You can make changes at a later stage if needed. Once configured, the Instances can be used in Playbooks. For detailed information on configuring and supporting multiple instances, please see [Supporting multiple instances](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/supporting-multiple-instances).

## Use Cases

1. Devo can be used as a source of alerts for Google SecOps to process.
2. Devo can be queried from Google SecOps to enrich Google SecOps alert context.

## Actions

### Ping

#### Description

Test connectivity to the Devo instance with parameters provided at the
integration configuration page in the Google SecOps Content Hub page.

If "siem.logtrust.alert.info" is not granted for the generated access token, the
Ping action fails even if the token is valid. For more information, see the
[Product Permission](https://docs.cloud.google.com/chronicle/docs/soar/marketplace-integrations/devo#product_permission) section.

#### Parameters

N/A

#### Use Case

The action is used to test connectivity at the integration configuration page in
the Google SecOps Content Hub page, and it can be executed as a manual action,
not used in playbooks.

#### Run On

The action doesn't run on entities, nor has mandatory input parameters.

#### Action Results

##### Script Result

| Script Result Name | Value Options | Example |
|---|---|---|
| is_success | True/False | is_success=False |

##### JSON Result

    N/A

##### Entity Enrichment

N/A

##### Insights

N/A

##### Case Wall

| Result type | Value/Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** *If successful:* "Successfully connected to the Devo instance with the provided connection parameters!" **The action should fail and stop a playbook execution:** *If not successful:* "Failed to connect to the LogRhythm server! Error is {0}".format(exception.stacktrace) | General |

### Advanced Query

#### Description

Execute an advanced query based on the provided parameters. Note that action is
not working on Google SecOps entities. To query a table other than
siem.logtrust.alert.info, create an additional token for that table following
the [Authentication tokens](https://docs.devo.com/space/latest/94763821)
document available within the Devo documentation and specify it on the
integration configuration page.

#### Parameters

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Query | String | N/A | Yes | Specify a query to execute against Devo instance. <br /> Example: "from siem.logtrust.alert.info". |
| Time Frame | DDL | Last Hour <br /> Possible Values: - Last Hour - Last 6 Hours - Last 24 Hours - Last Week - Last Month - Custom | No | Specify a time frame for the results. <br /> If "Custom" is selected, you also need to provide the "Start Time" parameter. |
| Start Time | String | N/A | No | Specify the start time for the query. <br /> This parameter is mandatory, if "Custom" is selected for the "Time Frame" parameter. <br /> Format: ISO 8601 <br /> Example: 2021-08-05T05:18:42Z |
| End Time | String | N/A | No | Specify the end time for the query. <br /> If nothing is provided and "Custom" is selected for the "Time Frame" parameter then this parameter uses current time. <br /> Format: ISO 8601 <br /> Example: 2021-08-05T05:18:42Z |
| Max Rows to Return | Integer | 50 | No | Specify the maximum number of rows the action should return. |

#### Run On

This action doesn't run on entities.

#### Action Results

##### Script Result

| Script Result Name | Value Options | Example |
|---|---|---|
| is_success | True/False | is_success=False |

##### JSON Result

    {
       "msg": "",
       "timestamp": 1630483519438,
       "cid": "01a5d92a25ba",
       "status": 0,
       "object": [
           {
               "eventdate": 1619452643049,
               "alertHost": "backoffice",
               "domain": "siemplify",
               "priority": 7.0,
               "context": "my.alert.siemplify.500",
               "category": "my.context",
               "status": 0,
               "alertId": "22797077",
               "srcIp": null,
               "srcPort": null,
               "srcHost": "",
               "dstIp": null,
               "dstPort": null,
               "dstHost": "",
               "protocol": "",
               "username": "user@siemplify.co",
               "application": "",
               "engine": "pil01-pro-custom-us-aws",
               "extraData": "{\"count\":\"13\",\"eventdate\":\"2021-04-26+15%3A56%3A30.0\"}"
           }
       ]
    }

##### Entity Enrichment

N/A

##### Insights

N/A

##### Case Wall

| Result type | Value/Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** *If found at least some data (is_success=true):* "Successfully retrieved results for the provided query in Devo." <br /> *If no results are found (is_success=false):* "No results found for the provided query in Devo." **The action should fail and stop a playbook execution:** *If errors are reported in the query:* "Error executing action "Advanced Search". Reason: {message}''.format(error.Stacktrace) *If the "Start Time" parameter is empty and the "Time Frame" parameter is set to "Custom" (fail):* "Error executing action "". Reason: "Start Time" should be provided, when "Custom" is selected in the "Time Frame" parameter." *If value of the "Start Time" parameter is greater than value of the "End Time" parameter (fail):* "Error executing action "". Reason: "End Time" should be later than "Start Time". *If a negative value or 0 is set for the "* Max Rows to Return" parameter*:* "Error executing action "". Reason: "Max Rows to Return" should be positive, non-zero number." *If a fatal error, like wrong credentials, no connection to the server, other is reported:* "Error executing action "Advanced Query". Reason: {0}''.format(error.Stacktrace) | General |
| Table | **Table Name:** Advanced Query Results **Table Columns:** All of the columns returned from the response. | General |

### Simple Query

#### Description

Execute a simple query based on the provided parameters. Note that action is not
working on Google SecOps entities. To query a table other than
siem.logtrust.alert.info, create an additional token for that table following
the [Authentication tokens](https://docs.devo.com/space/latest/94763821)
document available within the Devo documentation and specify it on the
integration configuration page.

#### Parameters

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Table Name | String | siem.logtrust.alert.info | Yes | Specify the table that should be queried. |
| Fields To Return | CSV | N/A | No | Specify the fields to return. <br /> If nothing is provided, the action returns all fields. |
| Where Filter | String | N/A | No | Specify the Where filter for the query that needs to be executed. |
| Time Frame | DDL | Last Hour Possible Values: Last Hour Last 6 Hours Last 24 Hours Last Week Last Month Custom | No | Specify a time frame for the results. <br /> If "Custom" is selected, you also need to provide the "Start Time" parameter. |
| Start Time | String | N/A | No | Specify the start time for the query. <br /> This parameter is mandatory, if "Custom" is selected for the "Time Frame" parameter. <br /> Format: ISO 8601 <br /> Example: 2021-08-05T05:18:42Z |
| End Time | String | N/A | No | Specify the end time for the query. <br /> If nothing is provided and "Custom" is selected for the "Time Frame" parameter then this parameter uses current time. <br /> Format: ISO 8601 Example: 2021-08-05T05:18:42Z |
| Max Rows to Return | Integer | 50 | No | Specify the maximum number of rows the action should return. |

#### Run On

This action doesn't run on entities.

#### Action Results

##### Script Result

| Script Result Name | Value Options | Example |
|---|---|---|
| is_success | True/False | is_success=False |

##### JSON Result

    {
       "msg": "",
       "timestamp": 1630483519438,
       "cid": "01a5d92a25ba",
       "status": 0,
       "object": [
           {
               "eventdate": 1619452643049,
               "alertHost": "backoffice",
               "domain": "siemplify",
               "priority": 7.0,
               "context": "my.alert.siemplify.500",
               "category": "my.context",
               "status": 0,
               "alertId": "22797077",
               "srcIp": null,
               "srcPort": null,
               "srcHost": "",
               "dstIp": null,
               "dstPort": null,
               "dstHost": "",
               "protocol": "",
               "username": "user@siemplify.co",
               "application": "",
               "engine": "pil01-pro-custom-us-aws",
               "extraData": "{\"count\":\"13\",\"eventdate\":\"2021-04-26+15%3A56%3A30.0\"}"
           }
       ]
    }

##### Entity Enrichment

N/A

##### Insights

N/A

##### Case Wall

| Result type | Value/Description | Type |
|---|---|---|
| Output message\* | **The action should not fail nor stop a playbook execution:** *If found at least some data (is_success=true):* "Successfully retrieved results for the query: "{constructed query}" in Devo." *If no results are found (is_success=false):* "No results found for the query {constructed query} in Devo". **The action should fail and stop a playbook execution:** *If errors are reported in the query:* "Error executing action "Simple Search". Reason: {message}''.format(error.Stacktrace) *If the "Start Time" parameter is empty and the "Time Frame" parameter is set "Custom" (fail):* "Error executing action "". Reason: "Start Time" should be provided, when "Custom" is selected in the "Time Frame" parameter." *If vale of the "Start Time" parameter is greater than the value of the "End Time" parameter (fail):* "Error executing action "". Reason: "End Time" should be later than "Start Time". If a negative value or 0 is set for the "Max Rows to Return" parameter: "Error executing action "". Reason: "Max Rows to Return" should be positive, non-zero number." If a fatal error, like wrong credentials, no connection to the server, other is reported: "Error executing action "Simple Query". Reason: {0}''.format(error.Stacktrace) | General |
| Table | **Table Name:** Simple Query Results **Table Columns:** All of the columns returned from the response | General |

## Connectors

## Devo Alerts Connector

#### Description

Connector can be used to fetch alert records from the siem.logtrust.alert.info
table from Devo. Connector whitelist can be used to ingest only specific types
of alerts based on the alert context value.

#### Configure Devo Alerts Connector in Google SecOps

For detailed instructions on how to configure a connector in
Google SecOps, see [Configuring the
connector](https://docs.cloud.google.com/chronicle/docs/soar/ingest/connectors/ingest-your-data-connectors).

##### Connector parameters

Use the following parameters to configure the connector:

| Parameter Display Name | Type | Default Value | Is Mandatory | Description |
|---|---|---|---|---|
| Product Field Name | String | Devo | Yes | Enter the source field name in order to retrieve the Product Field name. |
| Event Field Name | String | "context" | Yes | Enter the source field name in order to retrieve the Event Field name. |
| Environment Field Name | String | "" | No | Describes the name of the field where the environment name is stored. If the environment field isn't found, the environment is the default environment. |
| Environment Regex Pattern | String | .\* | No | A regex pattern to run on the value found in the "Environment Field Name" field. Default is .\* to catch all and return the value unchanged. Used to allow the user to manipulate the environment field through regex logic. If the regex pattern is null or empty, or the environment value is null, the final environment result is the default environment. |
| API URL | String | https://apiv2-us.devo.com | Yes | Specify API URL for the target Devo instance. |
| API Token | Password | N/A | No | If a token-based authentication is used, specify the API token for the target Devo instance. |
| API Key | Password | N/A | No | If an access keys authentication is used, specify the API key for the target Devo instance. |
| API Secret | Password | N/A | No | If an access keys authentication is used, specify the API secret for the target Devo instance. |
| Verify SSL | Checkbox | Checked | No | If enabled, Google SecOps server checks the certificate configured for API root. |
| Offset time in hours | Integer | 24 | Yes | Fetch alerts from X hours backwards. |
| Max Alerts Per Cycle | Integer | 30 | Yes | Number of alerts that should be processed during one connector run. |
| Minimum Priority to Fetch | String | Normal | Yes | Minimum priority of the alert to be ingested to Google SecOps, for example, Low or Medium. Possible Values: Very Low, Low, Normal, High, Very High |
| Use whitelist as a blacklist | Checkbox | Unchecked | Yes | If enabled, whitelist is used as a blacklist. |

#### Connector Rules

##### Proxy Support

The connector supports Proxy.

**Need more help?** [Get answers from Community members and Google SecOps professionals.](https://security.googlecloudcommunity.com/)