# Integrate LevelBlue USM Anywhere with
Google SecOps

This document explains how to integrate LevelBlue USM Anywhere with
Google Security Operations.

> [!NOTE]
> **Note:** AlienVault Unified Security Management Anywhere is now known as LevelBlue USM Anywhere. In Google SecOps, this integration appears under its legacy name, *AlienVault USM Anywhere*. This documentation uses LevelBlue USM Anywhere except where referencing literal interface labels.

## Use cases

The LevelBlue USM Anywhere integration uses Google SecOps
capabilities to support the following use cases:

- **Automated security alarm triage**: Ingest prioritized security alarms and
  their correlated events from LevelBlue USM Anywhere into
  Google SecOps cases while filtering out suppressed or
  low-priority detections.

- **Rapid alarm context investigation**: Retrieve complete metadata for a
  specific LevelBlue USM Anywhere alarm (including priority score, source and
  destination assets, geographic context, and suppression status) directly onto
  the Case Wall.

- **Targeted historical event hunting**: Query historical security events by
  account name, source asset, event name, and date window during automated or
  manual investigations to determine the scope of suspicious activity.

## Before you begin

Before you configure the LevelBlue USM Anywhere 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 your LevelBlue USM Anywhere cloud
  instance over HTTPS on TCP port `443`.

- **Authentication credentials and version selection** : Confirm which LevelBlue
  USM Anywhere authentication version your environment uses. Version `V2`
  (recommended) uses an OAuth 2.0 client ID and secret and is required to run
  the **Get Alarm Details** and **List Events** actions. Legacy version `V1`
  uses a standard username and password and supports connectivity validation and
  legacy alarm ingestion only.

- **Least-privilege user permissions**: Configure a dedicated LevelBlue USM
  Anywhere service account with the minimum permissions required for the actions
  and connectors used in your workflows, as detailed in the following table:

  | Component | Required LevelBlue USM Anywhere permissions |
  |---|---|
  | `Get Alarm Details` | Analyst or custom read-only role with permission to generate OAuth 2.0 credentials and view alarm records and associated events. |
  | `List Events` | Analyst or custom read-only role with permission to generate OAuth 2.0 credentials and search historical security event records. |
  | `Ping` | Valid user account credentials capable of authenticating and reading basic environment status in LevelBlue USM Anywhere. |
  | `AlienVault USM Anywhere Connector` | Analyst or custom read-only role with permission to query security alarms, alarm metadata, and correlated event details. |

For more information about configuring roles and generating OAuth 2.0 client
credentials, refer to the official
[LevelBlue USM Anywhere documentation](https://docs.levelblue.com/documentation/usm-anywhere)
and the
[Get OAuth Token API reference](https://docs.levelblue.com/api-reference/oauth/get-oauth-token).

## Integration parameters

The LevelBlue USM Anywhere integration requires the following parameters:

| Parameter | Description |
|---|---|
| `Api Root` | Required. The base URL of the LevelBlue USM Anywhere server, formatted as `https://SUBDOMAIN.alienvault.cloud`. |
| `ClientID` | Required. The OAuth 2.0 client ID associated with your LevelBlue USM Anywhere service account when `Product Version` is set to `V2`. If `Product Version` is set to `V1`, provide your LevelBlue USM Anywhere account username in this field instead. |
| `Secret` | Required. The OAuth 2.0 client secret associated with your LevelBlue USM Anywhere service account when `Product Version` is set to `V2`. If `Product Version` is set to `V1`, provide your LevelBlue USM Anywhere account password in this field instead. |
| `Product Version` | Required. The LevelBlue USM Anywhere authentication version to use. To use the **Get Alarm Details** and **List Events** actions, this parameter must be set to `V2`. The possible values are as follows: - `V1` - `V2` The default value is `V2`. |
| `Use SSL` | Required. If selected, the integration validates the SSL certificate when connecting to the LevelBlue USM Anywhere server. Enabled by default. |


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).

### Get Alarm Details

Use the **Get Alarm Details** action to retrieve comprehensive metadata for a
specific LevelBlue USM Anywhere alarm (including priority, rule intent, attack
strategy, method, source and destination details, and suppression state) and
display it on the Case Wall.


This action doesn't run on Google SecOps entities.

> [!NOTE]
> **Note:** This action requires `Product Version` to be set to `V2` in the integration configuration. For details about the underlying endpoint, see the [Get Alarm Details API reference](https://docs.levelblue.com/api-reference/alarms/get-alarm-details).

#### Action inputs

The **Get Alarm Details** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Alarm ID` | Required. The unique identifier of the LevelBlue USM Anywhere alarm to investigate. In playbooks triggered by the **AlienVault USM Anywhere Connector**, you can map the alert ticket identifier directly to this parameter. |

#### Action outputs

The **Get Alarm Details** 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 | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **Get Alarm Details** action provides the following table on the Case Wall:

- **Table name** : `Alarm <var class="prettyprint readonly">ALARM_ID</var> Details`
- **Columns** :
  - **ID**
  - **Priority**
  - **Priority Label**
  - **Occurred Time**
  - **Received Time**
  - **Rule Intent**
  - **Rule Strategy**
  - **Rule Method**
  - **Source Name**
  - **Source Organization**
  - **Source Country**
  - **Destination Name**
  - **Destination Organization**
  - **Destination Country**
  - **Is Suppressed**

##### JSON result

The following example shows the JSON result output received when using the
**Get Alarm Details** action:

```json
{
  "uuid": "5e2ee325-7a04-b082-0842-d06a14552f59",
  "status": "open",
  "priority": 36,
  "priority_label": "medium",
  "muted": false,
  "suppressed": false,
  "timestamp_occured": 1580131109000,
  "timestamp_received": 1580131109248,
  "rule_intent": "Environmental Awareness",
  "rule_strategy": "Windows Event Created",
  "rule_method": "Windows Audit Log Cleared",
  "source_name": "192.0.2.10",
  "source_username": "example_user",
  "destination_name": "198.51.100.20",
  "sensor_uuid": "2931521a-39f9-4e0e-88f2-4a2b34610e9a",
  "events_count": 1,
  "has_alarm": true
}
```

##### Output messages

The **Get Alarm Details** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully returned details about alarm ALARM_ID.` | The action succeeded. |
| `Failed to get alarm details. Error is ERROR_REASON.` | The action failed. Verify that the specified `Alarm ID` matches an existing alarm in LevelBlue USM Anywhere and check that your OAuth 2.0 credentials have read access to alarms. |
| `This action is not supported for AlienVault Anywhere V1 integration. Please use V2.` | The action failed. Open the integration configuration in Google SecOps, change `Product Version` to `V2`, and provide valid OAuth 2.0 `ClientID` and `Secret` credentials. |

##### Script result

The following table lists the value for the script result output when using the
**Get Alarm Details** action:

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

### List Events

Use the **List Events** action to search historical security events in LevelBlue
USM Anywhere by account name, event name, source asset, date window, or
suppression status and display matching events on the Case Wall.


This action doesn't run on Google SecOps entities.

> [!NOTE]
> **Note:** This action requires `Product Version` to be set to `V2` in the integration configuration. For details about the underlying endpoint, see the [Get a Page of Events API reference](https://docs.levelblue.com/api-reference/events/get-a-page-of-events).

#### Action inputs

The **List Events** action requires the following parameters:

| Parameter | Description |
|---|---|
| `Account Name` | Optional. The LevelBlue USM Anywhere account name associated with the security events to search. |
| `Event Name` | Optional. The full or partial name of the security event to search for, such as `Kerberos service ticket was requested`. |
| `Source Name` | Optional. The hostname or IP address of the source asset that generated the security events. |
| `Start Time` | Optional. The start date of the event search range, formatted as `DD/MM/YYYY`. |
| `End Time` | Optional. The end date of the event search range, formatted as `DD/MM/YYYY`. |
| `Suppressed` | Optional. If selected, the action includes or matches events marked as suppressed in LevelBlue USM Anywhere. |
| `Events Limit` | Optional. The maximum number of matching security events to return. The default value is `100`. |

#### Action outputs

The **List Events** 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 | Not available |
| JSON result | Available |
| Output messages | Available |
| Script result | Available |

##### Case wall table

The **List Events** action provides the following table on the Case Wall:

- **Table name** : `Alien Vault Anywhere Events`
- **Columns** :
  - **ID**
  - **Occurred Time**
  - **Received Time**
  - **Subcategory**
  - **Access Control Outcome**
  - **Event Severity**
  - **Source Port**
  - **Source Name**
  - **Destination Port**
  - **Destination Name**
  - **Has Alarm**

##### JSON result

The following example shows the JSON result output received when using the
**List Events** action:

```json
[
  {
    "access_control_outcome": "OK",
    "destination_canonical": "93f4b513-5390-4a8e-be97-949956761775",
    "destination_name": "EC2AMAZ-44A6GL4",
    "destination_port": "49707",
    "destination_username": "EC2AMAZ-44A6GL4$",
    "event_category": "Access & Authentication",
    "event_name": "Kerberos service ticket was requested",
    "event_severity": "INFO",
    "event_subcategory": "Authentication",
    "has_alarm": false,
    "id": "e489d3b0-bb09-8696-e235-23da207dc9b1",
    "log": "{\"winlogbeat\":{\"record_number\":\"2369959\",\"event_id\":4769}}",
    "packet_type": "log",
    "plugin": "AlienVault NIDS",
    "plugin_device": "AlienVault Sensor",
    "plugin_device_type": "Intrusion Detection",
    "plugin_rule": "4769 - A Kerberos service ticket was requested.",
    "plugin_version": "-",
    "rep_device_address": "192.0.2.15",
    "rep_device_canonical": "93f4b513-5390-4a8e-be97-949956761775",
    "rep_device_hostname": "EC2AMAZ-44A6GL4",
    "rep_device_rule_id": "4769",
    "sensor_uuid": "2931521a-39f9-4e0e-88f2-4a2b34610e9a",
    "source_canonical": "93f4b513-5390-4a8e-be97-949956761775",
    "source_name": "EC2AMAZ-44A6GL4",
    "source_port": "49707",
    "source_process": "C:\\Windows\\System32\\lsass.exe",
    "source_userid": "S-1-5-18",
    "source_username": "example_user",
    "suppressed": false,
    "tag_names": [],
    "timestamp_occured": 1579772348000,
    "timestamp_received": 1579772350000,
    "used_hint": false,
    "was_fuzzied": false,
    "links": {
      "self": {
        "href": "https://example.alienvault.cloud/api/2.0/events/e489d3b0-bb09-8696-e235-23da207dc9b1"
      }
    }
  }
]
```

##### Output messages

The **List Events** action provides the following output messages:

| Output message | Message description |
|---|---|
| `Successfully returned EVENTS_COUNT AlienVault Anywhere events` | The action succeeded. |
| `Failed to list Alien Vault Anywhere events! Error is ERROR_REASON` | The action failed. Verify that your LevelBlue USM Anywhere server is reachable, check that your OAuth 2.0 credentials are active, and confirm that the filter values match valid account or source names. |
| `Unable to parse start time START_TIME. Valid format is DD/MM/YYYY.` | The action failed. Update the `Start Time` parameter so the day appears first, followed by the two-digit month and four-digit year (for example, `22/04/2026`). |
| `Unable to parse end time END_TIME. Valid format is DD/MM/YYYY.` | The action failed. Update the `End Time` parameter so the day appears first, followed by the two-digit month and four-digit year (for example, `29/04/2026`). |
| `This action is not supported for AlienVault Anywhere V1 integration. Please use V2.` | The action failed. Open the integration configuration in Google SecOps, change `Product Version` to `V2`, and configure valid OAuth 2.0 credentials. |

##### Script result

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

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

### Ping

Use the **Ping** action to test connectivity and verify that your configured
credentials can authenticate with the LevelBlue USM Anywhere server.


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 |
|---|---|
| `Connected successfully.` | The action succeeded. |
| `Failed to connect to the AlienVaultAnywhere! Error is ERROR_REASON` | The action failed. Verify that the `API Root` URL is accurate, check that outbound HTTPS traffic on TCP port `443` is allowed, and confirm that your `ClientID` and `Secret` values are valid. |

##### Script result

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

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

## Connectors


To learn more about configuring connectors in Google SecOps,
see [Ingest your data (connectors)](https://docs.cloud.google.com/chronicle/docs/soar/ingest/connectors/ingest-your-data-connectors.md.txt).

> [!NOTE]
> **Note:** To prevent data loss, connectors utilize **Event Flattening** . If a raw alert contains a list of entities (such as multiple email addresses, hostnames, or IP addresses), connectors automatically flatten them into separate, unique events.
>
> For example, a single raw alert containing three different email addresses is ingested as three
> separate events, each containing one distinct email address.
>
> This process ensures that every entity is correctly indexed as a unique asset, making it fully
> searchable and actionable in playbooks.

<br />

### AlienVault USM Anywhere Connector

Use the **AlienVault USM Anywhere Connector** connector to ingest security
alarms and their correlated events from LevelBlue USM Anywhere into
Google SecOps alerts and cases.

For details about alarm polling
endpoints and filter parameters, see the
[Get a Page of Alarms API reference](https://docs.levelblue.com/api-reference/alarms/get-a-page-of-alarms).

#### Connector inputs

The **AlienVault USM Anywhere Connector** connector requires the following
parameters:

| Parameter | Description |
|---|---|
| `DeviceProductField` | Required. The event field name used to populate the device product attribute in Google SecOps alerts. The default value is `device_product`. |
| `EventClassId` | Optional. The name of the field that determines the event name (subtype). The default value is `message_plugin`. |
| `PythonProcessTimeout` | Required. The timeout limit, in seconds, for the Python process that runs the current script. The default value is `60`. |
| `Api Root` | Required. The base URL of the LevelBlue USM Anywhere server, formatted as `https://SUBDOMAIN.alienvault.cloud`. |
| `ClientID` | Required. The OAuth 2.0 client ID for your LevelBlue USM Anywhere service account when `Product Version` is set to `V2`, or your account username when `Product Version` is set to `V1`. |
| `Secret` | Required. The OAuth 2.0 client secret for your LevelBlue USM Anywhere service account when `Product Version` is set to `V2`, or your account password when `Product Version` is set to `V1`. |
| `Product Version` | Required. The LevelBlue USM Anywhere authentication version to use during alarm ingestion. The possible values are as follows: - `V1` - `V2` The default value is `V2`. |
| `Verify SSL` | Required. If selected, the integration validates the SSL certificate when connecting to the LevelBlue USM Anywhere server. |
| `Max Alerts Per Cycle` | Required. The maximum number of alarms to ingest during each connector run. The default value is `10`. |
| `Max Days Backwards` | Required. The number of days prior to the first connector run from which to retrieve alarms. This parameter can apply to the initial connector iteration after you enable the connector for the first time, or the fallback value for an expired connector timestamp. The default value is `1`. |
| `Padding Period` | Optional. The lookback buffer, in hours (from `0` to `12`), subtracted from the current time when querying for new alarms. Configure this setting if sensors experience delayed log delivery into LevelBlue USM Anywhere. Values outside the `0` to `12` range reset to `0`. The default value is `0`. |
| `Show Suppressed` | Optional. If selected while `Use Suppressed Filter` is enabled, the connector ingests only suppressed alarms. If left unselected while `Use Suppressed Filter` is enabled, the connector ingests only non-suppressed alarms. |
| `Use Suppressed Filter` | Optional. If selected, the connector filters alarms based on the `Show Suppressed` setting: - **Ingest all alarms (suppressed and non-suppressed)** : Clear `Use Suppressed Filter`. - **Ingest only non-suppressed alarms** : Select `Use Suppressed Filter` and clear `Show Suppressed`. - **Ingest only suppressed alarms** : Select both `Use Suppressed Filter` and `Show Suppressed`. For more information about alarm suppression in LevelBlue USM Anywhere, see [Suppression Rules from the Orchestration Rules Page](https://docs.levelblue.com/documentation/usm-anywhere/user-guide/rules-management/suppression-rules). |
| `Priority` | Optional. A comma-separated list of alarm priority levels to ingest (for example, `high,medium`). To ingest alarms of all priorities, leave this field empty. The possible values are as follows: - `high` - `medium` - `low` |
| `Rule Intent` | Optional. Filter ingested alarms by threat intent category. The possible values are as follows: - `System Compromise` - `Exploitation & Installation` - `Delivery & Attack` - `Reconnaissance & Probing` - `Environmental Awareness` |
| `Rule Strategy` | Optional. Filter ingested alarms by the attack strategy that triggered the detection rule (for example, `Client-Side Attack - Known Vulnerability`). |
| `Rule Method` | Optional. Filter ingested alarms by the specific detection method or rule signature (for example, `Windows Audit Log Cleared`). |
| `Proxy Server Address` | Optional. The address of the proxy server to use. |
| `Proxy Username` | Optional. The proxy username to authenticate with. |
| `Proxy Password` | Optional. The proxy password to authenticate with. |

#### Connector rules

- The connector supports proxies.

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