> For the complete documentation index, see [llms.txt](https://docs.vectra.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vectra.ai/configuration/response/siem/vectra-rux-playbooks-for-microsoft-sentinel-ccf.md).

# Vectra RUX Playbooks for Microsoft Sentinel CCF

## Introduction

The Vectra RUX playbooks for Microsoft Sentinel CCF deliver automated, intelligence-driven response workflows that help security teams rapidly investigate and remediate threats detected across network, identity, and cloud environments. Each playbook is implemented as an Azure Logic App and is purpose-built to streamline a specific stage of the detection-to-response lifecycle.

The playbooks are independent of the ingestion connector architecture and function the same way whether detections are ingested using the legacy Function App connector or the CCF connector.

## Vectra RUX Playbooks — Required Roles & Permissions <a href="#vectra-rux-playbooks--required-roles--permissions" id="vectra-rux-playbooks--required-roles--permissions"></a>

#### Overview <a href="#overview" id="overview"></a>

Deploying and operating the Vectra RUX playbooks for Microsoft Sentinel requires permissions across several systems: the Vectra AI platform, Azure, Microsoft Sentinel, Azure Key Vault, and optionally Microsoft Teams and Azure Storage. This document lists every required role and permission, organized by system, and indicates whether it is needed for the initial deployment, ongoing operation, or both.

Two personas are relevant:

**Deployment Administrator** — the person who sets up the integration. Needs broad permissions to create and configure Azure resources, assign roles, and deploy Logic Apps.

**SOC Analyst** — the person who runs playbooks day-to-day from Sentinel incidents. Needs a narrower set of operational permissions.

#### Vectra AI Platform <a href="#vectra-ai-platform" id="vectra-ai-platform"></a>

<table><thead><tr><th width="182.28125">Permission</th><th width="164.96875">Role</th><th width="171.48046875">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Create API client credentials</td><td>Administrator</td><td>Deployment Administrator</td><td>Required to generate the Client ID and Client Secret stored in Key Vault. The API client must be assigned the <strong>Security Analyst</strong> role — not Administrator.</td></tr><tr><td>API client role</td><td>Security Analyst</td><td>Service Account (API Client)</td><td>The playbooks authenticate to Vectra using this client. A higher-privilege role is not required and should not be used.</td></tr></tbody></table>

**Steps:** Configuration → Access → API Clients → Add API Client → select role **Security Analyst** → record Client ID and Client Secret.

#### Azure — Resource Deployment <a href="#azure--resource-deployment" id="azure--resource-deployment"></a>

<table><thead><tr><th width="198.34375">Permission</th><th width="213.640625">Azure Built-in Role</th><th width="181.95703125">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Create and manage resource groups</td><td><strong>Contributor</strong> (resource group scope) or <strong>Owner</strong> (subscription scope)</td><td>Deployment Administrator</td><td>Required to create the resource group that will contain the Key Vault, Logic Apps, and related resources.</td></tr><tr><td>Deploy ARM templates / Logic Apps</td><td><strong>Contributor</strong> (resource group scope)</td><td>Deployment Administrator</td><td>Required to deploy playbooks from Sentinel Content Hub or ARM templates.</td></tr><tr><td>Read Azure Tenant ID</td><td>Any authenticated user</td><td>Deployment Administrator</td><td>Tenant ID is visible in <strong>Microsoft Entra ID → Overview</strong>. No elevated role required.</td></tr><tr><td>Run Azure CLI / Cloud Shell queries</td><td><strong>Reader</strong> (subscription scope)</td><td>Deployment Administrator</td><td>Required only for the <code>VectraDetectionTimelineLink</code> playbook, which uses Azure Resource Graph queries to retrieve the workbook resource ID and Log Analytics workspace ID.</td></tr></tbody></table>

#### Azure Key Vault <a href="#azure-key-vault" id="azure-key-vault"></a>

<table><thead><tr><th width="200.87890625">Permission</th><th width="218.7421875">Azure Built-in Role / Policy</th><th width="174.3515625">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Create Key Vault</td><td><strong>Contributor</strong> (resource group scope)</td><td>Deployment Administrator</td><td></td></tr><tr><td>Set Key Vault permission model to Vault access policy</td><td><strong>Owner</strong> or <strong>Key Vault Administrator</strong></td><td>Deployment Administrator</td><td>The permission model must be set to <strong>Vault access policy</strong> (not RBAC) before secrets or access policies can be configured for the playbooks.</td></tr><tr><td>Create and manage secrets</td><td><strong>Key Vault Secrets Officer</strong> or access policy with <strong>Secret Set</strong> permission</td><td>Deployment Administrator</td><td>Required to create the <code>Vectra-Client-ID</code> and <code>Vectra-Client-Secret</code> secrets before playbook deployment. Subsequent token secrets (<code>Vectra-Access-Token</code>, <code>Vectra-Refresh-Token</code>) are written automatically by the <code>VectraGenerateAccessToken</code> playbook at runtime.</td></tr><tr><td>Grant Logic App managed identities access</td><td><strong>Key Vault Administrator</strong> or Owner of the Key Vault</td><td>Deployment Administrator</td><td>After each Logic App is deployed, its system-assigned managed identity must be granted an access policy with <strong>All Key permissions</strong> and <strong>All Secret permissions</strong>. This must be repeated for every deployed playbook.</td></tr><tr><td>Retrieve secrets at runtime</td><td>Access policy with <strong>Secret Get</strong> permission</td><td>Logic App Managed Identities (service)</td><td>Granted via the access policy step above. Each Logic App managed identity only needs Get; the broader All permissions at deployment time simplify the setup.</td></tr></tbody></table>

**Important:** If the Key Vault permission model is left as the default Azure RBAC, access policies will not be available and playbooks will fail to retrieve secrets at runtime.

#### Microsoft Sentinel <a href="#microsoft-sentinel" id="microsoft-sentinel"></a>

<table><thead><tr><th width="191.94140625">Permission</th><th width="235.30859375">Azure Built-in Role</th><th width="168.203125">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Install solution from Content Hub</td><td><strong>Microsoft Sentinel Contributor</strong></td><td>Deployment Administrator</td><td></td></tr><tr><td>Configure automation permissions</td><td><strong>Microsoft Sentinel Contributor</strong></td><td>Deployment Administrator</td><td>Required to authorize the resource group containing playbooks: Configuration → Automation → Configure permissions. This grants Sentinel the ability to execute Logic Apps from automation rules.</td></tr><tr><td>Create and manage automation rules</td><td><strong>Microsoft Sentinel Contributor</strong></td><td>Deployment Administrator</td><td></td></tr><tr><td>Create and manage analytics rules</td><td><strong>Microsoft Sentinel Contributor</strong></td><td>Deployment Administrator</td><td></td></tr><tr><td>Run playbooks manually from incidents</td><td><strong>Microsoft Sentinel Responder</strong> (minimum)</td><td>SOC Analyst</td><td></td></tr><tr><td>View incidents and alerts</td><td><strong>Microsoft Sentinel Reader</strong> (minimum)</td><td>SOC Analyst</td><td></td></tr></tbody></table>

#### Azure Log Analytics Workspace (Role Assignments for Logic Apps) <a href="#azure-log-analytics-workspace-role-assignments-for-logic-apps" id="azure-log-analytics-workspace-role-assignments-for-logic-apps"></a>

Several playbooks interact with Sentinel incidents and require the **Microsoft Sentinel Contributor** role to be assigned to their system-assigned managed identity at the workspace scope. This role assignment requires **Owner** or **User Access Administrator** on the workspace.

| Playbook                               | Sentinel Contributor Required |
| -------------------------------------- | ----------------------------- |
| `VectraIncidentTimelineUpdate`         | Yes                           |
| `VectraDetectionTimelineLink`          | Yes                           |
| `VectraSetDetectionStatus`             | Yes                           |
| `VectraCloseDetectionsOnIncidentClose` | Yes                           |
| All other playbooks                    | No                            |

**Who performs this:** Deployment Administrator, using **Access control (IAM)** on the Log Analytics workspace.

**Required permission to assign this role:** **Owner** or **User Access Administrator** at the Log Analytics workspace scope.

#### Logic App API Connections <a href="#logic-app-api-connections" id="logic-app-api-connections"></a>

After each Logic App is deployed, its API connections must be manually authorized. This requires the authorizing user to have valid credentials and appropriate access to each connected service.

<table><thead><tr><th width="243.015625">Connection</th><th width="250.6875">Authorization Method</th><th>Required Access</th></tr></thead><tbody><tr><td><code>MicrosoftSentinel-*</code></td><td>Managed Service Identity</td><td>No manual authorization required</td></tr><tr><td><code>Keyvault-*</code></td><td>OAuth (Azure AD)</td><td>Any authenticated Azure user with access to the subscription</td></tr><tr><td><code>Teams-*</code></td><td>OAuth (Azure AD)</td><td>Microsoft 365 account with Teams access; must be a member of the channel used for Adaptive Cards</td></tr><tr><td><code>AzureMonitorLogs-*</code></td><td>OAuth (Azure AD)</td><td>Any authenticated Azure user with Log Analytics Reader access</td></tr><tr><td><code>Azurefile-*</code> (PCAP only)</td><td>Storage Account Access Key</td><td>Access to the Storage Account's access keys (<strong>Owner</strong> or <strong>Contributor</strong> on the Storage Account)</td></tr></tbody></table>

**Who performs this:** Deployment Administrator, immediately after each Logic App deployment.

#### Azure Storage Account (PCAP Playbook Only) <a href="#azure-storage-account-pcap-playbook-only" id="azure-storage-account-pcap-playbook-only"></a>

The `VectraDownloadPcapFileToStorage` playbook requires an Azure Storage Account with a file share.

<table><thead><tr><th width="217.76171875">Permission</th><th width="195.16796875">Azure Built-in Role</th><th width="202.69140625">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Create Storage Account and file share</td><td><strong>Contributor</strong> (resource group scope)</td><td>Deployment Administrator</td><td>The file share name must match the storage account name.</td></tr><tr><td>Read Storage Account access keys</td><td><strong>Owner</strong> or <strong>Contributor</strong> (Storage Account scope)</td><td>Deployment Administrator</td><td>Required to authorize the <code>Azurefile</code> API connection during playbook setup.</td></tr><tr><td>Write files to Azure File Storage at runtime</td><td><strong>Storage Blob Data Contributor</strong></td><td>Logic App Managed Identity</td><td>Assign via <strong>Access control (IAM)</strong> on the Storage Account.</td></tr></tbody></table>

#### Microsoft Teams <a href="#microsoft-teams" id="microsoft-teams"></a>

<table><thead><tr><th width="266.51171875">Requirement</th><th width="333.45703125">Who Needs It</th><th>Notes</th></tr></thead><tbody><tr><td>Member of the SOC Teams channel used for Adaptive Cards</td><td>Deployment Administrator (to authorize connection) and SOC Analysts (to receive and respond to cards)</td><td>A dedicated channel (e.g., <code>SOC-Automation / Vectra-SOAR</code>) is recommended.</td></tr><tr><td>Teams Group ID and Channel ID</td><td>Deployment Administrator</td><td>Retrieved from the channel URL. Required as deployment parameters for all playbooks that use Teams Adaptive Cards.</td></tr></tbody></table>

### Summary by Persona <a href="#summary-by-persona" id="summary-by-persona"></a>

#### Deployment Administrator — minimum required roles <a href="#deployment-administrator--minimum-required-roles" id="deployment-administrator--minimum-required-roles"></a>

| Scope                                | Role                                       |
| ------------------------------------ | ------------------------------------------ |
| Vectra AI Platform                   | Administrator (to create API client)       |
| Azure Subscription or Resource Group | **Owner** or **Contributor**               |
| Azure Key Vault                      | **Key Vault Administrator** (or Owner)     |
| Log Analytics Workspace (IAM)        | **Owner** or **User Access Administrator** |
| Microsoft Sentinel                   | **Microsoft Sentinel Contributor**         |
| Azure Storage Account (PCAP only)    | **Owner** or **Contributor**               |

> A single Azure account with **Owner** at the resource group scope, combined with **Microsoft Sentinel Contributor** and **Key Vault Administrator**, is sufficient to complete all deployment steps.

#### SOC Analyst — minimum required roles <a href="#soc-analyst--minimum-required-roles" id="soc-analyst--minimum-required-roles"></a>

| Scope              | Role                                 |
| ------------------ | ------------------------------------ |
| Microsoft Sentinel | **Microsoft Sentinel Responder**     |
| Microsoft Teams    | Member of the designated SOC channel |

> Analysts do not require any Azure resource management permissions for day-to-day playbook operation.

### Pre-Deployment Access Checklist <a href="#pre-deployment-access-checklist" id="pre-deployment-access-checklist"></a>

<table><thead><tr><th width="792.21484375">Requirement</th><th>Confirmed</th></tr></thead><tbody><tr><td>Vectra administrator access to create an API client</td><td>☐</td></tr><tr><td>Azure account with Contributor or Owner on target resource group</td><td>☐</td></tr><tr><td>Ability to set Key Vault permission model and manage access policies</td><td>☐</td></tr><tr><td>Ability to assign roles on the Log Analytics workspace (Owner or User Access Administrator)</td><td>☐</td></tr><tr><td>Microsoft Sentinel Contributor role</td><td>☐</td></tr><tr><td>Microsoft 365 account with Teams access to authorize Teams API connections</td><td>☐</td></tr><tr><td>Access to Storage Account access keys (if deploying PCAP playbook)</td><td>☐</td></tr><tr><td>Azure CLI / Cloud Shell access (if deploying VectraDetectionTimelineLink)</td><td>☐</td></tr></tbody></table>

## Installation

### Deployment Overview

Playbook deployment follows a two-phase process. Complete all prerequisites once before beginning, then repeat the per-playbook steps for each playbook you deploy.

**Phase 1 — One-time setup (complete before first deployment):**

1. Complete all prerequisites in the **Pre-Deployment Installation** section below
2. Verify all items in the Pre-Deployment Checklist

**Phase 2 — Per-playbook installation (repeat for each playbook):**

1. Install the playbook from the Playbook templates tab
2. Authorize API connections
3. Grant managed identity access to Key Vault
4. Grant Sentinel Contributor role *(required by some playbooks)*
5. Create Automation Rules *(recommended for some playbooks)*

> **Important:** Deploy `VectraGenerateAccessToken` before any other playbook. All dependent playbooks call it for API authentication and will fail if it is not present.

### Pre-Deployment Installation

#### Vectra API Client Credentials

The playbooks interact with the Vectra platform over API therefore Vectra API client credentials are required.

1. Log in to Vectra - Access your Vectra Respond UX portal with administrator credentials.
2. From the main menu, select Configuration → Access → API Clients.
3. Click Add API Client to open the configuration dialog
4. Provide a relevant name for the API credentials select the role Security Analyst
5. Generate the credentials and record the client id and secret

#### Azure Key Vault

The Vectra playbooks authenticate to the Vectra API using OAuth2 client credentials and must retrieve those credentials securely at runtime. Azure Key Vault provides a centralized, access-controlled secret store that keeps credentials out of Logic App definitions and workflow configurations entirely. Rather than embedding the Vectra Client ID and Client Secret directly in a playbook, each Logic App retrieves only what it needs at the moment it runs — using its managed identity to authenticate to the Key Vault. This approach also simplifies credential rotation: when a Vectra API client secret needs to be updated, only the Key Vault secret needs to change, with no modification required to any deployed playbook.

{% stepper %}
{% step %}

### Create Azure Key Vault

* Open the Azure portal and search for **Key Vaults**.
* Select **Create** and configure the following settings:

<table><thead><tr><th width="165.1640625">Setting</th><th>Recommended Value</th></tr></thead><tbody><tr><td>Subscription</td><td>Same subscription as your Microsoft Sentinel workspace</td></tr><tr><td>Resource Group</td><td>Same resource group as your Sentinel workspace and playbooks</td></tr><tr><td>Key Vault Name</td><td>A unique name for the vault</td></tr><tr><td>Region</td><td>Same region as your Sentinel workspace</td></tr><tr><td>Pricing Tier</td><td>Standard</td></tr></tbody></table>

* Select *<mark style="color:purple;">**Next**</mark>***&#x20;(not Review + Create yet).**
* Set Permission model to Vault access policy and ensure the logged in user is listed under user.

<table><thead><tr><th width="165.1640625">Setting</th><th width="521.8359375">Required Value</th></tr></thead><tbody><tr><td>Permission Model</td><td>Vault access policy</td></tr><tr><td>Resource Access</td><td>No selection required</td></tr><tr><td>Access Policies</td><td><mark style="color:$warning;"><strong>Ensure your Azure user account is listed under USER</strong></mark></td></tr></tbody></table>

* Select **Review + Create**, then **Create**.
* Once deployment completes, select **Go to resource**.
  {% endstep %}

{% step %}

### Configure Key Vault Access Policy

Under **Settings**, select **Access configuration** and confirm the Permission model is set to **Vault access policy**.

> **Note:** If this is left as Azure role-based access control (the default), access policies will not be available and the playbooks will be unable to retrieve secrets at runtime.
> {% endstep %}

{% step %}

### Populate Vectra API Client Secrets

The following secrets must be created before deploying any playbooks. Use the exact secret names shown, including capitalization — the playbooks reference these names directly.

* In your Key Vault, navigate to **Objects → Secrets**.
* Select **Generate / Import** and create each of the following secrets:

<table><thead><tr><th width="225.578125">Name</th><th>Secret Value</th></tr></thead><tbody><tr><td><code>Vectra-Client-ID</code></td><td>The Client ID from your Vectra API client</td></tr><tr><td><code>Vectra-Client-Secret</code></td><td>The Client Secret from your Vectra API client</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

#### Microsoft Teams

Several playbooks use Microsoft Teams Adaptive Cards for interactive analyst input. Retrieve the following values before deployment.

<table><thead><tr><th width="162.0625">Value</th><th>How to Retrieve</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>In Teams, select <strong>...</strong> next to the channel → <strong>Get link to channel</strong> → copy the <code>groupId=</code> GUID from the URL</td></tr><tr><td>TeamsChannelId</td><td>From the same URL, extract the value between <code>/channel/</code> and the next <code>/</code>, then URL-decode it</td></tr></tbody></table>

Use a dedicated Team and channel for SOC automation (e.g., `SOC-Automation` / `Vectra-SOAR`) to keep automated messages separate from analyst discussions.

> **Note:** TeamsGroupId and TeamsChannelId are **optional** parameters for playbooks that support both comment and Teams input methods. If omitted, the playbook exits gracefully when no structured comment is found rather than posting a Teams card.

#### Sentinel Automation Permissions

Microsoft Sentinel requires explicit permission to execute Logic Apps through Automation Rules.

1. Open Microsoft Sentinel and navigate to **Configuration → Automation**.
2. Select **Configure permissions**.
3. Select the resource group containing the deployed playbooks.
4. Select **Apply**.

#### Azure Tenant ID

The Azure Tenant ID is a required parameter when deploying playbooks.

1. Sign in to the Azure portal.
2. Navigate to **Microsoft Entra ID** (use the search box if not visible on the home screen).
3. Find the **Tenant ID** in the **Basic information** section of the Overview screen.
4. Copy the Tenant ID using the copy icon. Store it alongside the other values in the Configuration Workbook App worksheet.

### Pre-Deployment Checklist

Use this checklist to confirm all prerequisites are in place before beginning playbook installation. Detailed instructions follow.

<table><thead><tr><th width="800">Requirement</th><th>Status</th></tr></thead><tbody><tr><td>Vectra API client created with Security Analyst role and Client ID and Secret recorded</td><td>☐</td></tr><tr><td>Azure Key Vault created and name recorded</td><td>☐</td></tr><tr><td>Key Vault permission model set to Vault access policy</td><td>☐</td></tr><tr><td>Vectra secrets added to Key Vault (<code>Vectra-Client-ID</code>, <code>Vectra-Client-Secret</code>)</td><td>☐</td></tr><tr><td>Microsoft Teams Group ID obtained</td><td>☐</td></tr><tr><td>Microsoft Teams Channel ID obtained</td><td>☐</td></tr><tr><td>Sentinel automation permissions configured</td><td>☐</td></tr><tr><td>Azure Tenant ID obtained</td><td>☐</td></tr></tbody></table>

#### Installing a Playbook

All playbooks follow the same installation flow.

1. Open the Azure Portal and navigate to **Microsoft Sentinel**.
2. Select your Sentinel workspace and navigate to **Configuration → Automation**.
3. Open the **Playbook templates** tab.
4. Use the **Source** filter and select **Vectra XDR**.
5. Select the desired playbook template and click **Create playbook**.
6. In the **Parameters** tab, provide all required values (refer to the Configuration Workbook Playbook worksheet).
7. Review configuration details and click **Create**.
8. Wait for deployment to complete, then proceed to authorize API connections and configure Key Vault access for the Logic App.

#### Standard Parameters

Most playbooks share the following base parameters. Playbook-specific parameters are listed in each playbook section.

| Parameter                      | Description                                                                                  |
| ------------------------------ | -------------------------------------------------------------------------------------------- |
| PlaybookName                   | Name for the deployed Logic App. Keep the default name unless you have a reason to rename it |
| KeyVaultName                   | Name of the Azure Key Vault storing Vectra credentials and tokens                            |
| TenantId                       | Azure AD Tenant ID                                                                           |
| BaseURL                        | Vectra API base URL (e.g., `https://tenant.region.portal.vectra.ai`)                         |
| GenerateAccessCredPlaybookName | Name of the deployed VectraGenerateAccessToken playbook                                      |

{% hint style="info" %}

#### Pay close attention to the BaseURL - do NOT include the trailing slash.

{% endhint %}

#### Authorizing API Connections

After deployment, all API connections used by the playbook must be authorized before the playbook can run.

1. Open the deployed Logic App.
2. Navigate to **Development Tools → API Connections**.
3. Open each connection listed and select **Edit API Connection**.
4. Select **Authorize**, sign in with valid Azure credentials, and click **Save**.
5. Repeat for all connections.

> **Note:** The `MicrosoftSentinel` connection uses Managed Service Identity and does not require manual authorization steps.

**Azure File Storage (PCAP playbook only):** The `Azurefile` connection requires a Storage Account Access Key rather than OAuth authorization.

1. Navigate to your Storage Account → **Security + Networking → Access keys**.
2. Click **Show keys** and copy either `key1` or `key2`.
3. Open the **Edit API Connection** for the Azurefile connection and paste the key into the **Azure Storage Account Access Key** field.
4. Click **Save**.

#### Configuring Key Vault Access for Logic Apps

Each Logic App uses a system-assigned managed identity to retrieve secrets from Key Vault at runtime. Configure this after deployment for every playbook.

1. Open the Logic App and navigate to **Settings → Identity**.
2. Copy the **Object (principal) ID**.
3. Open Azure Key Vault and navigate to **Settings → Access Policies**.
4. Click **Create**, select **All** for both Key permissions and Secret permissions, and click **Next**.
5. Paste the Object ID into the Principal search, select the Logic App identity, and proceed through **Next → Review and create → Create**.

#### Granting Sentinel Contributor Role

Some playbooks make modifications to Sentinel incidents and require the **Microsoft Sentinel Contributor** role to do so. Not all playbooks require this role assignment. Each playbook that requires this role is outlined in the individual playbook below.

1. Open **Log Analytics Workspaces** and select your workspace.
2. Select **Access control (IAM)** and click **Add role assignment**.
3. Search for **Microsoft Sentinel Contributor**, select it, and click **Next**.
4. Under **Members**, select **Managed identity** and click **Select members**.
5. Search for the playbook by name. If multiple results appear, confirm the correct one by matching the associated resource group.
6. Select the playbook identity and proceed through **Review + assign**.

The following playbooks require Sentinel Contributor:

* `VectraIncidentTimelineUpdate (Note: this playbook is not compatible with Microsoft Defender XDR attached workspaces)`
* `VectraDetectionTimelineLink`
* `VectraSetDetectionStatus`
* `VectraCloseDetectionsOnIncidentClose`

#### Creating Automation Rules

Some playbooks are designed to run automatically through Sentinel Automation Rules. While running them manually from an incident is always supported, the playbooks listed below are most effective when attached to automation rules so they trigger without analyst intervention.

To create an Automation Rule:

1. In Microsoft Sentinel, navigate to **Configuration → Automation**.
2. Select **Create → Automation rule**.
3. Configure the trigger condition (e.g., incident created, incident updated, status changed).
4. Under **Actions**, select **Run playbook** and choose the target playbook.
5. Save the rule.

The following playbooks work best with automation triggers:

| Playbook                                                         | Recommended Trigger                              |
| ---------------------------------------------------------------- | ------------------------------------------------ |
| VectraIncidentTimelineUpdate                                     | When incident is created or updated              |
| VectraAssignStaticUserToEntity / VectraAssignDynamicUserToEntity | When incident status changes to Active           |
| VectraSetDetectionStatus                                         | When incident status changes to Active or Closed |
| VectraDetectionTimlineLink                                       | When incident is Created                         |

#### Working Example

Since all playbooks require VectraGenerateAccessToken to function, let's install and configure that playbook first. This playbook requires:

* Authorizing API Connections
* Access to Key Vault

To install this playbook:

1. Open the Azure Portal and navigate to **Microsoft Sentinel**.
2. Select your Sentinel workspace and navigate to **Configuration → Automation**.
3. Open the **Playbook templates** tab.
4. Use the **Source** filter and select **Vectra XDR**.
5. Select **Vectra Generate Access Token** and click **Create playbook**.
6. Make sure the appropriate Resource Group and Region populated and don't change the Playbook name.
7. In the **Parameters** tab, provide all required values
8. Review configuration details and click **Create**.
9. Wait for deployment to complete, then proceed to authorize API connections and configure Key Vault access for the Logic App.

#### Parameters

<table><thead><tr><th width="300.07421875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>Azure Key Vault</td><td>vault.azure (keep the default)</td></tr><tr><td>KeyVaultName</td><td>Name of the Azure Key Vault storing Vectra credentials and tokens</td></tr><tr><td>TenantId</td><td>Azure AD Tenant ID</td></tr><tr><td>BaseURL</td><td>Vectra API base URL (e.g., <code>https://tenant.region.portal.vectra.ai</code>)</td></tr></tbody></table>

{% hint style="info" %}

#### Pay close attention to the BaseURL - do NOT include the trailing slash.

{% endhint %}

#### Authorizing API Connections

1. Navigate to **Development Tools → API Connections**.
2. Select **Keyvault-VectraGenerateAccessToken** listed and select **General > Edit API Connection**.
3. Select **Authorize**, sign in with valid Azure credentials, and click **Save**.

#### Configuring Key Vault Access for Logic Apps

1. Open the Logic App and navigate to **Settings → Identity**.
2. Copy the **Object (principal) ID**.
3. Open Azure Key Vault and navigate to **Settings → Access Policies**.
4. Click **Create**, select **All** for both Key permissions and Secret permissions, and click **Next**.
5. Paste the Object ID into the Principal search, **select** the Logic App identity, and proceed through **Next → Review and create → Create**.

#### Creating Automation Rules

Not required for this playbook.

#### Granting Sentinel Contributor Role

Not required for this playbook.

#### **Test this critical playbook to ensure it's working properly.**

1. Navigate back o **Overview** in the main menu for the VectraGenerateAccessToken Logic App.
2. Select **Run**, to test the playbook.
3. Select **Refresh** to retrieve the Status.
4. Verify the Status is **Succeeded** after it completes running.
5. If the playbook fails, select the failed run to open the playbook and review it to see where it's failing and resolve as appropriate.

{% hint style="info" %}

#### For additional confirmation, navigate to the Key Vault and review the Secrets. A successful run will have generated and populated Vectra-Access-Token and Vectra-Refresh-Token.

{% endhint %}

## Playbooks

#### Playbook Categories

| Category              | Purpose                                            |
| --------------------- | -------------------------------------------------- |
| Authentication        | Generate and manage OAuth tokens                   |
| Detection Operations  | Close, reopen, remediate, and tag detections       |
| Entity Operations     | Add notes, tags, assignments, and group membership |
| Incident Enrichment   | Decorate incidents and synchronize timelines       |
| Assignment and Triage | Assign ownership and resolve Vectra assignments    |
| Notifications         | Send Teams notifications and escalation prompts    |
| Evidence Collection   | Download PCAP files                                |
| Extensibility         | Provide starter workflows for customization        |

**Authentication**

| Playbook                  | Purpose                                                                                             |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| VectraGenerateAccessToken | Generates and refreshes OAuth access tokens; stored in Key Vault for use by all dependent playbooks |

**Detection Operations**

| Playbook                          | Purpose                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------ |
| VectraCloseDetections             | Closes one or more detections with a closure reason of Remediated or Benign          |
| VectraOpenClosedDetections        | Reopens previously closed detections                                                 |
| VectraSetDetectionStatus          | Automatically acknowledges or closes detections based on Sentinel incident status    |
| VectraAddNoteToDetections         | Adds a note to all detections associated with a Vectra entity                        |
| VectraAddTagToDetections          | Adds one or more tags to all active detections associated with a Vectra entity       |
| VectraAddTagToSelectedDetections  | Adds tags to analyst-selected detections from the entity's detection list            |
| VectraAddTagToEntityAllDetections | Adds tags to every detection associated with an entity, including fixed and inactive |

**Entity Operations**

| Playbook                         | Purpose                                                               |
| -------------------------------- | --------------------------------------------------------------------- |
| VectraAddNoteToEntity            | Adds a note to a Vectra entity                                        |
| VectraAddTagToEntity             | Adds one or more tags to a Vectra entity                              |
| VectraStaticAssignMemberToGroup  | Adds an entity to a predefined Vectra group                           |
| VectraDynamicAssignMemberToGroup | Interactively selects a Vectra group and assigns the entity via Teams |

**Assignment Operations**

| Playbook                        | Purpose                                                                            |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| VectraAssignStaticUserToEntity  | Assigns a predefined Vectra user to the entity associated with a Sentinel incident |
| VectraAssignDynamicUserToEntity | Prompts an analyst via Teams to select and assign a Vectra user to the entity      |

**Triage Operations**

| Playbook                         | Purpose                                                               |
| -------------------------------- | --------------------------------------------------------------------- |
| VectraStaticAssignMemberToGroup  | Adds an entity to a predefined Vectra group                           |
| VectraDynamicAssignMemberToGroup | Interactively selects a Vectra group and assigns the entity via Teams |

**Evidence Collection**

| Playbook                        | Purpose                                                                                     |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| VectraDownloadPcapFileToStorage | Retrieves PCAP files for specified detections from Vectra and uploads them to Azure Storage |

**Incident Enrichment**

| Playbook                     | Purpose                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| VectraIncidentTimelineUpdate | Synchronizes and deduplicates Vectra alerts in the Sentinel incident timeline                        |
| VectraDetectionTimelineLink  | Posts a comment on new incidents with the detection ID and a link to the Detection Timeline workbook |

### Authentication Operations

#### Vectra Generate Access Token

**This playbook is mandatory and must be deployed before all others.**

The Vectra Generate Access Token playbook is the foundational authentication component. It securely generates and refreshes OAuth access tokens and stores them in Azure Key Vault. All other Vectra playbooks call this playbook to obtain tokens for Vectra API authentication.

> **Important:** Do not rename this playbook. All dependent playbooks reference it by its default name and will fail if the name is changed.

<table><thead><tr><th width="215.00390625">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Azure Key Vault</td></tr><tr><td>Trigger</td><td>Invoked automatically by dependent playbooks — not run manually</td></tr><tr><td>Customization</td><td>Not required or supported</td></tr></tbody></table>

To complete the deployment of this playbook, follow the documented flow above to:

[Authorize required API connections](#authorizing-api-connections)

`Keyvault-VectraGenerateAccessToken`

[Grant the playbook key vault access](#configuring-key-vault-access-for-logic-apps)

### Detection Operations

#### Vectra Close Detections

Allows analysts to close one or more detections associated with a Vectra entity, specifying a closure reason of **Remediated** or **Benign**. The playbook first checks the incident Activity Log for structured comments; if none are found, it prompts the analyst via a Microsoft Teams Adaptive Card.

<table><thead><tr><th width="211.1953125">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Minimal. May be renamed.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="215.76171875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraCloseDetections`
* `Keyvault-VectraCloseDetections`
* `Teams-VectraCloseDetections`

**Method 1 — Incident comment**

Add a structured comment to the incident before running the playbook. The playbook reads it and closes the detections automatically. Small formatting mistakes will cause the playbook to fail.

```
close_dets:7270,7801
reason:Benign
```

Line breaks are mandatory. Accepted reasons: `Benign` or `Remediated`.

**Method 2 — Teams Adaptive Card**

If no valid comment is found, the playbook posts a Teams card with the following fields:

<table><thead><tr><th width="216.1328125">Field</th><th>Description</th></tr></thead><tbody><tr><td>Detections to Close</td><td>Multi-select — close multiple detection IDs in a single run</td></tr><tr><td>Closure Reason</td><td>Dropdown: Benign or Remediated</td></tr></tbody></table>

> **Note:** If the incident contains a valid `tag:` comment, the Teams card will not appear. Delete all `tag:` comments and re-run to re-enable the Teams input path.

#### Vectra Open Closed Detections

Allows analysts to reopen one or more previously closed detections associated with a Vectra entity. Follows the same comment-or-Teams input pattern as Vectra Close Detections.

<table><thead><tr><th width="204.4921875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Minimal. May be renamed.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="203.7109375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraOpenClosedDetections`
* `Keyvault-VectraOpenClosedDetections`
* `Teams-VectraOpenClosedDetections`

**Method 1 — Incident comment**

```
open_dets:7270,7801
```

**Method 2 — Teams Adaptive Card**

<table><thead><tr><th width="203.5859375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Detections to Reopen</td><td>Multi-select — reopen multiple detection IDs in a single run</td></tr></tbody></table>

> **Note:** If the incident contains a valid `tag:` comment, the Teams card will not appear. Delete all `tag:` comments and re-run to re-enable the Teams input path.

#### Vectra Close Detections on Incident Close

Allows analysts to close the detection in Vectra when the Incident in Sentinel is closed. The close reason from Sentinel is automatically passed into Vectra.

<table><thead><tr><th width="211.1953125">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault</td></tr><tr><td>Trigger</td><td>Automated — run from Sentinel incident automation</td></tr><tr><td>Customization</td><td>Minimal. May be renamed.</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraCloseDetectionsOnIncidentClose`
* `Keyvault-VectraCloseDetectionsOnIncidentClose`

**How it works:**

The playbook reads the current Sentinel incident closure status and acts accordingly:

| Incident Status                   | Action in Vectra                            |
| --------------------------------- | ------------------------------------------- |
| Closed (True Positive)            | Closes detections with reason: `remediated` |
| Closed (any other classification) | Closes detections with reason: `benign`     |

**Recommended automation rules:**

<table><thead><tr><th width="219.4140625">Trigger</th><th>Condition</th><th>Action</th></tr></thead><tbody><tr><td>When incident is updated</td><td>Status changed to <strong>Closed</strong></td><td>Run <code>VectraCloseDetectionsOnIncidentClose</code>→ closes detections with mapped reason</td></tr></tbody></table>

#### Vectra Set Detection Status

Automatically updates the investigation status of all detections associated with a Vectra entity based on the current state of the Sentinel incident. This playbook has no Teams card and no comment input method — it operates entirely automatically based on the incident.

<table><thead><tr><th width="205.98046875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault</td></tr><tr><td>Trigger</td><td>Automation Rule — triggered by incident status changes</td></tr><tr><td>Customization</td><td>Not required</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraSetDetectionStatus`
* `Keyvault-VectraSetDetectionStatus`

**Assign Sentinel Contributor Role**

This playbook also requires Sentinel Contributor. Retrieve the Logic App Identity ObjectID and then proceed to Log Analytics Workspaces.

Select your workspace and then **Access Control IAM > Add - Role Assignment**.

Under **Job Function Roles**, search for **Microsoft Sentinel Contributor** and select **Next**.

Paste in the Logic App identity (objectID) as the member and **Review and Assign** to completion.

**How it works:**

The playbook reads the current Sentinel incident status and acts accordingly:

| Incident Status                   | Action in Vectra                            |
| --------------------------------- | ------------------------------------------- |
| Closed (True Positive)            | Closes detections with reason: `remediated` |
| Closed (any other classification) | Closes detections with reason: `benign`     |
| Active (not Closed)               | Sets detections to `acknowledged`           |

**Recommended automation rules:**

<table><thead><tr><th width="219.4140625">Trigger</th><th>Condition</th><th>Action</th></tr></thead><tbody><tr><td>When incident is updated</td><td>Status changed to <strong>Active</strong></td><td>Run <code>VectraSetDetectionStatus</code> → acknowledges detections</td></tr><tr><td>When incident is updated</td><td>Status changed to <strong>Closed</strong></td><td>Run <code>VectraSetDetectionStatus</code> → closes detections with mapped reason</td></tr></tbody></table>

#### Vectra Add Note To Detections

Allows analysts to add a note to all detections associated with a Vectra entity from within a Sentinel incident. The playbook iterates over each detection ID linked to the entity and adds the note to each one individually. Follows the same comment-or-Teams input pattern as Vectra Add Note To Entity.

<table><thead><tr><th width="205.765625">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Note text is provided at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="206.16796875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Optional. Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Optional. Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddNoteToDetections`
* `Keyvault-VectraAddNoteToDetections`
* `Teams-VectraAddNoteToDetections`

**Method 1 — Incident comment**

```
note: [your note text here]
```

**Method 2 — Teams Adaptive Card**

If no valid comment is found, the playbook posts a Teams card with a free-text note input. The note is then applied to every detection associated with the entity.

> **Note:** If the incident contains a valid `tag:` comment, the Teams card will not appear. Delete all `tag:` comments and re-run to re-enable the Teams input path.

#### Vectra Add Tag To Detections

Allows analysts to add one or more tags to the desired detection. The playbook fetches existing tags for each detection and merges the new tags, preserving any tags already applied. Follows the same comment-or-Teams input pattern as Vectra Add Tag To Entity.

<table><thead><tr><th width="205.9921875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Tags are analyst-defined at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="206.078125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Optional. Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Optional. Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddTagToDetections`
* `Keyvault-VectraAddTagToDetections`
* `Teams-VectraAddTagToDetections`

**Method 1 — Incident comment**

```
tag: [tag name]
```

**Method 2 — Teams Adaptive Card**

Enter comma-separated tags in the Teams card. The tags are merged with any existing tags on each detection — existing tags are not overwritten.

> **Note:** If the incident contains a valid `tag:` comment, the Teams card will not appear. Delete all `tag:` comments and re-run to re-enable the Teams input path.

#### Vectra Add Tag To Entity Selected Detections

Allows analysts to add one or more tags to specific detections selected from the entity's detection list. Input is collected exclusively via Microsoft Teams — there is no comment-based input method.

<table><thead><tr><th width="205.69921875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Tags and detection selection are analyst-defined at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="206.37109375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddTagToEntitySelectedDetections`
* `Keyvault-VectraAddTagToEntitySelectedDetections`
* `Teams-VectraAddTagToEntitySelectedDetections`

**Teams Adaptive Card workflow:**

When triggered, the playbook posts a card with the following fields:

<table><thead><tr><th width="206.15234375">Field</th><th>Description</th></tr></thead><tbody><tr><td>Entity ID / Entity Type</td><td>Displayed for context</td></tr><tr><td>Tag values</td><td>Free-text. Enter one or more comma-separated tags. Tags may include spaces</td></tr><tr><td>Detections to tag</td><td>Multi-select dropdown. Each entry shows Detection ID and detection name</td></tr></tbody></table>

After submission, the specified tags are applied to the selected detections only.

Tag input format:

```
tag1, tag with space, workflow_tag_3
```

#### Vectra Add Tag To Entity All Detections

Allows analysts to add one or more tags to every detection associated with a Vectra entity, including active, fixed, and inactive detections. Input is collected exclusively via Microsoft Teams — there is no comment-based input method.

<table><thead><tr><th width="205.68359375">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Tags are analyst-defined at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.69921875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddTagToEntityAllDetections`
* `Keyvault-VectraAddTagToEntityAllDetections`
* `Teams-VectraAddTagToEntityAllDetections`

**Teams Adaptive Card workflow:**

When triggered, the playbook posts a card displaying Entity ID, Entity Type, and a free-text tag input field. All tags are applied to every detection tied to the entity upon submission.

Tag input format:

```
tag1, tag with space, tag_three
```

### Entity Operations

#### Vectra Add Note To Entity

Allows analysts to add a note directly to a Vectra entity from within a Sentinel incident. Supports structured comment input or a Teams Adaptive Card fallback. Basic markdown is supported in the note text.

<table><thead><tr><th width="205.93359375">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Note text is provided at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.9765625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Optional. Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Optional. Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddNoteToEntity`
* `Keyvault-VectraAddNoteToEntity`
* `Teams-VectraAddNoteToEntity`

**Method 1 — Incident comment**

```
note: [your note text here]
```

Only the text inside the brackets is added to the Vectra entity. Basic markdown (`**bold**`, `*italic*`, `[link](url)`) is supported, but some styles may not render correctly when using the comment method.

**Method 2 — Teams Adaptive Card**

If no valid comment is found, the playbook posts a Teams card displaying the Entity ID, Entity Type, and a free-text field for the note. Markdown is fully supported via the Teams input path.

| Category      | Details                                              |
| ------------- | ---------------------------------------------------- |
| Connectors    | Microsoft Sentinel, Azure Key Vault, Microsoft Teams |
| Trigger       | Manual — run from a Sentinel incident                |
| Customization | Not required. Note text is provided at runtime.      |

| Parameter      | Description                                       |
| -------------- | ------------------------------------------------- |
| TeamsGroupId   | Optional. Teams group for Adaptive Card prompts   |
| TeamsChannelId | Optional. Teams channel for Adaptive Card prompts |

#### Vectra Add Tag To Entity

Allows analysts to assign one or more tags to a Vectra entity from a Sentinel incident. Supports a single tag via incident comment or multiple tags via Teams Adaptive Card.

<table><thead><tr><th width="206.05078125">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident</td></tr><tr><td>Customization</td><td>Not required. Tags are analyst-defined at runtime.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.921875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Optional. Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Optional. Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAddTagToEntity`
* `Keyvault-VectraAddTagToEntity`
* `Teams-VectraAddTagToEntity`

**Method 1 — Incident comment**

```
tag: [tag name]
```

Only one tag is supported via comment. Multiple tags in comments will not work.

**Method 2 — Teams Adaptive Card**

If no valid comment is found, the playbook posts a Teams card. Enter one or more comma-separated tags:

```
tag1, tag with space, tag_three
```

Tags may include spaces and must not be enclosed in brackets.

> **Note:** If the incident contains a valid `tag:` comment, the Teams card will not appear. Delete all `tag:` comments and re-run to re-enable the Teams input path.

### Assignment Operations

#### Vectra Assign Static User To Entity

Automatically assigns a predefined Vectra User ID to the entity associated with a Sentinel incident. Useful when a single SOC owner is responsible for all entity triage or when automated, non-interactive assignment is required for Vectra operational metrics.

<table><thead><tr><th width="206.29296875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault</td></tr><tr><td>Trigger</td><td>Automation Rule (recommended) or manual</td></tr><tr><td>Customization</td><td>Required — a Vectra User ID must be supplied at deployment</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="206.42578125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Predefined Vectra User ID to assign to all entities</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAssignStaticUserToEntity`
* `Keyvault-VectraAssignStaticUserToEntity`

**Retrieving the Vectra User ID:**

```
GET /api/v3.4/users
```

Use the `id` field from the response (e.g., `39`) as the `UserId` parameter.

**Recommended automation rule:** Trigger when incident status changes from **New → Active**.

> **Important:** Use either Vectra Assign Static User To Entity or Vectra Assign Dynamic User To Entity in automation rules — not both. Running both simultaneously may create conflicting assignments.

#### Vectra Assign Dynamic User To Entity

Allows an analyst to select a Vectra user from a Teams Adaptive Card dropdown and assign that user to the entity associated with a Sentinel incident. The dropdown is populated dynamically from the Vectra user list at runtime.

<table><thead><tr><th width="205.63671875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Automation Rule (recommended) or manual</td></tr><tr><td>Customization</td><td>Not required</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.53125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraAssignDynamicUserToEntity`
* `Keyvault-VectraAssignDynamicUserToEntity`
* `Teams-VectraAssignDynamicUserToEntity`

**Teams Adaptive Card workflow:**

The card displays Entity ID, Entity Type, and a dropdown of available Vectra users (ID + Email + Role). The operator selects the appropriate user and submits. The selected user is immediately reflected as the Assigned User in Vectra.

**Recommended automation rule:** Trigger when incident status changes from **New → Active**.

> **Important:** Use either Vectra Assign Static User To Entity or Vectra Assign Dynamic User To Entity in automation rules — not both.

### Triage Operations

#### Vectra Static Assign Member To Group

Assigns one or more members to a specific Vectra group. This playbook is not launched from a Sentinel incident — it is designed for standalone use, run directly from Logic Apps or via a manual trigger.

<table><thead><tr><th width="206.2734375">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run directly from Logic Apps or automation trigger</td></tr><tr><td>Customization</td><td>Required — clone and hardcode the Group ID for each target group</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.53515625">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `Keyvault-VectraStaticAssignMemberToGroup`
* `Teams-VectraStaticAssignMemberToGroup`

**Customization required:**

This playbook must be cloned and customized for each Vectra group:

1. Clone the playbook.
2. Open it in the Logic App Designer.
3. Locate the `Initialize Group ID` variable and replace the placeholder with the actual numeric Group ID.
4. Save and re-authorize the cloned playbook.

To retrieve Group IDs:

```
GET /api/v3.4/groups
```

**Recommended naming convention:** `VectraAssignTo-GroupName` (e.g., `VectraAssignTo-SafeUsers`).

**Teams Adaptive Card workflow:**

The card prompts the operator to provide the Group ID (unless pre-configured via cloning) and one or more member values. Ensure member values match the format expected by the group type — for example, IP addresses for IP-type groups.

#### Vectra Dynamic Assign Member To Group

Enables operators to search, filter, select, and assign members to Vectra groups interactively through a multi-step Teams Adaptive Card workflow. Ideal for environments with many groups where static hard-coded assignment is impractical.

<table><thead><tr><th width="206.16796875">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Azure Key Vault, Microsoft Teams</td></tr><tr><td>Trigger</td><td>Manual — run directly from Logic Apps or automation trigger</td></tr><tr><td>Customization</td><td>Not required</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="206.34375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr></tbody></table>

**Required API connections to authorize:**

* `Keyvault-VectraDynamicAssignMemberToGroup`
* `Teams-VectraDynamicAssignMemberToGroup`

**Teams Adaptive Card workflow — three steps:**

**Step 1 — Filter groups:**

<table><thead><tr><th width="205.53125">Field</th><th>Description</th></tr></thead><tbody><tr><td>Group Type</td><td>Case-sensitive. Examples: <code>ip</code>, <code>account</code>, <code>domain</code>, <code>host</code>, <code>mac</code></td></tr><tr><td>Group Description (optional)</td><td>Case-insensitive keyword filter. Narrows the group list</td></tr></tbody></table>

**Step 2 — Select group:**

The playbook queries Vectra and returns a filtered list of matching groups. The operator selects the desired group from the dropdown.

**Step 3 — Provide member:**

Enter the member value to assign (e.g., an IP address, domain name, or username). The playbook has no syntax validation — ensure the value matches the format required for that group type.

### Evidence Collection

#### Vectra Download Pcap File To Storage

Allows analysts to retrieve PCAP files for specific Vectra detections directly from the Vectra platform and upload them to an Azure Storage Account for investigation and evidence collection.

The storage account requires a share that has the same name as the storage account. Ensure this share exists prior to running the playbook.

<table><thead><tr><th width="205.55859375">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Key Vault, Microsoft Teams, Azure File Storage</td></tr><tr><td>Trigger</td><td>Manual — run from a Sentinel incident or directly via Logic Apps</td></tr><tr><td>Customization</td><td>Not required. Storage file share names may be adjusted if needed.</td></tr></tbody></table>

**Additional parameters:**

<table><thead><tr><th width="205.7734375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>TeamsGroupId</td><td>Teams group for Adaptive Card prompts</td></tr><tr><td>TeamsChannelId</td><td>Teams channel for Adaptive Card prompts</td></tr><tr><td>StorageAccountName</td><td>Azure Storage Account used to store downloaded PCAP files</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraDownloadPcapFileToStorage`
* `Keyvault-VectraDownloadPcapFileToStorage`
* `Teams-VectraDownloadPcapFileToStorage`
* `Azurefile-VectraDownloadPcapFileToStorage` *(requires Storage Account Access Key — see Authorizing API Connections)*

**Teams Adaptive Card workflow:**

When triggered, the playbook posts a Teams card prompting the analyst to provide one or more detection IDs. Upon submission:

1. The playbook requests the PCAP file(s) from the Vectra API.
2. Each PCAP is downloaded and uploaded to the default Azure Storage file share.
3. Files are stored with a consistent naming structure for retrieval.

**Best practices:**

* Confirm that detections have PCAPs available in Vectra before triggering the playbook.
* Ensure Storage Account access policies are configured for the Logic App managed identity (Storage Blob Data Contributor).
* Use a private Teams channel for sensitive evidence workflows.
* Align PCAP retention with your organization's forensics and compliance requirements.

### Incident Enrichment

#### Vectra Incident Timeline Update

Ensures the Microsoft Sentinel incident timeline always reflects the most accurate, current, and deduplicated set of Vectra alerts associated with an entity. When triggered, the playbook retrieves the latest detections and entity scoring alerts, merges them into the incident timeline, and removes or relocates duplicate entries so only the latest unique Vectra alerts appear.

<table><thead><tr><th width="205.9765625">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Monitor Logs</td></tr><tr><td>Trigger</td><td>Automation Rule (recommended) or manual</td></tr><tr><td>Customization</td><td>Not required or supported</td></tr></tbody></table>

**Additional parameters:**

| Parameter     | Description                                  |
| ------------- | -------------------------------------------- |
| WorkspaceName | Name of the Sentinel Log Analytics workspace |

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraIncidentTimelineUpdate`
* `AzureMonitorLogs-VectraIncidentTimelineUpdate`

**How it works:**

The playbook performs three operations:

1. Retrieves the latest Vectra detections and entity scoring alerts via Azure Monitor Logs.
2. Compares them against the current incident timeline.
3. Adds new unique alerts to the incident timeline and removes duplicate or outdated entries. Older versions of alerts are moved to the Entity Timeline but removed from the main Incident Timeline.

The result is a clean, non-duplicated, analyst-friendly incident timeline.

**Recommended automation rule:** Trigger when a new alert is added to the incident.

| Category      | Details                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| Connectors    | Microsoft Sentinel, Azure Key Vault, Microsoft Teams, Azure File Storage |
| Trigger       | Manual — run from a Sentinel incident or directly via Logic Apps         |
| Customization | Not required. Storage file share names may be adjusted if needed.        |

{% hint style="info" icon="triangle-exclamation" %}
This playbook is not compatible with Microsoft Defender XDR attached workspaces.
{% endhint %}

#### Vectra Detection Timeline Link

Adds comment to incident to direct SOC Analyst to appropriate workbook to continue investigation.

#### Obtain Workbook and Workspace Parameters

This playbook requires special attributes that should be captured prior to beginning this playbook installation:

* WorkspaceName
* WorkspaceId
* WorkbookResourceId

{% hint style="info" icon="triangle-exclamation" %}
This playbook requires **VectraRUXDetectionTimeline** workbook to be saved to My Workbooks before proceeding.
{% endhint %}

**Step 1 – Obtain WorkbookResourceId**

Open Azure CLI Cloud Shell to run this command.\
Replace `<resource-group>` with the Resource Group containing the Vectra workbook and run:

```
az graph query -q "resources | where type =~ 'microsoft.insights/workbooks' | where resourceGroup =~ '<resource-group>' | project DisplayName=tostring(properties.displayName), WorkbookId=name, ResourceId=id | where DisplayName contains 'VectraRUXDetectionTimeline'" --query "data[].{DisplayName:DisplayName, WorkbookId:WorkbookId, ResourceId:ResourceId}" -o table
```

Example:

```
az graph query -q "resources | where type =~ 'microsoft.insights/workbooks' | where resourceGroup =~ 'rg-vectra-ccf' | project DisplayName=tostring(properties.displayName), WorkbookId=name, ResourceId=id | where DisplayName contains 'VectraRUXDetectionTimeline'" --query "data[].{DisplayName:DisplayName, WorkbookId:WorkbookId, ResourceId:ResourceId}" -o table
```

Record the value from the **ResourceId** column as:

```
WorkbookResourceId
```

***

**Step 2 – Obtain WorkspaceName and WorkspaceId**

Replace `<resource-group>` with the Resource Group containing the Log Analytics workspace and run:

```
az monitor log-analytics workspace list --resource-group <resource-group> --query "[].{WorkspaceName:name,WorkspaceId:id}" -o table
```

Example:

```
az monitor log-analytics workspace list --resource-group rg-vectra-ccf --query "[].{WorkspaceName:name,WorkspaceId:id}" -o table
```

Example output:

```
WorkspaceName    WorkspaceId
---------------  -------------------------------------------------------------------
la-vectra-ccf    /subscriptions/.../providers/Microsoft.OperationalInsights/workspaces/la-vectra-ccf
```

Record:

```
WorkspaceName
```

and

```
WorkspaceId
```

for use during playbook deployment.

<table><thead><tr><th width="205.9765625">Category</th><th>Details</th></tr></thead><tbody><tr><td>Connectors</td><td>Microsoft Sentinel, Azure Monitor Logs</td></tr><tr><td>Trigger</td><td>Automation Rule (recommended) or manual</td></tr><tr><td>Customization</td><td>Not required or supported</td></tr></tbody></table>

**Required API connections to authorize:**

* `MicrosoftSentinel-VectraDetectionTimelineLink`

**Assign Sentinel Contributor Role**

This playbook also requires Sentinel Contributor. Retrieve the Logic App Identity ObjectID and then proceed to Log Analytics Workspaces.

Select your workspace and then **Access Control IAM > Add - Role Assignment**.

Under **Job Function Roles**, search for **Microsoft Sentinel Contributor** and select **Next**.

Paste in the Logic App identity (objectID) as the member and **Review and Assign** to completion.

**How it works:**

The playbook adds a comment to the calling incident that includes a pointer to the workbook to aid with rapid investigation.

## Troubleshooting

| Problem                                                | Likely Cause                                                       | Recommended Action                                                                               |
| ------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Authentication failures                                | Missing or incorrect Key Vault secrets                             | Verify `Vectra-Client-ID`, `Vectra-Client-Secret`, and `Vectra-Base-URL` secret names and values |
| Token generation fails                                 | VectraGenerateAccessToken missing or misconfigured                 | Deploy and validate VectraGenerateAccessToken before deploying dependent playbooks               |
| Playbook cannot retrieve secrets                       | Managed identity lacks Key Vault access                            | Grant the Logic App managed identity an access policy with All Key and All Secret permissions    |
| Teams cards do not appear                              | Teams connection not authorized or Group/Channel IDs are incorrect | Reauthorize the Teams API connection and verify Group ID and Channel ID values                   |
| Adaptive Card submitted but workflow does not continue | Teams connector authorization expired                              | Reauthorize the Teams API connection in the Logic App                                            |
| PCAP download fails                                    | Storage account permissions missing                                | Verify the Logic App managed identity has Storage Blob Data Contributor on the storage account   |
| Playbook does not run from incident                    | Sentinel automation permissions not configured                     | Configure Sentinel automation permissions for the resource group containing the playbooks        |
| Automation rule does not trigger                       | Rule trigger condition or order mismatch                           | Review the automation rule trigger, conditions, and rule execution order                         |
| Vectra API call fails with 403                         | Insufficient API client role                                       | Confirm the Vectra API client has the Security Analyst role                                      |
| Vectra API call fails with 401                         | Expired or missing OAuth token                                     | Check VectraGenerateAccessToken is deployed and the Key Vault token secret is being refreshed    |
| Sentinel Contributor actions fail                      | Sentinel Contributor role not assigned                             | Grant the Logic App managed identity the Microsoft Sentinel Contributor role on the workspace    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vectra.ai/configuration/response/siem/vectra-rux-playbooks-for-microsoft-sentinel-ccf.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.