# Integrate LevelBlue Open Threat Exchange with
Google SecOps

This document explains how to integrate LevelBlue Open Threat Exchange with
Google Security Operations.

> [!NOTE]
> **Note:** AlienVault Open Threat Exchange is now known as LevelBlue Open Threat Exchange. In Google Security Operations, this integration appears under its legacy name, *AlienVaultTI*. This documentation uses LevelBlue Open Threat Exchange except where referencing literal interface labels.

## Use cases

The LevelBlue Open Threat Exchange integration uses Google SecOps
capabilities to support the following use cases:

- **Automated indicator reputation enrichment**: Look up external IPv4
  addresses, file hashes, URLs, and hostnames against LevelBlue Open Threat
  Exchange community pulses as soon as an alert arrives.

- **Threat pulse correlation and triage**: Populate Google SecOps
  entities with community pulse counts, threat tags, geolocation context, and
  malware analysis findings so analysts can prioritize high-risk indicators from
  a single console.

- **Privacy-aware alert processing**: Skip internal IP addresses and internal
  hostnames automatically during enrichment so private network identifiers are
  not sent outside your environment and mixed internal and external cases run
  without errors.

## Before you begin

Before you configure the LevelBlue Open Threat Exchange integration in
Google SecOps, verify that your environment meets the following
requirements:

- **Network connectivity** : Make sure that Google SecOps (or a
  deployed remote agent for private or on-premises networks) can reach
  `https://otx.alienvault.com` over HTTPS on TCP port `443`.

- **Threat intelligence subscription coverage**: Subscribe your dedicated
  LevelBlue Open Threat Exchange account to relevant community and vendor threat
  pulses so indicator lookups return comprehensive pulse metadata.

- **Least-privilege user permissions**: Configure a dedicated LevelBlue Open
  Threat Exchange community account with the minimum permissions required for
  the actions used in your playbooks, as detailed in the following table:

| Action | Required LevelBlue Open Threat Exchange permissions |
|---|---|
| `Enriches Entities` | Standard read-only community account with an active API key capable of querying public indicators and subscribed threat pulses. |
| `Ping` | Standard read-only community account with an active API key capable of validating connectivity and authentication. |

For more information about managing your account and retrieving your API key,
refer to the official
[LevelBlue Open Threat Exchange API documentation](https://otx.alienvault.com/api)
and the [LevelBlue Documentation Portal](https://docs.levelblue.com).

## Integration parameters

The LevelBlue Open Threat Exchange integration requires the following
parameters:

| Parameter | Description |
|---|---|
| `Api Key` | Required. The API key associated with your LevelBlue Open Threat Exchange service account used to authenticate indicator lookup requests. |


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

You can make changes at a later stage, if needed. After you configure an
integration instance, you can use it in playbooks. For more information about
how to configure and support multiple instances, see [Supporting
multiple instances](https://docs.cloud.google.com/chronicle/docs/soar/respond/integrations-setup/supporting-multiple-instances).

<br />

## Actions


For more information about actions, see [Respond to pending actions from your workdesk](https://docs.cloud.google.com/chronicle/docs/soar/overview-and-introduction/your-workdesk/respond-to-pending-actions-from-workdesk.md.txt) and [Run a
manual action in your case](https://docs.cloud.google.com/chronicle/docs/soar/investigate/working-with-cases/what-actions-can-you-take-on-a-case#run-manual-action).

### Enriches Entities

Use the **Enriches Entities** action to query LevelBlue Open Threat Exchange for
threat intelligence, community pulse references, malware analysis findings, and
geographic context across supported indicators in a case.

> [!NOTE]
> **Note:** This action supports `MD5`, `SHA-1`, and `SHA-256` file hashes, external IPv4 addresses, external hostnames, and URLs. Internal `IP Address` and `Hostname` entities are skipped automatically without failing the action.

This action runs on the following Google SecOps entities:

- `IP Address`
- `Hash`
- `Hostname`
- `URL`

#### Action inputs

None.

#### Action outputs

The **Enriches Entities** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Available |
| Entity enrichment table | Available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **Enriches Entities** action provides the following table for each enriched
entity:

- **Table name** : `<var class="prettyprint readonly">ENTITY_IDENTIFIER</var>`
- **Columns** :
  - **Key**
  - **Value**

##### Entity enrichment

The **Enriches Entities** action supports the following entity enrichment:

| Enrichment field name | Description |
|---|---|
| `AlienVault_FIELD_NAME` | Reputation and threat intelligence attributes returned by LevelBlue Open Threat Exchange for the enriched indicator, including pulse counts, indicator type, and malware analysis metadata. |
| `Country` | The country associated with the enriched indicator when geographic context is available. |

##### JSON result

The following example shows the JSON result output received when using the
**Enriches Entities** action:

```json
[
  {
    "Entity": "555a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd55",
    "EntityResult": {
      "general": {
        "indicator": "555a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd55",
        "type": "sha256",
        "type_title": "FileHash - SHA256",
        "sections": [
          "general",
          "analysis"
        ],
        "pulse_info": {
          "count": 11,
          "pulses": [
            {
              "id": "5bbf59f5d47a1b46ca035bde",
              "name": "Production malware feed",
              "TLP": "green",
              "tags": [
                "win32",
                "trojan"
              ]
            }
          ]
        }
      },
      "analysis": {
        "page_type": "None",
        "malware": {}
      }
    }
  }
]
```

##### Output messages

The **Enriches Entities** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Following entities were enriched by AlienVault. ENTITY_IDENTIFIERS` | The action succeeded. |
| `No entities were enriched.` | The action completed, and no matching threat intelligence records were returned for the target entities. |
| `Could not find results for the following entities: ENTITY_IDENTIFIERS` | The action failed for the specified entities. Verify that the listed indicators are valid external IPv4 addresses, supported file hashes (`MD5`, `SHA-1`, or `SHA-256`), external hostnames, or complete URLs. |
| `An error occurred on the following entities: ENTITY_IDENTIFIERS` | The action failed for the specified entities. Check that the indicator formatting is valid and retry the action if a temporary rate limit or connection interruption occurred. |
| `An error occurred while running action. Error: ERROR_REASON` | The action failed. Verify that your `Api Key` is valid in LevelBlue Open Threat Exchange and confirm that outbound HTTPS traffic on TCP port `443` to `https://otx.alienvault.com` is allowed. |

##### Script result

The following table lists the value for the script result output when using the
**Enriches Entities** action:

| Script result name | Value |
|---|---|
| `is_enriched` | `true` or `false` |

### Ping

Use the **Ping** action to test connectivity and verify that your configured API
key can authenticate with LevelBlue Open Threat Exchange.


This action doesn't run on Google SecOps entities.

#### Action inputs

None.

#### Action outputs

The **Ping** action provides the following outputs:

| Action output type | Availability |
|---|---|
| Case wall attachment | Not available |
| Case wall link | Not available |
| Case wall table | Not available |
| Entity enrichment table | Not available |
| JSON result | Not available |
| Output messages | Available |
| Script result | Available |

##### Output messages

The **Ping** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Connection Established.` | The action succeeded. |
| `Connection Failed.` | The action failed. Verify that your `Api Key` matches the active key in your LevelBlue Open Threat Exchange account and confirm that outbound HTTPS access on TCP port `443` is open. |

##### Script result

The following table lists the value for the script result output when using the
**Ping** action:

| Script result name | Value |
|---|---|
| `is_success` | `true` or `false` |

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