> This is part 1 of 5 of the full documentation (pages 1–100 of 454).
> The content is paginated: fetch every part to see all of it.
> Next part: https://docs.expel.io/llms-full.txt/1
> Page index: https://docs.expel.io/llms.txt

# 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
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.expel.io/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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

---

# Expel Documentation

Connect your technologies, learn about Expel Workbench™ features, and more in our documentation.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover-dark data-type="image">Cover image (dark)</th></tr></thead><tbody><tr><td>Get Started</td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FEPEcFtLhrtAXcsNdZ2Qx%2FTeamwork-OnLight-icon.png?alt=media&amp;token=3cfe2da7-2dbc-4c80-a46d-effa0f9d9131">Teamwork-OnLight-icon.png</a></td><td><a href="/workbench-setup/get-started">Get Started</a></td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FAf8OWaWfaUGHKvJWMuSk%2FTeamwork-OnDark-icon.png?alt=media&amp;token=d9c2fab7-5baf-4cc6-a8ea-ed133f669784">Teamwork-OnDark-icon.png</a></td></tr><tr><td>Expel Integrations</td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FyuxiEcsNkrVSB6LG7xh8%2FExpel-workbench-OnLight-icon.png?alt=media&amp;token=cfbe76ad-03e0-4dd1-bd54-b016f0574c09">Expel-workbench-OnLight-icon.png</a></td><td><a href="/connect-your-technology/about-integrations/expel-integrations">Expel Integrations</a></td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FESkTg5qX7lufjbL925ZR%2FExpel-workbench-OnDark-icon.png?alt=media&amp;token=890aaaa5-e6c2-48ac-b351-7ca6599e2d44">Expel-workbench-OnDark-icon.png</a></td></tr><tr><td>Get Support</td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FbSME4EY1omHFnpp7mvpX%2Fcommunication-OnLight-icon.png?alt=media&amp;token=3ce09179-d325-4427-8044-6950dd4b20e5">communication-OnLight-icon.png</a></td><td><a href="/support">How to Reach Us</a></td><td data-object-fit="contain"><a href="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FBL46rRRsJTjnzcHGyyYQ%2Fcommunication-OnDark-icon.png?alt=media&amp;token=ad7a6972-a49f-441f-a1ec-45f45e43a53c">communication-OnDark-icon.png</a></td></tr></tbody></table>


# Get Started

Welcome to Expel! The Customer Success team will reach out to you to assist, but the items below are what we plan to complete with you within 30 days of onboarding.

The order presented below is a suggested, but not strict order. Addressing these items is critical to considering your onboarding complete.

{% hint style="info" icon="user-crown" %}
Indicates an [Organization Admin ](/workbench-setup/get-started/add-and-manage-users/user-role-rights)user must complete the step.
{% endhint %}

{% stepper %}
{% step %}

### [Activate Your Workbench Account](/workbench-setup/get-started/activate-your-workbench-account)

Set up your account and log in!
{% endstep %}

{% step %}

### <i class="fa-user-crown" style="color:$info;">:user-crown:</i> [Add and Manage Users](/workbench-setup/get-started/add-and-manage-users)&#x20;

Invite others at your organization to Workbench, manage roles, lock or delete users, and more.
{% endstep %}

{% step %}

### [Manage Your Profile and User Account Settings](/workbench-setup/get-started/manage-your-profile-and-user-account-settings)

Reset your password, enable email notifications, toggle dark mode and more.
{% endstep %}

{% step %}

### <i class="fa-user-crown" style="color:$info;">:user-crown:</i> [Configure Your SSO Provider with Workbench](/workbench-setup/get-started/configure-your-sso-provider-with-workbench)

Allow Workbench users in your organization to log in via SSO.
{% endstep %}

{% step %}

### [Set Up Notifications](/workbench-setup/get-started/set-up-notifications)

Configure notifications to receive communication about your environment.&#x20;

{% hint style="info" %}
The ability to configure notifications depends on user role and notification type.
{% endhint %}
{% endstep %}

{% step %}

### <i class="fa-user-crown" style="color:$info;">:user-crown:</i> [Add and Manage Org Context](/workbench-setup/get-started/add-and-manage-org-context)

Add additional reference information so that our SOC analysts can act more efficiently during an incident.
{% endstep %}

{% step %}

### <i class="fa-user-crown" style="color:$info;">:user-crown:</i> [Connect Your Technologies](/workbench-setup/get-started/connect-your-technologies)

Start integrating your tech with Expel Workbench.
{% endstep %}

{% step %}

### <i class="fa-user-crown" style="color:$info;">:user-crown:</i> [Enable Auto Remediations](/workbench-setup/get-started/enable-auto-remediations)

Familiarize yourself with which remediation actions can be automated and begin setup.
{% endstep %}

{% step %}

### [Learn More about Workbench](/workbench-setup/get-started/learn-more-about-workbench)

You're off to a great start! Dive deeper into what Workbench has to offer.
{% endstep %}
{% endstepper %}


# Activate Your Workbench Account

This topic covers how to set up your account and begin using Workbench.

{% hint style="info" %}
**You must install an authenticator application such as Duo Mobile or Google Authenticator on your smartphone or other portable device with a built-in camera, or log in via SSO.** Expel requires non-SSO users to set up their Workbench account with multi-factor authentication (MFA) and to use it every time they log in.
{% endhint %}

Expel Workbench lets you see everything Expel is doing for you. It enables you to connect your technologies, manage various Expel-related settings, view your incidents and alerts, and toggle functionality like auto remediations. Here's how to get your account set up:

### Non-SSO Users <a href="#h_01j9xwekr8arj7edng6240yrgn" id="h_01j9xwekr8arj7edng6240yrgn"></a>

1. Check your inbox for a "Welcome to Expel" email.
   * This email includes a link to activate your Expel Workbench account.
   * If you haven’t received the email (or can't find it), [reach out to support](/support) we can resend it.
2. Select **Set Up My Account** and follow the instructions to configure your password and set up MFA with an authenticator app of your choice. You will have the option to scan a QR code or enter a secret key to add the account to the authenticator app.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FysNDwSoG5c6GiLKId58Z%2Factivate-mfa.png?alt=media&amp;token=6b8b366b-d17d-482a-8559-53a7bcdf61e8" alt="Step 2: Enable multi-factor authentication prompt in Workbench instructs you to install an MFA app and use it to scan the presented barcode. Optionally you may enter a code generated by your app." width="335"><figcaption></figcaption></figure></div>
3. You can now log in to Workbench using your email address (the one that received the Welcome email), the password you just created, and your authenticator app.

{% hint style="success" icon="bookmark" %}
Bookmark <https://workbench.expel.io/auth/login> for quick access to the login page.
{% endhint %}

### SSO Users <a href="#h_01j9xwefwyk6yqwnw37zq1ssqw" id="h_01j9xwefwyk6yqwnw37zq1ssqw"></a>

Look for the Workbench app in your organization's SSO platform and use it to log in. If you do not see it, contact the appropriate support person at your organization to get it added.


# Add and Manage Users

This topic covers how to manage users in Expel Workbench, as well as how to resolve first-time login issues.

{% hint style="info" icon="user-crown" %}
You must be an [Organization Admin user](/workbench-setup/get-started/add-and-manage-users/user-role-rights) to add and manage other users in Workbench.
{% endhint %}

## Prerequisites <a href="#h_01jaznwt5ympmw4b504k1s0tcb" id="h_01jaznwt5ympmw4b504k1s0tcb"></a>

1. **All users must install an authenticator application such as Duo or Google Authenticator on their smartphone or other portable device with a built-in camera, or log in via SSO.** Expel requires non-SSO users to set up their Workbench account with multi-factor authentication (MFA) and to use it every time they log in.
2. You must have Organization Admin permissions in Workbench to manage users.

## Add a User Account <a href="#h_01j0vpwav478894tewydxrgcwe" id="h_01j0vpwav478894tewydxrgcwe"></a>

Adding users to Workbench allows other members of your organization to monitor the status of your environment. Before you add a user, make sure you know the level of access the user needs ( organization analyst or organization admin). Administrator rights should not be assigned to everyone. [Learn more about user role rights in Expel Workbench.](/workbench-setup/get-started/add-and-manage-users/user-role-rights)

**If your organization uses SSO for logins, you must make sure that every new Workbench user is also assigned the Workbench app in your SSO provider.** To configure SSO in Workbench, go to [Connect Your Single Sign-On Tools](/workbench-setup/get-started/configure-your-sso-provider-with-workbench) and follow the instructions for your provider, then return to this setup guide.

To add a user to your organization:

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > Users**.
3. In the upper right, select **Add User**.
4. The Add User screen appears. Complete the following:
   * **Email/Username** - this must be an email address.
   * **Organization** - select the organization this user should have access to. If you don't have multiple organizations, this list isn't available.
   * **First name** - the user's first name.
   * **Last name** - the user's last name.
   * **Workbench user role** - select Organization Admin or Organization Analyst role for this user. *Keep in mind that Organization Admin gives full administrator rights to your organization's Workbench.*
   * **Organization Contact** - select if you want this user to be the point of contact for your organization if Expel needs to reach out.
   * **Assignable** - select if you want this user to be assigned alerts, actions, or investigations. For example, an analyst needs to see these. An admin may not need to see them.
5. Select **Save**.
6. SSO logins only - you must now also add (or ask someone at your organization to add) the Workbench app to the SSO platform for the user.

The new user account will appear with a "Locked" status until it is [activated](/workbench-setup/get-started/activate-your-workbench-account). After the user activates their account, the status will change to "Active" or "Assignable" based on the settings you chose.

## Edit a User Account <a href="#h_01htezy9bpd826jha875bzntt4" id="h_01htezy9bpd826jha875bzntt4"></a>

To edit user information or settings:

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > Users**.
3. Select the dropdown arrow next to the user whose account you want to edit.
4. Select **View and edit**.
5. Select **Edit User** to make necessary changes.
6. Select **Save**.

{% hint style="info" %}
To edit user **email notifications**, refer to [Manage Email Notifications](/workbench-setup/notifications/manage-email-notifications#manage-email-notifications-for-a-user-admins-only).
{% endhint %}

## Lock or Unlock a User Account <a href="#h_01j0y2x7e5p1f0wcpj9dgx87mq" id="h_01j0y2x7e5p1f0wcpj9dgx87mq"></a>

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > Users**.
3. Select the dropdown arrow next to the user you want to lock or unlock.
4. Select **Lock** or **Unlock**, depending on their current status.
5. The account status changes accordingly. (There is no confirmation message.)

{% hint style="info" %}
If a user's status reads "Locked - Re-enrollment sent" on their page, it means the user needs to check their email for an activation invitation. For instructions, see [Activate Your Workbench account](/workbench-setup/get-started/activate-your-workbench-account).
{% endhint %}

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F5UcTgexw9cyPjrsYyTMX%2Fuser-locked-not-activated.png?alt=media&amp;token=82752eb6-fe46-46b9-aec0-890048e03326" alt="Example indicates user John Smith has a status of Locked - Reenrollment sent" width="375"><figcaption></figcaption></figure></div>

## Delete a User Account <a href="#h_01j0y3yj9recxex7es78k0ses4" id="h_01j0y3yj9recxex7es78k0ses4"></a>

{% hint style="warning" %}
If you perform this action, account access is revoked immediately and permanently. The account no longer appears in the list. However, the user's activity history is still available.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > Users**.
3. Select the dropdown arrow next to the user you intend to delete.
4. Select **Delete user**.
5. Select **Delete**.
6. Workbench confirms the action with a "Successfully deleted user" message in the lower right.

## Resolve First-Time Login Issues <a href="#h_01jaznxhn76ygez3w9q3f38bra" id="h_01jaznxhn76ygez3w9q3f38bra"></a>

### SSO Users <a href="#h_01jaznxwxdf9pzx5j4594jmtf4" id="h_01jaznxwxdf9pzx5j4594jmtf4"></a>

SSO users must have the Workbench app added to their SSO platform by an administrator at your company. Their Workbench account must also use the same email address that is used by that platform.

1. First, verify that the user has the Workbench app in their SSO platform *and* that they have used the app (not a URL) to try to log in.
   * If they do not see the app, contact the appropriate support person at your organization to get it added.
2. If they do have the app but their login is failing, check their account in Workbench.
   * [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
   * Select **Organization Settings > Users**.
   * Look for the user and verify that their email address matches the email used for their SSO platform.
   * If it does not, use the arrow to select **View and edit** and then select the **Edit User** button to update their email address.

If the user is still unable to log in after following these steps, [contact support](/support) for help.

### Non-SSO Users <a href="#h_01j0vq877brxteyrsn4p6ypfe7" id="h_01j0vq877brxteyrsn4p6ypfe7"></a>

Non-SSO users should have received a "Welcome to Expel" email that includes a link to activate their account.

1. First, verify that the user tried to access their account via the link in the Welcome email (not via a Workbench URL).
   * If they cannot find the Welcome email, continue with this process.
   * If the link did not work, [contact support](/support) for help.
2. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
3. Select **Organization Settings > Users**.
4. Look for the user.
   * Verify with the user that their email address is the one you see listed in Workbench.
   * If you need to update the user's email address, use the arrow to select **View and edit** and then select the **Edit User** button to update their email address, then return to the list of users.
   * Use the arrow to select **Resend enrollment email**.

If the user is still unable to log in after following these steps, [contact support](/support) for help.


# User Role Rights

Learn how Expel features relate to Workbench user roles.

{% hint style="info" %}
At least these rights are available in Workbench. However, this list can change at any time and may not be accurate at any given viewing.
{% endhint %}

Workbench has two user roles: **Organization Admin** or **Organization Analyst**. Keep in mind that Organization Admin gives full administrator rights to your organization's Workbench.

Any user can be designated *assignable* by selecting a checkbox in the User profile. After a user is assignable:

* Their name appears in "Assign to" menus.
* Their initials are visible to other Expel users after an alert or action is assigned to them.

<table><thead><tr><th width="187">Feature</th><th>Action</th><th>Organization Admin</th><th>Organization Analyst</th></tr></thead><tbody><tr><td>Assign</td><td>assign to customer user</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Assemblers</td><td>view page</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>create/edit/delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Auto remediations</td><td>enable/disable</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>view</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>BOLO</td><td>view page</td><td>API only</td><td>API only</td></tr><tr><td>Customer context</td><td>view page</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>add context</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Customer configuration<sup>[1]</sup></td><td>view/edit</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Hunting</td><td>view hunts (org specific with hunting service)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Investigative actions</td><td>pivot to console</td><td>API only</td><td>API only</td></tr><tr><td>Investigation findings</td><td>create/edit/delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Investigation remediations</td><td>create/edit/delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Timeline</td><td>upload CSV</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>add/edit timeline event</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>My profile</td><td>edit email notifications</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>change password</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>reset Google Auth</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>edit user</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>"assignable" checkbox</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>"locked" checkbox</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Navigation bar</td><td>change organizations</td><td>Multi-org only</td><td>Multi-org only</td></tr><tr><td>My organization</td><td>view page</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Organizations list</td><td>view page</td><td>Multi-org only</td><td>Multi-org only</td></tr><tr><td></td><td>edit</td><td>Multi-org only</td><td></td></tr><tr><td></td><td>configure/edit PagerDuty integration</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>show PagerDuty service key</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>configure/edit Ticketing integration</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Organization Notifications</td><td>view</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>add, edit, delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Resilience</td><td>view all recommendations</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>show/hide recommendations</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td>Security devices</td><td>view page</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>add, edit, delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Workbench integrations (PD, ticketing, etc.)</td><td>configure/edit</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>test connection</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td>Users</td><td>view page</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td></tr><tr><td></td><td>"assignable" checkbox</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>change own role</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>change username</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>add, edit, delete</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>lock other users ("locked" checkbox)</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr><tr><td></td><td>resend enrollment email</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span></td><td></td></tr></tbody></table>

<sup>\[1]</sup> Customer configuration defaults can only be created by expel\_admin but overrides can be set per customer by org\_admin. However, each configuration has internal write and visibility properties that can further change who can view or edit the setting to SYSTEM, EXPEL, or ORGANIZATION.


# Manage Your Profile and User Account Settings

This section of Workbench allows you to manage aspects of your account.

To access your Profile, select the box in the upper right corner and select **Manage account** in the dropdown.

{% hint style="info" %}
You can also access this page by going to **Organization Settings > Your Profile**.
{% endhint %}

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fx7PrxwubLHPYablSaeoM%2Fwb_profilecorner_manageaccount.png?alt=media&amp;token=2e282b68-9753-4479-8910-17260adbd63d" alt="Manage account button in Workbench Profile flyout." width="171"><figcaption></figcaption></figure></div>

See below to learn more about the various options in your Profile.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F4UMvWcEPbRl21APX58PU%2Fwb_profile_areas_labeled.png?alt=media&amp;token=e8af8ca0-52da-44bb-89ae-e240ea61cfdc" alt="Areas of interest highlighted in Workbench UI."><figcaption></figcaption></figure></div>

A. **Change password and Reset Multifactor Authenticator**\
Use these links to reset your password or Multifactor Authenticator app.

B. **Account Details**\
This section provides information about you, including account status, activity, role, and more.

C. **Edit User**\
Select **Edit User** to change your email/username, first and last name, and other options depending on your user role.

D. **Email Notifications**\
This tab allows you to toggle [email notifications](/workbench-setup/notifications/manage-email-notifications) on or off, and select the conditions under which you will receive notifications. You may also opt into an **email digest** that will send a daily or weekly summary of open actions assigned to your organization.

<details>

<summary>Set Up an Email Digest</summary>

**About Email Digests**

An email digest is a scheduled summary of open [remediation](/workbench-reference/expel-terminology#remediation-action) and [investigative actions](/workbench-reference/expel-terminology#investigative-action) assigned to your organization. The digests provide you an accessible way to reference actions and see what needs to be completed in Workbench.

When you receive the email, the subject line will read: *Open actions assigned to your organization*

Each section lists the total number of open actions and includes:

* The name of the open action
* A link to the investigation
* A link to view open actions in Workbench&#x20;

**Configure an Email Digest**

1. [Log in to Workbench](https://workbench.expel.io/).
2. Select **Organization Settings > My Profile**.
3. Select **Email Notifications**.
4. In the Email Digest section, select **Add Digest**.
5. Select the frequency to receive the digest.

   For example, Weekly on Monday at 13:00 UTC.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F9DHv01KsICfsZrfCbyGm%2FEmail_digest_set_freq_result.png?alt=media&amp;token=3d92a4de-1975-4f55-ab63-d7b7fb419786" alt="Example shows email digest frequency set to Weekly on Monday at 13:00 UTC." width="375"><figcaption></figcaption></figure></div>
6. Select **Save**.

You can edit or delete existing digests via the pencil or trash can icon on a particular digest.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FVHFRAQgEcIHFkVRoK5T5%2FDigest_Hover_icons.png?alt=media&amp;token=97b419be-45c9-426c-95b3-71c36e37b10a" alt="Digest edit and delete options in Workbench."><figcaption></figcaption></figure></div>

</details>

E. **Preferences**\
This tab allows you to:

* Choose from a list of Workbench dashboards or pages and set one as your homepage.&#x20;
* Toggle context highlighting on or off.
* Apply filtering: Expel Managed Phishing subscribers can opt to filter data by phishing service, MDR service, or both.
* Apply a color theme including light or dark modes, or default to your device's theme setting.

F. **Support**\
Easily access links to submit a support ticket or visit the documentation.


# Configure Your SSO Provider with Workbench

Enable Workbench users in your organization to log in via SSO.

This guide provides instructions for specific Single Sign-On (SSO) providers and generic instructions useful for any SSO provider that supports SAML. Workbench logins **do not support System for Cross-domain Identity Management (SCIM)**. It only supports SAML and local logins.

{% hint style="info" icon="user-crown" %}
You must be an [Organization Admin user](/workbench-setup/get-started/add-and-manage-users/user-role-rights) to manage SSO.
{% endhint %}

{% tabs %}
{% tab title="Generic SAML SSO" %}
These instructions are for use with any SSO provider that supports SAML.

1. In Expel Workbench, navigate to **Organization Settings > My Organization** and select the organization.
2. Select the **Integrations** tab.
3. In the Single Sign-on section, select **Configure SSO**.
4. Copy and paste the following information from Expel Workbench into your SSO provider:
   * **ACS URL or Single Sign-on URL** can also be referred to as Assertion Consumer Service URL or Redirect URL.
   * **Audience URI or Audience** can also be referred to as SP Entity or SP Entity ID.
   * **ACS URI Validator** may not be required, depending on your SSO provider.
5. Leave **Yes, allow users to log in locally OR via SSO** selected for local logins. This makes initial SSO setup easier. You can change this later.
6. Select **Next**.
7. In your SSO provider, configure an email parameter or attribute. The attribute name in Workbench is case sensitive, so make sure the attribute name is `email` and not `Email`. You may need to create a custom attribute to ensure this. Refer to your SSO provider’s documentation to complete this step.
8. Select **Next**.
9. Copy and paste the appropriate information from your SSO provider into Expel Workbench:
   * **Single Sign-On URL or SAML 2.0 Endpoint** can also be referred to as the Login URL.
   * **Issuer or Issuer ID** can also be referred to as Identity Provider Issuer or Entity ID.
   * **Certificate** - copy and paste it into the field or upload as an attachment.
10. Select **Save**.
11. Before signing in with SSO, ensure that:
    * In your SSO provider, Workbench is assigned to all intended users.
    * The user email addresses in your SSO provider match the email configured for the users in Workbench. The email addresses are case-sensitive.
    * New members of your organization that need access to Workbench have user accounts created in Workbench and have Workbench assigned to them in your Identity Provider.
    * After you finish testing and setting up, you can disable local logins by completing these steps in Workbench:
      1. Navigate to **Organization Settings > Integrations tab**.
      2. Select **Edit** from the SSO list.
      3. Select **No, users can ONLY log in via SSO**.
      4. Save by selecting **Next > Next > Save**.
         {% endtab %}

{% tab title="Azure SSO" %}

1. Log in to your **Azure** console.
2. In the search bar at the top, search for **Enterprise Applications** and navigate to it.
3. On the page, select **New Application**.
4. On the **Add your own application** page, provide a name for the application and click **Add**.
5. On the newly created application page, on the left menu bar, under **Manage**, click **Properties**.
6. &#x20;Upload our logo and click **Save**. You can right-click this image and save it locally.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FKmnVM605ncDzYiudjsnQ%2FRGB_Expel_Logo_Black-Green.png?alt=media&amp;token=4e36d8a2-c4c4-4201-88c8-8cd6480c0321" alt="Expel logo in black and green color scheme." width="188"><figcaption></figcaption></figure></div>
7. Click **Overview** on the left menu bar to navigate to the application’s overview page.
8. Click **Set up single sign-on**.
9. For Select a single sign-on method, click **SAML**.

   You are now on the SAML-based Sign-on page in Azure.
10. Edit section 1- Basic SAML Configuration.
11. Open a new tab or window and log in to Expel Workbench (<https://workbench.expel.io>).
12. Navigate to **Organization Settings > My Organization** and select the organization.
13. On the Integrations tab, click **Single Sign-on > Configure SSO**.
14. Copy and paste the following from Expel Workbench into Azure:
    * **ACS URL or Single Sign-on URL → Reply URL (Assertion Consumer Service URL).**
    * **Audience URI or Audience → Identifier (Entity ID).** \
      \
      *You can put anything in this field. We recommend this value, but if your value naming standards are different, follow your standards. However, on step 17, be consistent and use this exact value or URI there, too.*<br>
    * Leave **Yes, allow users to log in locally OR via SSO** selected for local logins. This makes initial SSO setup easier. You can change this later.
15. In Azure, edit **Single sign-on** section 2 **User Attributes & Claims**, click **Add new claim**.
16. In the **Manage Claim** view, configure the settings as follows:

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FI2dHevHPqd4IR0fadXmb%2Fimage.png?alt=media&amp;token=ddbbb046-ef88-4e46-b4ed-fe00fea97431" alt="Manage claim settings include email as the name, Attribute for the source, and user.mail selected as the source attribute." width="375"><figcaption></figcaption></figure></div>

    * **Name -** enter "email" (case-sensitive).
    * **Namespace** - leave empty.
    * **Source** - select **Attribute**.
    * Select the appropriate value for your organization for **Source attribute**. This field populates each user’s email address, and can be different from the example shown.
    * &#x20;Select **Next**.
17. In Azure, navigate back to **Single sign-on** on the left menu bar. Copy the following values from Azure into Expel Workbench.
    * **Login URL → Single Sign-on URL or SAML 2.0 Endpoint.**
    * **Default Entity ID → Issuer or Issuer ID** or if you chose a different value in step 14, use that exact value or URI here.
    * **Certificate (Base64) → Certificate.**
18. In Expel Workbench, click **Save**.

{% hint style="warning" %}
&#x20;Before signing in with SSO, make sure that:

* In your SSO provider, Workbench is assigned to all intended users.
* The user email addresses in your SSO provider match the email that's configured for the users in Workbench. The emails are case sensitive.
* New members of your organization that need access to Workbench have user accounts created in Workbench and have Workbench assigned to them in your Identity Provider.
* After you finish testing and setting up, in Workbench, you can disable local logins by going to the **Integrations** tab in **Organization Settings**. Click **Edit** from the SSO list, and click **No, users can ONLY log in via SSO**. Then save by clicking **Next > Next > Save**.
  {% endhint %}
  {% endtab %}

{% tab title="Okta SSO" %}

1. Log into your **Okta** console.
2. Navigate to **Applications** in the main top navigation.
3. Click **Add Application > Create New App**.
4. The settings should be as follows:
   * **Platform** - Web.
   * **Sign on method** - SAML 2.0.
   * Click **Create**.

     *This screen can look slightly different depending on your Okta account.*
5. Under General Settings:

   * **App name** - Expel Workbench.
   * Upload our logo and click **Save**. You can right-click this image and save it locally.

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FKmnVM605ncDzYiudjsnQ%2FRGB_Expel_Logo_Black-Green.png?alt=media&amp;token=4e36d8a2-c4c4-4201-88c8-8cd6480c0321" alt="Expel logo in black and green." width="188"><figcaption></figcaption></figure></div>
   * Click **Next**.

   You are now on the Configure SAML step in Okta. Copy information from Expel Workbench to complete the integration.
6. Open a new tab or window and [log in to Expel Workbench](https://workbench.expel.io/).
7. Navigate to **Organization Settings > My Organization** and select the organization.
8. On the Integrations tab, click **Single Sign-on > Configure SSO**.
9. Copy and paste the following from Expel Workbench into Okta:
   * **ACS URL or Single Sign-on URL → Single sign on URL**
   * **Audience URI or Audience → Audience URI (SP Entity ID)**
   * Leave **Yes, allow users to log in locally OR via SSO** selected for local logins. This selection makes initial SSO setup easier. You can change this later.
10. In Okta, in (A) SAML Settings, under Attribute Statements (Optional):
    * For **Name**, enter "email", and select **user.email** from the Value list.

      *These fields are case sensitive.*
    * Click **Next**.
11. For the Okta feedback form, do one of the following:
    * Select **I’m an Okta customer adding an internal app** and fill in the following optional information as you see fit.
    * Select **This is an internal app that we have created**.
12. Click **Finish**.
13. In Okta under Sign On, click **Settings > View Setup Instructions**.
14. In Expel Workbench, click **Next** two times, until you see Step 3 of 3.
15. Copy and paste the following from Okta into Expel Workbench.
    * **Identity Provider Single-Sign-On URL → Single Sign-On URL or SAML 2.0 Endpoint**
    * **Identity Provider Issuer → Issuer or Issuer ID**
    * **X.509 Certificate → Certificate**
16. Click **Save** in Expel Workbench.

{% hint style="warning" %}
&#x20;Before signing in with SSO, make sure that:

* In your SSO provider, Workbench is assigned to all intended users.
* The user email addresses in your SSO provider match the email that's configured for the users in Workbench. The emails are case sensitive.
* New members of your organization that need access to Workbench have user accounts created in Workbench and have Workbench assigned to them in your Identity Provider.
* After you finish testing and setting up, in Workbench, you can disable local logins by going to the **Integrations** tab in **Organization Settings**. Click **Edit** from the SSO list, and click **No, users can ONLY log in via SSO**. Then save by clicking **Next > Next > Save**.
  {% endhint %}
  {% endtab %}

{% tab title="OneLogin SSO" %}

1. Log into your OneLogin Console and navigate to **Administration** in the top right corner.
2. Navigate to **Applications > Add App**.
3. Search for "SAML" and select **SAML Test Connector (IdP w/attr w/ sign response)**.
4. Under Portal:
   * **Display Name** - enter "Expel Workbench".
   * Upload our logo and click Save. You can right-click this image and save it locally.

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FKmnVM605ncDzYiudjsnQ%2FRGB_Expel_Logo_Black-Green.png?alt=media&amp;token=4e36d8a2-c4c4-4201-88c8-8cd6480c0321" alt="Expel logo in black and green." width="188"><figcaption></figcaption></figure></div>
   * Click **Save**.
5. Select **Configuration** in the left navigation.

   Copy information from Expel Workbench to complete the integration.
6. Open a new tab or window and [log in to Expel Workbench](https://workbench.expel.io/).
7. Navigate to **Organization Settings > My Organization** and select the organization.
8. On the Integrations tab, click **Single Sign-on > Configure SSO**.
9. Copy and paste the following from Expel Workbench into OneLogin:
   * **ACS URL or Single Sign-on URL → ACS (Consumer) URL.**
   * **Audience URI or Audience → Audience.**
   * **ACS URI Validator → ACS (Consumer) URI Validator.**
   * Leave **Yes, allow users to log in locally OR via SSO** selected for local logins. This makes initial SSO setup easier. You can change this later.
10. In Expel Workbench, click **Next**.
11. In OneLogin, in Parameters, do the following:
    * Click the “+” button on the left to add a new parameter.
    * For Field name, type the word "email" and select **Include SAML assertion**. Click **Save**.
12. Click **Save** in the upper right corner.
13. For Value, select **Email** from the list and click **Save**.
14. Navigate to SSO in the left navigation.
15. Right-click and open in a new tab or window **View Details** under the X.509 Certificate.
16. Copy and paste the X.509 Certificate from OneLogin into Expel Workbench.
17. Back in the SSO window, copy and paste the following from OneLogin into Expel Workbench:
    * **SAML 2.0 Endpoint (HTTP)→ Single Sign-On URL or SAML 2.0 Endpoint.**
    * **Issuer URL → Issuer or Issuer ID.**
18. Click **Save** in Expel Workbench.
19. Click **Save** in OneLogin.

{% hint style="warning" %}
Before signing in with SSO, make sure that:

* In your SSO provider, Workbench is assigned to all intended users.
* The user email addresses in your SSO provider match the email that's configured for the users in Workbench. The emails are case sensitive.
* New members of your organization that need access to Workbench have user accounts created in Workbench and have Workbench assigned to them in your Identity Provider.
* After you finish testing and setting up, in Workbench, you can disable local logins by going to the **Integrations** tab in **Organization Settings**. Click **Edit** from the SSO list, and click **No, users can ONLY log in via SSO**. Then save by clicking **Next > Next > Save**.
  {% endhint %}
  {% endtab %}
  {% endtabs %}

When SSO is enabled, it will show as **Active** in your **Organization Settings > Integrations** tab.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F4tf9eYh85wuEXBTQKrBY%2Fwb_SSO_active_enabled.png?alt=media&amp;token=bd9acf1b-43d9-4abd-be2c-0eb7fb7c4182" alt="ACTIVE tag in the Single Sign-On section of Workbench indicates SSO logins are enabled."><figcaption></figcaption></figure></div>


# Set Up Notifications

You can use more than one type of notification to receive messages about your environment.

Expel will be handling much of the work for you, but there will still be actions that require your response or items you will want to be aware of.

Determine who on your team should be receiving notifications and which [type](/workbench-setup/notifications/about-notifications#notification-types) of notification.

Familiarize yourself and begin setup by learning more:

* [About Notifications](/workbench-setup/notifications/about-notifications)
* [Video: Understanding Workbench Notifications](/resources/video-library/understanding-workbench-notifications)
* [Setup Guides](/workbench-setup/notifications/platform-setup)

{% hint style="success" icon="display-chart-up" %}
Beyond the two types of Workbench notifications, you may also subscribe to notifications from [Expel's Status Page](https://status.expel.io/).
{% endhint %}


# Add and Manage Org Context

Org Context refers to stored reference information about your environment that you are able to manage.

You can add or edit this information on the Org Context page ([Organization Settings > Context](https://workbench.expel.io/settings/context)).

## Prerequisites

1. <i class="fa-user-crown" style="color:$info;">:user-crown:</i> You must be an [Organization Admin](/workbench-setup/get-started/add-and-manage-users/user-role-rights) user in Workbench to add Org Context.

## Why Add Org Context

When an Investigation becomes flagged as an incident, Expel must do some work on your behalf to contain or resolve the issue. To do this, we perform a number of [Investigative Actions](/workbench-reference/expel-terminology#investigative-action) that sometimes result in us asking you to complete a manual verification of some kind (received by you as a Verify Action).

Adding reference information as Org Context can eliminate some of these Verify Actions, because we can refer to it during all of our investigative activities to see if the answer to a manual verification question has already been provided. **The more Org Context you add, the less Verify Actions will be needed from you, and the more efficiently our SOC analysts can act when an incident occurs.**

We encourage you to add as much reference information for each [type of Org Context](#types-of-org-context) as you can during your onboarding, and to actively maintain it over time. However, there is some [Org Context that is more useful to our SOC than others](#which-org-context-is-most-helpful-to-the-soc), so you should focus on those types if your ability to perform this task is limited.

## Types of Org Context

We currently support all of the following types of Org Context:

| <p><strong>Context Type</strong></p><p><em>Select it from the dropdown menu in Workbench.</em></p> | <p><strong>Examples</strong></p><p><em>Enter this type of reference information.</em></p>                                                                                                                                                |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cidr\_block                                                                                        | <ul><li>Network IP ranges (we also ask for these on the Welcome screen)</li><li>Correct CIDR formatting example: 192.0. 2.0/24 </li></ul>                                                                                                |
| domain                                                                                             | <ul><li>Domains specific to your organization that Expel should know about</li></ul>                                                                                                                                                     |
| email\_address                                                                                     | <ul><li>Email addresses of key individuals at your organization</li></ul>                                                                                                                                                                |
| file\_hash                                                                                         | <ul><li>File hash(es) that map to applications used by your organization</li><li>Hash functions: MD5, SHA-1, and/or SHA-256</li></ul>                                                                                                    |
| hostname                                                                                           | <ul><li>Hostnames used or maintained by your organization</li></ul>                                                                                                                                                                      |
| ip\_address                                                                                        | <ul><li>IP addresses used or maintained by your organization</li></ul>                                                                                                                                                                   |
| port                                                                                               | <ul><li>TCP or UPD ports used by your organization </li></ul>                                                                                                                                                                            |
| url                                                                                                | <ul><li>URLs used or maintained by your organization</li></ul>                                                                                                                                                                           |
| username                                                                                           | <ul><li>A username specific to a member of your organization</li></ul>                                                                                                                                                                   |
| other (string)                                                                                     | <ul><li>Approved applications (we also ask for these on the Welcome screen)</li><li>Approved security tools (we also ask for these on the Welcome screen)</li><li>Any string value that does not fit into the above categories</li></ul> |
| other (integer)                                                                                    | <ul><li>Any integer value that does not fit into the above categories</li></ul>                                                                                                                                                          |

**The Type column in your CSV file (if doing a batch upload) must contain only one of these types, and it must match exactly**. Example: a type entered as email address will fail upon upload; it must be entered as email\_address (with an underscore). If you need to upload batches of multiple types of context, you must upload separate CSV files for each type.

## Which Org Context is Most Helpful to the SOC?

Adding as much Org Context as possible when you onboard is the most helpful option, but if you have limited time, focus on adding the following:

| **Context**                                                                              | **Explanation**                                                                            |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| <p>Executives at your organizations</p><ul><li>email\_address</li><li>username</li></ul> | Helps our SOC understand which users are of highest risk at your organization.             |
| <p>Approved applications</p><ul><li>other (string)</li></ul>                             | Helps our SOC understand which applications are approved and normal in your environment.   |
| <p>Network IP ranges</p><ul><li>cidr\_block</li></ul>                                    | Helps our SOC understand normal network behavior.                                          |
| <p>Approved security tools</p><ul><li>other (string)</li></ul>                           | Helps our SOC understand which security tools are approved and normal in your environment. |

## Add Org Context

Org Context can be added by you or it may be added proactively by our SOC analysts. Here are our recommendations for how to choose your method:

* If you have a **single piece** of Org Context to add:
  * Follow the [Wizard](#wizard) instructions.
  * Choose the Simple form in step 8.
* If you have **multiple pieces** of Org Context to add and you want a single unique name to reference the full list:
  * Follow the [Wizard](#wizard) instructions.
  * Choose the Advanced form in step 8.
  * You must complete the Wizard for each type of context, as each list and unique name can only reference one [context type](#types-of-org-context).
* If you have only a **few pieces** of Org Context to add and you want a **unique name for each one**:
  * Follow the [Wizard](https://support.expel.io/hc/en-us/articles/7883574555667-Manage-Org-Context#h_01JT3EHFQR9QPAFQMACSNFGA6W) instructions.
  * Choose the Simple form in step 8.
  * You must complete the Wizard for each piece of context, and choose a unique name for each one.
* If you have **extensive** Org Context to add and you want each piece of context to have its **own unique name**:
  * Follow the [Batch Upload](#batch-upload-csv) instructions.
  * Make sure to download the CSV template file and use it for your data.
  * You must use separate CSV files for each type of context.

{% hint style="info" %}
You are also able to add some Org Context during your initial onboarding through the Welcome screen.
{% endhint %}

### Wizard

The wizard option lets you add one or more pieces of context, either with a 1:1 relationship to a name (Simple form) or a 1:many relationship where a single name references a list of context values (Advanced form).

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Context**.
   * If you have multiple organizations, be sure to also select the organization using the top dropdown menu.
3. Select the **All context** hyperlink.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FtO0k640d9iOrZfB1Ahd1%2Funknown.png?alt=media&amp;token=abbd37a8-02e6-4cd1-a4be-b9c2586f8096" alt="All context tab highlighted in Workbench." width="375"><figcaption></figcaption></figure></div>
4. Select **Add Context**.
5. Decide whether or not you would like to add detection tag(s) for this piece of context.&#x20;
   * Detection tags are solely used by the detection engine to give it additional information that helps it action more quickly on the associated context.&#x20;
   * Detection tags that are added here cannot be changed later.
   * Select **Do not add detection tags** if you do not want to add any tags for the detection engine.
   * Select **Add detection tags** to add tags for the detection engine, and then select one or more tags from the dropdown list (the available tags are managed by our SOC and cannot be edited by you).

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FkEDSlHzs6MkN5PsjhLFJ%2Funknown.png?alt=media&amp;token=28df7781-2e28-40da-a3f3-a3ca9530eec1" alt="Workbench Lets add context page asks if you would like to add tags and includes options to not add or add detection tags." width="563"><figcaption></figcaption></figure></div>

6. Select **Next**.
7. Enter a **unique name** for your context.
8. Decide whether to continue with the Simple form or select the Advanced form.
   * The **Simple form** is appropriate for a single piece of reference information of a single type, and that you wish to add in a 1:1 relationship with a single unique name (specified in step 7).
   * The **Advanced form** is appropriate for multiple pieces of reference information of a single type, and that you wish to add in a many:1 relationship to a single unique name (specified in step 7).&#x20;

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F2bUOkgTKLBObJlz7WdzU%2Funknown.png?alt=media&amp;token=67c12535-b508-4f3f-9c7c-402f371ab7a5" alt="Advanced form link in Workbench Context area." width="375"><figcaption></figcaption></figure></div>

9. Select a [context type](#types-of-org-context) from the dropdown list.
10. Enter or copy/paste in your context value(s). If using the Advanced form, you will have the option to paste in a list (make sure to use a line break between values).
11. Select a **category** (optional).&#x20;
    * Context categories are tags that are used in Workbench for grouping purposes, and do not impact the detection engine.
    * You can add new categories from this page by selecting the **Manage categories** link.
12. Add a **description** (optional) that helps you quickly understand what the context is (example: "This is the CEO's email.").
13. Select **Save**.
14. Repeat this process if you have additional context types to add.

### Batch Upload (CSV)

The batch upload option lets you quickly add multiple pieces of Org Context of the same type, each with a unique name. You must use a separate CSV file for each type of context.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Context**.
   * If you have multiple organizations, be sure to also select the organization using the top dropdown menu.
3. Select the **All context** hyperlink.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FtO0k640d9iOrZfB1Ahd1%2Funknown.png?alt=media&amp;token=abbd37a8-02e6-4cd1-a4be-b9c2586f8096" alt="All context tab in Workbench Context area." width="375"><figcaption></figcaption></figure></div>
4. Select **Add Context**.
5. Select the **Upload a CSV** hyperlink.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F7dxtPhxH8UxaTMSo63Wm%2Funknown.png?alt=media&amp;token=3c209390-e173-45c4-bb9c-09e4b481c77c" alt="Upload a CSV link in the Let&#x27;s add context section of Workbench." width="563"><figcaption></figcaption></figure></div>
6. First, download a template file. Choose the CSV option if you are using a non-Microsoft program like Google Sheets.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FjB764qpWRGhuiatEa9XA%2Funknown.png?alt=media&amp;token=c9e0086e-227d-4792-a3e8-624d8dbe1ab0" alt="CSV or Expel template options on the Let&#x27;s add context page in Workbench." width="563"><figcaption></figcaption></figure></div>
7. Next, create your CSV file using the template and save it locally (if using Excel, the file format must be saved as .csv). **Make sure you only have** [**one type**](#types-of-org-context) **of Org Context in your CSV file**.
8. Then, select **Attach File** and locate your CSV file.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F0hpJlkKyt3CUEBgG0bfa%2Fwb_context_attach_file.png?alt=media&amp;token=280d7105-b226-4850-b688-f588b6af907d" alt="Attach file option in the Context area of Workbench." width="563"><figcaption></figcaption></figure></div>
9. Select **Save**.
10. Repeat this process if you have additional context types to add.
11. If you experience any issues with your file upload, refer to the [CSV Troubleshooting](#csv-troubleshooting) section for help.&#x20;

## Edit Org Context

You must edit each piece of Org Context individually through Workbench; you cannot perform edits via a CSV file.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Context**.
   * If you have multiple organizations, be sure to also select the organization using the top dropdown menu.
3. Select the **All context** hyperlink.
4. Locate the piece of context you wish to edit. If you have a long list, you can filter in any column (some columns will allow filtering by a string, some will allow filtering by other criteria).

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FOsdj8jz8tXUvAwuPjyLe%2Funknown.png?alt=media&amp;token=d43b132c-9e58-4062-9bd6-2c0b2ec25e64" alt="The example shows filtering in the Name column." width="375"><figcaption></figcaption></figure></div>
5. Use the dropdown menu to select **Edit**.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FqFC7pTXrCSo4RFIyuyPA%2Funknown.png?alt=media&amp;token=38bd5431-04ac-4932-aa76-06850c47831a" alt="Use the dropdown arrow in the desired row to reveal and select Edit." width="563"><figcaption></figcaption></figure></div>
6. Make your edits, then select **Save** to save the changes.

## Delete Org Context

You can only delete Org Context if it is not currently in use by Expel. If it is currently in use, you will be alerted during the deletion process and will not be able to complete the action.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Context**.
   * If you have multiple organizations, be sure to also select the organization using the top dropdown menu.
3. Select the **All context** hyperlink.
4. Locate the piece of context you wish to delete. If you have a long list, you can filter in any column (some columns will allow filtering by a string, some will allow filtering by other criteria).

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FOsdj8jz8tXUvAwuPjyLe%2Funknown.png?alt=media&amp;token=d43b132c-9e58-4062-9bd6-2c0b2ec25e64" alt="This example shows filtering by the Name column." width="375"><figcaption></figcaption></figure></div>
5. Use the dropdown menu to select **Delete**.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FZT5Dm8bWdd5zIeOwDvnD%2Funknown.png?alt=media&amp;token=c92d02e3-46be-43f0-bbc7-cbccace878ca" alt="Select the dropdown arrow in the desired row to Delete context." width="563"><figcaption></figcaption></figure></div>
6. If you receive a message that the context is in use (as shown below) and you still wish to delete it, [contact support](/support) for assistance.&#x20;

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FGGA2vzi7OVrBGoSZBuQD%2Funknown.png?alt=media&amp;token=5e6e4dd2-7a1a-4a7a-9859-bb07a37be05e" alt="Delete context warning message stating This context is in use by Expel and can&#x27;t be deleted, rules using this context must be deleted first." width="563"><figcaption></figcaption></figure></div>

## CSV Troubleshooting

If you are having trouble uploading your Org Context via a CSV file, it is almost always due to a formatting issue. Here are some things to check:

* Make sure each entry in the Name column is unique - both to the CSV file and to any other context you have already added to Workbench.
* Make sure you have used a [supported type](#types-of-org-context), and that the type is entered correctly in the Type column (for example, a type entered as "email address" will fail upon upload; it must be entered as "email\_address"); refer to the [list of types](#types-of-org-context) for help with formatting.
* Make sure you have only chosen one type per CSV file, as you must use separate CSV files for different types of Org Context.
* Make sure you do not have any leading zeros in your IP address or CIDR block values (e.g. 1.2.03.4 or 01.2.3.4)

Make sure you have entered a supported value for your chosen type. Accepted values for each type are as follows (**do not use quotes in the CSV file**):

```
cidr_block: ['cidr'],

domain: ['string'],

email_address: ['string'],

file_hash: ['string'],

hostname: ['string'],

ip_address: ['ip_address'],

other: ['integer', 'string']

port: ['integer'],

url: ['string'],

username: ['string']
```


# Connect Your Technologies

Start integrating your tech with Expel Workbench.

Each vendor technology has a specific Expel onboarding process that usually includes some setup within the technology before adding it as a security device in Workbench. Certain types of on-prem technology (like AWS, Azure, GCP, Hyper-V, VMware, and Nutanix) may require you to use an [assembler](/connect-your-technology/expel-assembler) rather than adding it as a security device. You may also wish to configure an [IP allow list](/workbench-setup/configure-an-ip-allow-list).

## **Add an Assembler (if applicable)**

**Do you need an assembler?** Some technologies live on an internal, private network where a direct external connection cannot be established. These technologies will require the deployment of an Expel Assembler to connect.\
\
If you believe you may need an assembler, see the information below:

* To understand how our assemblers are built and how they work, go to the [About the Assembler](/connect-your-technology/expel-assembler/about-the-expel-assembler) guide.
* To deploy an assembler, go to the [Add a New Assembler](/connect-your-technology/expel-assembler/add-a-new-assembler) guide and follow the instructions; links will be provided at the end of that guide to configure your specific technology.

## **Set Up Your Technology**

To find setup instructions for your technology, do one of the following:

* Search for and view your technology's setup guide: <button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Search…</button>
* Browse the [**Integrations page** ](/connect-your-technology/about-integrations/expel-integrations)for our portfolio and select the hyperlink (if available) to go directly to the guide.
* If you are an [Organization Admin user](/workbench-setup/get-started/add-and-manage-users/user-role-rights), use the **Set up** buttons on your Welcome screen in Workbench to find links to your setup guides. For more information, go to [About the Welcome Screen](#about-the-welcome-screen-organization-admins-only).

If you cannot find the setup guide you need, [contact support](/support) for help.

{% hint style="info" %}
Some integrations require you to grant us a certain level of console access during the setup process. For more information, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access).
{% endhint %}

## About the Welcome Screen (Organization Admins Only)

If you are an [Organization Admin user](/workbench-setup/get-started/add-and-manage-users/user-role-rights), you will see a Welcome screen when you log in to Workbench that will contain a list of your technologies to onboard. Select one of the **Set up** buttons to find a link to the appropriate setup guide.

After you have successfully connected, the **Set up** button will disappear and will be replaced by a connection status (as shown below).

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FRSpD58VUcOTLewGY3K3g%2Funknown.png?alt=media&amp;token=078a13b4-f3b6-42e3-9352-f52bc8887a0e" alt="The Welcome screen in Workbench shows a list of technologies you may want to or have already added."><figcaption></figcaption></figure></div>

If you know you are this user type but do not see the Welcome screen, try going to **Dashboards > Alert Analysis**.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FwgzR1hqqn7YE8dN4NJ45%2Funknown.png?alt=media&amp;token=d95ef081-9274-4a2d-bc6c-e5bfedd18ea0" alt="" width="336"><figcaption></figcaption></figure></div>


# Enable Auto Remediations

In the event of a threat, auto remediations allow Workbench to automatically complete assigned actions on your team's behalf. Learn more:

* [About Auto Remediations](/workbench-setup/auto-remediations/about-auto-remediations)
* [Video: Introduction to Auto Remediations](/resources/video-library/auto-remediations#h_01j88e2vksmg0psj5j6wwh88pf)


# Learn More About Workbench

After you've set up your account, notifications, and more, and added at least once security device, take some time to learn more about Workbench. The suggestions below are a good place to start, and you can find more information in the **Workbench Reference** section.

{% content-ref url="/pages/SqvsHFEI421bRjyDs092" %}
[Expel Terminology](/workbench-reference/expel-terminology)
{% endcontent-ref %}

{% content-ref url="/pages/hKinicoVbM7sUTXL27A6" %}
[Dashboards](/workbench-reference/dashboards)
{% endcontent-ref %}

{% content-ref url="/pages/OCTmsBwGeZU9bs0FKJuO" %}
[Manage Investigations and Incidents](/workbench-reference/investigations-and-incidents)
{% endcontent-ref %}

{% content-ref url="/pages/slts4kSjWjmxQSSHXDbO" %}
[Detections](/workbench-reference/detections)
{% endcontent-ref %}


# Notifications


# About Notifications

Expel security monitoring tracks many moving parts at the same time. Many events, like a security device going offline or an Investigation being opened, trigger a notification from Workbench. You may also receive a notification if there is a manual action of some kind that you need to take in support of an Investigative Action.

## Notification Types

Your organization can use more than one type of notification to receive messages about your environment, if you choose. You can also leverage email, or integrations with Slack​​® or Microsoft Teams™, to communicate directly with us.

There are two types of notifications that can be set up in Workbench.

<table><thead><tr><th width="214.328125">Type</th><th>Usage</th></tr></thead><tbody><tr><td>Email notification</td><td><ul><li>Configured at the user level and sent to an individual email address.</li><li>Includes a link to take action in Workbench.</li><li>All users in an organization will receive the <a href="#default-email-notifications">default email notifications</a>, but each user can edit them as they wish.</li><li><a href="/workbench-setup/get-started/add-and-manage-users/user-role-rights">Organization Admin</a> users can also edit email notifications for other users.</li></ul></td></tr><tr><td>Organization notification</td><td><ul><li>Configured at the organization level.</li><li>Only <a href="/workbench-setup/get-started/add-and-manage-users/user-role-rights">Organization Admin</a> users can add, edit, or delete organization notifications.</li><li>Sent to a platform like Slack​​ or Microsoft Teams, or to other integrations like a ticketing system or webhook destination.</li><li>Requires someone in the organization to first set up an integration with a <a href="#supported-platforms">supported platform</a> before receiving any organization notifications, including the <a href="#default-organization-notifications">default organization notifications</a>.</li></ul></td></tr></tbody></table>

## Default Notifications

Certain notifications are enabled by default for organizations and users. You may set up additional notifications for your organization or for your email, and you may also [edit the default notifications](#how-to-set-up-notifications) at any time.

### Default Email Notifications

{% hint style="info" %}
Default email notifications are activated for a user as soon as they are set up in Workbench.
{% endhint %}

An email notification is always generated when the following events occur in Workbench, unless changed by a user or an admin at your organization:

* [Incident is created](#user-content-fn-1)[^1]
* [Incident is closed](#user-content-fn-2)[^2] (Wiz users only)
* [Investigation is created](#user-content-fn-3)[^3]
* [Investigation is assigned to my org](#user-content-fn-4)[^4]
* [Investigation is closed](#user-content-fn-5)[^5]
* [Investigative Action is assigned to me](#user-content-fn-6)[^6]
* [Investigative Action is assigned to my org](#user-content-fn-7)[^7]
* [Notify Action is assigned to my org](#user-content-fn-8)[^8]
* [Verify Action is assigned to me](#user-content-fn-9)[^9]
* [Verify Action is assigned to my org](#user-content-fn-10)[^10]
* [Remediation Action is assigned to me](#user-content-fn-11)[^11]
* [Remediation Action is assigned to my org](#user-content-fn-12)[^12]
* [Remediation Action is automated](#user-content-fn-13)[^13]
* [An assembler has a health status change](#user-content-fn-14)[^14]

### Default Organization Notifications

{% hint style="info" %}
Someone at your organization must first set up an integration with one of the [supported platforms](#supported-platforms) in order to begin receiving the default organization notifications.
{% endhint %}

An organization notification is always generated when the following events occur in Workbench, unless changed by an admin at your organization:

* [Incident is created](#user-content-fn-1)[^1]
* [Incident is assigned to an organization](#user-content-fn-4)[^4]
* [Incident is reopened](#user-content-fn-15)[^15]
* [Investigation is assigned to an organization](#user-content-fn-7)[^7]
* [Remediation Action is assigned to an organization](#user-content-fn-12)[^12]\*
* [Verify Action is assigned to an organization](#user-content-fn-10)[^10]
* [Investigative Action is assigned to an organization](#user-content-fn-7)[^7]
* [Notify Action is assigned to an organization](#user-content-fn-8)[^8]
* [Assembler has a health status change](#user-content-fn-14)[^14]
* [Security device has a health status change](#user-content-fn-16)[^16]
* [Announcement is created](#user-content-fn-17)[^17]
* [Emerging threat is created](#user-content-fn-18)[^18]
* Support ticket is created
* Support ticket is re-opened
* Support ticket is closed
* Support ticket comment created

*\* Exception: For ticketing systems only, when an Investigation occurs due to a Phishing alert, organization notifications for Remediation Actions are not sent to those systems by default. You can* [*contact Support*](/support) *to turn this notification on if you wish.*

### Supported Platforms

All of the following integrations are configured at the organization level and support your organization notifications.

{% hint style="info" %}
You can also use Teams or Slack to communicate with us directly.
{% endhint %}

* Microsoft Teams\*
* [OpsGenie](/workbench-setup/notifications/platform-setup/opsgenie-setup-for-organization-notifications)
* [PagerDuty](/workbench-setup/notifications/platform-setup/pagerduty-setup-for-organization-notifications)
* [ServiceNow](/workbench-setup/notifications/platform-setup/servicenow-setup-for-organization-notifications)
* Slack\*
* [Ticketing Systems](/workbench-setup/notifications/platform-setup/ticketing-system-setup-for-organization-notifications)
* [Webhooks](/connect-your-technology/about-integrations/webhooks-setup-for-workbench)

*\*Our* [*Support team*](/support) *can help you set up Teams and Slack.*

## How to Set Up Notifications

All notifications are set up in Workbench in [Settings > Organization Settings](https://workbench.expel.io/settings).&#x20;

{% hint style="info" %}
Email notifications are set up in a user's **Profile** page, and organization notifications are set up in the **My Organizations** section.

An [Organization Admin](/workbench-setup/get-started/add-and-manage-users/user-role-rights) user is required to set up organization notifications.
{% endhint %}

* To set up email notifications:
  * Simply select a notification event that will be sent to the user email.
* To set up organization notifications:
  * First use the Integrations tab to set up an integration with a [supported platform](#supported-platforms).
  * Then use the Notifications tab to create the individual notifications that are routed to that platform.

For detailed setup instructions, including how to change your notifications, see:

* [Manage Email Notifications for Workbench](/workbench-setup/notifications/manage-email-notifications)
* [Manage Organization Notifications for Workbench](/workbench-setup/notifications/manage-organization-notifications)

[^1]: Malicious activity was identified and we are looking into it. Stay tuned for remediation actions.

[^2]: The malicious activity we found is resolved.

[^3]: Additional information is needed and we are looking into it.

[^4]: We need your team to investigate this activity.

[^5]: Additional information was gathered and a conclusion was made.

[^6]: You are assigned an investigative action to help provide additional information related to this activity.

[^7]: We need a representative from your organization to provide more information to help draw a conclusion about the activity.

[^8]: We are sharing an update with your team of lower severity, but can include some actions you can take.

[^9]: We need you to let us know if an action that triggered suspicion is authorized or not.

[^10]: We need someone from your team to let us know if an action that triggered suspicion is authorized or not.

[^11]: You need to take an action to address the unwanted activity. This is typically assigned to you by someone from your team.

[^12]: We identified an action your team can take to address unwanted activity.

[^13]: Expel bots are doing this remediation for you, so your team does not need to do anything.

[^14]: The condition of the [Assembler](/connect-your-technology/expel-assembler/about-the-expel-assembler) has become either connected or disconnected.

[^15]: We reopened a previously closed Incident.

[^16]: Your security device has become either connected or disconnected.

[^17]: A global event was created by Expel.

[^18]: Expel Threat Intelligence has identified a new threat that needs your attention.


# Platform Setup

You must set up your platform integration before you can begin receiving organization notifications.


# Ticketing System Setup for Organization Notifications

When you connect Workbench to a ticketing system, you can send organization-level notifications to that ticketing system to track and manage, just like you do other tickets in your environment.

This guide is the first step of a larger process to enable organization notifications.&#x20;

{% hint style="info" %}
After completing the steps on this page, you will be instructed to go to [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) to set up your actual notifications.
{% endhint %}

## Supported Ticketing Systems

You can connect the following ticketing systems to Workbench:

* Asana
* Jira
* Request Tracker for Incident Response
* Splunk On-Call
* Striven

## Prerequisites

1. You must have a destination email address for your ticketing system before you begin.
   * This is the email that will receive and process the notifications from Workbench and route them to your ticketing system.
2. You must be an organization admin to integrate a ticketing system with Workbench.

## Step 1: Add a Ticketing System in Workbench

{% hint style="info" %}
Make sure you have the destination email address for your ticketing system before you begin these steps.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > My Organization**.
   * If you have multiple organizations, you must also select the appropriate organization name from the list.
3. Scroll down and select the **Integrations** tab.
4. Under **Email Ticketing Systems**, select **Add a ticketing destination**.
5. Enter the name of your ticketing system (you might enter "Jira", "Asana", etc.) and the email address to receive the ticket information from Workbench.
6. Select **Add**.
7. Look for an **Enabled** banner.
8. Now, select the **Test connection** link to test the connection.<br>

   <figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F3fA7YVWhpCOuVwfwNk9x%2Fticketing%20system_test%20connection.png?alt=media&amp;token=05957158-3b32-4fbf-b4cc-e86dff894070" alt="Image showing the enabled banner and the link to test the connection."><figcaption></figcaption></figure>
9. Check the receiving email and its ticketing system destination to be sure the test worked.
10. Repeat this process to add any other ticketing systems you wish to integrate.

## Step 2: Add Your Organization Notifications

Now you can begin setting up your organization notifications. See [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) for instructions.

{% hint style="info" %}
For a list of default notifications, see [Default Organization Notifications](/workbench-setup/notifications/about-notifications#default-organization-notifications). You can edit these notifications at any time using the instructions in the linked guide above.
{% endhint %}

## Ticketing Template Reference

All email ticketing notifications are delivered in plain text format and are sent from the Expel SOC (<soc@expel.io>).

The HTML and Handlebars structures of the most common notifications are outlined below, should you need to understand how to parse and trigger automated ticketing workflows based on these notifications. If a particular notification format is not shown here, please [contact support](/support) for further assistance.

### Expel Alert Opened

```
A {{current.expel_severity_display}} 
{{#if (condition current.alert_type "==" "ALERT_TYPE_PHISHING_SUBMISSION")}}
phishing
{{/if}}
alert was identified in your environment.
<br/><br/>
{{current.expel_name}}
<br/>
Expel alert ID: {{current.id}}
<br/>
{{meta.wb_url}}/activity/alerts/{{current.id}}
<br/><br/>
NEXT STEPS
<br/>
- No action required right now.
<br/>
- Stay alert for additional notifications, since the status of the alert may change and we may recommend more next steps as the scope becomes clear.
<br/><br/> 
ALERT DETAILS
<br/>
{{#if (condition current.alert_type "==" "ALERT_TYPE_HUNTING")}}
Expel alert: {{current.expel_name}}
<br/>
Expel alert time: {{current.expel_alert_time}}
{{else if (condition current.alert_type "!=" "ALERT_TYPE_PHISHING_SUBMISSION")}}
Vendor: {{vendor.name}}
<br/>
{{/if}}
{{#if (condition current.alert_type "!=" "ALERT_TYPE_HUNTING")}}
Vendor alert time: {{current.expel_alert_time}}
{{/if}}
```

### Expel Alert Closed

```
{{#if (condition current.alert_type "==" "ALERT_TYPE_PHISHING_SUBMISSION")}}
A phishing
{{else}}
An
{{/if}}
alert was closed in your environment: {{current.close_reason_display}}.
<br/><br/>
{{current.expel_name}}
<br/>
Expel alert ID: {{current.id}}
<br/>
{{meta.wb_url}}/activity/alerts/{{current.id}}
<br/><br/>
CLOSED REASON
<br/>
{{current.close_reason_display}}
<br/>

<br/>
{{#if (condition current.alert_type "==" "ALERT_TYPE_HUNTING")}}
Expel alert: {{current.expel_name}}
<br/>
Expel alert time: {{current.expel_alert_time}}
{{else if (condition current.alert_type "!=" "ALERT_TYPE_PHISHING_SUBMISSION")}}
Vendor: {{vendor.name}}
<br/>
{{/if}}
{{#if (condition current.alert_type "!=" "ALERT_TYPE_HUNTING")}}
Vendor alert time: {{current.expel_alert_time}}
{{/if}}
```

### Investigation Opened

```
An investigation was kicked off in your environment.
<br/><br/>

<a href="{{meta.wb_url}}/activity/investigations/{{current.short_link}}/actions">{{current.title}}</a>
<br/><br/>

{{#if meta.is_detect_only}}
Next Steps
<br/>
{{current.next_steps}}
{{else}}
Next Steps
<br/>
- Check Workbench for more details. We'll provide more details shortly.
<br/>
- Watch for remediation actions.
{{/if}}
<br/><br/>

{{#if meta.is_detect_only}}
SUMMARY
<br/>
{{current.open_summary}}
<br/>
<br/>
{{else if current.summary}}
SUMMARY
<br/>
{{current.summary}}
<br/>
<br/>
{{/if}}

{{#unless current.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Detection: {{current.detection_type_display}}
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>

DETAILS
<br/>
Created by: {{created_by_user_account.display_name}}
```

### Investigation Closed

```
We closed an investigation: {{current.decision_display}}
<br/>
<br/>
<a href="{{meta.wb_url}}/activity/investigations/{{current.short_link}}/actions">{{current.title}}</a>
<br/>
<br/>

Next Steps 
<br/>
• No action required right now.
<br/>
• If you have questions about this investigation, please contact the SOC or your engagement manager.
<br/><br/>

CLOSE REASON
<br/>
{{current.decision_display}}
<br/><br/>

{{#unless current.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Detection: {{current.detection_type_display}}
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>

DETAILS
<br/>
Closed by: {{updated_by_user_account.display_name}}
```

### Verify Action Assigned

```
A verify action was assigned to your organization.
<br/>
<br/>

{{#if investigation}}
<a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
{{else}}
<a href="{{meta.wb_url}}/alerts/{{current.expel_alert_id}}/actions?investigativeActionId={{current.id}}">Expel Alert</a>
{{/if}}
<br/>
<br/>

Next Steps
<br/>  
- Verify Activity (see below).
<br/>
- Log into Workbench to report the outcome of this investigative action.
<br/>
<br/>
VERIFY ACTIVITY
<br/>
<br/>
{{#markdown}}{{current.instructions}}{{/markdown}}
<br/>
<br/>
DETAILS
<br/>
<br/>
{{#markdown}}{{current.reason}}{{/markdown}}
<br/>
<br/>
Created by: {{created_by_actor.display_name}}
<br/>
<br/>
When you're done, please log into the Expel Workbench to complete the action.
<br/><br/>

{{#unless investigation.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>
```

### Incident Opened

```
{{#if (condition current.analyst_severity "==" "ANALYST_SEVERITY_CRITICAL")}}
A critical {{current.threat_type_display}}  incident has been identified in your environment.
{{else}}
{{#if current.threat_type_display}}A{{else}}An{{/if}} {{current.threat_type_display}} incident has been identified in your environment.
{{/if}}
<br/>
<br/>
<a href="{{meta.wb_url}}/activity/investigations/{{current.short_link}}/actions">{{current.title}}</a>
<br/>
<br/>

{{#if meta.is_detect_only}}
Next Steps
<br/>
{{current.next_steps}}
{{else}}
Next Steps
<br/>
- Check Workbench for more details. We'll provide more details shortly.
<br/>
- Watch for remediation actions.
{{/if}}
<br/>
<br/>

{{#if meta.is_detect_only}}
SUMMARY
<br/>
{{current.open_summary}}
<br/>
<br/>
{{else if current.summary}}
SUMMARY
<br/>
{{current.summary}}
<br/>
<br/>
{{/if}}

{{#unless current.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Detection: {{current.detection_type_display}}
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>

DETAILS
<br/>
Created by: {{created_by_user_account.display_name}}
```

### Incident Closed

```
{{#if (condition current.analyst_severity "==" "ANALYST_SEVERITY_CRITICAL")}}
Critical
{{/if}}
Incident closed
<br/><br/>
<a href="{{meta.wb_url}}/activity/investigations/{{current.short_link}}/actions">{{current.title}}</a>
<br/><br/>

NEXT STEPS
<br/>
• No action required right now.
<br/>
• If you have questions about this incident, please contact the SOC or your engagement manager.
<br/><br/>

{{#if meta.is_detect_only}}
SUMMARY
<br/>
{{current.open_summary}}
<br/>
<br/>
{{else if current.summary}}
SUMMARY
<br/>
{{current.summary}}
<br/>
<br/>
{{/if}}

{{#unless current.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Detection: {{current.detection_type_display}}
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>

DETAILS
<br/>
Closed by: {{updated_by_user_account.display_name}}
```

### Comment Added

```
There's a new comment on the 
{{#if investigation.is_incident}}
incident:
{{else}}
investigation:
{{/if}}
<br/><br/>

<a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/actions">{{investigation.title}}</a>
<br/><br/>

Next steps
<br/>
- Acknowledge and respond, if appropriate
<br/>
<br/>

COMMENT
<br/>
{{current.comment}}
<br/>
<br/>

DETAILS
<br/>
Commenter: {{updated_by_actor.display_name}}
<br/>
Added: {{current.created_at}}
<br/>
{{#if investigation.lead_expel_alert_id}}
Expel alert ID: {{investigation.lead_expel_alert_id}}
{{/if}}
```

### Remediation Action Assigned

```
{{#unless remediation_action.has_manual_fallback}}A {{#if investigation.is_critical}}critical {{/if}}remediation action was assigned to your organization - {{current.action}}{{/unless}}
{{#if remediation_action.has_manual_fallback}}Expel SOC attempting manual fallback - {{current.action}}{{/if}}
<br/>
<br/>
{{#if (and has_failed_assets (not remediation_action.has_manual_fallback))}} Automation failed, manual remediation needed. {{/if}}
{{#if remediation_action.has_manual_fallback}} Automation failed, Expel SOC attempting manual fallback. {{/if}}
<br/>
<br/>
<a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
<br/>
<br/>
<strong>Remediation Details:</strong>
<br/>
<br/>
{{#markdown}}{{current.action}}{{/markdown}}
<br/>
<br/>
{{#replace-all "\n" "<br />"}}{{detail_markdown}}{{/replace-all}}
<br/>
<br/>
{{#if investigation.is_incident}}
<strong>Incident details:</strong>
<br/>
<br/>
Detection:  {{investigation.detection_type}}
<br/>
Incident name: <a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
<br/>
Time detected: {{investigation.created_at}}
<br/>
Workbench link: {{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings
<br/>
<br/>
{{/if}}
<strong>Details:</strong>
<br/>
<br/>
Created by: {{created_by_actor.display_name}}
<br/><br/>

{{#unless investigation.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>
```

### Auto Remediation in Progress

```
Automated remediation action in progress- {{current.action}}
<br/>
<br/>
{{#if has_failed_assets}} Automation failed, manual remediation needed. {{/if}}
<br/>
<br/>
<a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
<br/>
<br/>
<strong>Remediation Details:</strong>
<br/>
<br/>
{{#markdown}}{{current.action}}{{/markdown}}
<br/>
<br/>
{{#replace-all "\n" "<br />"}}{{detail_markdown}}{{/replace-all}}
<br/>
<br/>
{{#if investigation.is_incident}}
<strong>Incident details:</strong>
<br/>
<br/>
Detection:  {{investigation.detection_type}}
<br/>
Incident name: {{investigation.title}}
<br/>
Time detected: {{investigation.created_at}}
<br/>
Workbench link: {{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings
<br/>
<br/>
{{/if}}
<strong>Details:</strong>
<br/>
<br/>
Created by: {{created_by_actor.display_name}}
<br/><br/>

{{#unless investigation.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>
```

### Remediation Completed

```
A {{#if investigation.is_critical}}critical {{/if}}remediation action for your organization was completed - {{current.action}}
<br/>
<br/>
<a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
<br/>
<br/>
<strong>Remediation Details:</strong>
<br/>
<br/>
{{#markdown}}{{current.action}}{{/markdown}}
<br/>
<br/>
{{#replace-all "\n" "<br />"}}{{detail_markdown}}{{/replace-all}}
<br/>
<br/>
{{#if investigation.is_incident}}
<strong>Incident details:</strong>
<br/>
<br/>
Detection:  {{investigation.detection_type}}
<br/>
Incident name: <a href="{{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings">{{investigation.title}}</a>
<br/>
Time detected: {{investigation.created_at}}
<br/>
Workbench link: {{meta.wb_url}}/activity/investigations/{{investigation.short_link}}/findings
<br/>
<br/>
{{/if}}
<strong>Details:</strong>
<br/>
<br/>
Created by: {{created_by_actor.display_name}}
<br/><br/>

{{#unless investigation.lead_expel_alert_id }}
INITIAL LEAD
<br/>
Organization reported
{{else}}
INITIAL LEAD
<br/>
Expel alert name: {{lead_expel_alert.expel_name}}
<br/>
Expel alert ID: {{lead_expel_alert.id}}
<br/>
Expel alert time: {{lead_expel_alert.created_at}}
{{/unless}}
<br/><br/>
```

### Unhealthy Security Device

```
Security device {{current.name}} has a problem: {{security_device.problem}}
<br/><br/>
```


# OpsGenie Setup for Organization Notifications

This guide is the first step of a larger process to enable organization notifications.&#x20;

{% hint style="info" %}
After completing the steps on this page, you will be instructed to go to [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) to set up your actual notifications.
{% endhint %}

## Step 1: Set Up the Integration in OpsGenie

1. In OpsGenie, navigate to **Teams** and select your team.
2. Navigate to **Settings**.
3. Search for and select "**API**" (you want to use the default API setup); the API settings will appear.
4. In the API settings, select the **correct assignee team**.
5. Select **Turn on integration** to enable the API within Opsgenie.
6. Copy the API key and save it for use in the next step.

## Step 2: Set Up the Integration in Workbench

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > My Organization**.
   * If you have multiple organizations, you must also select the appropriate organization name from the list.
3. Scroll down and select the **Integrations** tab.
4. Under OpsGenie, select **Add an Opsgenie destination**.
5. Enter a **name** for the service and paste in the **API key** (copied in Step 1), then select **Add**.
6. Look for an **Enabled** banner.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FoOt6Cigk8v5A8KJFgAAM%2Fopsgenie_enabled.png?alt=media&amp;token=1e0dc537-6a66-4c77-9c74-4d4d826a9849" alt="Image showing a green Enabled banner in the top left, above the service name."><figcaption></figcaption></figure>

## Step 3: Add Your Organization Notifications

Now you can begin setting up your organization notifications. See [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) for instructions.

{% hint style="info" %}
For a list of default notifications, see [Default Organization Notifications](/workbench-setup/notifications/about-notifications#default-organization-notifications). You can edit these notifications at any time using the instructions in the linked guide above.
{% endhint %}


# PagerDuty Setup for Organization Notifications

This guide is the first step of a larger process to enable organization notifications.&#x20;

{% hint style="info" %}
After completing the steps on this page, you will be instructed to go to [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) to set up your actual notifications.
{% endhint %}

## Step 1: Set Up the Integration in Workbench

Notifications can only be sent to a single PagerDuty service.&#x20;

{% hint style="warning" %}
After a security incident is resolved in Workbench, you must manually resolve the incident in PageDuty.&#x20;
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Select **Organization Settings > My Organization**.
   * If you have multiple organizations, you must also select the appropriate organization name from the list.
3. Scroll down and select the **Integrations** tab.
4. Under PagerDuty, select **Add a Pagerduty destination** and then select **Open PagerDuty** to begin integration.
5. A new tab opens in your browser; log in with your PagerDuty credentials.
6. In PagerDuty, select which service you want to add the integration to or create a new integration, then select **Connect**.&#x20;

{% hint style="warning" %}
You can only select one service.
{% endhint %}

7. Back in Workbench, look for an **Enabled** banner in the PagerDuty section.
8. Now, select the **Test connection** link to test the connection. The test creates and closes an incident in PagerDuty.<br>

   <figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FC74FUJVbBxJIlciM7ME3%2Fpagerduty_test%20connection.png?alt=media&amp;token=342541f0-305c-4e98-9e05-2ecb08a3d6ee" alt="The test connection link is beside the Last Tested timestamp."><figcaption></figcaption></figure>
9. Back in PagerDuty, navigate to your **Incidents** page.
10. In the **Activity for the Past 7 Days** section, look for the test connection. It will have a unique ID appended to the title, and two rows for the test event (one for the triggered event and one for the resolved activity).

## Step 2: Add Your Organization Notifications

Now you can begin setting up your organization notifications. See [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) for instructions.

{% hint style="info" %}
For a list of default notifications, see [Default Organization Notifications](/workbench-setup/notifications/about-notifications#default-organization-notifications). You can edit these notifications at any time using the instructions in the linked guide above.
{% endhint %}


# ServiceNow Setup for Organization Notifications

Expel offers a notification synchronization capability for ServiceNow (synchronization refers to Workbench's ability to continuously update a ticket based on state changes in Workbench).&#x20;

This guide is the first step of a larger process to enable organization notifications.&#x20;

{% hint style="info" %}
After completing the steps on this page, you will be instructed to go to [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) to set up your actual notifications.
{% endhint %}

## Scope and Limitations

When choosing to set up this integration, remember the following:

1. Only the **IT Service Management (ITSM)** and **Security Incident Response (SIR)** modules are supported, and the steps listed in this guide apply to both.
2. This plugin **cannot** be customized.&#x20;
   * If you are seeking customizable payloads for organization notifications, please instead utilize [webhooks](/connect-your-technology/about-integrations/webhooks-setup-for-workbench) or an [email ticketing system](/workbench-setup/notifications/platform-setup/ticketing-system-setup-for-organization-notifications).
3. ServiceNow will **not** be used to ingest your security signal for MDR purposes; it will only be used to support notifications.
4. Synchronization is only available for Workbench **Investigations** or for Investigations flagged as **Incidents**.&#x20;
   * See the [Reference](#reference) section for more information about notification synchronization.

## Prerequisites

1. You must have a ServiceNow Administrator account with *security\_admin* privileges.
2. You must be using either the ITSM or SIR module, as these are the two supported modules for this integration.
3. The ITSM or SIR module must *already* be added and enabled on the ServiceNow account.

## Step 1: Configure ServiceNow API Access for Expel

1. [Log in to the ServiceNow instance](https://www.servicenow.com/my-account/sign-in.html) using the administrator account.
2. [Elevate your role](https://docs.servicenow.com/bundle/xanadu-platform-security/page/administer/security/task/t_ElevateToAPrivilegedRole.html) to **security\_admin**.
3. Navigate to **User Administration > Users** and select **New** in the upper right corner.
4. For the User ID field, enter "expeluser". The rest of the fields can be left blank.
5. Select **Submit**.
6. From the Users list, select **expeluser**.
7. On the User page, select **Set Password**.
8. Select **Generate**. Copy the password and save it to a safe place, as you will need it in a later step.
9. Select **Save Password**.
10. Select **Close**.
11. Still on the User page, scroll down to the **Roles** tab and select **Edit**.
12. Grant the Expel user the appropriate role, depending on your module, so that it has the required permissions to access the incidents table from the REST APIs.

{% tabs %}
{% tab title="ITSM Module" %}

1. Enter "incident\_manager" in the Collection field.
2. Select **incident\_manager** in the list builder and select **>** to add it to the Roles List.
3. Select **Save**.
   {% endtab %}

{% tab title="SIR Module" %}

1. Enter "sn\_si.manager" in the Collection field.

2. Select **sn\_si.manager** in the list builder and select **>** to add it to the Roles List.

3. Select **Save**.
   {% endtab %}
   {% endtabs %}

4. Navigate to **System OAuth > Application Registry**.

5. Select **New** in the upper right.

6. Select **Create an OAuth API endpoint for external clients**.

7. Provide a **Name** for the registry.

8. The default settings can be left as is.

9. Select **Submit**.

10. On the Application Registries page, select the name of the registry you just created.

11. Copy the **Client ID** and **Client Secret** and save them in a safe place, as you will need these values in a later step.

## Step 2: Add ServiceNow as a Security Device in Workbench

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, type “ServiceNow” and then select the **ServiceNow** integration.
5. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName ServiceNow”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Username and Password** - enter "expeluser" for the username, and enter the password you generated in [Step 1](#step-1-configure-servicenow-api-access-for-expel).
   * **Server** - enter the URL from the ServiceNow instance you configured the Expel user on in [Step 1](#step-1-configure-servicenow-api-access-for-expel). For example: <https://dev1234.service-now.com>.
   * **Client ID and Client secret** - enter the ID and secret you obtained in [Step 1](#step-1-configure-servicenow-api-access-for-expel).
   * **Module** - use the dropdown to select the appropriate option depending on whether you are adding an ITSM or SIR device.
   * **Assignment group** - this is optional and can be left blank.
   * **Console Access** - granting Workbench access to your ServiceNow console is optional.
6. Select **Save**.
7. Your device should be created successfully within a few seconds. A few reminders:
   * To check on the status, select the downward arrow for your device in the first column and choose **View details**. You can then scroll to the **Connection** section to see if your device is fully connected.
   * You must refresh the page to see updates.
   * Note that a status of "N/A" for Last successful poll is expected.
   * If your device does not report a healthy connection, check that the values you entered into Workbench are correct. If you need further troubleshooting, [contact Support](/support).
8. In the **Integrations** tab on the [**Organization Settings**](#user-content-fn-1)[^1] page, look for a new section titled ServiceNow, and ensure it says **Enabled**.&#x20;
   * If it you find this section and it is enabled, proceed to [Step 3: Add Your Organization Notifications](#step-3-add-your-organization-notifications).&#x20;
   * If there is no new ServiceNow section, continue to the next step.
9. In the side menu, navigate to **Organization Settings > My Organizations** and select the name of your organization.
10. Select the **Integrations** tab.
11. Scroll to the ServiceNow section and select **Enable ServiceNow integration**.

## Step 3: Add Your Organization Notifications

Now you can begin setting up your organization notifications. See [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications) for instructions. If you wish to enable synchronization as part of your organization notifications, see [How to Configure](#how-to-configure) in the Reference section for more information.

{% hint style="info" %}
For a list of default notifications, see [Default Organization Notifications](/workbench-setup/notifications/about-notifications#default-organization-notifications). You can edit these notifications at any time using the instructions in the linked guide above.
{% endhint %}

## Reference

### Synchronization Capabilities

Synchronization is only available for Incidents and Investigations. Upon creation of a ServiceNow ticket, any subsequent change or update associated with that Investigation or Incident is captured and logged as a comment on that same ticket.&#x20;

{% hint style="warning" %}
Fields are not currently updated.
{% endhint %}

For example, if any of the following occurs, a comment is added to the ServiceNow ticket that was created when the Investigation/Incident opened in Workbench:

* An **Expel Alert** is added to the Investigation/Incident.
* A **Verify/Notify Action** is created and sent as part of the Investigation/Incident.
* A **Remediation Action** is assigned, automated, or completed as part of the Investigation/Incident.

When a ticket is created, the following fields are set:

* **Title** - name of Workbench event (example: `[ORG-XXX] Incident created: Authentication from suspicious country`)
* **Description** - includes the `URL` to the Workbench event (Incident or Investigation) and details about the event.
* **Incident State** - set to `In Progress`.
* **Caller** - set to `Expel Integration`.

### How to Configure

There is a specific action of `has any state change` within organization notifications for the `Investigation` and `Incident` event types, and it is only supported for ServiceNow. When configuring notifications for this set of conditions, set the `notify via` destination to ServiceNow.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fk4uOMFon1mRFGCZtISGB%2Fwb_servicenow_syncing.png?alt=media&amp;token=8563fc64-cf5a-44db-b1ac-6e419cd382e1" alt="Image of the conditions and notify via settings." width="375"><figcaption></figcaption></figure></div>

Once saved, whenever an Investigation or Incident is updated in Workbench, comments are appended to the associated ServiceNow ticket. The comments include a URL back to the original Investigation or Incident, and details about the update.

### Supported Synchronization Events

For the below events, one ServiceNow ticket is created and continuously updated throughout the lifecycle of the Investigation or Incident.

| Workbench Event | State or Action                                                                                                                                    | What Happens in ServiceNow |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| Incident        | Created                                                                                                                                            | Ticket created             |
| Incident        | <p>Assigned</p><p>Closed</p><p>Downgraded</p><p>Promoted</p><p>Reopened</p><p>Remediation Action assigned/completed/failed</p>                     | Comment added to ticket    |
| Investigation   | Created                                                                                                                                            | Ticket created             |
| Investigation   | <p>Alert added</p><p>Assigned</p><p>Closed</p><p>Reopened</p><p>Investigative Action created/assigned/approved/denied (this includes Verifies)</p> | Comment added to ticket    |

### Unsupported Synchronization Events

For the below events, one unique ServiceNow ticket is created for each event. For example, if configured, a new Expel Alert would yield one ServiceNow ticket. If configured, when that Expel Alert is closed, it would yield another ServiceNow ticket.

| Workbench Event                      | State or Action                                             | What Happens in ServiceNow |
| ------------------------------------ | ----------------------------------------------------------- | -------------------------- |
| Expel Alert                          | Created                                                     | Ticket created             |
| Investigative Action                 | <p>Analysis assigned</p><p>Assigned</p><p>Manual action</p> | Ticket created             |
| Notify Action                        | Assigned                                                    | Ticket created             |
| Verify Action                        | <p>Assigned</p><p>Approved</p><p>Denied</p>                 | Ticket created             |
| Custom Rule                          | Created                                                     | Ticket created             |
| Assembler Health Status Change       | <p>First Time Healthy</p><p>Unhealthy</p><p>Healthy</p>     | Ticket created             |
| Security Device Health Status Change | <p>First Time Healthy</p><p>Unhealthy</p><p>Healthy</p>     | Ticket created             |

[^1]: In the side menu, navigate to Settings > Organization Settings.


# Manage Email Notifications

*This topic covers notifications that are sent to an individual's email address. If you are looking for organization-level notifications that are sent to an integration or plug-in, see* [*Manage Organization Notifications*](/workbench-setup/notifications/manage-organization-notifications)*.*&#x20;

Workbench allows alerts, data, and other messages to be sent directly to an email address. You may set up as many email notifications as you wish, and Workbench Organization Admins can also set up email notifications on behalf of users in their organization.&#x20;

{% hint style="info" %}

* You may also use [organization notifications](/workbench-setup/notifications/manage-organization-notifications) simultaneously.&#x20;
* For more information about notifications, including a list of email notifications enabled by default, see [About Notifications](/workbench-setup/notifications/about-notifications).
* You may also set up an [email digest](/workbench-setup/get-started/manage-your-profile-and-user-account-settings#set-up-an-email-digest) that will send a daily or weekly summary of open actions assigned to your organization.
  {% endhint %}

## Prerequisites

* If you wish to set up email notifications on behalf of other users, you must have Organization Admin permissions in Workbench.

## Add an Email Notification for Yourself

When you set up an email notification, you simply select a notification event that should be sent to the email address.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the top right, select your initials and then select **Manage account**.

![Select the icon in the top right and then select manage account under the email address.](https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F2Z7uTsD7bZqxsAWV8Sdx%2Funknown.png?alt=media\&token=cacc398d-7929-4ad4-b767-f084e06c2bec)

3. The My Profile page should display, with the **Email Notifications** tab selected by default.&#x20;

{% hint style="info" %}
If it does not, navigate to **Settings > Organization Settings > My Profile** and select the **Email Notifications tab**.
{% endhint %}

4. Select **Add Notification**.
5. Complete the fields as follows:
   * **Conditions** - select an event, and then select an action; some events may also allow you to add one or more conditions.
   * **Notify via** - the email you have set up with Workbench displays here (the destination email cannot be changed on this screen).
   * Select **Save** to activate the notification.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FKA1pEknNS8YEQlNBYipD%2Funknown.png?alt=media&amp;token=9e2e4ff5-81e4-4b19-9acd-0f66aac2c037" alt="Image showing an example configuration for an alert."><figcaption></figcaption></figure>

6. Repeat this process for any additional notifications you wish to set up for your email address.

## Edit an Email Notification for Yourself

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the top right, select your initials and then select **Manage account**.

![Select the icon in the top right and then select manage account under the email address.](https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F2Z7uTsD7bZqxsAWV8Sdx%2Funknown.png?alt=media\&token=cacc398d-7929-4ad4-b767-f084e06c2bec)

3. The My Profile page should display, with the **Email Notifications** tab selected by default.

{% hint style="info" %}
If it does not, navigate to **Settings > Organization Settings > My Profile** and select the **Email Notifications** tab.
{% endhint %}

4. Select the **edit** icon for the notification you wish to edit.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FYgc2Z5lqg2I82UzChVvX%2Funknown.png?alt=media&amp;token=c2bfd75e-91fa-4a71-8913-1ac7a4c5f2b9" alt="The edit icon for the alert is at the top right."><figcaption></figcaption></figure>

5. Make changes to the conditions as needed, then select **Save**.
6. Repeat this process for any additional notifications you wish to edit.

## Delete an Email Notification for Yourself

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the top right, select your initials and then select **Manage account**.

![Select the icon in the top right and then select manage account under the email address.](https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F2Z7uTsD7bZqxsAWV8Sdx%2Funknown.png?alt=media\&token=cacc398d-7929-4ad4-b767-f084e06c2bec)

3. The My Profile page should display, with the **Email Notifications** tab selected by default.

{% hint style="info" %}
If it does not, navigate to **Settings > Organization Settings > My Profile** and select the **Email Notifications** tab.
{% endhint %}

4. Select the **delete** icon for the notification you wish to delete.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fn74qZsBGQXVf7sOHizUx%2Funknown.png?alt=media&amp;token=287c6e5e-f485-4eca-9f0e-c380569960bc" alt="The delete icon for the alert is at the top right."><figcaption></figcaption></figure>

5. On the confirmation screen, select **Delete**.
6. Repeat this process for any additional notifications you wish to delete.

## Manage Email Notifications for a User (Admins only)

If you have Organization Admin permissions, you can view and control email notifications for the users in your organization. You may wish to use this feature, for example, to set up appropriate notifications for new users during their onboarding.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Access your organization's user list by using the side menu to navigate to **Settings > Organization Settings > Users**.
3. Find the user whose notifications you wish to manage.
4. Use the arrow to the left of their name to select **View and edit**.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FhllTjIPBTB24E24VgyER%2Funknown.png?alt=media&amp;token=ad535f57-b76a-4702-8b06-45e7141e5d45" alt="Use the arrow beside the username to access the view and edit option."><figcaption></figcaption></figure>

5. You are now on the user's My Profile page, and can follow the same instructions in this guide (begin at step 4 in each set of instructions) to:
   * [Add an email notification](#add-an-email-notification-for-yourself)
   * [Edit an email notification](#edit-an-email-notification-for-yourself)
   * [Delete an email notification](#delete-an-email-notification-for-yourself)
6. Repeat this process for any additional users.


# Manage Organization Notifications

*This topic covers organization-level notifications that are sent to an integration or plug-in. If you are looking for email notifications, see* [*Manage Email Notifications*](/workbench-setup/notifications/manage-email-notifications)*.*

{% hint style="info" %}

* All organization notifications are viewed and edited on the Notifications tab in [Organization Settings](https://workbench.expel.io/settings/organizations).
* For more information about notifications, including a list of organization notifications enabled by default, see [About Notifications](/workbench-setup/notifications/about-notifications).
  {% endhint %}

Workbench uses organization notifications to specify when to send requested data to an integration destination, and what the scope of the data should be. It is important to understand that an integration destination will not receive any data after setup (configured on the Integrations tab) until at least one organization notification is also created for that integration (configured on the Notifications tab).

## Prerequisites

1. You must have organization admin permissions in Workbench to set up notifications.
2. You must have already set up an integration for the [supported platform(s)](/workbench-setup/notifications/about-notifications#supported-platforms) you want to use, and any separate destinations you wish to have for that integration.

## Add an Organization Notification

{% hint style="warning" %}
You must have already [set up the integration(s)](/workbench-setup/notifications/about-notifications#supported-platforms) you want to use, and any separate destinations you wish to have for that integration, before you can add a notification.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Settings > Organization Settings**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select the **Notifications** tab.
4. Select **Add Notification**.
5. Complete the fields as follows:
   * **Conditions** - select an event, and then select an action; some events may also allow you to add one or more conditions.&#x20;
   * **Notify via** - select the name of the destination for your chosen integration (in this example, the integration is a webhook and the specific destination we created within that integration is called "Example Webhook").
   * Select **Save** to activate the notification.

{% hint style="info" %}
**For** [**ServiceNow**](/workbench-setup/notifications/platform-setup/servicenow-setup-for-organization-notifications#how-to-configure) **only:** There is a specific action of `has any state change` within organization notifications for the `Investigation` and `Incident` event types. When configuring notifications for this set of conditions, set the `notify via` destination to ServiceNow.
{% endhint %}

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fow3lV3HMhVWTxjp8fUlU%2Funknown.png?alt=media&amp;token=70418dc2-da82-4ee7-a4cb-990c0752dc30" alt="Image showing example conditions, actions, and destination."><figcaption></figcaption></figure>

6. Repeat this process for any additional notifications you wish to set up for your integration(s).

## Edit an Organization Notification

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Settings > Organization Settings**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select the **Notifications** tab.
4. Select the **edit** icon for the notification you wish to edit.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fr5DEsQUs4ai8YwG1XCmw%2Funknown.png?alt=media&amp;token=d0708ef1-6220-49dd-b2d3-153e9fd2a677" alt="Use the pencil icon to edit the notification."><figcaption></figcaption></figure>

5. Make changes to the conditions and destination as needed, then select **Save**.
6. Repeat this process for any additional notifications you wish to edit.

## Delete an Organization Notification

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Settings > Organization Settings**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select the **Notifications** tab.
4. Select the **delete** icon for the notification you wish to delete.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FOEwdnH0ecNqdIzQYVHXr%2Funknown.png?alt=media&amp;token=fa512783-3897-4fa4-b34d-f635a961e89d" alt="Use the trashcan icon to delete the notification."><figcaption></figcaption></figure>

5. On the confirmation screen, select **Delete**.
6. Repeat this process for any additional notifications you wish to delete.

## Disable All Notifications for an Integration

Disabling an integration will also automatically disable all organization notifications for that integration.&#x20;

{% hint style="info" %}
You might choose to disable at the integration-level if you wish to temporarily turn off all notifications for that integration (and do not want to manually delete those notifications, or disconnect and delete the integration completely).
{% endhint %}

1. [Log in to Workbench](https://support.expel.io/hc/en-us/articles/4484518380563-Manage-Organization-Notifications-for-Workbench#h_01JJADRWQ3JWHNPRNQBTQ370SW).
2. In the side menu, navigate to **Settings > Organization Settings**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select the **Integrations** tab.
4. Locate the integration and use the arrow <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADgAAABACAYAAABP97SyAAABRklEQVR4AeySQQ6DMAwEUS+8jw/wRd7GkVOrOVRKpJYAxpaDttJKJthk19PXuq7vJ+s1PPyngL0DFkERTL4B/UWTA2raE8HmipI3iGByQE17IthcUfIGEUwOqGlPBKsVdfgggh1CqyyLYLWODh9EsENolWUXgsuyDPM8XxKz27ZVJi0PLgGnaRrQWWPMoHEcz47+7XcJyG0YRdRHRC860numxy0gJjCMqPdED9rrufrONSCmMI6of4l36Ne7O87cA2KSAIi6FGeoPLu7DgmIaYIgakSNqD0VFpAQBCrFmbdCAxLmG5A6QuEBI0KVdyhguY2TdYp2EUyBwWBCBA3LSzEqgikwGEyIoGF5KUZFMAUGgwkRNCwvxagIpsBgMCGChuWlGBXBMAxOF4mg02LDPiuCYat2ukgEnRYb9lkRDFu100WPJ/gBAAD///xRtLkAAAAGSURBVAMAVmQJgCugYIUAAAAASUVORK5CYII=" alt="" data-size="line"> to open the menu, then select **Disable**.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FckRGkG1Qaa1fpXP2mYQD%2Funknown.png?alt=media&amp;token=2d9771a1-759c-46fa-be34-fd49c239fff2" alt="Select disable from the menu that displays."><figcaption></figcaption></figure>

5. The integration is now disabled, and so are notifications. You can use the same arrow to re-enable the integration whenever you wish.


# Manage Threaded Notifications in Slack or Teams

{% hint style="warning" %}
This option is only available for two-way, or bidirectional, notifications in Slack or Microsoft Teams specifically when **Investigations** or **Incidents** are created in Workbench.
{% endhint %}

*If you are looking for organization-level notifications that are sent to an integration or plug-in, see* [*Manage Organization Notifications*](/workbench-setup/notifications/manage-organization-notifications)*. If you are looking for email notifications, see* [*Manage Email Notifications*](/workbench-setup/notifications/manage-email-notifications)*.*

Workbench can integrate with Slack or Microsoft Teams to allow for two-way messaging with our SOC Analysts. You can thread your replies directly onto the Slack or Teams "Investigation Created" and "Incident Created" notifications, and responses from Workbench will flow back into your Slack or Microsoft Teams thread, creating a seamless conversation loop.

## Prerequisites

1. You must have already set up the [Slack or Microsoft Teams platforms](/workbench-setup/notifications/platform-setup) so that they can receive organization notifications in Workbench.
   * Our [Support team](/support) can help you with this step.
2. You must have a **valid email address** in your Slack or Teams profile.
3. You must have the **Comment Created** organization notification turned on for Slack or Microsoft Teams.
4. You must have either (or both) of the **Incident Created** and **Investigation Created** organization notifications turned on for Slack or Microsoft Teams.&#x20;

{% hint style="info" %}
For help turning on the necessary organization notifications, see [Manage Organization Notifications](/workbench-setup/notifications/manage-organization-notifications).
{% endhint %}

## Bidirectional Notifications via Slack

{% tabs %}
{% tab title="Slack to Workbench" %}

1. Add a comment to an existing **Incident Created** or **Investigation Created** thread in Slack. You may also include images. Ruxie (our automated response bot) acknowledges the message is received.
2. The comment appears on the Incident or Investigation in Workbench and the SOC is notified, with no support ticket or Workbench login required.<br>

   <figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FUThMiXXKX552SlwG9iES%2Funknown.png?alt=media&amp;token=08ed2c38-a185-4218-afa7-ca9106a526c2" alt="Image showing an example Slack thread."><figcaption></figcaption></figure>

{% endtab %}

{% tab title="Workbench to Slack" %}

1. Add a comment to an Incident or Investigation in Workbench and the SOC is notified without the need to create a ticket.
2. The comment appears in a thread under the **Incident Created** or **Investigation Created** notification in Slack. Further communication for this Incident or Investigation will occur in this thread.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fi54C1XNMhKtfR8js3PyB%2Funknown.png?alt=media&amp;token=5ad88631-1933-4034-9b44-f6c7d2d13bf2" alt="Image showing an example Workbench and Ruxie thread."><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}

## Bidirectional Notifications via Microsoft Teams

{% tabs %}
{% tab title="Teams to Workbench" %}

1. Add a comment to an existing **Incident Created** or **Investigation Created** thread in Teams. You may also include images. Ruxie (our automated response bot) acknowledges the message is received.
2. The comment appears on the Incident or Investigation in Workbench and the SOC is notified, with no support ticket or Workbench login required.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fu06oXQXTW35tqHPuQppk%2Funknown.png?alt=media&amp;token=a71f4f13-b212-45fc-9204-ed6c326b7f04" alt="Image showing an example thread."><figcaption></figcaption></figure>
{% endtab %}

{% tab title="Workbench to Teams" %}

1. Add a comment to an Incident or Investigation in Workbench and the SOC is notified without the need to create a ticket.
2. The comment appears in a thread under the **Incident Created** or **Investigation Created** notification in Teams. Further communication for this Incident or Investigation will occur in this thread.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F6kOXOwLkscA1HGxM143U%2Funknown.png?alt=media&amp;token=ca430bdc-bcd0-4cb7-b392-becd30b4fffe" alt="Image showing an example Workbench and Ruxie thread."><figcaption></figcaption></figure>
{% endtab %}
{% endtabs %}


# Auto Remediations


# About Auto Remediations

This topic provides general information about auto remediations and which ones are available.

*If you are ready to set up your auto remediations, go to* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench)*.*

When you enable an auto remediation, you allow Expel to automate certain response capabilities within your system(s) so that attacks can be rapidly contained without requiring any intervention from you. All remediation actions are created in Workbench, but the actions themselves are taken within your specific vendor technologies.

* Our SOC analysts make the call on when and what to remediate based on the settings you specify.
* Expel automates the remediation action itself but not the decision to remediate.
* The remediation action is only initiated from an [Incident](/workbench-reference/expel-terminology#incident) and not from an [Investigation](/workbench-reference/expel-terminology#investigation) (exception: the attack surface is different for Managed Phishing, so we do initiate the remediation action from both).
* You have the option to customize a deny list so that certain files or paths are not subject to the actions of a remediation.
* You may disable a remediation at any time via Workbench.
* If for some reason Expel cannot complete the remediation, the action will be assigned to you to complete.

Auto remediations are configured by going to **Organization Settings** > **My Organizations** > **Auto Remediations** tab. You must have **Administrator** access in Workbench to configure auto remediations.

Watch our Introduction to Auto Remediations video to learn more.

{% embed url="<https://player.vimeo.com/video/1134411904?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0&h=c4c1fcfb35>" %}

## **Available Auto Remediations** <a href="#h_01hz5c2axyn535hfes2n7e3mt3" id="h_01hz5c2axyn535hfes2n7e3mt3"></a>

Expel offers a number of auto remediations, which are enabled or disabled at the organization level. Use these links to skip ahead to learn more about the ones you are most interested in.

* [Block Known Bad Hashes](#h_01hz5c2axy8yyxhrqt99qr8vhx)
* [Contain Hosts](#h_01hz5c2axyj8rgnvfavbys88g9)
* [Deactivate Access Keys](#h_01hz5c2axynj0m4sb6wfgaz8xr)
* [Delete Malicious Files](#h_01hz5c2axyay1nxkt3mabxm921)
* [Delete Registry Key](#h_01hz5c2axz455wcshc3qm7v9d2)
* [Disable Accounts](#h_01hz5c2axz455wcshc3qm7v9d2)
* [Kill Processes](#h_01hz5c2axzbe8snapcbds4rypv)
* [Remove Malicious Email](#h_01hz5c2axztcyb5tz99gved5mm)
* [Reset Credentials](#id-01j7m2h11k0zab3fp6gfs2418c)

### **Block Known Bad Hashes** <a href="#h_01hz5c2axy8yyxhrqt99qr8vhx" id="h_01hz5c2axy8yyxhrqt99qr8vhx"></a>

Blocking known bad hashes (which may be referred to by different vendor technologies as application blocking, banning hashes, blacklisting hashes, or indicator-based file blocking) prevents further propagation of an attack by blocking potentially malicious processes and files by their hash values.

All EDR vendors block the execution of a process by its hash. Some vendors also prevent the file itself from being accessed or modified, while other vendors ban shared libraries (DLLs). Depending on the vendor and the endpoint system, a couple of minutes of latency may exist between the action and the prevention.

Watch our Auto Block Bad Hashes video for a configuration walkthrough and to learn more.

{% embed url="<https://player.vimeo.com/video/1134411874?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0&h=ede2afbc5e>" %}

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Contain Hosts** <a href="#h_01hz5c2axyj8rgnvfavbys88g9" id="h_01hz5c2axyj8rgnvfavbys88g9"></a>

Host containment (which may be referred to by different vendor technologies as quarantine or isolation) blocks incoming and outgoing network traffic except for the traffic necessary to maintain a connection to the security device console. This allows investigators to continue triaging a device from a security device console, while reducing the risks involved with allowing a compromised device to have continued access to the local network.

Each vendor technology handles host containment differently, but they usually perform the following actions:

* Block all TCP traffic to any IP/ports.
* Block all UDP connections except for those responsible for DNS requests (e.g. UDP/53); DNS/DHCP is generally allowed in order to ensure the bilateral communication between the console and the contained device.
* Allow ARP to ensure MAC addresses can resolve to IP addresses.
* Allow ICMP (ping).
* Terminate active sockets.

Some security devices can also allow connections to an allowed IP list.

Watch our Auto Host Containment video for a walkthrough and to learn more about this remediation action.

{% embed url="<https://player.vimeo.com/video/1134411768?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0&h=078d598549>" %}

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Deactivate Access Keys** <a href="#h_01hz5c2axynj0m4sb6wfgaz8xr" id="h_01hz5c2axynj0m4sb6wfgaz8xr"></a>

In response to a suspected security incident in your cloud environment, Expel can automatically deactivate potentially compromised long-term AWS access keys that are tied to AWS IAM users, based on unique access key IDs.

Deactivating keys is a proactive measure that aims to sever the attacker's access point and mitigate the risk of a further data breach or system compromise. The goal is to contain the threat by preventing adversaries from continuing to use these keys to access your cloud resources. When Workbench completes the action, the deactivation occurs immediately in AWS.

**Note**

Expel only automates the deactivation of long-term access keys; we do not delete or rotate keys, because such measures are more destructive and are potentially premature. After your access keys are deactivated, you should rotate the compromised keys via AWS and update all cloud applications and services that require these keys to complete tasks.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Delete Malicious Files** <a href="#h_01hz5c2axyay1nxkt3mabxm921" id="h_01hz5c2axyay1nxkt3mabxm921"></a>

If our SOC analysts identify a malicious file that must be removed, Workbench completes the action automatically after that action is created unless it is specifically called out as a file path or hostname on the deny list. If it is on the deny list, we assign the action to your team and notify you based on your notification preferences.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Delete Registry Key** <a href="#h_01hz5c2axz455wcshc3qm7v9d2" id="h_01hz5c2axz455wcshc3qm7v9d2"></a>

When your Windows-based Crowdstrike environment is threatened in such a way that deleting a malicious registry key is necessary, Workbench completes the action automatically after our SOC analysts make the determination. This is often leveraged when malware is using compromised registry keys to run every time the system starts or a user logs in. The deletion nullifies the threat in seconds, and prevents the malware from regaining control of the system.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Disable Accounts** <a href="#h_01hz5c2axz455wcshc3qm7v9d2" id="h_01hz5c2axz455wcshc3qm7v9d2"></a>

Disabling a user account (which may be referred to by different vendor technologies as blocking user, suspending user, changing user status, removing user from org, or locking user account) prevents further propagation of an attack by targeting a compromised user account's username or email address. As part of automating this action in Workbench, we also log the compromised user out of their existing session. Both of these actions are immediate in the target vendor technology.

Watch our Auto Disable Account video for a configuration walkthrough and to learn more.

{% embed url="<https://player.vimeo.com/video/1134411818?amp;app_id=58479&autopause=0&badge=0&byline=0&player_id=0&portrait=0&title=0&h=94663ed567>" %}

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Kill Processes** <a href="#h_01hz5c2axzbe8snapcbds4rypv" id="h_01hz5c2axzbe8snapcbds4rypv"></a>

If our SOC analysts identify a malicious process that must be killed, Workbench completes the action automatically after that action is created unless it is specifically called out as a process path or hostname on the deny list. If it is on the deny list, we assign the action to your team and notify you based on your notification preferences.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Remove Malicious Email** <a href="#h_01hz5c2axztcyb5tz99gved5mm" id="h_01hz5c2axztcyb5tz99gved5mm"></a>

If our SOC analysts identify a malicious email that must be removed, Workbench completes the action automatically after that action is created unless it is specifically called out as an inbox on the deny list. If it is on the deny list, we assign the action to your team and notify you based on your notification preferences.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**

### **Reset Credentials** <a href="#id-01j7m2h11k0zab3fp6gfs2418c" id="id-01j7m2h11k0zab3fp6gfs2418c"></a>

Requiring a user to reset their credentials (which may be referred to by different vendor technologies as "expire password", or "force change password on next sign-in") prevents further propagation of an attack by stopping unauthorized access. After this remediation action is taken, the compromised user must authenticate with MFA before creating new credentials. As part of automating this action in Workbench, we also log the compromised user out of their existing session. Both of these actions are immediate in the target vendor technology.

**Ready to enable this auto remediation?** **Go to** [**Enable an Auto Remediation in Workbench**](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) **to get started.**


# Enable an Auto Remediation in Workbench

Expel offers a variety of auto remediations for specific devices.

For more information and a list of available auto remediations, see [About Auto Remediations](/workbench-setup/auto-remediations/about-auto-remediations). Auto remediations are configured by going to **Organization Settings > My Organizations > Auto Remediations tab**.

## Prerequisites <a href="#h_01jfd2nw8bn9d4339n56yfpxw4" id="h_01jfd2nw8bn9d4339n56yfpxw4"></a>

1. You must have an [Organization Admin](/workbench-setup/get-started/add-and-manage-users/user-role-rights) role in Workbench, as auto remediations are enabled at the organization level.
2. You must meet all other prerequisites that are required for your specific device (additional prerequisites will be listed in the guides linked in Step 1 on this page).

## Step 1: Prepare the Vendor Device(s) <a href="#h_01jfd2nw8bbv4gq2anpz6drh61" id="h_01jfd2nw8bbv4gq2anpz6drh61"></a>

The first step is to follow the setup guide for the specific auto remediation + device(s) you wish to enable. The guides show you how to set up the device properly on the vendor side in preparation for the auto remediation.

{% hint style="warning" %}
**Remember that the auto remediation will only work if you have first completed the associated device setup guide(s).**
{% endhint %}

### Before You Begin <a href="#h_01jfd2nw8bb2sds6m039njytam" id="h_01jfd2nw8bb2sds6m039njytam"></a>

1. Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation.
2. Know that you may need to complete more than one device setup guide. For example:
   * **If you have more than one device that will have an auto remediation enabled, you will need to complete a setup guide for each device.**\
     \
     *Example: To enable Auto Disable Account for both GitHub and Google Workspace, you will need to complete both the GitHub Auto Disable Account and Google Workspace: Auto Disable Account setup guides.*
   * **If you wish to enable more than one auto remediation on a particular device, you will need to complete more than one setup guide for that device.**\
     \
     *Example: To enable both Auto Disable Account and Reset Credentials for Office 365, you will need to complete both the Office 365: Auto Disable Account and Office 365: Reset Credentials setup guides.*
3. Remember that auto remediations are not yet available for all devices; if a device setup guide does not exist for a particular auto remediation, that auto remediation cannot be enabled for the device.

### Locate And Complete Your Setup Guide(s) <a href="#h_01jfd2nw8cgga7kf1sr87j5nnp" id="h_01jfd2nw8cgga7kf1sr87j5nnp"></a>

1. Search for or navigate to the setup guide(s) for the auto remediation + device(s) you wish to set up.&#x20;

<button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Search…</button>

2. Follow all steps in each setup guide.
3. Return to this page and continue to the [Step 2](#h_01jfd2nw8cra7eb7phk8tywrtj) section to finish the setup process.

## Step 2: Enable the Auto Remediation in Workbench <a href="#h_01jfd2nw8cra7eb7phk8tywrtj" id="h_01jfd2nw8cra7eb7phk8tywrtj"></a>

Next, you will enable the auto remediation in Workbench and specify your preferred device(s).

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > My Organizations**.
   * If you have multiple organizations, you must also select the appropriate organization name from the list.
3. Scroll down and select the **Auto Remediations** tab.
4. Locate the auto remediation you wish to enable and hover over it, then select the **pencil** icon to edit it.
5. In the Step 1 section:
   * You should have already completed this step by using the guides linked in Step 1 above.
   * If not, follow the instructions in your setup guide(s) and return to this section to complete the remaining steps.
6. In the Step 2 section:
   * Choose the specific device(s) you would like this auto remediation to apply to (you may choose multiple devices).
   * The SOC analysts will *only* run this auto remediation on the device(s) you set as preferred, so be sure to check your selections carefully.
   * If applicable, [review the setup and note additional permissions required](/workbench-setup/auto-remediations/auto-remediation-manual-fallback) before opting in to **manual fallback** for eligible auto remediations. Manual fallback is available for customers with Pro Support or MDR Premium Pro tier. With manual fallback enabled, in the event that an automated action fails and Expel has console access, our SOC will attempt to manually perform remediation.

{% hint style="info" %}
**Your choices apply to this auto remediation only; you may choose other preferred devices for other auto remediations.** The devices shown in the dropdown menu will vary based upon what you have configured in Workbench and which auto remediation you are enabling.
{% endhint %}

7. In the Step 3 section:
   * Create an allow or deny list (optional; varies by auto remediation) by utilizing context labels. If you do not wish to create a deny list, continue to the next step.
   * If you need to edit the existing context labels in some way, [contact support](/support) for assistance.
8. In the Step 4 section:
   * Use the link to review Expel’s terms and conditions.
   * Select the **Enable** checkbox.
9. Select **Save**.
10. Repeat all of these steps to configure additional auto remediations.
    * Make sure you have set up your devices as instructed in [Step 1](#h_01jfd2nw8bbv4gq2anpz6drh61) before enabling additional auto remediations in Workbench.

The auto remediation is now enabled and active. If we are unable to complete an auto remediation and you do not have manual fallback configured, the action will be assigned to you for completion as a manual remediation in Workbench. If you have manual fallback configured, we will first attempt the action manually. If we are unable to complete the action via the security device console, the action will be assigned to you with an explanation of why we could not complete it ourselves.


# Auto Remediation Manual Fallback

The manual fallback feature allows Expel to perform hands-on remediation if an automated action fails.

*This guide supports an optional feature as part of the larger setup process in* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench)*.*

If you opt to enable manual fallback, in the event that an automated action fails and Expel has console access, our SOC will attempt to manually perform hands-on remediation on your behalf.

{% hint style="info" %}
The manual fallback option is available to customers who have purchased Expel's Pro Support or MDR Premium Pro tier and have enabled a supported auto remediation. If you do not have access to certain auto remediation components and would like to, [contact Support](/support). **Manual fallback is supported for one security device per auto remediation.**
{% endhint %}

This option is available for the following auto remediations:

* [Cortex XDR: Contain Hosts](/workbench-setup/auto-remediations/contain-hosts/palo-alto-networks-cortex-xdr-contain-hosts)
* [Crowdstrike: Contain Hosts](/workbench-setup/auto-remediations/contain-hosts/crowdstrike-contain-hosts)
* [Microsoft Defender for Endpoint: Contain Hosts](/workbench-setup/auto-remediations/contain-hosts/microsoft-defender-for-endpoint-contain-hosts)

To enable manual fallback:

1. Select the device on which you would like to configure manual fallback.
2. In the **Recommended actions** field, provide specific instructions for any unique workflows or setup that SOC analysts may need to perform remediation actions in your environment. This text will be sent to the SOC analyst when manual fallback is required to help them successfully perform the response in your console.

{% hint style="info" %}
If you have "Auto-Remediation Failed" [notifications](/workbench-setup/notifications/about-notifications) enabled on a device configured for manual fallback, the notifications will include contextual text indicating if a manual fallback is underway for that specific failed remediation.
{% endhint %}

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fgit-blob-8911dd146f82ac6f61579702446c605f04cac27d%2Fmanual_fallback_section-2.png?alt=media" alt="Manual fallback opt-in section in Step 2: Set preferred devices."><figcaption></figcaption></figure>

### Required Permissions <a href="#h_01kbqqrjdxhrp0js3wqynvkx2w" id="h_01kbqqrjdxhrp0js3wqynvkx2w"></a>

Depending on the technology, Expel may require more than console access to support manual fallback. **Please review the requirements below to ensure Expel has access to perform remediation when needed.**

\
**Cortex XDR: Contain Hosts**

The [Palo Alto Networks Cortex XDR Pro setup guide](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-cortex-xdr-pro-setup-for-workbench) provides the necessary permissions within the console access section (Privileged Security Admin role). Ensure your configuration includes this role.

\
**CrowdStrike: Contain Hosts**

Expel requires additional permissions than what are included in the [CrowdStrike Falcon Insight XDR setup guide](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench). To enable manual fallback, you must log into your CrowdStrike Falcon console and update the API Client so that the API scopes for Hosts and Real Time Response are set to **Read/Write access**. This scope allows Expel to view hosts and perform critical actions like Network Containment and Remove from Containment.

\
**Microsoft Defender for Endpoint: Contain Hosts**

If you chose [Option 1: Basic AAD Permissions](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench#option-1-basic-aad-permissions) during setup, ensure you have granted **full access**, which we require to complete manual fallback.

If you chose [Option 2: RBAC Permissions](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench#option-2-rbac-permissions) during setup, ensure that you have granted the following permissions depending on your technology:

| **Microsoft Defender for Endpoint** | <ol><li>Active remediation actions (all)</li></ol>                                                                                      |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Microsoft Defender XDR**          | <ol><li>Security operations \ Security data \ Response (manage)</li><li>Security operations \ Advanced live response (manage)</li></ol> |

After you have completed the above, refer back to [Step 2.7 of Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench#h_01jfd2nw8cra7eb7phk8tywrtj) to finish configuring the auto remediation.


# Block Bad Hashes


# Broadcom Carbon Black Cloud: Block Bad Hashes

This guide helps you set up your Carbon Black Cloud device and grant necessary permissions so that you can enable the Block Bad Hashes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a hash that must be blocked, Workbench completes the action automatically unless it is specifically called out as a "Never block" asset (these hashes must be added as context and then configured in Workbench; see [Step 2](#h_01jgyc8wpyhctwv9qstbsatmnq)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Carbon Black Cloud Reputation Overrides API**

`appservices/v6` , `sha256`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><code>appservices/v6/orgs/{org_key}/reputations/overrides/_search</code></td><td>Pre-check: look up whether the hash is already on the block list</td></tr><tr><td>POST</td><td><code>appservices/v6/orgs/{org_key}/reputations/overrides/</code></td><td>Add a blacklist reputation override for the hash (the block)</td></tr></tbody></table>

Revert (unblock): POST `.../reputations/overrides/_search` to find the override ID, then POST `.../reputations/overrides/_delete` to remove it.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jgyc5bhehrsnz8xw7dkf0d7r" id="h_01jgyc5bhehrsnz8xw7dkf0d7r"></a>

1. Make sure you assign all API permissions in the [Broadcom Carbon Black Cloud Setup for Workbench](/connect-your-technology/a-c-integrations/broadcom/broadcom-carbon-black-cloud-formerly-cb-threathunter-and-cb-defense-setup-for-workbench) guide.
2. Enable the following permissions for Expel:
   * Manage Reputations and Auto-Banned List
   * View Reputations

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fhg36R02J5NaUkXPB7ivX%2FCARBON%20BLACK%20PERMISSIONS.png?alt=media&amp;token=39577bc5-d7b2-4e4d-bd53-8bcdd6bcfeb4" alt="Carbon Black UI indicates Manage Reputations and Auto-Banned List and View Reputations permissions are enabled." width="563"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any hashes for a "do not block" list, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, add any hashes that should be on the "do not block" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hashes as "Never block" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies a hash that must be blocked, any hashes added as "Never block" assets are assigned to you as actions rather than being blocked automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Carbon Black Cloud device is now ready for the Block Bad Hashes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# CrowdStrike: Block Bad Hashes

This guide helps you set up your CrowdStrike device and grant necessary permissions so that you can enable the Block Bad Hashes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a hash that must be blocked, Workbench completes the action automatically unless it is specifically called out as a "Never block" asset (these hashes must be added as context and then configured in Workbench; see [Step 2](#h_01jgyc8wpyhctwv9qstbsatmnq)).

{% hint style="info" %}
CrowdStrike can only block .exe execution through hash. Any other file type is still able to run.&#x20;
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**CrowdStrike Falcon IOC Management API**

`/iocs/.../v1` , `sha256`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/iocs/queries/indicators/v1</code></td><td>Pre-check: find an existing IOC matching the hash</td></tr><tr><td>POST</td><td><code>/iocs/entities/indicators/v1</code></td><td>Create a custom IOC for the hash with action <code>prevent</code>, severity high, applied to all hosts (the block)</td></tr></tbody></table>

Revert (unblock): GET `/iocs/queries/indicators/v1` to find the IOC ID, then DELETE `/iocs/entities/indicators/v1?ids=...`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jgywa3vxbvzh5mrtyntfr5sx" id="h_01jgywa3vxbvzh5mrtyntfr5sx"></a>

1. Make sure you assign all API permissions in the [CrowdStrike Falcon Setup for Workbench](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench) guide.
2. Within API scopes, enable both **read** and **write** permissions for **IOC Management** for the Expel API client.
3. In Prevention Policies, enable **Custom Blocking** in the Malware Protection/Execution Blocking for each operating system (Windows, Mac, Linux).\ <br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FoEvFhRlU21tAV5KIWTcU%2Fpolicy-change1.png?alt=media&amp;token=818e56e7-db50-4b6d-8ba4-712b12cf7d93" alt="Select Edit Policy in the Prevention Policies list."><figcaption></figcaption></figure></div>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FpF1yEgKXkEkC2e80jabx%2Fpolicy-change2.png?alt=media&amp;token=271f40f9-104f-4eb8-8576-c6697a17e81f" alt="Within the Policy Settings tab, Custom Blocking has been enabled."><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any hashes for a "do not block" list, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, add any hashes that should be on the "do not block" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hashes as "Never block" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies a hash that must be blocked, any hashes added as "Never block" assets are assigned to you as actions rather than being blocked automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your CrowdStrike device is now ready for the Block Bad Hashes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Defender for Endpoint: Block Bad Hashes

This guide helps you set up your Microsoft Defender for Endpoint device and grant necessary permissions so that you can enable the Block Bad Hashes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a hash that must be blocked, Workbench completes the action automatically unless it is specifically called out as a "Never block" asset (these hashes must be added as context and then configured in Workbench; see [Step 3](#h_01jgyc8wpyhctwv9qstbsatmnq)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Defender for Endpoint API**

base `https://api.securitycenter.windows.com`, `sha256`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/indicators?$filter=indicatorValue eq '{hash}'</code></td><td>Pre-check: is the hash already a blocked indicator</td></tr><tr><td>POST</td><td><code>api/indicators</code></td><td>Create the indicator with action to alert and block, severity High (the block)</td></tr></tbody></table>

Revert (unblock): GET `api/indicators?$filter=...` to find the indicator ID, then DELETE `api/indicators/{id}` for each match.

## Prerequisites <a href="#h_01jh0vcwgakvzn6ss6mxtwcgy4" id="h_01jh0vcwgakvzn6ss6mxtwcgy4"></a>

* Your organization uses Microsoft Defender Antivirus in Active Mode and Cloud-based protection is enabled.
* The Anti-malware client version must be 4.18.1901.x or later.
* Devices are on Windows 10, version 1703 or later, or Windows Server 2016 and 2019.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh0w8t5faasa8yvezv0vv17v" id="h_01jh0w8t5faasa8yvezv0vv17v"></a>

1. Make sure you assign all API permissions in the [Microsoft Defender for Endpoint Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench) guide.
2. Select **Settings > Endpoints > Advanced features**.
3. Turn on **Allow or block file**.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FY4Z3wMQWny9flnoqAbnb%2Fatp3.png?alt=media&amp;token=a2d325ce-d53f-4f41-aaf0-ef32c08450aa" alt="The Microsoft Defender UI indicates Allow of block file is enabled." width="375"><figcaption></figcaption></figure></div>
4. Select **Save preferences**.

## Step 2: Update API Permissions <a href="#h_01hx9ee0ykrs3z64h169bz8e1h" id="h_01hx9ee0ykrs3z64h169bz8e1h"></a>

### **Option 1: Enable the Defender for Enterprise Application** <a href="#h_01jh1h31m7t91jp4e4cgfm4ngj" id="h_01jh1h31m7t91jp4e4cgfm4ngj"></a>

1. Select **Grant admin consent** in the **Expel Defender for Endpoint Integration > API permissions** tab and consent to the new API permissions.

### **Option 2: Create a Custom Microsoft Entra ID Application** <a href="#h_01jh1h21c3s2146jjk9nneywy3" id="h_01jh1h21c3s2146jjk9nneywy3"></a>

1. Follow the previous API permissions steps.
2. Add the following WindowsDefenderATP permissions:
   * Ti.ReadWrite
   * Ti.ReadWrite.All
3. Grant admin consent.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FUhGrWbRjnViOtB9GWyiK%2FATP_indicator_permissions2.png?alt=media&amp;token=bd51f067-296c-4b0b-8d33-87bf5c60333a" alt="Microsoft Defender UI indicates Ti.ReadWrite and Ti.ReadWrite.All permissions are Granted for Expel." width="375"><figcaption></figcaption></figure></div>

## Step 3: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any hashes for a "do not block" list, skip to** [**Step 4**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, add any hashes that should be on the "do not block" list as [context](https://support.expel.io/hc/en-us/articles/34624474608275-Expel-Terminology#h_01JAR4HC55JYAWVBVT7XTXP850) for your environment. You will then be able to select those hashes as "Never block" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies a hash that must be blocked, any hashes added as "Never block" assets are assigned to you as actions rather than being blocked automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Microsoft Defender for Endpoint device is now ready for the Block Bad Hashes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Palo Alto Networks Cortex XDR: Block Bad Hashes

This guide helps you set up your Palo Alto Networks (PAN) Cortex XDR device and grant necessary permissions so that you can enable the Block Bad Hashes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a hash that must be blocked, Workbench completes the action automatically unless it is specifically called out as a "Never block" asset (these hashes must be added as context and then configured in Workbench; see [Step 2](#h_01jgyc8wpyhctwv9qstbsatmnq)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Cortex XDR Public API**

`public_api/v1`, `sha256`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><code>public_api/v1/hash_exceptions/blocklist/</code></td><td>Add the hash to the Cortex XDR block list (the block)</td></tr></tbody></table>

No separate pre-check call; if the hash is already present, the API returns an error that Expel maps to "already remediated." No unblock capability is implemented for Cortex XDR.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh1s4h4756ad0yzsv8sdjd1s" id="h_01jh1s4h4756ad0yzsv8sdjd1s"></a>

1. Make sure you assign all API permissions in the [PAN Cortex XDR Pro Setup for Workbench](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-cortex-xdr-pro-setup-for-workbench) guide.
2. This includes the permissions to add hashes to the block list.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F7iJ4AQ8F1EjcUAvZOtGJ%2FScreen%20Shot%202021-09-16%20at%201.15.04%20PM-20210916-171554.png?alt=media&amp;token=3768d955-c3f2-4ecb-a995-8f15f7b1ca79" alt="The Block Hashes role has the Allow List/Block List permission selected." width="375"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any hashes for a "do not block" list, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, add any hashes that should be on the "do not block" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hashes as "Never block" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies a hash that must be blocked, any hashes added as "Never block" assets are assigned to you as actions rather than being blocked automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Palo Alto Cortex XDR device is now ready for the Block Bad Hashes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# SentinelOne: Block Bad Hashes

This guide helps you set up your SentinelOne device and grant necessary permissions so that you can enable the Block Bad Hashes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a hash that must be blocked, Workbench completes the action automatically unless it is specifically called out as a "Never block" asset (these hashes must be added as context and then configured in Workbench; see [Step 2](#h_01jgyc8wpyhctwv9qstbsatmnq)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**SentinelOne API**

`web/api/v2.1`, `sha1`

{% hint style="info" %}
`sha1` reflects the hash type Expel's remediation currently declares. The hash algorithm is not sent to SentinelOne (only the raw hash value is submitted), so this remediation will likely also accept a `sha256` hash. This has not been verified against SentinelOne's live API, however.
{% endhint %}

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>web/api/v2.1/restrictions</code></td><td>Pre-check: find existing blocklist entries matching the hash</td></tr><tr><td>GET</td><td><code>web/api/v2.1/accounts</code></td><td>Resolve tenant scope (account IDs) for the restriction filter</td></tr><tr><td>GET</td><td><code>web/api/v2.1/sites</code></td><td>Fallback scope resolution, only if no account IDs are found</td></tr><tr><td>POST</td><td><code>web/api/v2.1/restrictions</code></td><td>Create a black_hash blocklist entry — called once per OS (Windows, macOS, Linux)</td></tr></tbody></table>

Revert (unblock): GET `web/api/v2.1/restrictions` to find the restriction ID(s), then DELETE `web/api/v2.1/restrictions` (batch delete by ID).

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh1s4h4756ad0yzsv8sdjd1s" id="h_01jh1s4h4756ad0yzsv8sdjd1s"></a>

1. Make sure you assign all API permissions in the [SentinelOne Setup for Workbench](/connect-your-technology/q-z-integrations/sentinelone/sentinelone-singularity-endpoint-setup-for-workbench) guide.
2. This includes enabling all deny list permissions for the API user.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FNSQ5X7wIGXRkW0L2XW94%2FScreen%20Shot%202021-08-25%20at%204.10.05%20PM.png?alt=media&amp;token=1bea6e3e-031e-4cf0-816f-bb3279c5591d" alt="Blacklist View, Blacklist Edit, Blacklist Delete, and Blacklist Create permissions are configured to Allowed." width="563"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any hashes for a "do not block" list, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, add any hashes that should be on the "do not block" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hashes as "Never block" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies a hash that must be blocked, any hashes added as "Never block" assets are assigned to you as actions rather than being blocked automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your SentinelOne device is now ready for the Block Bad Hashes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Contain Hosts


# Broadcom Carbon Black Cloud: Contain Hosts

This guide helps you set up your Broadcom Carbon Black Cloud device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Carbon Black Cloud Device Actions API**

`appservices/v6`, full quarantine

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><code>appservices/v6/orgs/{org_key}/devices/_search</code></td><td>Look up the device by hostname to resolve its ID</td></tr><tr><td>GET</td><td><code>appservices/v6/orgs/{org_key}/devices/{deviceId}</code></td><td>Pre-check: read the <code>quarantined</code> state</td></tr><tr><td>POST</td><td><code>appservices/v6/orgs/{org_key}/device_actions</code></td><td>Quarantine the device (<code>action_type</code> is  <code>QUARANTINE</code>, <code>toggle</code> is <code>true</code>)</td></tr><tr><td>GET</td><td><code>appservices/v6/orgs/{org_key}/devices/{deviceId}</code></td><td>Check to make sure the device was quarantined</td></tr></tbody></table>

Revert (release): same `device_actions` call with the `toggle` set to `false`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

1. Make sure you assign all API permissions in the [Broadcom Carbon Black Cloud Setup for Workbench](/connect-your-technology/a-c-integrations/broadcom/broadcom-carbon-black-cloud-formerly-cb-threathunter-and-cb-defense-setup-for-workbench) guide.
2. Enable the Quarantine permission for the Expel role.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F0rtFgecRAxD8qJ7LBJTL%2Fpermissions_annoated.png?alt=media&amp;token=f7043d93-366c-4072-a97b-4cdf60b19078" alt="Expel Custom Role has the Quarantine permission enabled." width="375"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Carbon Black Cloud device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Broadcom Carbon Black EDR: Contain Hosts

This guide helps you set up your Broadcom Carbon Black EDR device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh6c6d256fs3mp78bf2ggywt)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Carbon Black EDR (On-prem/Response) Sensor API**

full isolation, toggled via a sensor field

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/v2/sensor?hostname={hostname}</code></td><td>Look up the sensor ID by hostname</td></tr><tr><td>GET</td><td><code>api/v1/sensor/{sensorId}</code></td><td>Pre-check: read <code>network_isolation_enabled</code> and <code>is_isolating</code></td></tr><tr><td>PUT</td><td><code>api/v2/sensor/{sensorId}</code></td><td>Isolate: set <code>network_isolation_enabled</code> as <code>true</code></td></tr><tr><td>GET</td><td><code>api/v1/sensor/{sensorId}</code></td><td>Poll isolation flags until isolated; also read <code>last_checkin_time</code></td></tr></tbody></table>

Revert (release): PUT `api/v2/sensor/{sensorId}` with `network_isolation_enabled` set to `false`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh6c69pwy1v91mbgt8a5jt7t" id="h_01jh6c69pwy1v91mbgt8a5jt7t"></a>

Make sure you assign all API permissions in the [Carbon Black EDR Setup for Workbench](/connect-your-technology/a-c-integrations/broadcom/broadcom-carbon-black-edr-formerly-cb-response-setup-for-workbench) guide. The generic API access granted gives Expel permission for isolation.

## Step 2: Update Your Context <a href="#h_01jh6c6d256fs3mp78bf2ggywt" id="h_01jh6c6d256fs3mp78bf2ggywt"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jh6c78x9h9kepqjzbr6qfzkt)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jh6c78x9h9kepqjzbr6qfzkt" id="h_01jh6c78x9h9kepqjzbr6qfzkt"></a>

Your VMware Carbon Black EDR device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# CrowdStrike: Contain Hosts

This guide helps you set up your CrowdStrike device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**CrowdStrike Falcon Hosts API**

full network containment

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/devices/queries/devices/v1?filter=hostname:'{hostname}'</code></td><td>Look up candidate device IDs by hostname</td></tr><tr><td>GET</td><td><code>/devices/entities/devices/v2?ids=...</code></td><td>Fetch host details to confirm the match</td></tr><tr><td>POST</td><td><code>/devices/entities/devices-actions/v2?action_name=contain</code></td><td>Queue network containment of the host</td></tr><tr><td>GET</td><td><code>/devices/entities/devices/v2?ids=...</code></td><td>Poll <code>status</code> until <code>contained</code>; also read <code>last_seen</code></td></tr></tbody></table>

Revert (release): POST `/devices/entities/devices-actions/v2?action_name=lift_containment`.

## Step 1: Allow Appropriate Permissions in Your Crowdstrike Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

1. Make sure you assign all API permissions in the [CrowdStrike Falcon Insight XDR Setup for Workbench](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench) guide.
2. Enable both **read and write** permissions for Hosts and **read** permission for Host Groups for the Expel API Client.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FAmdbcvnIs8aqWQfm2ctv%2FAPI-permissions2.png?alt=media&amp;token=c60ff335-93f7-4d8f-8b67-b80406209f7b" alt="Read and Write permissions are enabled for Hosts and Host groups." width="375"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your CrowdStrike device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Cybereason: Contain Hosts

This guide helps you set up your Cybereason device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Cybereason REST API**

full isolation (session-cookie auth via POST login.html on connect)

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><code>/rest/visualsearch/query/simple</code></td><td>Look up the sensor by hostname to see if hostname is isolated</td></tr><tr><td>POST</td><td><code>/rest/monitor/global/commands/isolate</code></td><td>Isolate the host</td></tr><tr><td>POST</td><td><code>/rest/visualsearch/query/simple</code></td><td>Poll isolation status until the host is isolated</td></tr></tbody></table>

Revert (release): POST `/rest/monitor/global/commands/un-isolate`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

Make sure you assign all API permissions in the [Cybereason Setup for Workbench](/connect-your-technology/a-c-integrations/cybereason-endpoint-detection-and-response-edr-setup-for-workbench) guide, including providing Level 3 to the Expel user provisioned in Cybereason.

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Cybereason device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Defender for Endpoint: Contain Hosts

This guide helps you set up your Microsoft Defender for Endpoint device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh687zj4svsxpwz14z1x6vd5)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Defender for Endpoint API**

base `https://api.securitycenter.windows.com` , full isolation

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/machines?$filter=contains(computerDnsName, '{hostname}')</code></td><td>Resolve hostname to machine ID (skipped if an asset ID is supplied)</td></tr><tr><td>GET</td><td><code>api/machineactions?$filter=...</code></td><td>Pre-check: read most recent <code>isolate</code>/<code>unisolate</code> action state</td></tr><tr><td>POST</td><td><code>api/machines/{machineId}/isolate</code></td><td>Isolate the device</td></tr><tr><td>GET</td><td><code>api/machineactions?$filter=...</code></td><td>Poll action <code>status</code> until the containment completes</td></tr><tr><td>GET</td><td><code>api/machines/{machineId}</code></td><td>Fetch <code>lastSeen</code> for logging</td></tr></tbody></table>

Revert (release from containment): POST `api/machines/{machineId}/unisolate` , or POST `api/machineactions/{machineActionId}/cancel` if an isolate action is still pending.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

Microsoft Defender for Endpoint customers have two options to activate the appropriate permissions needed to allow Workbench to support Host Containment.

### **Option 1: Allow appropriate permissions in your EDR console** <a href="#h_01jh687sqmyzxcdxacq4q4t199" id="h_01jh687sqmyzxcdxacq4q4t199"></a>

1. Make sure you select Grant admin consent within the Expel Defender for Endpoint Integration > API Permissions tab and consent to the new API permissions.

### **Option 2: Create Custom Microsoft Entra ID application** <a href="#h_01jh687zj4svsxpwz14z1x6vd5" id="h_01jh687zj4svsxpwz14z1x6vd5"></a>

1. Make sure you assign all required permissions in the [Microsoft Defender for Endpoint Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench) guide.
2. Add the machine.isolate Windows Defender permission.
3. Grant admin consent.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fdz84HtQofzTmAgC6oezB%2FMS_ATP_api_permissions4.png?alt=media&amp;token=794edf89-966b-43c0-8a07-891e909d826c" alt="Machine Isolate is Granted for Expel in the configured permissions list." width="563"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Microsoft Defender for Endpoint device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Palo Alto Networks Cortex XDR: Contain Hosts

This guide helps you set up your Palo Alto Networks (PAN) Cortex XDR Pro device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](https://support.expel.io/hc/en-us/articles/36549337569555) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Cortex XDR public API**&#x20;

`public_api/v1`,  full isolation

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>POST</td><td><code>/public_api/v1/endpoints/get_endpoint/</code></td><td>Look up endpoint ID by hostname; pre-check to read <code>is_isolated</code></td></tr><tr><td>POST</td><td><code>/public_api/v1/endpoints/isolate</code></td><td>Isolate the endpoint</td></tr><tr><td>POST</td><td><code>/public_api/v1/endpoints/get_endpoint/</code></td><td>Poll <code>is_isolated</code> until the response is that the agent is isolated; also read <code>last_seen</code></td></tr></tbody></table>

Revert (release): POST `/public_api/v1/endpoints/unisolate`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

1. Make sure you assign all API permissions in the [PAN Cortex XDR Pro Setup for Workbench](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-cortex-xdr-pro-setup-for-workbench) guide.
2. Enable the Isolate permission under Response for the Expel role.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F1VIHKfxzVHHvCOKG41Kt%2Fimage__4_.png?alt=media&amp;token=0193b0d9-1f3f-4d74-a902-7eb5fea27c7d" alt="Isolate is enabled in the permissions list." width="470"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Cortex XDR device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# SentinelOne: Contain Hosts

This guide helps you set up your SentinelOne device and grant necessary permissions so that you can enable the Contain Hosts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a host that must be contained, Workbench completes the action automatically. You have the option to restrict these actions to specific hosts by configuring an allow or deny list (the hosts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**SentinelOne API**

`web/api/v2.1`, full network isolation

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td>web/api/v2.1/agents</td><td>Look up agent ID by hostname; pre-check to read <code>status</code></td></tr><tr><td>POST</td><td>/web/api/v2.1/agents/actions/disconnect</td><td>Disconnect (isolate) the agent from the network</td></tr><tr><td>GET</td><td>web/api/v2.1/agents</td><td>Poll <code>status</code> until disconnected; also read last active date</td></tr></tbody></table>

Revert (reconnect): POST `/web/api/v2.1/agents/actions/connect`.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

Make sure you assign all API permissions in the [SentinelOne Setup for Workbench](/connect-your-technology/q-z-integrations/sentinelone/sentinelone-singularity-endpoint-setup-for-workbench) guide, including the IR Team role, with Network Quarantine permissions all enabled.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FEOqeH3BnXELNXL9mEFwP%2Fir_team_perms.png?alt=media&amp;token=edcd75ea-4b93-4144-bd98-893648c076b8" alt="In the SentinelOne IR Team role, Network Quarantine Control View, Network Quarantine Control Modify Settings, and Network Quarantine Control Manage Rules And Tags permissions are all enabled." width="563"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any hosts for a "do not contain" or "always contain" list, and instead wish for Expel to automatically contain&#x20;*****all*****&#x20;identified hosts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding hosts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those hosts as "Never contain" or "Always contain" assets when you enable the auto remediation in Workbench. In this instance, the context update process is usually accomplished by sending us a .csv file.

{% hint style="info" %}
If our SOC identifies a host that must be contained and you have created either an allow ("Always contain") or deny ("Never contain") list in Workbench, any hosts falling outside of those parameters are assigned to you as actions rather than being contained automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your SentinelOne device is now ready for the Contain Hosts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Deactivate Access Keys


# AWS CloudTrail: Deactivate Access Keys

This guide helps you set up your AWS CloudTrail device and grant necessary permissions so that you can enable the Deactivate Access Keys auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a long-term access key that must be deactivated in order to mitigate the risk of a data breach, Workbench completes the action automatically. You have the option to restrict these actions to specific access keys by configuring an allow or deny list (the access keys must first be added as context, and then the list can be configured in Workbench; see [Step 3](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**AWS IAM**

via `boto3`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint (IAM Action)</th><th>Purpose</th></tr></thead><tbody><tr><td>AssumeRole</td><td><code>sts:AssumeRole</code></td><td>Assume the cross-account Expel role to obtain temporary credentials</td></tr><tr><td>GET</td><td><code>iam:GetAccessKeyLastUsed</code></td><td>Resolve the username that owns the target access key</td></tr><tr><td>GET</td><td><code>iam:ListAccessKeys</code></td><td>Enumerate the user's keys and filter to the target key</td></tr><tr><td>POST</td><td><code>iam:UpdateAccessKey</code></td><td>Deactivate the key (sets <code>Status</code> to <code>Inactive</code> but does not delete the key)</td></tr></tbody></table>

Reversible: the revert capability re-runs `iam:UpdateAccessKey` with `Status` of `Active`.

## Step 1: Find the Role Name in Workbench <a href="#h_01jh8exvpfrg9p96jbqajt3k96" id="h_01jh8exvpfrg9p96jbqajt3k96"></a>

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Navigate to **Organization Settings > Security Devices**.
3. Next to the name of your AWS CloudTrail device, in the dropdown, select **Edit**.
4. In the Edit Security Device window, find the Role ARN that you configured during your AWS CloudTrail onboarding.
5. Copy and save the role name, which is usually the last portion of the Role ARN field after the forward slash (for example, *ExpelServiceRole*, *ExpelAssumeRole*, or *ExpelRole*).<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FXzYPXnuUOWBUlrvVhY5L%2FAWS%20CloudTrail%20Security%20Device%20settings?alt=media&amp;token=e87dd1a1-3ee7-4e90-a081-6c08cf30f6ad" alt="This example shows ExpelServiceRole in the Role ARN field." width="375"><figcaption></figcaption></figure></div>
6. Close the Edit Security Device window.

## Step 2: Add Permissions to the Existing Expel Policy in the AWS Console <a href="#h_01jh8f0fwz0ttdj7r59669a3as" id="h_01jh8f0fwz0ttdj7r59669a3as"></a>

1. [Log in to the AWS IAM console](https://console.aws.amazon.com/iam/).
2. Navigate to Roles.
3. On the Roles screen, find and open the role whose name you saved in the previous step.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FpBt8Lg8Jqs5LWBFD03sT%2FIAM%20Roles%20screen?alt=media&amp;token=8ab845c7-972d-4561-bca9-cf26abb1044e" alt="In this example, the ExpelServiceRole role is selected in CloudTrail." width="375"><figcaption></figcaption></figure></div>
4. Find and open the attached policy that was configured during onboarding (for example, *ExpelAccessPolicy* or *ExpelAPIPolicy*).
5. Add the `iam:UpdateAccessKey` permission to the `"Resource": "*"` section.

{% hint style="info" %}
If CloudFormation, ControlTower, or Terraform manages this policy, edit this policy at the source of truth so the edits aren’t accidentally overwritten later.
{% endhint %}

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FyqAPPTFb61aC0bKslbmQ%2FAWS%20CloudTrail%20policy%20permissions?alt=media&amp;token=73595b78-e896-46b6-8f83-c566b84b723f" alt="The iam:UpdateAccessKey permission has been added to the AWS policy editor." width="375"><figcaption></figcaption></figure></div>

6. Save the policy.
7. Repeat both steps of the process for each of your configured AWS CloudTrail devices.

## Step 3: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any access keys for a "do not deactivate" or "always deactivate" list, and instead wish for Expel to automatically deactivate&#x20;*****all*****&#x20;identified access keys, skip to** [**Step 4**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding access keys as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those access keys as "Never deactivate" or "Always deactivate" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an access key that must be deactivated and you have created either an allow ("Always deactivate") or deny ("Never deactivate") list in Workbench, any access keys falling outside of those parameters are assigned to you as actions rather than being deactivated automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your AWS CloudTrail device is now ready for the Deactivate Access Keys auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# AWS GuardDuty: Deactivate Access Keys

This guide helps you set up your AWS GuardDuty device and grant necessary permissions so that you can enable the Deactivate Access Keys auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies a long-term access key that must be deactivated in order to mitigate the risk of a data breach, Workbench completes the action automatically. You have the option to restrict these actions to specific access keys by configuring an allow or deny list (the access keys must first be added as context, and then the list can be configured in Workbench; see [Step 3](#h_01jh5zhtqthkyym38xnhr25vgj)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**AWS IAM**

via `boto3`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint (IAM Action)</th><th>Purpose</th></tr></thead><tbody><tr><td>AssumeRole</td><td><code>sts:AssumeRole</code></td><td>Assume the cross-account Expel role to obtain temporary credentials</td></tr><tr><td>GET</td><td><code>iam:GetAccessKeyLastUsed</code></td><td>Resolve the username that owns the target access key</td></tr><tr><td>GET</td><td><code>iam:ListAccessKeys</code></td><td>Enumerate the user's keys and filter to the target key</td></tr><tr><td>POST</td><td><code>iam:UpdateAccessKey</code></td><td>Deactivate the key (sets <code>Status</code> to <code>Inactive</code> but does not delete the key)</td></tr></tbody></table>

Reversible: the revert capability re-runs `iam:UpdateAccessKey` with `Status` of `Active`.

## Step 1: Find the Role Name in Workbench <a href="#h_01jh8jdnjtzb13cjmz9dpcbpvz" id="h_01jh8jdnjtzb13cjmz9dpcbpvz"></a>

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Navigate to **Organization Settings > Security Devices**.
3. Next to the name of your AWS GuardDuty device, in the dropdown, select **Edit**.
4. In the Edit Security Device window, find the Role ARN that you configured during AWS GuardDuty onboarding.
5. Copy and save the role name, which is usually the last portion of the Role ARN field after the forward slash (for example, *ExpelServiceRole*, *ExpelGuarddutyAssumeRole*, or *ExpelRole*).

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FLaxZ6jI1SolQu9KjvarU%2FAWS%20GuardDuty%20Security%20Device%20settings?alt=media&amp;token=b018ce91-aa04-40bb-be19-907086d7eab0" alt="In this example, ExpelServiceRole is highlighted in the Role ARN field." width="375"><figcaption></figcaption></figure></div>
6. Close the Edit Security Device window.

## Step 2: Add Permissions to the Existing Expel Policy in the AWS Console <a href="#h_01jh8jgjj5wr4r0jyxw8bdr5mx" id="h_01jh8jgjj5wr4r0jyxw8bdr5mx"></a>

1. [Log in to the AWS IAM console](https://console.aws.amazon.com/iam/).
2. Navigate to Roles.
3. On the Roles screen, find and open the role whose name you saved in the previous step.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F9vX0bO4EQBdhJVsyTi4X%2FIAM%20Roles%20screen?alt=media&amp;token=7a375cf7-b075-4b1d-adf0-b4c55981923d" alt="In this example, ExpelServiceRole is selected in the Roles list in GuardDuty." width="375"><figcaption></figcaption></figure></div>
4. Find and open the attached policy that was configured during onboarding (for example, *ExpelGuardDutyConnectorPolicy* or *ExpelAPIPolicy*).
5. Add the following permissions to the `"Resource": "*"` section:

   * `iam:List*`
   * `iam:Get*`
   * `iam:UpdateAccessKey`

   *If CloudFormation manages this policy, edit this policy at the source of truth so the edits aren’t accidentally overwritten later.*

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FSb57dCOV4OfGJ94jTXDe%2FAWS%20GuardDuty%20policy%20permissions?alt=media&amp;token=315a6632-d1eb-4e95-b7f6-9e29e686cf52" alt="The three permissions are added to the Resource section in the GuardDuty Policy editor." width="375"><figcaption></figcaption></figure></div>
6. Save the policy.
7. Repeat both steps of the process for each of your configured AWS GuardDuty devices.

## Step 3: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any access keys for a "do not deactivate" or "always deactivate" list, and instead wish for Expel to automatically deactivate&#x20;*****all*****&#x20;identified access keys, skip to** [**Step 4**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding access keys as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those access keys as "Never deactivate" or "Always deactivate" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an access key that must be deactivated and you have created either an allow ("Always deactivate") or deny ("Never deactivate") list in Workbench, any access keys falling outside of those parameters are assigned to you as actions rather than being deactivated automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your AWS GuardDuty device is now ready for the Deactivate Access Keys auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Delete Malicious Files


# CrowdStrike: Delete Malicious Files

This guide helps you set up your CrowdStrike device and grant necessary permissions so that you can enable the Delete Malicious Files auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## Prerequisites <a href="#h_01hz2r8qtmdxqtp1dcd11h31ev" id="h_01hz2r8qtmdxqtp1dcd11h31ev"></a>

1. You must have enabled read and write permissions for the Real Time Response OAuth2 API client. See [Step 1 of CrowdStrike Falcon Insight XDR Setup for Workbench](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) for instructions and/or to verify your permissions.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## How It Works <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**CrowdStrike Real Time Response (RTR)**

active-responder command tier

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/devices/queries/devices/v1</code></td><td>Look up device ID by hostname</td></tr><tr><td>POST</td><td><code>/devices/entities/devices/v2</code></td><td>Fetch host details to confirm the match</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-init-session/v1</code></td><td>Open an RTR session on the host</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-active-responder-command/v1</code></td><td>Run path to delete the file</td></tr></tbody></table>

Identifies the file by path. No revert (an optional pre-delete backup can zip/upload the file first).

## Step 1: Edit the Response Policy in CrowdStrike <a href="#h_01hz2r8qtmbqhh1gtt2nj7yt74" id="h_01hz2r8qtmbqhh1gtt2nj7yt74"></a>

**If you have already enabled other auto remediations for CrowdStrike Falcon, some of the response policy settings may already be in place. Make sure to verify the sensor settings in your response policy as described below.**

For this auto remediation to work, you must enable both Real Time Response and the `get` command on the appropriate response policies in the Sensor Settings. The `get` command allows Expel to extract your files from a remote host. Refer to the [CrowdStrike documentation](https://falcon.crowdstrike.com/documentation/page/b8c1738c/real-time-response-and-network-containment#nc81f726) for additional help with this step.

**Before you begin, remember that you must have already** [enabled read and write permissions](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) **for Real Time Response for the OAuth2 API client in CrowdStrike.**&#x20;

1. [Log in to CrowdStrike Falcon](https://falcon.crowdstrike.com/login/?unilogin=1).
2. In the top left menu, navigate to **Host setup and management** **> Response and containment > Response policies**.
3. Select the response policy that contains the hosts you want to enable for this auto remediation.
4. In the policy's Sensor Settings:
   * Select the **Real Time Response** checkbox to enable it.
   * Select the **get** checkbox to enable the `get` command.
   * Select **Save**.
5. Repeat these steps for any additional response policies that contain hosts that need this auto remediation enabled, and be sure to do this for all three platforms (Windows, MacOS, Linux).

## Step 2: Update Your Context <a href="#h_01jhrm39k6zwpsdc6r9c995qgr" id="h_01jhrm39k6zwpsdc6r9c995qgr"></a>

**If you do not want to specify any files for a "do not delete" or "always delete" list, and instead wish for Expel to automatically delete all identified files, skip to** [**Step 3**](#h_01j7kypdqgvzxv5wa84vspabyr)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding files as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those files as "Never delete" or "Always delete" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies files that must be deleted and you have created either an allow ("Always delete") or deny ("Never delete") list in Workbench, any files falling outside of those parameters are assigned to you as actions rather than being deleted automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01j7kypdqgvzxv5wa84vspabyr" id="h_01j7kypdqgvzxv5wa84vspabyr"></a>

Your CrowdStrike device is now ready for the Delete Malicious Files auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Defender for Endpoint: Delete Malicious Files

This guide helps you set up your Microsoft Defender for Endpoint device and grant necessary permissions so that you can enable the Delete Malicious Files auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jj4s9s9dzdhs11pn5p8zrckq" id="h_01jj4s9s9dzdhs11pn5p8zrckq"></a>

If our SOC identifies a malicious file that must be deleted due to malware or suspicious hash, Workbench completes the action automatically unless the machine is offline or the file is specifically designated as a "Never Delete" asset (these files must be added as context and then configured in Workbench; see [Step 3](#h_01jj4s9s9e687wb2rzkmxws3kt)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Defender for Endpoint API**

base `https://api.securitycenter.windows.com` via Live Response, hard delete

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/machines?$filter=contains(computerDnsName, '{hostname}')</code></td><td>Resolve hostname to machine ID (skipped if an asset ID is supplied)</td></tr><tr><td>GET</td><td><code>api/machines/{machineId}</code></td><td>Read osPlatform to choose the PowerShell vs Bash delete script</td></tr><tr><td>POST</td><td><code>api/libraryfiles</code></td><td>Upload the delete script to the live-response library</td></tr><tr><td>POST</td><td><code>api/machines/{machineId}/runliveresponse</code></td><td>Run the script to delete the file</td></tr><tr><td>GET</td><td><code>api/machineactions/{machineActionId}</code></td><td>Poll action status until it completes</td></tr><tr><td>GET</td><td><code>api/machineactions/{machineActionId}/GetLiveResponseResultDownloadLink(index=0)</code></td><td>Fetch the result to check for script errors</td></tr></tbody></table>

Identifies the file by path (not hash). Hard delete (`Remove-Item -Force / rm -f`). No revert.

## Scope and Limitations <a href="#h_01jj4s9s9dh3brkk5951ca9f3v" id="h_01jj4s9s9dh3brkk5951ca9f3v"></a>

When choosing to enable this auto remediation, remember the following:

* If your machine is offline at the time the auto remediation is triggered, the action will be assigned to you to perform manually instead.
* Due to limitations with the Microsoft Defender for Endpoint API, there is no ability to undo a delete file action performed via the auto remediation.

## Prerequisites <a href="#h_01jj4s9s9djsm4c0hdsj34ted9" id="h_01jj4s9s9djsm4c0hdsj34ted9"></a>

1. You must have admin access in Azure to add the API permissions to the enterprise application.&#x20;
2. You must have admin access in Microsoft Defender to enable live response.
3. You must be using one of these [supported operating systems](https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response#minimum-requirements).
4. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Grant Necessary Permissions in Azure <a href="#h_01jj4s9s9exrthh7rkmd8t6exa" id="h_01jj4s9s9exrthh7rkmd8t6exa"></a>

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required.&#x20;

1. [Log in to Azure.](https://portal.azure.com/)
2. Search for and select **App Registrations**.
3. On the App registrations page, select the **All applications** tab.
4. Locate and select the Microsoft Defender for Endpoint application that you configured [during your initial onboarding](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench).
5. In the left menu, select **Manage > API Permissions**.
6. Select **Add a permission**.
7. Search for "WindowsDefenderATP".
8. Select the following two **Application** permissions for WindowsDefenderATP:
   * Machine.LiveResponse
   * Library.Manage
9. Select **Update permissions**.
10. Check the Status column for your new permissions, and make sure to **grant admin consent** if you see a "Not granted" message.

## Step 2: Grant Necessary Permissions in Microsoft Defender <a href="#h_01jj4s9s9e61m5f0byhynt23yp" id="h_01jj4s9s9e61m5f0byhynt23yp"></a>

These permissions allow us to run a small script on the machine that uses an ID or process path to kill the process. The script is in Powershell for Windows and Bash for Linux and Mac.

1. Log in to the [Microsoft Defender portal](https://security.microsoft.com/).
2. Go to **Settings > Endpoints > Advanced Features**.&#x20;
3. Turn on the following three settings:
   * Live Response
   * Live Response for Servers
   * Live Response unsigned script execution
4. Select **Save preferences**.

## Step 3: Update Your Context <a href="#h_01jj4s9s9e687wb2rzkmxws3kt" id="h_01jj4s9s9e687wb2rzkmxws3kt"></a>

**If you do not want to specify any processes for a "do not delete" list, skip to** [**Step 4**](#h_01jj4s9s9eve79yahw27rqzepf)**.**

Working with your Customer Success Manager, add any files that should be on the "do not delete" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those files as "Never delete" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies a file that must be deleted, any file added as "Never delete" assets are assigned to you as actions rather than being killed automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jj4s9s9eve79yahw27rqzepf" id="h_01jj4s9s9eve79yahw27rqzepf"></a>

Your Microsoft Defender for Endpoint device is now ready for the Delete Malicious Files auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Delete Registry Key


# CrowdStrike: Delete Registry Key

This guide helps you set up your CrowdStrike device and grant necessary permissions so that you can enable the Delete Registry Key auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jkb8gh526rqq71p4s7wzxbck" id="h_01jkb8gh526rqq71p4s7wzxbck"></a>

If our SOC identifies a registry key that must be deleted, Workbench completes the action automatically unless the registry path, value, or hostname is specifically designated as a "Never delete" asset (these assets must be added as context and then configured in Workbench; see [Step 2](#h_01jkb8gh524bj3qh97jj4er6tm)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**CrowdStrike Real Time Response (RTR)**

active-responder command tier, Windows only

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/devices/queries/devices/v1</code></td><td>Look up device ID by hostname</td></tr><tr><td>POST</td><td><code>/devices/entities/devices/v2</code></td><td>Confirm the host and read platform name (gates on Windows)</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-init-session/v1</code></td><td>Open an RTR session on the host</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-active-responder-command/v1</code></td><td>Run path to delete the key/value</td></tr></tbody></table>

Windows only. No revert (an optional backup can `reg export` the key first).

## Scope and Limitations <a href="#h_01jkb8gh52mgaky46trzv9gtt6" id="h_01jkb8gh52mgaky46trzv9gtt6"></a>

When choosing to enable this auto remediation, remember the following:

* Expel can only create a backup of your registry before deletion if you give us permission to run custom scripts in your response policy (optional), as described in this guide.
* This auto remediation will only work on Windows-based operating systems, and cannot be configured for Mac or Linux.

## Prerequisites <a href="#h_01jkb8gh52nfvx31fp19w7z2z6" id="h_01jkb8gh52nfvx31fp19w7z2z6"></a>

1. You must have already enabled read and write permissions for the Real Time Response OAuth2 API client. See Step 1 of [CrowdStrike Falcon Insight XDR Setup for Workbench](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) for instructions and/or to verify your permissions.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Edit the Response Policy in CrowdStrike <a href="#h_01jkb8gh52zbhcyxvk75eg4r67" id="h_01jkb8gh52zbhcyxvk75eg4r67"></a>

**If you have already enabled other auto remediations for CrowdStrike Falcon, some of the response policy settings may already be in place. Make sure to verify the sensor settings in your response policy as described below.**

For this auto remediation to work, you must enable both Real Time Response and the `get` command on the appropriate response policies in the Sensor Settings. The `get` command allows Expel to extract your files from a remote host. You may also choose to enable custom scripts (optional) to allow us to create a backup of the registry before deletion.

Before you begin, remember that you must have already [enabled read and write permissions](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) for Real Time Response for the OAuth2 API client in CrowdStrike.&#x20;

1. [Log in to CrowdStrike Falcon](https://falcon.crowdstrike.com/login/?unilogin=1).
2. In the top left menu, navigate to **Host setup and management** **> Response and containment > Response policies**.
3. Make sure you are in the **Windows** platform (this auto remediation does not work for Mac or Linux).
4. Select the response policy that contains the hosts you want to enable for this auto remediation.
5. In the policy's Sensor Settings:
   * Select the **Real Time Response** checkbox to enable it.
   * Select the custom scripts checkbox (optional) to enable running custom scripts. *This permission is required if you want us to create a backup of the registry before deletion; if you do not wish to use this feature, skip this setting.*
   * Select the **get** checkbox to enable the `get` command.
   * Select **Save**.
6. Repeat these steps for any additional response policies that contain hosts that need this auto remediation enabled.

## Step 2: Update Your Context <a href="#h_01jkb8gh524bj3qh97jj4er6tm" id="h_01jkb8gh524bj3qh97jj4er6tm"></a>

**If you do not want to specify any registry paths, values, or hosts for a "do not delete" list, and instead wish for Expel to automatically delete all identified registries, skip to** [**Step 3**](#h_01jkb8gh528z16qdz8p9zk280g)**.**

Working with your Customer Success Manager, add any registry paths, values, or hosts that should be on the "do not delete" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select them as "Never delete" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies a registry that must be deleted, any registries with associated paths, values, or hosts that were added as "Never delete" assets are assigned to you as actions rather than being deleted automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jkb8gh528z16qdz8p9zk280g" id="h_01jkb8gh528z16qdz8p9zk280g"></a>

Your CrowdStrike device is now ready for the Delete Registry Key auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Disable Accounts


# Azure Cloud Direct: Disable Accounts

This guide helps you set up your Azure Cloud Direct device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

requires `User.ReadWrite.All`, always targets the global `graph.microsoft.com` host

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td>v1.0/users/{userid}</td><td>Get user details; see if account is enabled for the pre-check</td></tr><tr><td>PATCH</td><td>v1.0/users/{userid}</td><td>Disable the account</td></tr><tr><td>POST</td><td>v1.0/users/{userid}/revokeSignInSessions</td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td>beta/users/{userid}/invalidateAllRefreshTokens</td><td>Revoke all refresh tokens</td></tr></tbody></table>

## Scope and Limitations <a href="#h_01j7kypdqgb3n0715pj3hey31m" id="h_01j7kypdqgb3n0715pj3hey31m"></a>

When choosing to enable this auto remediation, remember the following:

* After a previously logged-in account is disabled, it can still access some resources until the access token expires and requires re-authentication. *Default expiration is 60 to 90 minutes after the disabling; as a result, it is possible for a user to remain logged in and to access some of the resources for up to 90 minutes after an account is disabled.*
* This auto remediation will not work on admin user accounts, or on any user who is assigned a privileged directory-level role or a privileged read-only role.
* While an account is disabled, the admin or user cannot reset the password. After the account is re-enabled, the account must be reset manually.

## Prerequisites <a href="#h_01jh8nq251nv5b8fbtex2jg713" id="h_01jh8nq251nv5b8fbtex2jg713"></a>

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Grant Necessary Permissions <a href="#h_01jh8mnfygz4b6p8rhnyxm11nh" id="h_01jh8mnfygz4b6p8rhnyxm11nh"></a>

The option you choose in this section depends on how you initially [onboarded your Azure Cloud device](/connect-your-technology/l-p-integrations/microsoft/microsoft-azure-setup-for-workbench) in Workbench.

* If you chose to enable the Azure Enterprise application, follow [Option 1](#h_01jh8n0bjdxxhn53r6j0t3zndk).
* If you chose to create a custom Microsoft Entra ID application, follow [Option 2](#h_01jh8n0edbykrcyfnqfdyybw5n).

### Option 1 (Azure Enterprise Applications) <a href="#h_01jh8n0bjdxxhn53r6j0t3zndk" id="h_01jh8n0bjdxxhn53r6j0t3zndk"></a>

**New installation**

No changes are required.

**Existing installation**

1. Navigate to the Expel Azure Integration > API Permissions.
2. Select the Grant admin consent button.
3. Consent to the new API permissions.

### Option 2 (Microsoft Entra ID Applications) <a href="#h_01jh8n0edbykrcyfnqfdyybw5n" id="h_01jh8n0edbykrcyfnqfdyybw5n"></a>

**New and existing installations**

1. Follow all previous API permission steps for [Option 2: Create Custom Microsoft Entra ID Application in Azure Cloud (Direct) Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-azure-setup-for-workbench#option-2-create-a-custom-entra-id-app).
2. Add this Microsoft Graph application permission to your custom Microsoft Entra ID application:
   * User.ReadWrite.All, User.Read.All

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FIoc7jdV2uQNGCSEIBkyt%2Fmceclip0.png?alt=media&amp;token=e1980ced-de11-4f44-8559-b7bc827c3948" alt="User.ReadWrite.All and User.Read.All permissions are selected." width="337"><figcaption></figcaption></figure></div>
3. Verify `User.ReadWrite.All` is added, and then select Grant admin consent.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FmcylmEGkNvUiz0r96Jkb%2Fmceclip1.png?alt=media&amp;token=0ed33756-2188-4d0a-8391-bd628056d6a7" alt="User.ReadWrite.All and Grant admin consent for Expel are highlighted on the Configured permissions screen." width="375"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Azure Cloud Direct device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Duo Cloud: Disable Accounts

This guide helps you set up your Duo Cloud device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

{% hint style="warning" %}
Disabling denies future authentication/MFA; it does not revoke active sessions or existing tokens.&#x20;
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Duo Admin API**

`/admin/v1`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/admin/v1/users?username={username}</code></td><td>Look up the Duo user to get user ID and current status</td></tr><tr><td>POST</td><td><code>/admin/v1/users/{user_id}</code></td><td>Modify user to set the status as <code>disabled</code></td></tr></tbody></table>

Revert sets `status=active`. Endpoint paths are the Duo Admin API paths hit by the `duo_client` SDK (not defined in Expel's own code).

{% hint style="warning" %}
A user's group-level status can override individual user status, so the disable may not take effect for grouped users.
{% endhint %}

## Step 1: Grant Necessary Permissions <a href="#h_01jh8vqe0e3ypz6epvgnsm4zer" id="h_01jh8vqe0e3ypz6epvgnsm4zer"></a>

There are two options for completing this step.

### Option 1 (Refresh the Secret Key) <a href="#h_01jh8vthwrzrnb7tw3hwf7y7re" id="h_01jh8vthwrzrnb7tw3hwf7y7re"></a>

1. Add `Grant write resource` permission to the Duo Admin API created for Expel (Expel API).
2. Refresh the Secret Key and update this information in Expel Workbench.

### Option 2 (Generate New API Credentials) <a href="#h_01jh8vtkxyxmwfn13f5ee7h4ak" id="h_01jh8vtkxyxmwfn13f5ee7h4ak"></a>

Instead of refreshing the secret key, you can generate new API credentials and replace the information in Workbench:

1. Follow the instructions in [Cisco Duo Setup for Workbench](/connect-your-technology/a-c-integrations/cisco/cisco-duo-setup-for-workbench).
2. Add `Grant write resource` permission to the list of required permissions.

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Duo Cloud device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# GitHub: Disable Accounts

This guide helps you set up your GitHub device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. This action removes the user's access to the organization's private repos, teams, and resources, and severs org-authorized token/SAML-SSO access tied to membership. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 3](#h_01jgycgywj4m9tc7j443dvsmf1)).

{% hint style="warning" %}
This remediation is *not* an account block or an enterprise account suspend. Therefore it does not delete or globally suspend the user's GitHub account, and also does not directly revoke the user's personal access tokens (PATs), SSH keys, or web sessions (which all live on the user's personal account). Note that PAT impact is not documented in Expel's code; this reflects the behavior of the org member-removal endpoint.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**GitHub REST API**

org-scoped

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/orgs/{org}/members/{username}</code></td><td>Confirm the user is a current org member</td></tr><tr><td>GET</td><td><code>/orgs/{org}/memberships/{username}</code></td><td>Read membership state (active/pending) for the pre-check</td></tr><tr><td>DELETE</td><td><code>/orgs/{org}/members/{username}</code></td><td>Remove the user from the organization (the disable action)</td></tr></tbody></table>

Revert re-invites the user via PUT `/orgs/{org}/memberships/{username}`; the user must accept an emailed invite (expires \~3 months), so re-enable is not automatic.

## Step 1: Allow Appropriate Permissions in Your EDR Console <a href="#h_01fs7gwjh91x8crymftnked1kr" id="h_01fs7gwjh91x8crymftnked1kr"></a>

1. Make sure you've completed the steps in the appropriate GitHub Setup guide ([Cloud](/connect-your-technology/d-j-integrations/github/github-cloud-setup-for-workbench) | [Self-Hosted (On-Prem)](/connect-your-technology/d-j-integrations/github/github-self-hosted-on-prem-setup-for-workbench)) to ensure you've configured the permissions necessary for auto remediation.

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your GitHub device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Google Workspace: Disable Accounts

This guide helps you set up your Google Workspace device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 3](#h_01jh5zhtqthkyym38xnhr25vgj)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Google Admin SDK Directory API**

`admin/directory/v1`, via the google-api-python-client SDK

<table><thead><tr><th width="150.63671875">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET (<code>users.get</code>)</td><td><code>admin/directory/v1/users/{userKey}</code></td><td>Look up the user and read the current suspended flag</td></tr><tr><td>POST (<code>users.signOut</code>)</td><td><code>admin/directory/v1/users/{userKey}/signOut</code></td><td>Sign the user out of all sessions (must run before suspend)</td></tr><tr><td>PUT (<code>users.update</code>)</td><td><code>admin/directory/v1/users/{userKey}</code></td><td>Suspend the account</td></tr></tbody></table>

Session revocation and suspension are two separate calls. `users.signOut` invalidates all web/device sign-in sessions (done first because it is not allowed once suspended); it does not revoke third-party OAuth app grants. Revert sets `suspended: false` (no `users.signOut` on revert); requires a write scope (`admin.directory.user`) on the device.

## Step 1: Add OAuth Scopes to Google <a href="#h_01fs7gwjh91x8crymftnked1kr" id="h_01fs7gwjh91x8crymftnked1kr"></a>

1. Open the Google Workspace admin console:  <https://admin.google.com/ac/owl/domainwidedelegation>.
2. Navigate to **Security > API Controls > Manage Domain Wide Delegation**.
3. Select **Edit** next to the Expel API client.
4. Scroll to the bottom and add the following OAuth scopes:
   * <https://www.googleapis.com/auth/admin.directory.user&#x20>;
   * <https://www.googleapis.com/auth/admin.directory.user.security>

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FbX9vPSe1l3TwMBBRcFdK%2Fmceclip0.png?alt=media&amp;token=11ba125d-60ee-462d-acf4-6e9065a4e4a1" alt="The two OAuth scopes are added on the Edit scopes screen." width="295"><figcaption></figcaption></figure></div>
5. Select **Authorize**.

## Step 2: Add OAuth Scopes to Workbench <a href="#id-01fyq4stnpj06pw23g3q66eqxx" id="id-01fyq4stnpj06pw23g3q66eqxx"></a>

1. In a new browser tab, [log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Navigate to **Organization Settings > Security Devices**.
3. Find **Google Workspace** in the list.
4. Select the **down arrow** in the Google Workspace row, and select **View & Edit**.
5. Scroll to the end of API scopes field and add the OAuth scopes:
   * <https://www.googleapis.com/auth/admin.directory.user&#x20>;
   * <https://www.googleapis.com/auth/admin.directory.user.security>

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FsihfTsj1hs0hY0FSsBOd%2Fmceclip1.png?alt=media&amp;token=a4331a3c-4b0e-42fa-a1a3-052191f52ffd" alt="The two OAuth scopes are added to the API scopes field, separated by a comma." width="445"><figcaption></figcaption></figure></div>
6. Select **Save**.

## Step 3: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 4**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Google Workspace device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft 365: Disable Accounts

This guide helps you set up your Microsoft 365 device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

requires `User.ReadWrite.All`, same calls for cloud-only and hybrid/on-prem-synced users&#x20;

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/users/{userid}</code></td><td>Get user details; see if account is enabled for the pre-check</td></tr><tr><td>PATCH</td><td><code>v1.0/users/{userid}</code></td><td>Disable the account</td></tr><tr><td>POST</td><td><code>v1.0/users/{userid}/revokeSignInSessions</code></td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td><code>beta/users/{userid}/invalidateAllRefreshTokens</code></td><td>Revoke all refresh tokens</td></tr></tbody></table>

## Scope and Limitations <a href="#h_01j7kypdqgb3n0715pj3hey31m" id="h_01j7kypdqgb3n0715pj3hey31m"></a>

When choosing to enable this auto remediation, remember the following:

* After a previously logged-in account is disabled, it can still access some resources until the access token expires and requires re-authentication. *Default expiration is 60 to 90 minutes after the disabling; as a result, it is possible for a user to remain logged in and to access some of the resources for up to 90 minutes after an account is disabled.* It is therefore recommended that the Reset Credentials remediation is invoked immediately before this auto remediation.
* This auto remediation will not work on admin user accounts, or on any user who is assigned a privileged directory-level role or a privileged read-only role.
* While an account is disabled, the admin or user cannot reset the password. After the account is re-enabled, the account must be reset manually.

**If you have an on-prem Active Directory or hybrid Entra ID/ on-prem Active Directory environment**, consider the following safety precautions before enabling this auto remediation:

* This remediation action will perform Account Disablement in Entra ID and NOT in on-prem AD.&#x20;
* In hybrid environments, the On-prem AD configuration always takes precedence and is considered the "Source of Truth." Microsoft initiates automatic syncs from on-prem AD to Entra ID every 30-60 min.&#x20;
* For hybrid environments, the account disablement Expel pushes via Entra ID will be rolled back by Microsoft after the next sync. You must also lock the account in the on-prem environment before the next sync to keep the account locked.&#x20;
* **To safely disable accounts in on-prem or hybrid AD environments, Expel recommends using our Microsoft Defender for Endpoint: On-Prem/Hybrid Disable Accounts auto remediation. Enable this auto remediation via the** [**Microsoft Defender for Endpoint: Disable Accounts**](/workbench-setup/auto-remediations/disable-accounts/microsoft-defender-for-endpoint-disable-accounts) **setup guide.**

## Prerequisites <a href="#h_01jh8nq251nv5b8fbtex2jg713" id="h_01jh8nq251nv5b8fbtex2jg713"></a>

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Grant Necessary Permissions <a href="#h_01jh8mnfygz4b6p8rhnyxm11nh" id="h_01jh8mnfygz4b6p8rhnyxm11nh"></a>

The option you choose in this section depends on how you initially [onboarded your Microsoft 365 device](/connect-your-technology/l-p-integrations/microsoft/microsoft-365-setup-for-workbench) in Workbench.

* If you chose to enable the Microsoft 365 integration, follow [Option 1](#h_01jh8n0bjdxxhn53r6j0t3zndk).
* If you chose to create a custom Azure application, follow [Option 2](#h_01jh8n0edbykrcyfnqfdyybw5n).

### Option 1 (Microsoft 365 Integrations) <a href="#h_01jh8n0bjdxxhn53r6j0t3zndk" id="h_01jh8n0bjdxxhn53r6j0t3zndk"></a>

**New installation**

No changes are required.

**Existing installation**

1. Open **Expel O365 Integration > API Permissions**.
2. Select the **Grant admin consent** button.
3. Consent to the new API permissions.

### Option 2 (Custom Azure Applications) <a href="#h_01jh8n0edbykrcyfnqfdyybw5n" id="h_01jh8n0edbykrcyfnqfdyybw5n"></a>

**New and existing installations**

1. Follow all previous API permission steps in [Microsoft 365 Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-365-setup-for-workbench).
2. Add this Microsoft Graph application permission to your custom Azure application:
   * User.ReadWrite.All

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F5IAyrVpK4JJNEdac8W0G%2Fmceclip0.png?alt=media&amp;token=0da25616-5f71-436c-bd6d-7c265f570700" alt="User.ReadWrite.All is selected in the permissions list." width="337"><figcaption></figcaption></figure></div>
3. Verify `User.ReadWrite.All` is added, and then select **Grant admin consent**.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FHX6DP45OBnB5TJQzYglW%2Fmceclip1.png?alt=media&amp;token=5a8aa9c6-f783-40ad-a62f-f4ac9f9ad416" alt="The permission and Grant consent buttons are highlighted on the Configured permissions page." width="375"><figcaption></figcaption></figure></div>

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Microsoft 365 device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Defender for Endpoint: Disable Accounts

This guide helps you set up your Microsoft Defender for Endpoint device and grant necessary permissions so that you can enable the On-Prem/Hybrid Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01kcq57nmvm6yat269p4wpscb4" id="h_01kcq57nmvm6yat269p4wpscb4"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session.

This remediation action will attempt to perform both on-premise (domain controller) and cloud (Entra ID) disablement for a user. It will first attempt to disable the user account on specified Domain Controller(s) (domain controller host names are set up via context; see [Step 2](#h_01kcsp5bjygeny4ax81k7xajj3)) using Microsoft Defender for Endpoint Live Response, before attempting to force a cloud sync. Even if this sync attempt fails, a separate task is executed via Microsoft Graph to ensure the user account is also disabled in Entra ID.

Active user sessions and refresh tokens for the disabled account are revoked via Microsoft Graph. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 3](#h_01kcspj3vvdk6xb2b8a4h2eqt7)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API (for Cloud/Entra ID users)**

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/users/{userid}</code></td><td>Get user details (check if user exists, if on premise sync is enabled, and if the account is enabled)</td></tr><tr><td>PATCH</td><td><code>v1.0/users/{userid}</code></td><td>Disable the account</td></tr><tr><td>POST</td><td><code>v1.0/users/{userid}/revokeSignInSessions</code></td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td><code>beta/users/{userid}/invalidateAllRefreshTokens</code></td><td>Revoke all refresh tokens</td></tr></tbody></table>

**Microsoft Defender for Endpoint API (for On-Prem/Hybrid users)**

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint (IAM Action)</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/machines/{id}</code></td><td>Get machine details (OS platform)</td></tr><tr><td>POST</td><td><code>api/machines/{id}/runliveresponse</code></td><td>Execute PowerShell script on domain controller</td></tr><tr><td>GET</td><td><code>api/machineactions/{id}</code></td><td>Poll for action completion status</td></tr><tr><td>POST</td><td><code>api/libraryfiles</code></td><td>Upload PowerShell script to library</td></tr></tbody></table>

## Scope and Limitations <a href="#h_01kcq5eztav8pyj62wr1w0r9ex" id="h_01kcq5eztav8pyj62wr1w0r9ex"></a>

When choosing to enable this auto remediation, remember the following:

* This remediation will work for on-prem-only, hybrid, or cloud-only Entra ID/Active Directory environments, meaning account disablement in Entra ID will not be rolled back after an Active Directory sync in hybrid AD environments. However, if you have a cloud-only Entra ID environment, we recommend you instead leverage the [Microsoft 365: Disable Accounts](/workbench-setup/auto-remediations/disable-accounts/microsoft-365-disable-accounts) remediation action.
* After a previously logged-in account is disabled, it can still access some resources until the access token expires and requires re-authentication. Default expiration is 60 to 90 minutes after the disabling; as a result, it is possible for a user to remain logged in and to access some of the resources for up to 90 minutes after an account is disabled.
* This auto remediation will not work on admin user accounts, or on any user who is assigned a privileged directory-level role or a privileged read-only role.
* While an account is disabled, the user cannot reset the password. After the account is re-enabled, the account must be reset manually.

## Prerequisites <a href="#h_01kcq5hx4rea8x67re9r32f4mb" id="h_01kcq5hx4rea8x67re9r32f4mb"></a>

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have a valid license for Microsoft Defender for Endpoint Plan 2 (P2) or Microsoft 365 E5/A5/G5 (which includes P2).
4. Your Live Response target devices must belong to a device group with an automation level of at least `Semi – require approval for all folders`. This level of access is necessary for us to make Live Response commands via API; see [Step 2](#h_01kcsp5bjygeny4ax81k7xajj3) for more information.

## Step 1: Grant Necessary Permissions <a href="#h_01kcq5k599jrmnfwv6ak0wvtar" id="h_01kcq5k599jrmnfwv6ak0wvtar"></a>

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required.

The option you choose in this section depends on how you initially onboarded your Microsoft Defender for Endpoint device in Workbench.

* If you chose to enable the Microsoft Defender for Endpoint integration, follow [Option 1](#h_01kcsmn27ggefkex683wdbx0x1).
* If you chose to create a custom Azure application, follow [Option 2](#h_01kcsmsmmh9wjmdp8gpxq4kwme).

### Option 1 (Microsoft Defender for Endpoint Integrations) <a href="#h_01kcsmn27ggefkex683wdbx0x1" id="h_01kcsmn27ggefkex683wdbx0x1"></a>

#### **New installation** <a href="#h_01kd3far7jwfefbc0n0a0t3ns0" id="h_01kd3far7jwfefbc0n0a0t3ns0"></a>

No changes are required.

#### **Existing installation** <a href="#h_01kd3fav39jq65ys7r6yg4wwg4" id="h_01kd3fav39jq65ys7r6yg4wwg4"></a>

1. Open **Expel Microsoft Defender for Endpoint Integration > API Permissions**.
2. Select **Grant admin consent**.
3. Consent to the new API permissions.

### Option 2 (Custom Azure Applications) <a href="#h_01kcsmsmmh9wjmdp8gpxq4kwme" id="h_01kcsmsmmh9wjmdp8gpxq4kwme"></a>

**New and existing installations:**

1. Follow all previous API permission steps in [Microsoft Defender for Endpoint Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench).
2. Add these Microsoft Graph application permissions to your custom Azure application:
   * Directory.ReadWrite.All
   * User.EnableDisableAccount.All
   * User.ManageIdentities.All
   * User.Read.All
   * User.RevokeSessions.All
3. Add these WindowsDefenderATP application permissions to your custom Azure application:
   * Library.Manage
   * Machine.LiveResponse
   * Machine.ReadWrite.All

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fi2ufy7Wk4CdtjKM10Fr6%2FMS-permissions.png?alt=media&amp;token=fb7f4185-b829-4e79-af69-da7cb01efe89" alt="The Microsoft Graph and WindowsDefenderATP permissions are added to the Admin consent list." width="563"><figcaption></figcaption></figure></div>

## Step 2: Enable Live Response <a href="#h_01kcsp5bjygeny4ax81k7xajj3" id="h_01kcsp5bjygeny4ax81k7xajj3"></a>

In order to enable on-prem/hybrid disablement of accounts, you must allow Expel to run PowerShell commands via Microsoft Live Response on a domain controller.

{% hint style="warning" %}
Your target devices must belong to a device group with an automation level of at least `Semi – require approval for all folders`, but you may also choose `Full - remediate threats automatically`. If device groups are not used, ensure the default `Ungrouped devices (default)` group is updated to meet the minimum setting. This level of access is necessary for us to make Live Response commands via API.

Refer to the [Microsoft Documentation](https://learn.microsoft.com/en-us/defender-endpoint/automation-levels) for more information about automation levels.
{% endhint %}

**Ensure Domain Controllers are Onboarded with Live Response**

1. Go to the Microsoft Defender portal and sign in.
2. Check Domain Controller Onboarding Status:
   * Go to **Assets > Devices** in the Microsoft Defender portal.
   * Search for your Domain Controller hostnames.
   * Ensure their status is **Active** and the Onboarding status is **Onboarded**.

**Enable Live Response Advanced Features**

1. In the navigation pane, select **Settings > Endpoints > Advanced features**.
2. Ensure the following features are **enabled**:
   * Live Response
   * Live Response on Servers
   * Live Response unsigned script execution
3. Select **Save preferences**.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FF24lDGzti60PrPU3E36G%2Flive-response-advanced-features.png?alt=media&amp;token=296096d1-69ac-417f-821f-8bf2c1b1591b" alt="The three features are toggled to the On position." width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
Expel will only use the Microsoft Defender for Endpoint Live Response “unsigned script execution” permission to issue remediation commands to your Domain Controllers via the Live Response channel. These commands are limited to the remediation actions you opt into in org settings. Expel uses the Live Response “unsigned script execution” permission for the following Microsoft Defender for Endpoint remediation actions:

* Account disablement and enablement (in case a disabled account should be reverted)
* Process termination (as part of the **Kill Processes** remediation action)
* File deletion (as part of the **Delete Malicious Files** remediation action)&#x20;

Enabling this option **does not** alter the local PowerShell Execution Policy enforced by GPO on the server. It strictly permits the execution of unsigned scripts only when initiated through the authenticated Live Response session. It does not allow users logged directly into the server to run unsigned scripts. Furthermore, execution via Live Response is restricted to users with specific RBAC permissions (e.g., Global/Security Admins) within the Microsoft Defender portal.
{% endhint %}

## Step 3: Update Your Context <a href="#h_01kcspj3vvdk6xb2b8a4h2eqt7" id="h_01kcspj3vvdk6xb2b8a4h2eqt7"></a>

Working with your Customer Success Manager:

1. (Optional) Create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment.
2. Specify the hostnames of one or more domain controllers which should be used for on-prem disablement via Live Response (mandatory for on-prem/hybrid disablement).

In order for the remediation action to identify your domain controllers’ hostnames, ensure they are tagged with the Domain Controller detection tag in Workbench:

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fi4kTv03H5yUEhh2N7oUQ%2Fadd-context.png?alt=media&amp;token=6af1ee42-189c-43cf-bd79-4ff8a53e73e9" alt="The Domain controller tag is added in the Add detection tags field of Workbench." width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01kcspnxec7tqv6gqg2t3n4sn8" id="h_01kcspnxec7tqv6gqg2t3n4sn8"></a>

Your **Microsoft Defender for Endpoint** device is now ready for the On-Prem/Hybrid **Disable Accounts** auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Entra ID via Event Hub: Disable Accounts

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

This guide helps you set up your Microsoft Entra ID via Event Hub device so that you can enable the Disable Accounts auto remediation in Workbench. During the setup process, you will grant Expel all necessary permissions for the remediation to work.

## How It Works

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#step-2-update-your-context)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

requires `User.ReadWrite.All`, same calls for cloud-only and hybrid/on-prem-synced users&#x20;

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/users/{userid}</code></td><td>Get user details; see if account is enabled for the pre-check</td></tr><tr><td>PATCH</td><td><code>v1.0/users/{userid}</code></td><td>Disable the account</td></tr><tr><td>POST</td><td><code>v1.0/users/{userid}/revokeSignInSessions</code></td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td><code>beta/users/{userid}/invalidateAllRefreshTokens</code></td><td>Revoke all refresh tokens</td></tr></tbody></table>

## Scope and Limitations

When choosing to enable this auto remediation, remember the following:

* After a previously logged-in account is disabled, it can still access some resources until the access token expires and requires re-authentication. *Default expiration is 60 to 90 minutes after the disabling; as a result, it is possible for a user to remain logged in and to access some of the resources for up to 90 minutes after an account is disabled.* It is therefore recommended that the Reset Credentials remediation is invoked immediately before this auto remediation.
* This auto remediation will not work on admin user accounts, or on any user who is assigned a privileged directory-level role or a privileged read-only role.
* While an account is disabled, the admin or user cannot reset the password. After the account is re-enabled, the account must be reset manually.

**If you have an on-prem Active Directory or hybrid Entra ID/ on-prem Active Directory environment**, consider the following safety precautions before enabling this auto remediation:

* This remediation action will perform Account Disablement in Entra ID and NOT in on-prem AD.&#x20;
* In hybrid environments, the On-prem AD configuration always takes precedence and is considered the "Source of Truth." Microsoft initiates automatic syncs from on-prem AD to Entra ID every 30-60 min.&#x20;
* For hybrid environments, the account disablement Expel pushes via Entra ID will be rolled back by Microsoft after the next sync. You must also lock the account in the on-prem environment before the next sync to keep the account locked.&#x20;
* **To safely disable accounts in on-prem or hybrid AD environments, Expel recommends using our Microsoft Defender for Endpoint: On-Prem/Hybrid Disable Accounts auto remediation. Enable this auto remediation via the** [**Microsoft Defender for Endpoint: Disable Accounts**](/workbench-setup/auto-remediations/disable-accounts/microsoft-defender-for-endpoint-disable-accounts) **setup guide.**

## Prerequisites

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have already completed all of the steps in [Microsoft Entra ID via Event Hub Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench).

## Step 1: Grant Necessary Permissions

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required.

1. [Log in to Azure](https://portal.azure.com/).
2. Navigate to the **Microsoft Entra ID** service.
3. Go to **Manage > App registrations**.
4. Select the custom Entra ID app you created when you [set up your Expel integration](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench#step-2-create-a-custom-entra-id-app).
5. Navigate to **Manage > API permissions**.
6. Locate the **Microsoft Graph** API and add the following two permissions:
   * `Directory.ReadWrite.All`
   * `User.EnableDisableAccount.All`
7. Make sure to **Grant admin consent** for both permissions.

## Step 2: Update Your Context <a href="#step-2-update-your-context" id="step-2-update-your-context"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#step-3-return-to-the-main-setup-guide)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-setup/get-started/add-and-manage-org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#step-3-return-to-the-main-setup-guide" id="step-3-return-to-the-main-setup-guide"></a>

Your Microsoft Entra ID via Event Hub device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Okta: Disable Accounts

This guide helps you set up your Okta device and grant necessary permissions so that you can enable the Disable Accounts auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jh8ncdq41ghs4zvz4pj1n7wp" id="h_01jh8ncdq41ghs4zvz4pj1n7wp"></a>

If our SOC identifies an account (username or email address) that is compromised and must be disabled, Workbench completes the action automatically and logs the user out of their session. You have the option to restrict these actions to specific accounts by configuring an allow or deny list (the accounts must first be added as context, and then the list can be configured in Workbench; see [Step 2](#h_01jh5zhtqthkyym38xnhr25vgj)).

{% hint style="info" %}
Some vendors refer to disabling a user account as blocking a user, suspending a user, changing user status, removing a user from the org, or locking a user account.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Okta Core API**

`/api/v1`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/api/v1/users/{id}</code></td><td>Look up the user and read status</td></tr><tr><td>POST</td><td><code>/api/v1/users/{id}/lifecycle/suspend</code></td><td>Suspend (disable) the user</td></tr><tr><td>DELETE</td><td><code>/api/v1/users/{id}/sessions?oauthTokens=true</code></td><td>Clear all sessions and revoke OIDC/OAuth refresh + access tokens</td></tr></tbody></table>

Session clearing and OAuth token revocation happen in the one DELETE call (`oauthTokens` defaults to `true`). No personal access token handling.

## Prerequisites <a href="#h_01jh8yk2yky81h67dwkq0zm0a3" id="h_01jh8yk2yky81h67dwkq0zm0a3"></a>

1. You must have admin privileges in Okta (either Super Administrator privileges *or* Report Administrator + Group Administrator permissions).
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Grant Necessary Permissions <a href="#h_01jh8xj51d1dhrdzeb4v1kj509" id="h_01jh8xj51d1dhrdzeb4v1kj509"></a>

The Okta API token uses the Read-Only Admin permission in Workbench and the Auto Disable Accounts feature requires the Group Admin permission. In Okta, API tokens have the same permissions as the user who creates them and, if the user permissions change, the API token permissions also change.

As a result, you have the following options:

* If you want to edit the existing user permissions, choose [Option 1](#id-01fqhx9dx1wdr1pygen54vcyy4) (you must have Super Administrator privileges to choose this option).
* If you want to generate a new API token with the required permissions and then update your security device in Workbench, choose [Option 2](#id-01frndpr50ynfykpsywztadmvx) (you must have Report Administrator + Group Administrator permissions to choose this option).

### Option 1: Edit Existing User Permissions <a href="#id-01fqhx9dx1wdr1pygen54vcyy4" id="id-01fqhx9dx1wdr1pygen54vcyy4"></a>

The user you edit should be the one that created the API token, which is the same user you configured in [Okta Workforce Identity Setup for Workbench](/connect-your-technology/l-p-integrations/okta-workforce-identity-setup-for-workbench).

1. Log in to your Okta organization as a user with Super Administrator permissions.
2. Add the Report Administrator + Group Administrator permissions to the existing user for Expel.

### Option 2: Generate a New API Token <a href="#id-01frndpr50ynfykpsywztadmvx" id="id-01frndpr50ynfykpsywztadmvx"></a>

1. Log in to your Okta organization as a user with Report Administrator + Group Administrator permissions.
2. Follow Step 2 of the [Okta Workforce Identity Setup for Workbench](/connect-your-technology/l-p-integrations/okta-workforce-identity-setup-for-workbench) to generate a new API token.
3. In a new browser tab, [log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
4. Navigate to **Settings > Security Devices**.
5. Find **Okta** in the security device list.
6. On the right side of the Okta row, select the **down arrow**, and select **View & Edit**.
7. Replace the **API Token** with the newly generated token.
8. Select **Save**.

## Step 2: Update Your Context <a href="#h_01jh5zhtqthkyym38xnhr25vgj" id="h_01jh5zhtqthkyym38xnhr25vgj"></a>

**If you do not want to specify any accounts for a "do not disable" or "always disable" list, and instead wish for Expel to automatically disable&#x20;*****all*****&#x20;identified accounts, skip to** [**Step 3**](#h_01jgycgywj4m9tc7j443dvsmf1)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding accounts as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those accounts as "Never disable" or "Always disable" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an account that must be disabled and you have created either an allow ("Always disable") or deny ("Never disable") list in Workbench, any accounts falling outside of those parameters are assigned to you as actions rather than being disabled automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Okta device is now ready for the Disable Accounts auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Kill Processes


# Crowdstrike: Kill Processes

This guide helps you set up your CrowdStrike device and grant necessary permissions so that you can enable the Kill Processes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**CrowdStrike Real Time Response (RTR)**

active-responder command tier

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/devices/queries/devices/v1</code></td><td>Look up device ID by hostname</td></tr><tr><td>POST</td><td><code>/devices/entities/devices/v2</code></td><td>Fetch host details to confirm the match</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-init-session/v1</code></td><td>Open the RTR session on the host</td></tr><tr><td>POST</td><td><code>/real-time-response/combined/batch-active-responder-command/v1</code></td><td>Kill processes (when given a process path, runs <code>ps</code> first to resolve PIDs, then kills each)</td></tr></tbody></table>

Kills by PID directly, or resolves a process path to PIDs via `ps` and kills each. No revert.

## Prerequisites <a href="#h_01hz2r8qtmdxqtp1dcd11h31ev" id="h_01hz2r8qtmdxqtp1dcd11h31ev"></a>

1. You must have enabled read and write permissions for the Real Time Response OAuth2 API client. See Step 1 of [CrowdStrike Falcon® Setup for Workbench](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) for instructions and/or to verify your permissions.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Edit the Response Policy in Crowdstrike <a href="#h_01hz2r8qtmbqhh1gtt2nj7yt74" id="h_01hz2r8qtmbqhh1gtt2nj7yt74"></a>

For this auto remediation to work, you must enable Real Time Response on the appropriate response policies in the Sensor Settings. Refer to the [Crowdstrike documentation](https://falcon.crowdstrike.com/documentation/page/b8c1738c/real-time-response-and-network-containment#nc81f726) for additional help with this step.

**Before you begin, remember that you must have already** [enabled read and write permissions](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench#h_01hpm2g4z34q379y0r4afz6mtt) **for Real Time Response for the OAuth2 API client in CrowdStrike.**&#x20;

1. [Log in to CrowdStrike Falcon](https://falcon.crowdstrike.com/login/?unilogin=1).
2. In the top left menu, navigate to **Support and Resources** > **Host Setup and Management** section > **Response Policies**.
3. Locate the response policy that contains the hosts you want to enable for this auto remediation, and select it.&#x20;
   * In the Sensor Settings, select the **Real Time Response** checkbox to enable it.
   * Select **Save**.
   * Repeat these steps for any additional response policies that contain hosts that need this auto remediation enabled, and be sure to do this for all three platforms (Windows, MacOS, Linux).

## Step 2: Update Your Context <a href="#h_01jj4s9s9e687wb2rzkmxws3kt" id="h_01jj4s9s9e687wb2rzkmxws3kt"></a>

**If you do not want to specify any processes for a "do not kill" list, skip to** [**Step 3**](#h_01j7kypdqgvzxv5wa84vspabyr)**.**

Working with your Customer Success Manager, add any processes that should be on the "do not kill" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those processes as "Never kill" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies a process that must be killed, any processes added as "Never kill" assets are assigned to you as actions rather than being killed automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01j7kypdqgvzxv5wa84vspabyr" id="h_01j7kypdqgvzxv5wa84vspabyr"></a>

Your CrowdStrike device is now ready for the Kill Processes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Defender for Endpoint: Kill Processes

This guide helps you set up your Microsoft Defender for Endpoint device and grant necessary permissions so that you can enable the Kill Processes auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jj4s9s9dzdhs11pn5p8zrckq" id="h_01jj4s9s9dzdhs11pn5p8zrckq"></a>

If our SOC identifies a process that must be killed due to malware or suspicious behavior, Workbench completes the action automatically unless the machine is offline or the process is specifically designated as a "Never kill" asset (these processes must be added as context and then configured in Workbench; see [Step 3](#h_01jj4s9s9e687wb2rzkmxws3kt)).

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Defender for Endpoint API**

base `https://api.securitycenter.windows.com`, via Live Response

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>api/machines?$filter=contains(computerDnsName, '{hostname}')</code></td><td>Resolve hostname to machine ID (skipped if an asset ID is supplied)</td></tr><tr><td>GET</td><td><code>api/machines/{machineId}</code></td><td>Read osPlatform to choose the PowerShell vs Bash kill script</td></tr><tr><td>POST</td><td><code>api/libraryfiles</code></td><td>Upload the kill script (ExpelStopProcess.ps1 / .sh) to the live-response library</td></tr><tr><td>POST</td><td><code>api/machines/{machineId}/runliveresponse</code></td><td>Run the script</td></tr><tr><td>GET</td><td><code>api/machineactions/{machineActionId}</code></td><td>Poll action status until it completes</td></tr><tr><td>GET</td><td><code>api/machineactions/{machineActionId}/GetLiveResponseResultDownloadLink(index=0)</code></td><td>Fetch the result to check for script errors</td></tr></tbody></table>

Kills by PID or process path. No revert.

## Scope and Limitations <a href="#h_01jj4s9s9dh3brkk5951ca9f3v" id="h_01jj4s9s9dh3brkk5951ca9f3v"></a>

When choosing to enable this auto remediation, remember the following:

* If your machine is offline at the time the auto remediation is triggered, the action will be assigned to you to perform manually instead.
* There is no ability to undo a kill process action that is performed via the auto remediation.

## Prerequisites <a href="#h_01jj4s9s9djsm4c0hdsj34ted9" id="h_01jj4s9s9djsm4c0hdsj34ted9"></a>

1. You must have admin access in Azure to add the API permissions to the enterprise application.&#x20;
2. You must have admin access in Microsoft Defender to enable live response.
3. You must be using one of these [supported operating systems](https://learn.microsoft.com/en-us/defender-endpoint/api/run-live-response#minimum-requirements).
4. You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Grant Necessary Permissions in Azure <a href="#h_01jj4s9s9exrthh7rkmd8t6exa" id="h_01jj4s9s9exrthh7rkmd8t6exa"></a>

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required.&#x20;

1. [Log in to Azure.](https://portal.azure.com/)
2. Search for and select **App Registrations**.
3. On the App registrations page, select the **All applications** tab.
4. Locate and select the Microsoft Defender for Endpoint application that you configured [during your initial onboarding](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench).
5. In the left menu, select **Manage > API Permissions**.
6. Select **Add a permission**.
7. Search for "WindowsDefenderATP".
8. Select the following two **Application** permissions for WindowsDefenderATP:
   * Machine.LiveResponse
   * Library.Manage
9. Select **Update permissions**.
10. Check the Status column for your new permissions, and make sure to **grant admin consent** if you see a "Not granted" message.

## Step 2: Grant Necessary Permissions in Microsoft Defender <a href="#h_01jj4s9s9e61m5f0byhynt23yp" id="h_01jj4s9s9e61m5f0byhynt23yp"></a>

These permissions allow us to run a small script on the machine that uses an ID or process path to kill the process. The script is in Powershell for Windows and Bash for Linux and Mac.

1. Log in to the [Microsoft Defender portal](https://security.microsoft.com/).
2. Go to **Settings > Endpoints > Advanced Features**.&#x20;
3. Turn on the following three settings:
   * Live Response
   * Live Response for Servers
   * Live Response unsigned script execution
4. Select **Save preferences**.

## Step 3: Update Your Context <a href="#h_01jj4s9s9e687wb2rzkmxws3kt" id="h_01jj4s9s9e687wb2rzkmxws3kt"></a>

**If you do not want to specify any processes for a "do not kill" list, skip to** [**Step 4**](#h_01jj4s9s9eve79yahw27rqzepf)**.**

Working with your Customer Success Manager, add any processes that should be on the "do not kill" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those processes as "Never kill" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies a process that must be killed, any processes added as "Never kill" assets are assigned to you as actions rather than being killed automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jj4s9s9eve79yahw27rqzepf" id="h_01jj4s9s9eve79yahw27rqzepf"></a>

Your Microsoft Defender for Endpoint device is now ready for the Kill Processes auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Remove Malicious Email


# Google Workspace (Formerly G Suite): Remove Malicious Email

This guide helps you set up your Google Workspace device and grant necessary permissions so that you can enable the Remove Malicious Email auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## How It Works <a href="#h_01jgydp2j2h80jh6z0z91at9ne" id="h_01jgydp2j2h80jh6z0z91at9ne"></a>

If our SOC identifies an email that must be removed, Workbench completes the action automatically unless it is specifically called out as a "Never remove" asset (the inboxes must first be added as context and then configured in Workbench; see [Step 3](#h_01jgyc8wpyhctwv9qstbsatmnq)). Quarantine inboxes are often called out as "Never remove" assets.&#x20;

{% hint style="info" %}
The remediation runs per recipient mailbox (domain-wide delegation, impersonates each user). The messages are moved to Trash, where they are recoverable, rather than being permanently deleted.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Gmail API**

`gmail/v1` via the google-api-python-client SDK, messages located via BigQuery Gmail logs

<table><thead><tr><th width="158.53515625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>Query</td><td>BigQuery Gmail logs (<code>gmail_logs_dataset</code>)</td><td>Find recipients and candidate messages by subject, sender, time window</td></tr><tr><td>GET (<code>messages.list</code>)</td><td><code>gmail/v1/users/me/messages?q=rfc822msgid:{id}</code></td><td>Search the recipient's mailbox for the exact message</td></tr><tr><td>GET (<code>messages.get</code>)</td><td><code>gmail/v1/users/me/messages/{id}</code></td><td>Read labels, thread ID, headers (skip if already trashed)</td></tr><tr><td>POST (<code>messages.trash</code>)</td><td><code>gmail/v1/users/me/messages/{id}/trash</code></td><td>Move the message to Trash</td></tr></tbody></table>

Reversible via `messages.modify` and removing the `TRASH` label.

## Step 1: Allow Appropriate Permissions <a href="#h_01jh5zgcgw8ekzjnfd2tzwjvat" id="h_01jh5zgcgw8ekzjnfd2tzwjvat"></a>

1. Make sure you assign all API permissions in the [Google Workspace (formerly G Suite) Setup for Workbench](/connect-your-technology/d-j-integrations/google/google-workspace-formerly-g-suite-setup-for-workbench) guide.
2. From the same project you created during onboarding for Google Workspace, search for **Gmail API** and select it.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FEgMu5UIBxpX0P7QRJgpf%2Fmceclip0.png?alt=media&amp;token=4abec372-90ce-40eb-a0f4-a22caf678c2a" alt="Gmail API search result in the Google Workplace Marketplace." width="375"><figcaption></figcaption></figure></div>
3. Enable the Gmail API permissions for the project by selecting **Enable**.
4. In the Google Workspace admin console, navigate to **Domain-wide Delegation**: <https://admin.google.com/ac/owl/domainwidedelegation>.
5. Locate the API Client created for the Service Account during onboarding, and then select **Edit.**

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FL20USoLcDq7tRFT434Zi%2Fmceclip2.png?alt=media&amp;token=2d49bada-7243-4497-ad7a-701b54ae8358" alt="API client list shows the service account." width="563"><figcaption></figcaption></figure></div>
6. Add the following OAuth scope:&#x20;
   * <https://www.googleapis.com/auth/gmail.modify>

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FOo0NBDAVRTy53GaHpOjJ%2Fmceclip3.png?alt=media&amp;token=e4d2e017-62ff-40e6-a7b4-35ff962d7085" alt="The OAuth scope is added to the Edit scopes list." width="236"><figcaption></figcaption></figure></div>
7. Select **AUTHORIZE**.

## Step 2: Enable Google Workspace Logs in BigQuery <a href="#id-01fy4r4gfznfkpqtqkz176kq02" id="id-01fy4r4gfznfkpqtqkz176kq02"></a>

1. Confirm you are signed in to the [Google Admin console](https://admin.google.com/) with a **super administrator account**. *You cannot complete these steps without super admin permissions.*
2. Navigate to **Reporting > Data integrations**.
3. Choose the **BigQuery Export** card and select **Edit**.
4. To activate BigQuery logs, select the **Enable Google Workspace data export to Google BigQuery** checkbox.
   1. Under BigQuery project ID, select the project created for the Google Workspace integration.
   2. Under New dataset within the project, enter `gmail_logs_dataset` as the name for the new BigQuery dataset. *If you require a custom dataset name, please* [*reach out to Expel Support*](/support) *for assistance. Providing the custom name allows us to properly configure this feature.*
5. Select **Save**.
6. In the same project for the Google Workspace integration, navigate to the **IAM & Admin** console. Find the [previously created service account](/connect-your-technology/d-j-integrations/google/google-workspace-formerly-g-suite-setup-for-workbench), select the **pencil icon**, and then add the role **BigQuery Job User** to the service account.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FM1vqfKdD4iJnIy2D4iZi%2Fmceclip8.png?alt=media&amp;token=93ff275b-715f-4628-8ce6-4436e00c6e57" alt="IAM and Admin Permissions list shows the service account." width="563"><figcaption></figcaption></figure></div>
7. Search for and add BigQuery Job User, and then select **Save**.

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FiT03wdzmRf4BewIwJml8%2Fmceclip9.png?alt=media&amp;token=7fe44160-bfce-4df0-8a4e-ec6cc1df9596" alt="BigQuery Job User role is selected on the Edit permissions screen." width="279"><figcaption></figcaption></figure></div>
8. In the Google Cloud console, navigate to BigQuery: <https://console.cloud.google.com/bigquery>
9. Find the **gmail\_logs\_dataset** created in [Step 2](#id-01fy4r4gfznfkpqtqkz176kq02).
10. Open the dropdown menu using the three dots on the right, and then select **Open**.

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FciR0zss4WeERs4AaKhLd%2Fgoogle-workspace-dropdown.png?alt=media&amp;token=a52e9252-6d8c-4ae1-b108-a911ea9d70b5" alt="" width="256"><figcaption></figcaption></figure></div>
11. On the Dataset info screen, select **EDIT DETAILS** in the top right.

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FCRzHu3Trn4mlW4qf9w4n%2Fmceclip3.png?alt=media&amp;token=eb54e71e-48a9-4a10-a263-7be355b7a463" alt="gmail_logs_dataset info details page." width="375"><figcaption></figcaption></figure></div>
12. Select **Enable table expiration**. Enter the length of time to retain the log tables, and then select **SAVE**. *Default retention is set to 60 days, but we recommend **30 days**.*

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FSGx81MLrPcuA7KR2zRIu%2Fmceclip13.png?alt=media&amp;token=c355abb4-f6a7-4e58-bc85-cec015d13e0f" alt="Enable table expiration box is checked and 30 is entered into the Default maximum table age field." width="188"><figcaption></figcaption></figure></div>
13. Select **SHARING >** **Permissions.**

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FYnqRWcCUi5nOnzw0wnPs%2Fmceclip4.png?alt=media&amp;token=0445daeb-bef1-41af-b808-21779b61826b" alt="gmail_logs_dataset info details screen with Permissions selected." width="375"><figcaption></figcaption></figure></div>
14. Select **Add principal**.
15. Under New principals, add the service account, and then select the role **BigQuery Data Viewer**.

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FOnqxc0glc7zdeL4Qi0qw%2Fmceclip15.png?alt=media&amp;token=d94f1b56-2a70-4476-817f-8b6eec276bbb" alt="The service account and BigQuery Data Viewer role are added." width="375"><figcaption></figcaption></figure></div>
16. Select **SAVE**.

## Step 3: Update Your Context <a href="#h_01jgyc8wpyhctwv9qstbsatmnq" id="h_01jgyc8wpyhctwv9qstbsatmnq"></a>

**If you do not want to specify any inboxes for a "do not remove" list, skip to** [**Step 4**](#h_01jgycgywj4m9tc7j443dvsmf1)**. Quarantine inboxes are often called out as "Never remove" assets.**

Working with your Customer Success Manager (CSM), add any inboxes that should be on the "do not remove" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies an email that must be removed, any emails from inboxes added as "Never remove" assets are assigned to you as actions rather than being removed automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01jgycgywj4m9tc7j443dvsmf1" id="h_01jgycgywj4m9tc7j443dvsmf1"></a>

Your Google Workspace device is now ready for the Remove Malicious Email auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft 365: Remove Malicious Email

This guide helps you set up your Microsoft 365 device and grant necessary permissions so that you can enable the Remove Malicious Email auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*&#x20;

## How It Works

If our SOC identifies an email that must be removed, Workbench completes the action automatically unless it is specifically called out as a "Never remove" asset (the inboxes must first be added as context and then configured in Workbench; see [Step 3](#step-3-update-your-context)). Quarantine inboxes are often called out as "Never remove" assets.

{% hint style="info" %}
This is a soft delete (the message is moved to Deleted Items) and is reversible. It runs per recipient mailbox.
{% endhint %}

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

`v1.0`, messages located depending on the tenant (Exchange Online PowerShell for migrated tenants or the Reporting Web Service for legacy tenants)

<table data-search="false"><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/servicePrincipals(appId='{client-id}')/appRoleAssignments</code></td><td>Detect migrated vs. legacy tenant (picks the message trace path)</td></tr><tr><td>Powershell</td><td><code>Connect-ExchangeOnline</code>, <code>Get-MessageTraceV2</code>, <code>Disconnect-ExchangeOnline</code></td><td><strong>For migrated tenants.</strong> Open an Exchange Online session using the Graph-issued access token; locate delivered messages by sender, time range, and subject; use this info to build the recipient list; close the Exchange Online session</td></tr><tr><td>GET</td><td><code>reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$filter=SenderAddress eq '{sender}' and StartDate eq datetime'{start}' and EndDate eq datetime'{end}'&#x26;$format=json</code></td><td><strong>For legacy tenants (fallback).</strong> Locate delivered messages by sender and time; use this info to build the recipient list</td></tr><tr><td>GET</td><td><code>v1.0/users?$filter=mail eq '{recipient}'</code></td><td>Use recipient email to find the username</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=internetMessageId eq '{id}'</code></td><td>Find the message in the mailbox</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=receivedDateTime ge {received-25h} and receivedDateTime le {received+25h}&#x26;$select=id,subject,parentFolderId,from,receivedDateTime</code></td><td>Fallback when the exact message ID lookup returns nothing; page the mailbox and match subjects carrying a prepended tag</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/mailFolders/deleteditems</code></td><td>Get the Deleted Items folder ID</td></tr><tr><td>POST</td><td><code>v1.0/users/{user}/mailFolders/{folder}/messages/{msgId}/move</code></td><td>Move the message to Deleted Items</td></tr></tbody></table>

Reversible via the revert capability, which moves the message back to its original folder.

## Prerequisites

* You must install and activate Microsoft 365 Message Trace so that we can automatically remove the malicious email from other inboxes. For instructions, see [Microsoft 365 Message Trace Setup](/more-features/expel-managed-phishing/setup-guides/microsoft-365-message-trace-setup).
* You must have admin access in Workbench, as auto remediations are enabled at the organization level.

## Step 1: Assign the SecurityReader Role

The SecurityReader role allows us to perform a message trace or search your instance when we identify an email that needs remediation. This role provides read-only access.

1. Log in to the [Azure portal.](https://portal.azure.com/)
2. Navigate to the **Microsoft Entra ID** service.
3. Go to **Manage > Roles and administrators**.
4. Use the search bar to locate the **Security Reader** role, then select it to view its assignments.
5. Select **Add assignments**.
6. Use the search box under **Select member(s)** to locate your custom app. You are searching for the app's service principal, which usually has the same name as the app registration.
7. Select your app, then choose **Add**. You should now see the app's service principal listed as an active member of the Security Reader role.

## Step 2: Add an Additional API Permission

The `Exchange.ManageAsApp` permission allows us to connect to PowerShell to run the necessary commands to remove an email.

{% hint style="info" %}
If you used the **Expel O365 Integration** when onboarding the Microsoft 365 device:

* If you onboarded **after March 12, 2026**, the `Exchange.ManageAsApp` permission has already been granted and you may skip to [Update Your Context](#step-3-update-your-context).
* If you onboarded **prior to March 12, 2026**, skip to [Manually Grant Admin Consent](#manually-grant-admin-consent-legacy-customers-only).

If you used a **custom app** when onboarding the Microsoft 365 device, follow the below instructions to add the `Exchange.ManageAsApp` permission.
{% endhint %}

1. Navigate to the **App registrations** page in the Azure portal: <https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade>
2. Find and select the custom app you created when you set up your security device.
3. In the left menu, go to **Manage > API permissions**.
4. Select **Add a permission**.
5. Locate the **Office 365 Exchange Online** API, and add the `Exchange.ManageAsApp`\
   permission as an application permission (not as a delegated permission).
6. Select **Grant admin consent** and **Yes** at the prompt.

## Step 3: Update Your Context

**If you do not want to specify any inboxes for a "do not remove" list, skip to** [**Step 4**](#step-4-return-to-the-main-setup-guide)**. Quarantine inboxes are often called out as "Never remove" assets.**

Working with your Customer Success Manager (CSM), add any inboxes that should be on the "do not remove" list as [org context](/workbench-reference/expel-terminology#org-context) for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.&#x20;

{% hint style="info" %}
If our SOC identifies an email that must be removed, any emails from inboxes added as "Never remove" assets are assigned to you as actions rather than being removed automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide

Your Microsoft 365 device is now ready for the Remove Malicious Email auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*

***

### Manually Grant Admin Consent (Legacy Customers Only)

If you onboarded your Microsoft 365 security device **prior to March 12, 2026**, and you also used the **Expel O365 integration (not a custom app)** to create your API connection, you must go back into Azure to **grant us admin consent** in order for the Microsoft Remove Malicious Email auto remediation to work. This permission was not included in the Expel O365 integration prior to that date.

1. Log in to <https://portal.azure.com/>.
2. Select **Enterprise Applications**.
3. Select the Expel application.
4. In the left menu, go to **Security > Permissions**.
5. Select the **Grant admin consent for Expel** button.
6. Select the **Refresh** option to verify that the permissions have been updated.
7. Go to [Step 3: Update Your Context](#step-3-update-your-context).


# Microsoft Entra ID via Event Hub: Remove Malicious Email

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

This guide helps you set up your Microsoft Entra ID via Event Hub device so that you can enable the Remove Malicious Email auto remediation in Workbench. During the setup process, you will grant Expel all necessary permissions for the remediation to work.

## How It Works

If our SOC identifies an email that must be removed, Workbench completes the action automatically unless it is specifically called out as a "Never remove" asset (the inboxes must first be added as context and then configured in Workbench; see Step 3). Quarantine inboxes are often called out as "Never remove" assets.

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

`v1.0`, messages located depending on the tenant (Exchange Online PowerShell for migrated tenants or the Reporting Web Service for legacy tenants)

<table data-search="false"><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/servicePrincipals(appId='{client-id}')/appRoleAssignments</code></td><td>Detect migrated vs. legacy tenant (picks the message trace path)</td></tr><tr><td>Powershell</td><td><code>Connect-ExchangeOnline</code>, <code>Get-MessageTraceV2</code>, <code>Disconnect-ExchangeOnline</code></td><td><strong>For migrated tenants.</strong> Open an Exchange Online session using the Graph-issued access token; locate delivered messages by sender, time range, and subject; use this info to build the recipient list; close the Exchange Online session</td></tr><tr><td>GET</td><td><code>reports.office365.com/ecp/reportingwebservice/reporting.svc/MessageTrace?$filter=SenderAddress eq '{sender}' and StartDate eq datetime'{start}' and EndDate eq datetime'{end}'&#x26;$format=json</code></td><td><strong>For legacy tenants (fallback).</strong> Locate delivered messages by sender and time; use this info to build the recipient list</td></tr><tr><td>GET</td><td><code>v1.0/users?$filter=mail eq '{recipient}'</code></td><td>Use recipient email to find the username</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=internetMessageId eq '{id}'</code></td><td>Find the message in the mailbox</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/messages?$filter=receivedDateTime ge {received-25h} and receivedDateTime le {received+25h}&#x26;$select=id,subject,parentFolderId,from,receivedDateTime</code></td><td>Fallback when the exact message ID lookup returns nothing; page the mailbox and match subjects carrying a prepended tag</td></tr><tr><td>GET</td><td><code>v1.0/users/{user}/mailFolders/deleteditems</code></td><td>Get the Deleted Items folder ID</td></tr><tr><td>POST</td><td><code>v1.0/users/{user}/mailFolders/{folder}/messages/{msgId}/move</code></td><td>Move the message to Deleted Items</td></tr></tbody></table>

Reversible via the revert capability, which moves the message back to its original folder.

## Prerequisites

1. You must install and activate Microsoft 365 Message Trace so that we can automatically remove the malicious email from other inboxes. For instructions, see Microsoft 365 Message Trace Setup.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have already completed all of the steps in [Microsoft Entra ID via Event Hub Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench).

## Step 1: Assign the SecurityReader Role

The SecurityReader role allows us to perform a message trace or search your instance when we identify an email that needs remediation. This role provides read-only access.

1. Log in to the [Azure portal.](https://portal.azure.com/)
2. Navigate to the **Microsoft Entra ID** service.
3. Go to **Manage > Roles and administrators**.
4. Use the search bar to locate the **Security Reader** role, then select it to view its assignments.
5. Select **Add assignments**.
6. Use the search box under **Select member(s)** to locate your custom app. You are searching for the app's service principal, which usually has the same name as the app registration.
7. Select your app, then choose **Add**. You should now see the app's service principal listed as an active member of the Security Reader role.

## Step 2: Add Additional API Permissions

The `Exchange.ManageAsApp` permission allows us to connect to PowerShell to run the necessary commands to remove an email. The `Mail.ReadWrite` permission supports our fallback code for if/when email removal via the Exchange method fails.

1. Navigate to the **App registrations** page in the Azure portal: <https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade>
2. Find and select the custom app you created when you set up your security device.
3. In the left menu, go to **Manage > API permissions**.
4. Select **Add a permission**.
5. Locate the **Office 365 Exchange Online** API and add the following two permissions as application permissions (not as delegated permissions):
   * `Exchange.ManageAsApp`
   * `Mail.ReadWrite`
6. Make sure to **Grant admin consent** for both permissions.

## Step 3: Update Your Context <a href="#step-3-update-your-context" id="step-3-update-your-context"></a>

**If you do not want to specify any inboxes for a "do not remove" list, skip to** [**Step 4**](#step-4-return-to-the-main-setup-guide)**. Quarantine inboxes are often called out as "Never remove" assets.**

Working with your Customer Success Manager (CSM), add any inboxes that should be on the "do not remove" list as [org context](/workbench-setup/get-started/add-and-manage-org-context) for your environment. You will then be able to select those inboxes as "Never remove" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies an email that must be removed, any emails from inboxes added as "Never remove" assets are assigned to you as actions rather than being removed automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#step-4-return-to-the-main-setup-guide" id="step-4-return-to-the-main-setup-guide"></a>

Your Microsoft Entra ID via Event Hub device is now ready for the Remove Malicious Email auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Reset Credentials


# Microsoft 365: Reset Credentials

This guide helps you set up your Microsoft 365 device and grant necessary permissions so that you can enable the Reset Credentials auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## Scope and Limitations <a href="#h_01j7kypdqgb3n0715pj3hey31m" id="h_01j7kypdqgb3n0715pj3hey31m"></a>

When choosing to enable this auto remediation, remember the following:

* This auto remediation will not work on admin user accounts or on accounts that Microsoft considers Privileged (as these accounts cannot be forced to change their password).
* While an account is temporarily disabled, the user cannot have their credentials reset. It is therefore recommended that, in the event of a suspected compromised user, this remediation is applied directly before the Disable Accounts remediation is applied.

**If you have an on-prem Active Directory or hybrid Entra ID/ on-prem Active Directory environment**, consider the following safety precautions before enabling this auto remediation:

* In hybrid environments, the on-prem AD configuration always takes precedence and is considered the "source of truth." Microsoft initiates automatic syncs from on-prem AD to Entra ID every 30-60 minutes. Make sure to enable password writeback so that password changes made in Microsoft Entra ID are synchronized back to your local active directory (password writeback is not enabled by default in a hybrid environment).
* The Reset Credentials auto remediation will not prompt the affected user to set a new password until the account in question has been unlocked. If an account unlocks (due to sync) prior to client engagement, there is a risk that the bad actor with access to the account could reset credentials and maintain access before client engagement. This risk can be addressed by MFA implementation, as [required by Microsoft](https://learn.microsoft.com/en-us/entra/identity/authentication/concept-mandatory-multifactor-authentication?tabs=dotnet) for all Azure sign-in attempts.

## How It Works <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

This remediation forces a password change at the next login, and revokes sessions and refresh tokens. It does not set a new password.

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

`v1.0`, `beta`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/users/{userid}</code></td><td>Get user; read <code>passwordProfile</code> for the pre-check</td></tr><tr><td>PATCH</td><td><code>v1.0/users/{userid}</code></td><td>Force change at next sign-in; sets <code>passwordProfile.forceChangePasswordNextSignInWithMfa</code> (falls back to <code>forceChangePasswordNextSignIn</code>)</td></tr><tr><td>POST</td><td><code>v1.0/users/{userid}/revokeSignInSessions</code></td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td><code>beta/users/{userid}/invalidateAllRefreshTokens</code></td><td>Revoke all refresh tokens</td></tr></tbody></table>

## Prerequisites <a href="#h_01j7kypdqg3f3s33034zmvxxbs" id="h_01j7kypdqg3f3s33034zmvxxbs"></a>

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. Make sure all end user accounts have MFA enabled, to allow the auto remediation to run properly.
4. Make sure to enable password writeback so that password changes made in Microsoft Entra ID are synchronized back to your local active directory (password writeback is not enabled by default in a hybrid environment).

## Step 1: Grant Necessary Permissions <a href="#h_01j7kypdqgwswbqzpav08nn2v0" id="h_01j7kypdqgwswbqzpav08nn2v0"></a>

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required. The way you grant us these permissions will depend on how you set up your initial Microsoft 365 security device.&#x20;

* If you chose to use the Expel application during your onboarding, go to [Option 1](#h_01j7kypdqgcasm9sv3y64ssvhj).
* If you chose to create your own custom Microsoft Entra ID application during your onboarding, go to [Option 2](#h_01j7kypdqghg5vpsznkhb8xm6k).
* If you aren't sure, go to your enterprise applications in Azure and look for either the Expel Microsoft 365 Integration application or your custom application. Then proceed based on which one you find.

### Option 1: Grant Permissions in the Expel Application <a href="#h_01j7kypdqgcasm9sv3y64ssvhj" id="h_01j7kypdqgcasm9sv3y64ssvhj"></a>

If you chose to use the Expel Microsoft 365 Integration application during your security device onboarding, you will simply need to grant admin consent so that we may perform the auto remediation.

{% hint style="info" %}
If you have set up other auto remediations for Microsoft 365, you may have completed this step already. We recommend that you verify this permission before moving on to [Step 2](#h_01j7kypdqgpw4e0yb9fg0gjqcr).
{% endhint %}

1. Log in to <https://portal.azure.com/>.
2. Select **Enterprise Applications**.
3. Select the Expel application.
4. In the left menu, go to **Security > Permissions**.
5. Select the **Grant admin consent for Expel** button.
6. Select the **Refresh** option to verify that the permissions have been updated.
7. Go to [Add an Expel Assignment to the User Administrator Role](#h_01j7kypdqgpw4e0yb9fg0gjqcr).

### Option 2: Grant Permissions in Your Microsoft Entra ID Application <a href="#h_01j7kypdqghg5vpsznkhb8xm6k" id="h_01j7kypdqghg5vpsznkhb8xm6k"></a>

If you chose to create your own custom application during your security device onboarding, you will need to grant us with admin consent *and* add user read/write permissions for the Microsoft Graph API so that we may perform the auto remediation.

1. Log in to <https://portal.azure.com/>.
2. Use the search field to locate the **Expel Cloud Service** application, which will display within the MicroSoft Entra ID section of the search results (you registered and created this app during your security device onboarding). Locating it in this manner will allow you to configure permissions via Application Registration.
3. Go to **Manage > API Permissions**.
   * If you do not see this option, you are not in the right place. Try going to Security > Permissions and looking for a message that says "To configure requested permissions for apps you own, use the app registration." The accompanying Application Registration link will take you to the right place.
4. If you see the **User.ReadWrite.All** permission in the configured permissions for Microsoft Graph *and* the type shows as **Application**, you are done and can skip to [Add an Expel Assignment to the User Administrator Role](#h_01j7kypdqgpw4e0yb9fg0gjqcr). If not, continue to step 5.
5. Select **Add a permission**.
6. Select **Microsoft Graph**.
7. Select **Application permissions** as the type.
8. Navigate to the **User.ReadWrite.All** permission and use the checkbox to select it.
9. Select **Add permissions** to save your changes.
10. Use the search field to find and select **Enterprise Applications**.
11. Select your custom application.
12. In the left menu, go to **Security > Permissions**.
13. Select the **Grant admin consent for Expel** button.
14. Select the **Refresh** option to verify that the permissions have been updated.

## Step 2: Add an Expel Assignment to the User Administrator Role <a href="#h_01j7kypdqgpw4e0yb9fg0gjqcr" id="h_01j7kypdqgpw4e0yb9fg0gjqcr"></a>

You will need to add an assignment for Expel within the User Administrator role to allow us to reset user credentials.

1. Still in the Azure portal, search for **Microsoft Entra ID**.
2. Go to **Manage > Roles and Administrators**.
3. Search for and select the **User Administrator** role.
4. Select **Add assignments** to add the assignment for Expel. *Important: This assignment must be added to the Expel application or to your custom application (whichever one you configured in the previous section).*

If you need additional help with assignments, refer to the [Azure documentation](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/custom-overview).&#x20;

## Step 3: Update Your Context <a href="#h_01jhrm39k6zwpsdc6r9c995qgr" id="h_01jhrm39k6zwpsdc6r9c995qgr"></a>

**If you do not want to specify any credentials for a "do not reset" or "always reset" list, and instead wish for Expel to automatically reset all identified credentials, skip to** [**Step 4**](#h_01j7kypdqgvzxv5wa84vspabyr)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding credentials as context for your environment. You will then be able to select those credentials as "Never reset" or "Always reset" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies credentials that must be reset and you have created either an allow ("Always reset") or deny ("Never reset") list in Workbench, any credentials falling outside of those parameters are assigned to you as actions rather than being reset automatically.
{% endhint %}

## Step 4: Return to the Main Setup Guide <a href="#h_01j7kypdqgvzxv5wa84vspabyr" id="h_01j7kypdqgvzxv5wa84vspabyr"></a>

Your Microsoft 365 device is now ready for the Reset Credentials auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Microsoft Entra ID via Event Hub: Reset Credentials

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

This guide helps you set up your Microsoft Entra ID via Event Hub device so that you can enable the Reset Credentials auto remediation in Workbench. During the setup process, you will grant Expel all necessary permissions for the remediation to work.

## Scope and Limitations

When choosing to enable this auto remediation, remember the following:

* This auto remediation will not work on admin user accounts or on accounts that Microsoft considers Privileged (as these accounts cannot be forced to change their password).
* While an account is temporarily disabled, the user cannot have their credentials reset. It is therefore recommended that, in the event of a suspected compromised user, this remediation is applied directly before the Disable Accounts remediation is applied.

**If you have an on-prem Active Directory or hybrid Entra ID/ on-prem Active Directory environment**, consider the following safety precautions before enabling this auto remediation:

* In hybrid environments, the on-prem AD configuration always takes precedence and is considered the "source of truth." Microsoft initiates automatic syncs from on-prem AD to Entra ID every 30-60 minutes. Make sure to enable password writeback so that password changes made in Microsoft Entra ID are synchronized back to your local active directory (password writeback is not enabled by default in a hybrid environment).
* The Reset Credentials auto remediation will not prompt the affected user to set a new password until the account in question has been unlocked. If an account unlocks (due to sync) prior to client engagement, there is a risk that the bad actor with access to the account could reset credentials and maintain access before client engagement. This risk can be addressed by MFA implementation, as [required by Microsoft](https://learn.microsoft.com/en-us/entra/identity/authentication/concept-mandatory-multifactor-authentication?tabs=dotnet) for all Azure sign-in attempts.

## How It Works <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

This remediation forces a password change at the next login, and revokes sessions and refresh tokens. It does not set a new password.

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Microsoft Graph API**

`v1.0`, `beta`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>v1.0/users/{userid}</code></td><td>Get user; read <code>passwordProfile</code> for the pre-check</td></tr><tr><td>PATCH</td><td><code>v1.0/users/{userid}</code></td><td>Force change at next sign-in; sets <code>passwordProfile.forceChangePasswordNextSignInWithMfa</code> (falls back to <code>forceChangePasswordNextSignIn</code>)</td></tr><tr><td>POST</td><td><code>v1.0/users/{userid}/revokeSignInSessions</code></td><td>Revoke all sign-in sessions</td></tr><tr><td>POST</td><td><code>beta/users/{userid}/invalidateAllRefreshTokens</code></td><td>Revoke all refresh tokens</td></tr></tbody></table>

## Prerequisites

1. You must be an Azure admin for your organization, as you must have the ability to grant app permissions and add assignments.
2. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
3. You must have already completed all of the steps in [Microsoft Entra ID via Event Hub Setup for Workbench](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench).
4. Make sure all end user accounts have MFA enabled, to allow the auto remediation to run properly.
5. Make sure to enable password writeback so that password changes made in Microsoft Entra ID are synchronized back to your local active directory (password writeback is not enabled by default in a hybrid environment).

## Step 1: Grant Necessary Permissions

The remediation actions the Expel SOC creates in Workbench will run in your vendor technology, so granting us certain permissions is required.

1. [Log in to Azure](https://portal.azure.com/).
2. Navigate to the **Microsoft Entra ID** service.
3. Go to **Manage > App registrations**.
4. Select the custom Entra ID app you created when you [set up your Expel integration](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench#step-2-create-a-custom-entra-id-app).
5. Navigate to **Manage > API permissions**.
6. Locate the **Microsoft Graph** API and add the following two permissions:
   * `Directory.ReadWrite.All`
   * `User.RevokeSessions.All`
7. Make sure to **Grant admin consent** for both permissions.

## Step 2: Update Your Context

**If you do not want to specify any credentials for a "do not reset" or "always reset" list, and instead wish for Expel to automatically reset all identified credentials, skip to** [**Step 3**](#step-3-return-to-the-main-setup-guide)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding credentials as context for your environment. You will then be able to select those credentials as "Never reset" or "Always reset" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies credentials that must be reset and you have created either an allow ("Always reset") or deny ("Never reset") list in Workbench, any credentials falling outside of those parameters are assigned to you as actions rather than being reset automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#step-3-return-to-the-main-setup-guide" id="step-3-return-to-the-main-setup-guide"></a>

Your Microsoft Entra ID via Event Hub device is now ready for the Reset Credentials auto remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# Okta: Reset Credentials

This guide helps you set up your Okta device and grant necessary permissions so that you can enable the Reset Credentials auto remediation in Workbench.

*This guide is the first step of a larger process to enable auto remediations. After completing the steps on this page, you will be instructed to return to the* [*Enable an Auto Remediation in Workbench*](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) *guide to finish your setup.*

## Scope and Limitations <a href="#h_01j7kzj88ex6fwepzfjmj4wd48" id="h_01j7kzj88ex6fwepzfjmj4wd48"></a>

When choosing this auto remediation, remember the following:

* While an account is temporarily disabled, the user will not be able to reset their password; they will be forced to change their password as soon as the account is re-enabled.

## How It Works <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

This remediation uses `expire_password` to force change at next login, and not the `reset_password` email link flow; it does not set a temporary password. It also clears all sessions and OAuth tokens.

### Endpoints Used <a href="#h_01kcq58zyx8ybb32hecxz7qhhp" id="h_01kcq58zyx8ybb32hecxz7qhhp"></a>

**Okta Core API**

`/api/v1`

<table><thead><tr><th width="123.40625">Method</th><th>Endpoint</th><th>Purpose</th></tr></thead><tbody><tr><td>GET</td><td><code>/api/v1/users/{id}</code></td><td>Look up the user and read status</td></tr><tr><td>POST</td><td><code>/api/v1/users/{id}/lifecycle/expire_password</code></td><td>Expire the password (forces a change at next login)</td></tr><tr><td>DELETE</td><td><code>/api/v1/users/{id}/sessions?oauthTokens=true</code></td><td>Clear all sessions, and revoke OIDC/OAuth refresh and access tokens</td></tr></tbody></table>

No revert.

## Prerequisites <a href="#h_01j7kzjrgtywbzeknw86aq4whx" id="h_01j7kzjrgtywbzeknw86aq4whx"></a>

1. You must have admin access in Workbench, as auto remediations are enabled at the organization level.
2. Make sure all end-user accounts have MFA enabled to allow the auto remediation to run properly.

## Step 1: Configure Auto Reset Credentials for Okta <a href="#h_01j7kzm3m1mzc350fgbz3npfq2" id="h_01j7kzm3m1mzc350fgbz3npfq2"></a>

This procedure applies to a regular Okta installation in Workbench. If you have questions or need assistance, [contact Support](/support).

The Okta API token uses the [Read-only admin permission](https://help.okta.com/en-us/content/topics/security/administrators-read-only-admin.htm) and Expel's Auto Reset Credential feature requires the [Group admin permission](https://help.okta.com/en-us/content/topics/security/administrators-group-admin.htm). In Okta, API tokens have the same permissions as the user who creates them and if user permissions change, the API token permissions also change. As a result, you have the following options:

* [Option 1](#h_01j7kzr0bqt7ax4nz2qyjtnm8r): Edit the existing user to add the Group admin role. This existing user should be the same one you used to configure an API key in [Okta Workforce Identity Setup for Workbench](/connect-your-technology/l-p-integrations/okta-workforce-identity-setup-for-workbench).
* [Option 2](#h_01j7m1fjf4qmd46gcwp875q5wc): Generate a new separate API token with the required permissions level.

### Option 1: Edit the Permissions of the User that Created the Existing API Token <a href="#h_01j7kzr0bqt7ax4nz2qyjtnm8r" id="h_01j7kzr0bqt7ax4nz2qyjtnm8r"></a>

1. Identify the Read-only admin account used to create the API token.
2. Log into the Okta console from an account that has [Super administrator privileges](https://help.okta.com/en-us/content/topics/security/administrators-super-admin.htm) and add the permissions of the **Group admin** to the existing user for Expel.

### Option 2: Generate a New API Token and Update Workbench <a href="#h_01j7m1fjf4qmd46gcwp875q5wc" id="h_01j7m1fjf4qmd46gcwp875q5wc"></a>

1. Generate a new API token in Okta using an account with **Report administrator** and **Group administrator** privileges. For instructions, follow [Step 2 of the Okta Workforce Identity Setup for Workbench guide](/connect-your-technology/l-p-integrations/okta-workforce-identity-setup-for-workbench#h_01hyebzs0p1gyt5w8asegrh3k9), replacing "Read-only Administrator" with "Report Administrator" and "Group Administrator" privileges.
2. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
3. Navigate to **Organization Settings > Security Devices**.
4. Find Okta in the security device list.
5. In the Okta row, select the **down arrow**, and select **Edit**.
6. Replace the API Token with the newly generated token.
7. Select **Save**.

## Step 2: Update Your Context <a href="#h_01jhrm39k6zwpsdc6r9c995qgr" id="h_01jhrm39k6zwpsdc6r9c995qgr"></a>

**If you do not want to specify any credentials for a "do not reset" or "always reset" list, and instead wish for Expel to automatically reset all identified credentials, skip to** [**Step 3**](#h_01j7kypdqgvzxv5wa84vspabyr)**.**

Working with your Customer Success Manager, prepare to create an allow or deny list by adding credentials as context for your environment. You will then be able to select those credentials as "Never reset" or "Always reset" assets when you enable the auto remediation in Workbench.

{% hint style="info" %}
If our SOC identifies credentials that must be reset and you have created either an allow ("Always reset") or deny ("Never reset") list in Workbench, any credentials falling outside of those parameters are assigned to you as actions rather than being reset automatically.
{% endhint %}

## Step 3: Return to the Main Setup Guide <a href="#h_01j7kypdqgvzxv5wa84vspabyr" id="h_01j7kypdqgvzxv5wa84vspabyr"></a>

Your Okta device is now ready for the Reset Credentials Auto Remediation. You should now do one of the following:

* **If you do not need to set up any other devices for this auto remediation**, you can return to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process.
* **If you need to set up additional devices for this auto remediation, or wish to use this device with multiple auto remediations**, be sure to [complete those setup guides as well](/workbench-setup/auto-remediations) before returning to the [Enable an Auto Remediation in Workbench](/workbench-setup/auto-remediations/enable-an-auto-remediation-in-workbench) guide to finish Step 2 of the process. *Make sure to follow the setup guide that is specific to your auto remediation, as device setup instructions are unique to each auto remediation and device.*


# API Key Self-Service

Workbench allows you to create and manage your API keys via service accounts.

Each service account has specific access restrictions or role settings and can hold and organize multiple API keys, and you may create multiple service accounts if you choose.

For help with the Workbench API, [go to the API reference docs](https://workbench.expel.io/api/v2/docs/).

{% hint style="info" %}
An API key is different from a temporary access token. Temporary access tokens expire in 13 hours while API keys do not expire.
{% endhint %}

## Prerequisites <a href="#h_01jafwrhyrq3kt3fbpc5q9nvk1" id="h_01jafwrhyrq3kt3fbpc5q9nvk1"></a>

1. You must have API access to view the Service Accounts page and to generate API keys ([contact sales to upgrade](https://expel.com/contact/)).
2. You must have admin privileges in Workbench to manage service accounts or API keys.

## Generate Your First API Key <a href="#h_01jafwrhyrt3at73ecp90wvajf" id="h_01jafwrhyrt3at73ecp90wvajf"></a>

To generate an API key, you must first create a service account. Remember, you must have API access to view the Service Accounts page in Workbench.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings** > **Service Accounts**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select **Add Service Account**.
4. Complete the fields as follows:
   * **Service Account Name** - enter a name that might help you easily identify this service account.
   * **Workbench Service Account Role** - select the appropriate role for this service account (*organization admins* can access all API calls; *organization analysts* can perform common non-administrative API calls like marking investigative actions complete or sending remediation actions to another tool, but they cannot perform administrative calls like adding context or users).
   * To enable read-only API access for the service account, select the **Read-only Access** checkbox.
   * Select **Save**.
5. In the new service account, select **Generate API Key**.
6. Enter a name for the API key, then select **Next**.
7. **Copy the API key** and save it to a safe place (this is the only time you can view your API key), then select **Done**.

## Manage Your Service Accounts <a href="#h_01jafwrhyrnykwqvx430hcda5h" id="h_01jafwrhyrnykwqvx430hcda5h"></a>

If you want your API keys to have different permission levels, you must create different service accounts. Each service account has its own permission settings that apply to all of the API keys within it.

You can edit, delete, or disable your service accounts at any time on the Service Accounts page ([Organization Settings > Service Accounts](https://workbench.staging.expel.io/settings/service-accounts)). If you have multiple organizations, you must first select the appropriate organization name from the list.

{% hint style="danger" %}
Use caution when deleting, as you cannot restore a deleted service account. Deleting a service account will also delete all of its API keys.
{% endhint %}

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FU2KI1d0e4FJ411VofOcP%2Funknown.png?alt=media&amp;token=7bf9a532-e6e9-49d4-a451-19ebf803522e" alt="Workbench Service Account page shows options to Generate, Edit, Delete, and Disable API keys." width="563"><figcaption></figcaption></figure></div>

## Manage Your API Keys <a href="#h_01jafwrhyrekh65k88f1yn3xj9" id="h_01jafwrhyrekh65k88f1yn3xj9"></a>

If you have multiple service accounts, you must generate your API key within the service account that has the permission level you want to set. The API key takes on the permissions of the service account it is in.

You can generate API keys or delete them at any time on the Service Accounts page ([Organization Settings > Service Accounts](https://workbench.staging.expel.io/settings/service-accounts)). If you have multiple organizations, you must first select the appropriate organization name from the list.

{% hint style="danger" %}
Use caution when deleting, as you cannot restore a deleted API key. Make sure the key is not used by critical services or processes before you delete it.
{% endhint %}

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FN5wedw2CAGaxZYuqFIqb%2Fwb_serviceaccount_generateAPIkey.png?alt=media&amp;token=0091e5fb-5f08-47e4-b93b-0acb92f46b4d" alt="The Trash Can icon deletes an API key." width="563"><figcaption></figcaption></figure></div>


# Configure an IP Allow List

All traffic from Expel to your security devices will originate from the following IP addresses. If your security tech supports an IP allow list, please configure it to include all IPs listed below.

* 34.75.13.114
* 34.75.152.7
* 35.243.190.98
* 104.196.158.205
* 34.75.81.28
* 34.75.210.18
* 20.101.120.26
* 52.168.181.55
* 74.225.153.94
* 100.50.35.194
* 100.56.66.84
* 98.95.204.173
* 18.213.81.223
* 54.85.49.81
* 3.88.246.133
* 50.112.212.124
* 44.240.17.93
* 44.230.60.218
* 100.21.152.130
* 54.184.158.35
* 35.162.84.154


# About Integrations


# Expel Integrations

This page contains a full list of our supported integrations.

We connect to these integrations in one of the following ways:

* **Direct (via API)**
* **Direct (via a collector)**
* **Direct (via a syslog)**
* **Via a SIEM connection** **(**[**learn more**](/connect-your-technology/about-integrations/about-siem-integrations-and-connections#h_01k1eeqqcmef9jbdzkgcnaq7vx)**)**

In cases where the integration is only available via a SIEM connection, all supported SIEMs are listed in the chart. For more information about each integration's detection strategy (including supported versions, platforms, event log sources, detection rules, etc.) refer to the [detection strategy guides](/detection-strategy-guides/a-c).

## Security Device Integrations <a href="#h_01kac7n4nt89m2fjhas0g66rrc" id="h_01kac7n4nt89m2fjhas0g66rrc"></a>

**To access an integration's setup guide, select the integration name.**&#x20;

Integrations with an asterisk (\*) are [investigative-only](#investigative-only).

| Supported Integration                                                                                                                                                                                                               | Supported Connection(s)                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [1Password](/connect-your-technology/l-p-integrations/1password-setup-for-workbench)                                                                                                                                                | Direct (via API)                                                                            |
| [Abnormal AI](/connect-your-technology/a-c-integrations/abnormal-ai-setup-for-workbench)                                                                                                                                            | Direct (via API)                                                                            |
| [Akamai Guardicore Segmentation (formerly Guardicore Centra)](/connect-your-technology/a-c-integrations/akamai-guardicore-segmentation-formerly-guardicore-centra-setup-for-workbench)                                              | Direct (via API)                                                                            |
| [Amazon Elastic Kubernetes Service](/connect-your-technology/a-c-integrations/amazon-aws/amazon-elastic-kubernetes-service-setup-for-workbench)                                                                                     | Direct (via API)                                                                            |
| [Anthropic Claude Enterprise Compliance API](/connect-your-technology/a-c-integrations/anthropic-claude-enterprise-compliance-api-setup-for-workbench)                                                                              | Direct (via API)                                                                            |
| [Arista NDR (via Webhook)](/connect-your-technology/a-c-integrations/arista-ndr-via-webhook-setup-for-workbench)                                                                                                                    | Direct (via API)                                                                            |
| [Aurora Endpoint Security (formerly Cylance PROTECT AV)](/connect-your-technology/a-c-integrations/aurora-endpoint-security-formerly-cylance-protect-av-setup-for-workbench)                                                        | Direct (via API)                                                                            |
| [AWS CloudTrail](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail)                                                                                                                                               | Direct (via API)                                                                            |
| [AWS GuardDuty](/connect-your-technology/a-c-integrations/amazon-aws/aws-guardduty/aws-guardduty-setup-for-workbench)                                                                                                               | Direct (via API)                                                                            |
| [AWS GuardDuty GovCloud](/connect-your-technology/a-c-integrations/amazon-aws/aws-guardduty/aws-guardduty-govcloud-setup-for-workbench)                                                                                             | Direct (via API)                                                                            |
| [Box](/connect-your-technology/a-c-integrations/box-setup-for-workbench)                                                                                                                                                            | Direct (via API)                                                                            |
| [Broadcom Carbon Black Cloud (formerly CB ThreatHunter and CB Defense)](/connect-your-technology/a-c-integrations/broadcom/broadcom-carbon-black-cloud-formerly-cb-threathunter-and-cb-defense-setup-for-workbench)                 | Direct (via API)                                                                            |
| [Broadcom Carbon Black EDR (formerly CB Response)](/connect-your-technology/a-c-integrations/broadcom/broadcom-carbon-black-edr-formerly-cb-response-setup-for-workbench)                                                           | Direct (via API)                                                                            |
| [Broadcom Symantec Endpoint Protection (via SIEM)](/connect-your-technology/a-c-integrations/broadcom/broadcom-symantec-endpoint-protection-via-siem-setup-for-workbench)                                                           | <p>Exabeam Fusion New-Scale SIEM</p><p>Splunk</p><p>Sumo Logic</p>                          |
| [Check Point AV, Anti-Bot, and IPS (via SIEM)](/connect-your-technology/a-c-integrations/check-point/check-point-av-anti-bot-and-ips-via-siem-setup-for-workbench)                                                                  | Sumo Logic                                                                                  |
| [Check Point Quantum Network Security](/connect-your-technology/a-c-integrations/check-point/check-point-quantum-network-security-setup-for-workbench)                                                                              | Direct (via API)                                                                            |
| [Cisco ASA (via SIEM)](/connect-your-technology/a-c-integrations/cisco/cisco-asa-via-siem-setup-for-workbench)                                                                                                                      | <p>Exabeam Fusion New-Scale SIEM</p><p>Splunk</p><p>Sumo Logic</p>                          |
| [Cisco ASA (via Syslog)](/connect-your-technology/a-c-integrations/cisco/cisco-asa-via-syslog-setup-for-workbench)                                                                                                                  | Direct (via API)                                                                            |
| [Cisco Duo](/connect-your-technology/a-c-integrations/cisco/cisco-duo-setup-for-workbench)                                                                                                                                          | Direct (via API)                                                                            |
| [Cisco Firepower (via SIEM)](/connect-your-technology/a-c-integrations/cisco/cisco-firepower-via-siem-setup-for-workbench)                                                                                                          | <p>Exabeam Fusion New-Scale SIEM</p><p>Microsoft Sentinel</p><p>Splunk</p><p>Sumo Logic</p> |
| [Cisco Meraki](/connect-your-technology/a-c-integrations/cisco/cisco-meraki-setup-for-workbench)                                                                                                                                    | Direct (via API)                                                                            |
| [Cisco Meraki (via SIEM)](/connect-your-technology/a-c-integrations/cisco/cisco-meraki-via-siem-setup-for-workbench)                                                                                                                | <p>Splunk</p><p>Sumo Logic</p>                                                              |
| [Cisco Secure Endpoint (formerly AMP)](/connect-your-technology/a-c-integrations/cisco/cisco-secure-endpoint-formerly-amp-setup-for-workbench)                                                                                      | Direct (via API)                                                                            |
| [Cisco Umbrella](/connect-your-technology/a-c-integrations/cisco/cisco-umbrella-setup-for-workbench)                                                                                                                                | Direct (via API)                                                                            |
| [Cloudflare WAF](/connect-your-technology/a-c-integrations/cloudflare/cloudflare-waf-setup-for-workbench)\*[^1]                                                                                                                     | Direct (via API)                                                                            |
| [Cloudflare ZTNA](/connect-your-technology/a-c-integrations/cloudflare/cloudflare-zero-trust-network-access-via-webhook-setup-for-workbench)                                                                                        | Direct (via API)                                                                            |
| [Corelight Open NDR (via Collector)](/connect-your-technology/a-c-integrations/corelight-open-ndr-via-collector-setup-for-workbench)                                                                                                | Direct (via the Splunk Collector)                                                           |
| [Cribl](/connect-your-technology/a-c-integrations/cribl-setup-for-workbench)                                                                                                                                                        | Direct (via API)                                                                            |
| [CrowdStrike Falcon Identity Protection](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench)                                                                                  | Direct (via API)                                                                            |
| [CrowdStrike Falcon Insight XDR](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-insight-xdr-setup-for-workbench)                                                                                          | Direct (via API)                                                                            |
| [CrowdStrike Falcon Next-Gen SIEM](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-falcon-next-gen-siem-setup-for-workbench)                                                                                      | Direct (via API)                                                                            |
| [CrowdStrike Logscale](/connect-your-technology/a-c-integrations/crowdstrike/crowdstrike-logscale-setup-for-workbench)                                                                                                              | Direct (via API)                                                                            |
| [Cyberark Identity](/connect-your-technology/a-c-integrations/cyberark/cyberark-identity-setup-for-workbench)                                                                                                                       | Direct (via API)                                                                            |
| [Cyberark Privileged Access Management (PAM) (via SIEM)](/connect-your-technology/a-c-integrations/cyberark/cyberark-privileged-access-management-pam-via-siem-setup-for-workbench)                                                 | Splunk                                                                                      |
| [Cybereason Endpoint Detection and Response (EDR)](/connect-your-technology/a-c-integrations/cybereason-endpoint-detection-and-response-edr-setup-for-workbench)                                                                    | Direct (via API)                                                                            |
| [Darktrace](/connect-your-technology/d-j-integrations/darktrace-setup-for-workbench)                                                                                                                                                | Direct (via API)                                                                            |
| [Datadog Observability & Analytics Platform](/connect-your-technology/d-j-integrations/datadog-observability-and-analytics-platform-setup-for-workbench)                                                                            | Direct (via API)                                                                            |
| [Devo](/connect-your-technology/d-j-integrations/devo-setup-for-workbench)\*[^1]                                                                                                                                                    | Direct (via API)                                                                            |
| [Dropbox](/connect-your-technology/d-j-integrations/dropbox-setup-for-workbench)                                                                                                                                                    | Direct (via API)                                                                            |
| [Elastic Security (SIEM)](/connect-your-technology/d-j-integrations/elastic-security-siem-setup-for-workbench)                                                                                                                      | Direct (via API)                                                                            |
| [Exabeam Fusion New-Scale SIEM Collector](/connect-your-technology/d-j-integrations/exabeam/exabeam-fusion-new-scale-siem-collector-setup-for-workbench)                                                                            | Direct (via API)                                                                            |
| [Exabeam Fusion XDR](/connect-your-technology/d-j-integrations/exabeam/exabeam-fusion-xdr-setup-for-workbench)\*[^1]                                                                                                                | Direct (via API)                                                                            |
| [Exabeam Threat Center](/connect-your-technology/d-j-integrations/exabeam/exabeam-threat-center-setup-for-workbench)                                                                                                                | Direct (via API)                                                                            |
| [ExtraHop Reveal(x) 360](/connect-your-technology/d-j-integrations/extrahop/extrahop-reveal-x-360-setup-for-workbench)                                                                                                              | Direct (via API)                                                                            |
| [ExtraHop Reveal(x) Enterprise](/connect-your-technology/d-j-integrations/extrahop/extrahop-reveal-x-enterprise-setup-for-workbench)                                                                                                | Direct (via API)                                                                            |
| [Fastly Next-Gen WAF (formerly Signal Sciences WAF)](/connect-your-technology/d-j-integrations/fastly-next-gen-waf-formerly-signal-sciences-waf-setup-for-workbench)\*[^1]                                                          | Direct (via API)                                                                            |
| [Forcepoint Web Filter (via SIEM)](/connect-your-technology/d-j-integrations/forcepoint-web-filter-via-siem-setup-for-workbench)                                                                                                    | Exabeam Fusion New-Scale SIEM                                                               |
| [Fortinet FortiAnalyzer](/connect-your-technology/d-j-integrations/fortinet/fortinet-fortianalyzer-setup-for-workbench)                                                                                                             | Direct (via API)                                                                            |
| [Fortinet FortiCNAPP (formerly Lacework)](/connect-your-technology/d-j-integrations/fortinet/fortinet-forticnapp-formerly-lacework-setup-for-workbench)                                                                             | Direct (via API)                                                                            |
| [Fortinet FortiGate (via SIEM)](/connect-your-technology/d-j-integrations/fortinet/fortinet-fortigate-via-siem-setup-for-workbench)                                                                                                 | <p>Microsoft Sentinel</p><p>Securonix</p><p>Splunk</p><p>Sumo Logic</p>                     |
| [GitHub](/connect-your-technology/d-j-integrations/github)                                                                                                                                                                          | Direct (via API)                                                                            |
| [GitLab](/connect-your-technology/d-j-integrations/gitlab-setup-for-workbench)                                                                                                                                                      | Direct (via API)                                                                            |
| [Google Cloud Platform](/connect-your-technology/d-j-integrations/google/google-cloud-platform-setup-for-workbench)                                                                                                                 | Direct (via API)                                                                            |
| [Google Kubernetes Engine](/connect-your-technology/d-j-integrations/google/google-kubernetes-engine-setup-for-workbench)                                                                                                           | Direct (via API)                                                                            |
| [Google Security Operations (SecOps)](/connect-your-technology/d-j-integrations/google/google-security-operations-secops-setup-for-workbench)                                                                                       | Direct (via API)                                                                            |
| [Google Workspace (formerly G Suite)](/connect-your-technology/d-j-integrations/google/google-workspace-formerly-g-suite-setup-for-workbench)                                                                                       | Direct (via API)                                                                            |
| [Google Workspace Alert Center](/connect-your-technology/d-j-integrations/google/google-workspace-alert-center-setup-for-workbench)                                                                                                 | Direct (via API)                                                                            |
| [JumpCloud](/connect-your-technology/d-j-integrations/jumpcloud-setup-for-workbench)                                                                                                                                                | Direct (via API)                                                                            |
| [LastPass](/connect-your-technology/l-p-integrations/lastpass-setup-for-workbench)                                                                                                                                                  | Direct (via API)                                                                            |
| [Logz.io](/connect-your-technology/l-p-integrations/logz.io-setup-for-workbench)\*[^1]                                                                                                                                              | Direct (via API)                                                                            |
| [Microsoft 365](/connect-your-technology/l-p-integrations/microsoft/microsoft-365-setup-for-workbench)                                                                                                                              | Direct (via API)                                                                            |
| [Microsoft Azure](/connect-your-technology/l-p-integrations/microsoft/microsoft-azure-setup-for-workbench)                                                                                                                          | Direct (via API)                                                                            |
| [Microsoft Azure Kubernetes Service](/connect-your-technology/l-p-integrations/microsoft/microsoft-azure-kubernetes-service-setup-for-workbench)                                                                                    | Direct (via API)                                                                            |
| [Microsoft Azure Log Analytics](/connect-your-technology/l-p-integrations/microsoft/microsoft-azure-log-analytics-setup-for-workbench)                                                                                              | Direct (via API)                                                                            |
| Microsoft Azure Log Analytics Collector                                                                                                                                                                                             | Direct (via a collector)                                                                    |
| Microsoft Azure Monitor (formerly Azure Activity logs)\*[^1]                                                                                                                                                                        | Direct (via API)                                                                            |
| [Microsoft Defender for Cloud Apps](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-cloud-apps-setup-for-workbench)                                                                                      | Direct (via API)                                                                            |
| [Microsoft Defender for Endpoint](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-endpoint-setup-for-workbench)                                                                                          | Direct (via API)                                                                            |
| [Microsoft Defender for Identity](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-for-identity-setup-for-workbench)                                                                                          | Direct (via API)                                                                            |
| [Microsoft Defender XDR](/connect-your-technology/l-p-integrations/microsoft/microsoft-defender-xdr-setup-for-workbench)                                                                                                            | Direct (via API)                                                                            |
| [Microsoft Entra ID Protection](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-protection-setup-for-workbench)                                                                                              | Direct (via API)                                                                            |
| [Microsoft Entra ID via Event Hub](/connect-your-technology/l-p-integrations/microsoft/microsoft-entra-id-via-event-hub-setup-for-workbench)                                                                                        | Direct (via API)                                                                            |
| [Microsoft Intune](/connect-your-technology/l-p-integrations/microsoft/microsoft-intune-setup-for-workbench)                                                                                                                        | Direct (via API)                                                                            |
| [Microsoft Sentinel](/connect-your-technology/l-p-integrations/microsoft/microsoft-sentinel-setup-for-workbench)                                                                                                                    | Direct (via API)                                                                            |
| [Mimecast](/connect-your-technology/l-p-integrations/mimecast-advanced-email-security-setup-for-workbench)                                                                                                                          | Direct (via API)                                                                            |
| [Netskope CASB and Next Gen SWG](/connect-your-technology/l-p-integrations/netskope-casb-and-next-gen-swg-setup-for-workbench)                                                                                                      | Direct (via API)                                                                            |
| [Okta Auth0](/connect-your-technology/l-p-integrations/okta-auth0-setup-for-workbench)                                                                                                                                              | Direct (via API)                                                                            |
| [Okta Workforce Identity](/connect-your-technology/l-p-integrations/okta-workforce-identity-setup-for-workbench)                                                                                                                    | Direct (via API)                                                                            |
| [OneLogin](/connect-your-technology/l-p-integrations/onelogin-setup-for-workbench)                                                                                                                                                  | Direct (via API)                                                                            |
| [Oracle Cloud Infrastructure](/connect-your-technology/l-p-integrations/oracle-cloud-infrastructure)                                                                                                                                | Direct (via API)                                                                            |
| [Orca Security](/connect-your-technology/l-p-integrations/orca-security-setup-for-workbench)                                                                                                                                        | Direct (via API)                                                                            |
| [Palo Alto Networks Cortex XDR Pro](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-cortex-xdr-pro-setup-for-workbench)                                                                             | Direct (via API)                                                                            |
| [Palo Alto Networks Cortex XSIAM](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-cortex-xsiam-setup-for-workbench)                                                                                 | Direct (via API)                                                                            |
| [Palo Alto Networks Next Gen Firewall](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-next-gen-firewall-setup-for-workbench)                                                                       | Direct (via API)                                                                            |
| [Palo Alto Networks Prisma Cloud Compute (formerly Twistlock)](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-prisma-cloud-compute-formerly-twistlock-setup-for-workbench)                         | Direct (via API)                                                                            |
| [Palo Alto Networks SaaS Security (formerly Prisma SaaS)](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-saas-security-formerly-prisma-saas-setup-for-workbench)                                   | Direct (via API)                                                                            |
| [Palo Alto Networks Strata](/connect-your-technology/l-p-integrations/palo-alto-networks/palo-alto-networks-strata-setup-for-workbench)                                                                                             | Direct (via API)                                                                            |
| [Panther Cloud SIEM](/connect-your-technology/l-p-integrations/panther-cloud-siem-setup-for-workbench)                                                                                                                              | Direct (via API)                                                                            |
| [PingOne Platform (via Collector)](/connect-your-technology/l-p-integrations/pingone-platform-via-collector-setup-for-workbench)                                                                                                    | Direct (via the Splunk Collector or Exabeam Fusion New-Scale SIEM Collector)                |
| [Proofpoint Insider Threat Management (via SIEM)](/connect-your-technology/l-p-integrations/proofpoint/proofpoint-insider-threat-management-via-siem-setup-for-workbench)                                                           | Sumo Logic                                                                                  |
| [Proofpoint TAP for MDR](/connect-your-technology/l-p-integrations/proofpoint/proofpoint-tap-for-mdr-setup-for-workbench)                                                                                                           | Direct (via API)                                                                            |
| [QRadar](/connect-your-technology/q-z-integrations/qradar-setup-for-workbench)                                                                                                                                                      | Direct (via API)                                                                            |
| [Qualys VMDR](/detection-strategy-guides/n-q/qualys-vmdr-setup-for-workbench)\*                                                                                                                                                     | Direct (via API)                                                                            |
| [Rapid7 InsightVM](/detection-strategy-guides/n-q/rapid7-insightvm-setup-for-workbench)\*                                                                                                                                           | Direct (via API)                                                                            |
| [Salesforce](/connect-your-technology/q-z-integrations/salesforce-setup-for-workbench)                                                                                                                                              | Direct (via API)                                                                            |
| [Securonix Next-Gen SIEM](/connect-your-technology/q-z-integrations/securonix-next-gen-siem-setup-for-workbench)\*[^1]                                                                                                              | Direct (via API)                                                                            |
| [SentinelOne Singularity Data Lake](/connect-your-technology/q-z-integrations/sentinelone/sentinelone-singularity-data-lake-setup-for-workbench)\*[^1]                                                                              | Direct (via API)                                                                            |
| [SentinelOne Singularity Endpoint](/connect-your-technology/q-z-integrations/sentinelone/sentinelone-singularity-endpoint-setup-for-workbench)                                                                                      | Direct (via API)                                                                            |
| [SentinelOne Singularity Hologram (formerly Attivo) (via SIEM)](/connect-your-technology/q-z-integrations/sentinelone/sentinelone-singularity-hologram-formerly-attivo-via-siem-setup-for-workbench)                                | <p>Splunk</p><p>Sumo Logic</p>                                                              |
| [ServiceNow](/workbench-setup/notifications/platform-setup/servicenow-setup-for-organization-notifications)                                                                                                                         | Direct (via API)                                                                            |
| [Slack](/connect-your-technology/q-z-integrations/slack-setup-for-workbench)                                                                                                                                                        | Direct (via API)                                                                            |
| [Snowflake](/connect-your-technology/q-z-integrations/snowflake-setup-for-workbench)                                                                                                                                                | Direct (via API)                                                                            |
| [Splunk](/connect-your-technology/q-z-integrations/splunk/splunk-setup-for-workbench)                                                                                                                                               | Direct (via API)                                                                            |
| [Splunk Collector](/connect-your-technology/q-z-integrations/splunk/splunk-collector-setup-for-workbench)                                                                                                                           | Direct (via API)                                                                            |
| [Splunk Core Alerts (via Collector)](/connect-your-technology/q-z-integrations/splunk/splunk-core-alerts-via-collector-setup-for-workbench)                                                                                         | Direct (via the Splunk Collector)                                                           |
| [Sublime Security](/connect-your-technology/q-z-integrations/sublime-security-setup-for-workbench)                                                                                                                                  | Direct (via API)                                                                            |
| [Sumo Logic Cloud Infrastructure Security](/connect-your-technology/q-z-integrations/sumo-logic/sumo-logic-cloud-infrastructure-security-setup-for-workbench)\*[^1]                                                                 | Direct (via API)                                                                            |
| [Sumo Logic Cloud SIEM Enterprise](/connect-your-technology/q-z-integrations/sumo-logic/sumo-logic-cloud-siem-enterprise-setup-for-workbench)                                                                                       | Direct (via API)                                                                            |
| Sumo Logic Collector                                                                                                                                                                                                                | Direct (via API)                                                                            |
| [Tanium XEM Core](/connect-your-technology/q-z-integrations/tanium)                                                                                                                                                                 | Direct (via API)                                                                            |
| [Tenable Vulnerability Management](/detection-strategy-guides/s-z/tenable-vulnerability-management-setup-for-workbench)\*                                                                                                           | Direct (via API)                                                                            |
| [Thales Imperva Cloud Web Application Firewall (formerly Imperva Cloud)](/connect-your-technology/q-z-integrations/thales-imperva/thales-imperva-cloud-web-application-firewall-formerly-imperva-cloud-setup-for-workbench)\*[^1]   | Direct (via API)                                                                            |
| [Thales Imperva Web Application Firewall (formerly Imperva SecureSphere)](/connect-your-technology/q-z-integrations/thales-imperva/thales-imperva-web-application-firewall-formerly-imperva-securesphere-setup-for-workbench)\*[^1] | Direct (via API)                                                                            |
| [Trellix Endpoint Security (HX) (formerly FireEye HX)](/connect-your-technology/q-z-integrations/trellix-endpoint-security-hx-formerly-fireeye-hx-setup-for-workbench)                                                              | Direct (via API)                                                                            |
| [Varonis DatAlert](/connect-your-technology/q-z-integrations/varonis-datalert-setup-for-workbench)                                                                                                                                  | Direct (via API)                                                                            |
| Varonis SaaS                                                                                                                                                                                                                        | Direct (via API)                                                                            |
| [Vectra AI (NDR)](/connect-your-technology/q-z-integrations/vectra-ai-ndr-setup-for-workbench)                                                                                                                                      | Direct (via API)                                                                            |
| [Verizon Network Detection and Response (formerly ProtectWise)](/connect-your-technology/q-z-integrations/varonis-datalert-setup-for-workbench)                                                                                     | Direct (via API)                                                                            |
| [Wiz](/connect-your-technology/q-z-integrations/wiz-setup-for-workbench)                                                                                                                                                            | Direct (via API)                                                                            |
| [Workday](/connect-your-technology/q-z-integrations/workday-setup-for-workbench)                                                                                                                                                    | Direct (via API)                                                                            |
| [Zscaler Internet Access (ZIA) (via SIEM)](/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-zia-via-siem-setup-for-workbench)                                                                              | <p>Microsoft Sentinel</p><p>Splunk</p><p>Sumo Logic</p>                                     |
| [Zscaler Internet Access (ZIA) (via Webhook)](/connect-your-technology/q-z-integrations/zscaler/zscaler-internet-access-via-webhook-setup-for-workbench)                                                                            | Direct (via API)                                                                            |

#### Investigative-only

Expel does not ingest bulk data for detection analysis against these integrations, but we may query specific data for investigative purposes. These integrations are connected to Workbench so that SOC analysts or [Ruxie](/workbench-reference/expel-terminology#ruxie) can perform queries to support an [investigation](/workbench-reference/expel-terminology#investigation) or [incident](/workbench-reference/expel-terminology#incident). Separately, Expel may request console access credentials to support SOC pivots during an investigation. Hunting support isn't currently available for these integrations. Expel recommends onboarding them purely to strengthen investigative capability.

## Other Integrations <a href="#h_01kac6xwde9tm5rzr1vympsrs6" id="h_01kac6xwde9tm5rzr1vympsrs6"></a>

You can also integrate with certain supported systems or notification methods in Workbench via your Organization Settings.

<table data-view="cards"><thead><tr><th>Method</th><th>Usage</th></tr></thead><tbody><tr><td>Microsoft Teams</td><td>To receive messages from Expel, including notifications</td></tr><tr><td>Opsgenie</td><td>To be notified of incidents in Workbench at a specific Opsgenie destination</td></tr><tr><td>PagerDuty</td><td>To be notified of important events at a specific PagerDuty destination</td></tr><tr><td>Single Sign-On</td><td>To log into Workbench using your SSO provider</td></tr><tr><td>Slack</td><td>To receive messages from Expel, including notifications</td></tr><tr><td>Ticketing Systems</td><td>To receive a plain text email of your organization's assigned actions in a ticketing destination</td></tr><tr><td>Webhooks</td><td>To be notified of important events at a specific webhook destination</td></tr><tr><td>Wiz</td><td>To sync Expel Alerts with the originating Wiz issues</td></tr></tbody></table>

[^1]: Investigative-only.


# Why Expel Asks for Console Access

For many of our integrations, we require that you grant our SOC analysts a certain level of access to the vendor technology's console when you set up your security device in Workbench. This page explains why we need this access, at what level, and under what circumstances.

## Why We Need Access

Gaining access to your console allows our SOC analysts to fully triage and research any events that result in an [Expel Alert](/workbench-reference/alerts/how-expel-alerts-work). At a base level, we must be able to determine the vector and extent of attacker activity for an identified threat. We do this by querying the integration via the Workbench API to obtain all necessary data.

However, some integrations do not allow us to get everything we need via the API. In these cases we ask you for console access. For example:

* Logs are not always queryable via the API, so maintaining access to the console is critical for gathering necessary log data.
* Some artifacts cannot be pulled remotely via the API and must be gathered directly from the console; examples include PCAP, malware reports, and certain types of files like browser histories or malicious binaries quarantined by EDR.
* Events from EDR integrations do not always include fundamental information (like network connections) that is necessary for triage, and this information can only be gathered by accessing the console.

{% hint style="info" %}
Remember that a vendor alert does not typically include all of the contextual timeline activity surrounding the event of interest, so maintaining console access helps us quickly bridge any gaps.
{% endhint %}

## Which Integrations Require Console Access <a href="#h_01jv2eckpj53y47s3tjy9mz4sv" id="h_01jv2eckpj53y47s3tjy9mz4sv"></a>

We have less of a need for console access if the information within the console is similar in display/quality as the information queryable via API. Therefore we generally require console access for the following types of integrations:

1. Endpoint Detection and Response (EDR)
2. SIEM
3. Any network technology with artifacts that can be downloaded (but not queried via API)
4. Integrations that are not fully queryable via API, including webhook integrations

Note that currently, cloud security logs (both Cloud Identity / SaaS and Cloud Infrastructure) are typically ingested into an internal SIEM and then queried by Expel, so direct access is not necessarily needed.

## Access Levels <a href="#h_01jv2eckpjgp4qbwb10ckk1v4p" id="h_01jv2eckpjgp4qbwb10ckk1v4p"></a>

### Minimum Requirements <a href="#h_01jv2eckpjmtgx8x8mkv69hbhb" id="h_01jv2eckpjmtgx8x8mkv69hbhb"></a>

The level of access that we ask for is meant to support [essential triage and research activities](/workbench-reference/alerts/how-expel-alerts-work#event-triage-process). At minimum, we ask for visibility into:

* Alert data
* Timeline events recorded by the security technology
* Live response/real time response shell (EDR integrations only; more info on this below)

For some integrations, we ask for read-only access. For others, like Wiz (which supports status syncing), we ask for read and write access so that we can simultaneously update the status in your console.

### Live Response/Real Time Response Shell Access <a href="#h_01jv2eckpjv5qrscs7tgsd50g6" id="h_01jv2eckpjv5qrscs7tgsd50g6"></a>

For EDR integrations, a live session (shell) is often created on the host to pull in artifacts such as browser history, suspicious files, log data, and registry entries. We ask for access to this shell to acquire those artifacts during an investigation, which helps us tremendously with identifying a root cause or attack vector for an identified threat.

**Simply enabling real time response (without granting shell access) is not enough, because it does not always allow our SOC analysts to acquire the artifacts and files.** Some reasons for this limitation include:

* EDR agent software on the host not supporting file or log acquisition
* The host being offline, and therefore no live session is available
* EDR agent software not supporting live response for the host operating system

Not every EDR integration supports live response/real time response, but many do. If we are unable to acquire a needed artifact due to lack of direct access, you may have to manually locate and upload it for us. This can increase triage time.<br>


# About SIEM Integrations and Connections

This topic helps you understand the difference between SIEM integrations and SIEM connections, and how you can leverage each one.

There are security devices with **SIEM-based technology** (like Splunk) that you may integrate via a direct API connection, and there are **via SIEM connections** that can be leveraged for supported vendor technology. A via SIEM connection can be set up in lieu of a direct API connection, or it can be used to onboard vendor technology that we currently only support by connecting via a SIEM.

## About SIEM Integrations <a href="#h_01k1eeqqca46spd009rqtk9rhr" id="h_01k1eeqqca46spd009rqtk9rhr"></a>

### Ingestion and Triage Process <a href="#h_01k1eeqqcb8j96bp5rpqxvjg0x" id="h_01k1eeqqcb8j96bp5rpqxvjg0x"></a>

For SIEM-based technology that is set up in Workbench as a direct API connection, we leverage your SIEM's out-of-the-box (OOTB) detection rules and/or your custom detection rules to map the SIEM alerts to our own ingestion criteria. This enables [Ruxie](/workbench-reference/expel-terminology#ruxie) to follow the normal [event triage process](/workbench-reference/alerts/how-expel-alerts-work#event-triage-process), and to create an [Expel Alert](/workbench-reference/alerts/how-expel-alerts-work) that is sent to our SOC analysts for analysis. We also run queries against your SIEM logs to search for additional types of data, which may result in the creation of an Expel Alert.

### Console Access <a href="#h_01k1eeqqcc7xp79c12nztpw5rp" id="h_01k1eeqqcc7xp79c12nztpw5rp"></a>

A SIEM alert does not typically include all of the contextual timeline activity surrounding an event of interest, and sometimes we cannot get all necessary data via API. In those cases, we will ask you for a certain level of console access during onboarding. Granting it is optional, but we strongly recommend you provide it.

The level of access that we require is meant to support essential triage and research activities, and to help us determine the vector and extent of attacker activity for an identified threat. At minimum, we will ask for visibility into alert data, timeline events recorded, and live response/real time response shell (if applicable).

For more information about console access, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access).

### Setup Process <a href="#h_01k1eeqqcd7tvj8kp2et3g21yc" id="h_01k1eeqqcd7tvj8kp2et3g21yc"></a>

Setting up a SIEM device follows the same general process as setting up any direct integration in Workbench. You may, however, have a second step if you wish to use custom detection rules:

1. Set up the **SIEM device** in Workbench by locating its setup guide. <button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Find your setup guide…</button>
2. If you have any **custom or OOTB detection rules** enabled or if you wish to add some, [follow the detection rule submission process](/connect-your-technology/about-integrations/about-siem-integrations-and-connections#h_01k1eeqqcj8yhaynheewq6vvwd).

* Your device will show as "Healthy" in Workbench, but Expel Alerts will not appear until the rule review process is complete.

{% hint style="info" %}
Setting up your device as a first step (including granting all [necessary console access](#h_01k1eeqqcc7xp79c12nztpw5rp)) greatly facilitates the evaluation and approval process for your custom detection rules.
{% endhint %}

### Criteria for Detection Rule Acceptance <a href="#h_01k1eeqqcga7gqdry9bpv6m23h" id="h_01k1eeqqcga7gqdry9bpv6m23h"></a>

Our SIEM-based technology integrations do not necessarily support all of your detection rules. We will partner with you to evaluate all detection rules and inform you on how much we can support them based on the following criteria:

* **Fidelity** - the detection rule should have an alert volume that suggests high fidelity (for example, an average weekly alert volume less than 3 suggests the rule has high fidelity)
* **Redundancy** - the detection rule name, description, and query should not duplicate (or suggest a duplication of) alerts that would surface through a direct API integration with a non-SIEM technology
* **Evidence** - the detection rule must provide us with an adequate number of artifacts to action upon (two or fewer artifacts suggests insufficient information for our SOC analysts)
* **Scope** - the detection rule name, description, and query must align with your service and should not be written for a different category of service

If we are unable to support your detection rule because it does not meet the criteria above, we will let you know so that you can make modifications and resubmit it to us.

### How to Submit Your Detection Rule(s) <a href="#h_01k1eeqqcj8yhaynheewq6vvwd" id="h_01k1eeqqcj8yhaynheewq6vvwd"></a>

To submit your detection rule(s), [contact Support](/support) and **be sure to include a CSV file with all details (EXACT rule name, description, query) in your request**. You may submit multiple detection rules in a single support request.

We will then review the submission and create our own custom mapping to determine how each rule should be handled. Please allow 10 to 20 business days for us to complete this process and notify you of a decision. If your detection rule did not meet our [criteria for acceptance](#h_01k1eeqqcga7gqdry9bpv6m23h), you may make changes and re-submit it to us through the same process.

{% hint style="info" %}
If you need expedited processing for a small amount of urgently needed custom detection rules, let us know in your initial request and we will do our best to meet your timelines. For OOTB rules, we may only require some scoping to verify what we cover rather than a full rule review.
{% endhint %}

## About via SIEM Connections <a href="#h_01k1eeqqcmef9jbdzkgcnaq7vx" id="h_01k1eeqqcmef9jbdzkgcnaq7vx"></a>

A direct API connection is the conventional (and more robust) way to set up your integration if it is available. But in cases where we do not yet support an API connection for the technology, or where you already have some internal SOC tuning in place for your vendor alerts, you can set up a connection via a SIEM instead. **You must use a supported SIEM to set up this type of connection, and you must also connect to a supported vendor technology.**

Visit the [Expel Integrations page](/connect-your-technology/about-integrations/expel-integrations) to see which integrations allow you to connect via a SIEM, and which SIEMs are supported.

### Considerations and Limitations <a href="#h_01k1eeqqcmrf23k78ed40p0rvd" id="h_01k1eeqqcmrf23k78ed40p0rvd"></a>

Our ability to perform follow-up or triage for your data is limited in this type of connection, as we do not have access to the full security data for the source nor do we have access to the console. This is why a direct API connection is the preferred method of integration when available—especially in cases where a vendor alert from a [supported (direct API) integration](/connect-your-technology/about-integrations/expel-integrations) is only passing through a SIEM because of a custom detection rule.

However, if the vendor alert coming into your SIEM has already been tuned by your own SOC, the SIEM alert is likely stronger than the original vendor alert. In these instances, a via SIEM connection may be preferable to a direct API connection. **But you must choose one or the other.** If you have already set up your integration as a direct API connection, you should not also create a via SIEM connection due to duplication issues.

### Ingestion and Triage Process <a href="#h_01k1eeqqcncfwmxyytjjjgajz5" id="h_01k1eeqqcncfwmxyytjjjgajz5"></a>

[Expel Alerts](/workbench-reference/alerts/how-expel-alerts-work) are created by ingesting your SIEM alerts and also by looking at its log data. This will result in any of the following triage actions:

* Our SOC analysts triaging an Expel Alert
* Our SOC analysts storing evidence from the SIEM logs that we can use to inform future Investigations
* Our SOC analysts sending a question directly to you about an event's authorization (or lack of authorization) that is referenced in the Expel Alert

{% hint style="warning" %}
We can only ingest SIEM alerts for connected vendor technology that we [already support via a direct integration](/connect-your-technology/about-integrations/expel-integrations).
{% endhint %}

### Setup Process <a href="#h_01k1eeqqcqwebqscecnhc0f3c6" id="h_01k1eeqqcqwebqscecnhc0f3c6"></a>

Setting up a via SIEM connection requires three steps:

1. Make sure your **SIEM's data sources** are logging properly.
   * You will need to specify which logs the SIEM should ingest, where they should be stored, and any other data quality information that should be included.
   * If you need help with this step, follow your SIEM's documentation or work with your SIEM's representative.
2. Set up the **SIEM as a security device** in Workbench by locating its setup guide. <button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Find your setup guide…</button>
3. Set up a **via SIEM connection as a separate security device** in Workbench (you will find these instructions in your setup guide).

{% hint style="warning" %}
Custom detection rules cannot be used for a via SIEM connection.
{% endhint %}

## FAQs <a href="#h_01k1eeqqcsf6dragb6jjzkv3rw" id="h_01k1eeqqcsf6dragb6jjzkv3rw"></a>

**Do all SIEM integrations receive the same level of support?**

Our SIEM integrations are broken into tiers. See [MDR SIEM Tiers](/connect-your-technology/about-integrations/tiers-and-support) for more information.

**Is there a security device tuning period after setup?**

Yes, for about 48 hours. Sometimes we are not able to apply the proper tuning on our end, so we may reach out with tuning suggestions for you to apply within your SIEM. [Learn more about device tuning](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

**Who maintains a custom detection rule after it is implemented?**

Our SOC analysts may apply minor suppressions to maintain fidelity but, ultimately, you are responsible for the performance of the rule and its adherence to our criteria.

**Why might you adjust the severity of a custom detection rule?**

We make decisions about how to surface your custom detection rules according to their projected fidelity and impact. If the alert volume begins suggesting a different level of fidelity that does not align with the currently assigned severity, we will adjust it.

**Do you support Windows event logs?**

No, we no longer support this type of SIEM log.

## Find Your Setup Guide(s) <a href="#h_01k1eeqqcv1axvezh31vcnq1wj" id="h_01k1eeqqcv1axvezh31vcnq1wj"></a>

If you are ready to get started, use search for your technology's setup guide.

<button type="button" class="button primary" data-action="search" data-icon="magnifying-glass">Find your setup guide…</button>


# MDR SIEM Tiers

Tiers specify what we can ingest for each integration, whether or not custom rules are leveraged, and which resulting Expel actions are supported.

{% hint style="warning" %}
MDR SIEM tiers only apply to SIEM-based technology and not to integrations that use a via SIEM connection.
{% endhint %}

## Advanced (Tier 1)

{% hint style="info" icon="money-bills" %}
Plan Options: Premium, Premium Pro
{% endhint %}

For Advanced (Tier 1) SIEMs, we may leverage either out-of-the-box (OOTB) or custom rules to map the SIEM alerts to our own ingestion criteria. We also use the SIEM for investigation telemetry.

**This tier includes:**

* Support for OOTB vendor detection rules (queried via API), and post Expel rule review to determine level of support per rule (e.g. full support, partial support, index as evidence).
* Support for custom detection rules (queried via API), and post Expel rule review to determine level of support per rule (e.g. full support, partial support, index as evidence).&#x20;
* 50 custom rules reviewed per contract year.
* Triage of all generated alerts to the appropriate support level based on Expel rule reviews.

**Advanced (Tier 1) SIEM integrations:**

* CrowdStrike Falcon NextGen SIEM
* Google Security Operations (SecOps)
* Microsoft Sentinel&#x20;
* Palo Alto Networks Cortex XSIAM
* Splunk - Enterprise Security (Splunk ES)
* Splunk - Core (Splunk Core)
* Sumo Logic Cloud SIEM (CSE)

## Essentials (Tier 2)

{% hint style="info" icon="money-bills" %}
Plan Options: Select, Premium, Premium Pro
{% endhint %}

For Essential (Tier 2) SIEMs, we leverage your SIEM's out-of-the-box (OOTB) rules to map the SIEM alerts to our own ingestion criteria, but we do not support any custom rules you may have in place. We also use the SIEM for investigation telemetry.

**This tier includes:**

* Support for OOTB vendor detection rules (queried via API), and post Expel rule review to determine level of support per rule (e.g. full support, partial support, index as evidence).
* Triage of all generated alerts to the appropriate support level based on Expel rule reviews.

**Essentials (Tier 2) SIEM integrations:**

* Datadog Observability & Analytics Platform
* Elastic Security (SIEM)
* Exabeam Fusion SIEM
* Exabeam Fusion XDR
* Exabeam Threat Center
* Hunters SOC Platform
* Palo Alto Strata
* Panther Cloud SIEM
* QRadar
* SentinelOne Singularity Data Lake

## Investigative Only (Tier 3)

{% hint style="info" icon="money-bills" %}
Plan Options: Starter, Select, Premium, Premium Pro
{% endhint %}

For Investigative Only (Tier 3) SIEMS, no alerts from the SIEM are mapped to Expel Alerts, but the SIEM's data can still be used by us for investigation telemetry. We strongly recommend you set up Tier 3 SIEMs in Workbench to increase the available investigative support.

**This tier includes:**

* APIs for [Investigative Actions](/workbench-reference/expel-terminology#investigative-action).
* Using the data as an investigative source.

**Investigative Only (Tier 3) SIEM integrations:**

* Devo
* LogRhythm
* Logz.io
* Securonix Next-Gen SIEM
* Sumo Logic Cloud Infrastructure Security


# About MDR for Email

MDR for Email provides 24/7 SOC coverage of the alerts generated by your email security tools.

## Scope and Limitations <a href="#h_01jrjp0rrked0rny1phj7wwb44" id="h_01jrjp0rrked0rny1phj7wwb44"></a>

* The service can be used with any email provider, however if you have an email provider *other than* Google Workspace or Microsoft 365, certain actions like message trace, search for other recipients, and auto remediation will not be available.

## MDR for Email vs Managed Phishing <a href="#h_01jrjp0rrk93nbz4zpm62bheht" id="h_01jrjp0rrk93nbz4zpm62bheht"></a>

Both of these services are intended to protect you against phishing emails, however the method and scope of ingestion differs.

* **MDR for Email** monitors your existing email security tools and ingests their alerts (we do not ingest the email itself). This service is powered by automatic monitoring of alerts via a Workbench integration to one of the [supported email security tools](#h_01jrjp0rrksnyqz3skccjvv8kd).
* [**Managed Phishing** ](/more-features/expel-managed-phishing)monitors user submissions of suspected phishing emails and ingests the entire email text, attachments, full metadata, .eml files, etc. This service is powered by human submissions of suspected phishing emails (via a submission button that we add to your email program, or by forwarding the email to us).

You may use both services simultaneously to create comprehensive MDR coverage within Workbench for your email monitoring.

## Investigation and Remediation Process <a href="#h_01jrjp0rrk2xrrnyxsr7a34244" id="h_01jrjp0rrk2xrrnyxsr7a34244"></a>

MDR for Email focuses on *the data included in the alerts* coming from your email security tools. Therefore we only ingest objects like sender, file name, file hash, subject, message size, reply-to address, URLs, recipient actions, etc. We do *not* review the full email text, examine the .eml files, or retrieve any files that may have been included in the original email (this level of ingestion is part of Managed Phishing).

### Ingestion and Triage <a href="#h_01jrjp0rrkrfxpmqvyda2mw6w2" id="h_01jrjp0rrkrfxpmqvyda2mw6w2"></a>

When an alert is generated by your email security tool, we ingest it and then process it according to our [detection strategy](#h_01jrjp0rrk2a4jqm6f2hme5vda). For suspected phishing attempts that may present a security issue, Ruxie creates an [Expel Alert](/workbench-reference/alerts/how-expel-alerts-work) so that our SOC Analysts can determine whether or not they need to open an Investigation.

{% hint style="info" %}
You can look for information about your ingested email security alerts on any of the following Workbench pages: [Service Review dashboard](https://workbench.expel.io/dashboards/service-review), [Alert Analysis dashboard](https://workbench.expel.io/dashboards/alert-analysis), [Security Devices page](https://workbench.expel.io/settings/security-devices), or [Situation Report dashboard](https://workbench.expel.io/dashboards/situation-report).
{% endhint %}

### Investigation <a href="#h_01jrjp0rrk6gakz26cbcz105hr" id="h_01jrjp0rrk6gakz26cbcz105hr"></a>

The MDR for Email Investigation seeks answers to the following questions:

* Is the URL valid?
* Has anyone or any system at the organization accessed the URL?
* What can we discern about the sender domain, including its age and any historical virus information?
* Does the file hash contain any viruses?
* Do we have any existing information about the sender from prior incidents?
* Has anyone else at the organization received the same email?
* Is the file present on any other systems within the organization or any security devices?
* Have any suspicious logins occurred within the organization since the email was received?
* What can we discern about the source IP address?
* Are there any related Expel Alerts, either open or resolved?

If our SOC analysts do not believe the email associated with the alert is malicious after performing the Investigation, they will close it.

### Remediation <a href="#h_01jrjp0rrke00fk9dm80bevyg8" id="h_01jrjp0rrke00fk9dm80bevyg8"></a>

If our SOC analysts confirm during the Investigation that malicious activity is present, the Investigation is flagged as an incident. We then work with you (via [Remediation Actions](/workbench-reference/expel-terminology#remediation-action)) to remediate the phishing attempt and delete any malicious email(s), or you can automate part of this process by setting up the [Remove Malicious Email](/workbench-setup/auto-remediations/remove-malicious-email) auto remediation.

Messages that are not correlated or otherwise flagged by Expel's internal detections will appear as **TUNING**-severity alerts in Workbench with the title "**Uncorrelated Email Message Event**".

Any auto-removal actions for these alerts will be logged and tracked within an auto-generated incident named "**MDR for Email Auto-Remediation Tracking**" so that you and the SOC have one central incident to monitor all removals carried out by this automation for auditing.

## Set Up MDR for Email <a href="#h_01jrjp0rrksnyqz3skccjvv8kd" id="h_01jrjp0rrksnyqz3skccjvv8kd"></a>

If you are ready to set up your service, we currently support the following email security tools:

* [Abnormal AI for MDR Setup](/connect-your-technology/a-c-integrations/abnormal-ai-setup-for-workbench)
* [Proofpoint TAP for MDR Setup](/connect-your-technology/l-p-integrations/proofpoint/proofpoint-tap-for-mdr-setup-for-workbench)
* [Sublime Security Setup for Workbench](/connect-your-technology/q-z-integrations/sublime-security-setup-for-workbench)

## Detection Strategy <a href="#h_01jrjp0rrk2a4jqm6f2hme5vda" id="h_01jrjp0rrk2a4jqm6f2hme5vda"></a>

Learn more in the MDR for Email Detection Strategy guides.

* [Abnormal AI Detection Strategy Guide](/detection-strategy-guides/a-c/abnormal-ai-detection-strategy)
* [Proofpoint TAP Detection Strategy Guide](/detection-strategy-guides/n-q/proofpoint/proofpoint-tap-detection-strategy)
* [Sublime Security Detection Strategy Guide](/detection-strategy-guides/s-z/sublime-security-detection-strategy)


# Creating Test Alerts

After you successfully connect to a cloud environment, you can create a test alert to confirm it is working and learn more about how Expel responds to incidents.

To do this, you'll take a simple action in your cloud environment. Then, follow the instructions below for your Cloud integration, and receive an email from Expel that shows you what we would do if it were a real incident.

{% tabs %}
{% tab title="Google Cloud Platform (GCP)" %}
Create a temporary Google Cloud Platform (GCP) project and we'll produce an incident as if it were malicious activity. You don’t have to put anything in the project.

There's nothing inherently malicious in creating a GCP project; this is just an easy way to simulate how Expel responds to actual malicious events.

To create a test alert:

1. Go to the [GCP Cloud Resource Manager](https://console.cloud.google.com/cloud-resource-manager).
2. Select **Create Project**.
3. Give the project an ID that starts with `expeltestproject`. Project names in GCP must be globally unique, so try something like **expeltestproject-x8yf92f**, but vary the characters at the end.
4. Fill in the billing account, organization, and a location that makes sense.
5. Select **Create**.

   Within 10-15 minutes, you get an email from <soc@expel.io> with the subject line "*Findings ready for review"*.
6. Select the link in that notification to see the findings report.

{% hint style="info" %}
You can shut down the project immediately after creating it.
{% endhint %}
{% endtab %}

{% tab title="Microsoft Azure" %}
Create an Azure Automation Account named `expeltestautomation`, and we'll produce an incident as if this were malicious activity. You don’t have to do anything in the automation account.

There's nothing inherently malicious in creating an automation account; this is just an easy way to simulate how Expel responds to actual malicious events.

To create a test alert:

1. Log in to the [Azure portal](https://portal.azure.com/).
2. From the top menu, select **+ Create a resource**.
3. Under Categories, select **IT & Management Tools**, and then select **Automation**.
4. Select **Create**.
5. Select a Subscription and Resource Group.
6. Type the Automation account name `expeltestautomation`.
7. Select a Region.
8. Select **Review + Create**, then **Create**.

   Within 10-15 minutes, you get an email from <soc@expel.io> with the subject line "*Findings ready for review*".
9. Select the link in that notification to see the findings report.

{% hint style="info" %}
You can delete the automation account immediately after creating it.
{% endhint %}
{% endtab %}
{% endtabs %}


# Webhooks Setup for Workbench

The Webhook integration allows Expel to notify you about specific events via webhooks without requiring API polling. You can add destination URLs that leverage either a username and password authentication, or hash-based message authentication code (HMAC) header authentication. After you have added a webhook destination, you can then set up a variety of notifications that will send the desired data to it.

## Prerequisites

1. You must have organization admin permissions in Workbench to add webhooks and set up notifications.
2. You must have sufficient understanding of webhooks, JSON objects, and one of the available webhook authentication methods (basic or HMAC).
3. You should be able to follow Expel's best practices [(found in Step 1)](#step-1-prepare-your-receiving-server) when setting up or choosing a server to ensure the connection is secure.

## How Expel's Webhook Integration Works

Expel sends an `HTTP POST` request via a webhook to your HTTP server when an Expel event (that you specify) happens in Workbench. The HTTP request contains a payload formatted in JSON, with a maximum size of 10 MB (although in practice it will be much lower), which holds all of the data about the Workbench event. Your server must then respond with a status code to acknowledge receipt of the message so that we do not retry sending it.

Setting up a webhook in Workbench is a three-step process:

1. First, you must make sure your **HTTP server** is ready to accept the webhook request.
   * There are a few best practices for server setup that we recommend you utilize in order to secure your webhooks.
   * Your server must know where in the webhook request to find the authentication credentials and how to submit a response, whether you are managing the server yourself or using a third-party vendor.
2. Next, you will add a **webhook destination** in Workbench to allow your server to consume the `HTTP POST` requests that come from Expel.&#x20;
   * The webhook destination must be set to authenticate via one of our two available authentication methods (username and password, or HMAC header).
   * You will generate a test webhook request as part of this process, to ensure the connection is working properly.
3. Finally, you will set up a **notification** in Workbench to specify when Expel should send a webhook request to the webhook destination.
   * A notification must be created in order for any data to be sent to your webhook destination, because the notification tells Expel what to send and when to send it.
   * Some Expel events also allow you to specify one or more conditions for the notification.

{% hint style="info" %}
You may set up multiple notifications to send a variety of webhook requests to a single webhook destination, or you may create multiple webhook destinations to organize your webhook requests in that way.
{% endhint %}

### Webhook Data Model

The webhook body includes a payload that is always UTF-8-encoded JSON. Its structure will vary based on the Expel event you choose when you set up the notification, but it will embed a consistent series of representational [Expel events that are formatted using key:value pairs](/connect-your-technology/about-integrations/webhook-model-reference). It will also include an HTML header that you will use for authentication purposes.

Some examples of Expel events include:&#x20;

* Expel Alert is created (uses the Expel Alert Event data model)
* Investigation is closed (uses the Investigation Event data model)
* Remediation Action is assigned to me (uses the Remediation Action Event data model)
* Security device has a health status change (uses the Security Device Event data model)

There are nearly 50 Expel events to choose from when setting up a webhook, and 9 different data models leveraged to create the format of the JSON body.

```
{
    "rule": "investigation is created",
    "event_name": "investigation_created",
    "data": {...},
    "guid": "ab12c34d-e567-8fg9-1012-h345i67jk8lm"
}
```

* `rule` - the name of the notification that produced the webhook.
* `event_name` - the name of the event that triggered the notification; this name will always be associated with a specific Expel model, like an Investigation or an Expel Alert (see the [Webhook Model Reference](/connect-your-technology/about-integrations/webhook-model-reference) for a full breakdown of all events and models).
* `data` - the contents of the event as captured by Workbench plus any additional information or updates (the content here is based on the model).
* `guid` - the unique ID for the main object associated with the webhook.

### Failure Handling

During your initial webhook setup, Expel can share error information for failed “Test Connection” requests to help determine any issues. However, Expel cannot troubleshoot any issues with webhook processing by your receiving server or endpoint, as we do not have the visibility or ability to fix these errors. We can only address internal errors.

## Step 1: Prepare Your Receiving Server

You may process the webhook requests however you like, as long as the HTTP server uses one of the two available authorization methods.

### Implement Recommended Best Practices

When setting up an HTTP server for consuming Expel webhooks, we recommend that you do the following to secure your webhooks:

* Make sure the server always uses HTTPS, and that it has a valid signed certificate.
* Set a limit on requests per second and on request size to help prevent Denial of Service (while it is unlikely that Expel webhooks will constitute a large volume of requests, the server should be able to handle bursts of requests).
* [Configure an IP allow list](/workbench-setup/configure-an-ip-allow-list) if you wish to further limit unwanted traffic.
* Make sure your chosen authentication mechanism always verifies the contents of the Expel-Signature-256 header or Authorization header for every single webhook request, so that you can immediately dispose of any messages not sent by Expel.

### Webhook Authentication

You will need to know where to find the authorization information within the webhook request's HTTP header.

{% tabs %}
{% tab title="Basic Authentication" %}
If you choose to use basic authentication, every webhook request sent by Expel will contain the HTTP header `Authorization`, formatted as `Basic {base64 username:password}`. This header is the basic access authentication encoded username and password for validating the webhook.

Basic authorization is often used by customers who are leveraging a third-party provider for their server. Generally, the receiving system will provide a username and password for this type of authentication, and those values can be added to the username and password fields when you add a new webhook destination in Workbench.
{% endtab %}

{% tab title="HMAC Authentication" %}
If you choose to use HMAC authentication, every webhook request sent by Expel will contain the HTTP header `Expel-Signature-256`, formatted as `sha256={some hash}`. This header is a SHA-256 HMAC hex digest of the webhook payload bytes, generated using the secret key.

All webhook requests that Expel sends are encoded using UTF-8. The HMAC hex digest should be computed using the secret key and webhook payload, both encoded as UTF-8.
{% endtab %}

{% tab title="Bearer Token Authentication" %}
If you choose to use bearer token authentication, every webhook request sent by Expel will contain the HTTP header `Authorization`, formatted as `Bearer {token}`. This header carries the bearer token for validating the webhook.

Bearer token authentication is commonly used by customers whose receiving system issues API tokens rather than username and password credentials. Generally, the receiving system will generate the token, and that value can be added to the Bearer Token field when you add a new webhook destination in Workbench.

Expel sends the token exactly as you entered it, prefixed with `Bearer`. Enter only the token value itself, do not include the word "Bearer", or it will be sent twice.
{% endtab %}
{% endtabs %}

### HTTP Response

Your server must respond to the webhook `POST` request with an appropriate status code (no response body is required) whenever it receives a webhook request. The codes are as follows:

* `200` - indicates the request was successfully received by the webhook, with no retries needed from Expel.
* `406` - indicates the request was rejected by the webhook, with no retries requested from Expel.
* Any other valid `4xx` or `5xx` code - indicates a processing failure of some kind, with retries requested; Expel uses a polynomial backoff and will resend the request at the following intervals: 1 minute, 8 minutes, 27 minutes, 64 minutes, and 125 minutes.

## Step 2: Add a New Webhook Destination

You must first add a webhook destination before you can set up the notifications that will send your events and data to that destination.&#x20;

{% hint style="warning" %}
**You cannot edit the authentication information for a webhook after it has been created, or re-obtain the HMAC secret key.** If you need to make a change to your authentication or if you have lost your secret key, you should delete the webhook and start over by adding a new one.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Settings > Organization Settings**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. On the My Organizations page, select the **Integrations** tab.
4. Scroll to the Webhooks section and select the **Add a webhook destination** link.
5. Complete the fields as follows:
   * **Webhook destination name** - enter a name that might help you identify this webhook destination.
   * **Webhook destination URL** - enter the destination URL, making sure to start with `https://`.
   * **Webhook auth type** - select **Basic Auth** to use a username and password, **HMAC Header** to use HMAC authentication, or **Bearer Token** to use a bearer token.
6. Do one of the following:
   * If you chose basic auth: enter the **username** and **password**.
   * If you chose HMAC: **copy your secret key** and save it to a secure location. You will need it for HMAC header comparison.
   * If you chose Bearer Token: enter the **token value**.
7. Select **Add**.
8. Select **Test connection**.
9. Look for a "Successfully sent" message to appear along with a timestamp.

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FJVVcNC1xLQprcr11itc9%2Funknown.png?alt=media&amp;token=7ff3d455-65e2-4fed-9791-da3be5656975" alt="An image showing the Successfully Sent message vs the Connection Failed message." width="563"><figcaption></figcaption></figure></div>

10. Do one of the following:
    * If you are using basic auth and the test is successful, you are done. Skip to [Set Up the Notification](#step-3-set-up-the-notification).&#x20;
    * If you are using HMAC and the test is successful, continue to the next step.&#x20;
    * If you are using Bearer Token and the test is successful, you are done. Skip to [Set Up the Notification](#step-3-set-up-the-notification).&#x20;
    * If the test failed, check your URL (and HMAC signature calculations, if applicable) to be sure they are correct.

{% hint style="info" %}
If you need to update your login credentials or generate a new secret key, you must delete the webhook and start the process again. Credentials and secret keys cannot be viewed or edited after saving, and secret keys cannot be regenerated for an existing webhook.
{% endhint %}

11. For HMAC authorization only:&#x20;
    * Make sure you can successfully calculate the HMAC signature by using your secret key (this process is usually done programmatically via a script) to verify that the webhook originated from Expel.
    * Remember that the HMAC hex digest should be computed using the secret and webhook payload, both encoded as UTF-8
    * Compare this result to the `Expel-Signature-256` header in the webhook request.

## Step 3: Set Up the Notification

You can now set up one or more notifications that use this webhook as a destination. See [About Notifications](/workbench-setup/notifications/about-notifications) for information about the different types of Workbench notifications that are available. In this instance, you will be setting up an *organization notification*.

1. Still in Organization Settings, select the **Notifications** tab.
2. Select **Add Notification**.
3. Complete the fields as follows:
   * **Conditions** - select an event, and then select an action; some events may also allow you to add one or more conditions.
   * **Notify via** - select the name of the webhook destination you added in [Step 2](#step-2-add-a-new-webhook-destination).
4. Select **Save** to activate the notification.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FcKPDzr9y64OQ1e9NPjc7%2Funknown.png?alt=media&amp;token=2cf3718d-37d0-4907-8eb9-e7c99524668a" alt="An image of the notification setup screen."><figcaption></figcaption></figure>

5. Repeat this process for any additional notifications you wish to set up for that webhook.&#x20;

{% hint style="info" %}
You can also add additional webhooks at any time, and then return to your notification to add the new webhook as an additional destination in the **Notify via** section.
{% endhint %}


# Webhook Model Reference

The available notification rules in Workbench Settings map to events and models that appear in the data key on the webhook payload.

For more information about events and webhook data models, see [Webhooks Setup for Workbench](/connect-your-technology/about-integrations/webhooks-setup-for-workbench).

## Events

The following table contains the mapping of rules to events, and the models used for each event.

| Event                                         | Model                                                                 | Rule Name                                   |
| --------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------- |
| `announcement_created`                        | [Announcement event](#announcement-event)                             | Announcement is created                     |
| `assembler_connected`                         | [Assembler event](#assembler-event)                                   | Assembler has a health status change        |
| `assembler_disconnected`                      | [Assembler event](#assembler-event)                                   | Assembler has a health status change        |
| `custom_rule_created`                         | [Context label event](#context-label-event)                           | Custom rule is created                      |
| `expel_alert_assigned`                        | [Expel Alert event](#expel-alert-event)                               | Expel alert is assigned to my org           |
| `expel_alert_closed`                          | [Expel Alert event](#expel-alert-event)                               | Expel alert is closed                       |
| `expel_alert_created`                         | [Expel Alert event](#expel-alert-event)                               | Expel alert is created                      |
| `expel_alert_reopened`                        | [Expel Alert event](#expel-alert-event)                               | Expel alert is reopened                     |
| `incident_assigned`                           | [Investigation event](#investigation-event)                           | Incident is assigned to my org              |
| `incident_closed`                             | [Investigation event](#investigation-event)                           | Incident is closed                          |
| `incident_created`                            | [Investigation event](#investigation-event)                           | Incident is created                         |
| `incident_downgraded`                         | [Investigative Action event](#investigative-action-event)             | Incident is downgraded                      |
| `incident_promoted`                           | <p><a href="#investigation-event">Investigation event</a></p><p> </p> | Incident is promoted                        |
| `incident_reopened`                           | [Investigation event](#investigation-event)                           | Incident is reopened                        |
| `investigation_alert_added`                   | [Expel Alert event](#expel-alert-event)                               | Investigation has an alert added            |
| `investigation_assigned`                      | [Investigation event](#investigation-event)                           | Investigation is assigned to my org         |
| `investigation_manual_remediations_completed` | [Investigation event](#investigation-event)                           | Investigation is assigned to my org         |
| `investigation_closed`                        | [Investigation event](#investigation-event)                           | Investigation is closed                     |
| `investigation_created`                       | [Investigation event](#investigation-event)                           | Investigation is created                    |
| `investigation_manual_remediations_completed` | [Investigation event](#investigation-event)                           | Investigation manual remediations completed |
| `investigative_action_manual_action`          | [Investigative Action event](#investigative-action-event)             | Investigative action has manual action      |
| `investigative_action_assigned`               | [Investigative Action event](#investigative-action-event)             | Investigative action is assigned            |
| `investigative_action_analysis_assigned`      | [Investigative Action event](#investigative-action-event)             | Investigative action is assigned to me      |
| `investigative_action_assigned`               | [Investigative Action event](#investigative-action-event)             | Investigative action is assigned to me      |
| `investigative_action_analysis_assigned`      | [Investigative Action event](#investigative-action-event)             | Investigative action is assigned to my org  |
| `investigative_action_assigned`               | [Investigative Action event](#investigative-action-event)             | Investigative action is assigned to my org  |
| `investigative_action_analysis_assigned`      | [Investigative Action event](#investigative-action-event)             | Investigative action analysis is assigned   |
| `notify_action_assigned`                      | [Investigative Action event](#investigative-action-event)             | Notify action is assigned to my org         |
| `remediation_action_assigned`                 | [Remediation Action event](#remediation-action-event)                 | Remediation action is assigned to me        |
| `remediation_action_automation_failed`        | [Remediation Action asset event](#remediation-action-asset-event)     | Remediation action is assigned to me        |
| `remediation_action_assigned`                 | [Remediation Action event](#remediation-action-event)                 | Remediation action is assigned to my org    |
| `remediation_action_automation_failed`        | [Remediation Action asset event](#remediation-action-asset-event)     | Remediation action is assigned to my org    |
| `remediation_action_automated`                | [Remediation Action event](#remediation-action-event)                 | Remediation action is automated             |
| `security_device_first_healthy`               | [Security device event](#security-device-event)                       | Security device has a health status change  |
| `security_device_healthy`                     | [Security device event](#security-device-event)                       | Security device has a health status change  |
| `security_device_unhealthy`                   | [Security device event](#security-device-event)                       | Security device has a health status change  |
| `security_device_first_healthy`               | [Security device event](#security-device-event)                       | Security device is first healthy            |
| `verify_action_approved`                      | [Investigative Action event](#investigative-action-event)             | Verify action has outcome                   |
| `verify_action_denied`                        | [Investigative Action event](#investigative-action-event)             | Verify action has outcome                   |
| `verify_action_approved`                      | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to me             |
| `verify_action_assigned`                      | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to me             |
| `verify_action_denied`                        | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to me             |
| `verify_action_acknowledged`                  | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to my org         |
| `verify_action_approved`                      | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to my org         |
| `verify_action_assigned`                      | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to my org         |
| `verify_action_denied`                        | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to my org         |
| `verify_action_unacknowledged`                | [Investigative Action event](#investigative-action-event)             | Verify action is assigned to my org         |

## Data Models

The following tables contain key-value models for specific webhook events.

### Announcement Event

| Key               | Value                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `announcement_id` | string                                                                                                                                                                                                                                                                                                                                                                                           |
| `change_action`   | string                                                                                                                                                                                                                                                                                                                                                                                           |
| `current`         | <p>array of:</p><p></p><p>{</p><p>id: string,</p><p>created\_at: timestamp,</p><p>updated\_at: timestamp,</p><p>created\_by\_id: string,</p><p>updated\_by\_id: string,</p><p>announcement\_type: one of \[ANNOUNCEMENT\_TYPE\_HOLIDAY, </p><p>ANNOUNCEMENT\_TYPE\_THREAT\_BULLETIN, </p><p>ANNOUNCEMENT\_TYPE\_TESTING, </p><p>ANNOUNCEMENT\_TYPE\_GENERAL], </p><p>message: string</p><p>}</p> |
| `previous`        | <p>array of:<br></p><p>{</p><p>id: string,</p><p>created\_at: timestamp,</p><p>updated\_at: timestamp,</p><p>created\_by\_id: string,</p><p>updated\_by\_id: string,</p><p>announcement\_type: one of \[ANNOUNCEMENT\_TYPE\_HOLIDAY, </p><p>ANNOUNCEMENT\_TYPE\_THREAT\_BULLETIN, </p><p>ANNOUNCEMENT\_TYPE\_TESTING, </p><p>ANNOUNCEMENT\_TYPE\_GENERAL], </p><p>message: string</p><p>}</p>    |

### Assembler Event

| Key                | Value                                                                     |
| ------------------ | ------------------------------------------------------------------------- |
| `assembler_id`     | string                                                                    |
| `change_action`    | string                                                                    |
| `current`          | [Assembler](https://workbench.expel.io/api/v2/docs/#tag/assemblers)       |
| `previous`         | [Assembler](https://workbench.expel.io/api/v2/docs/#tag/assemblers)       |
| `organization`     | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations) |
| `created_by_actor` | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)               |
| `updated_by_actor` | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)               |
| `deleted_by_actor` | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)               |

### Context Label Event

| Key                     | Value                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `context_label_id`      | string                                                                                           |
| `change_action`         | string                                                                                           |
| `current`               | [ContextLabel](https://workbench.expel.io/api/v2/docs/#tag/context_labels)                       |
| `previous`              | [ContextLabel](https://workbench.expel.io/api/v2/docs/#tag/context_labels)                       |
| `organization`          | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                        |
| `context_label_actions` | array of [ContextLabelAction](https://workbench.expel.io/api/v2/docs/#tag/context_label_actions) |
| `investigations`        | array of [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)             |

### Expel Alert Event

| Key                       | Value                                                                       |
| ------------------------- | --------------------------------------------------------------------------- |
| `expel_alert_id`          | string                                                                      |
| `change_action`           | string                                                                      |
| `current`                 | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alerts)      |
| `previous`                | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alerts)      |
| `organization`            | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)   |
| `vendor`                  | [Vendor](https://workbench.expel.io/api/v2/docs/#tag/vendors)               |
| `vendor_id`               | Vendor Event ID                                                             |
| `investigation`           | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations) |
| `updated_by_user_account` | [UserAccount](https://workbench.expel.io/api/v2/docs/#tag/user_accounts)    |

### Investigation Event

| Key                               | Value                                                                                                                                                                                                                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `investigation_id`                | string                                                                                                                                                                                                                                                                                                                   |
| `change_action`                   | string                                                                                                                                                                                                                                                                                                                   |
| `current`                         | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)                                                                                                                                                                                                                                              |
| `previous`                        | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)                                                                                                                                                                                                                                              |
| `organization`                    | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                |
| `created_by_organization`         | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                |
| `update_by_organization`          | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                |
| `created_by_user_account`         | [UserAccount](https://workbench.expel.io/api/v2/docs/#tag/user_accounts)                                                                                                                                                                                                                                                 |
| `updated_by_user_account`         | [UserAccount](https://workbench.expel.io/api/v2/docs/#tag/user_accounts)                                                                                                                                                                                                                                                 |
| `lead_expel_alert`                | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alerts)                                                                                                                                                                                                                                                   |
| `investigation_findings`          | array of [InvestigationFinding](https://workbench.expel.io/api/v2/docs/#tag/investigation_findings)                                                                                                                                                                                                                      |
| `previous_assigned_to_org`        | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                |
| `current_assigned_to_org`         | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                |
| `remediation_action_asset_groups` | <p>array of:<br></p><p>{</p><p>remediation\_action:<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_actions"> RemediationAction</a>, </p><p>remediation\_action\_assets: array of<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets"> RemediationActionAsset</a></p><p>}</p> |
| `organization_resilience_actions` | array of [OrganizationResilienceAction](https://workbench.expel.io/api/v2/docs/#tag/organization_resilience_actions)                                                                                                                                                                                                     |
| `is_detect_only`                  | boolean                                                                                                                                                                                                                                                                                                                  |
| `engagement_manager`              | [EngagementManager](https://workbench.expel.io/api/v2/docs/#tag/engagement_managers)                                                                                                                                                                                                                                     |

### Investigative Action Event

| Key                                   | Value                                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `investigative_action_id`             | string                                                                                            |
| `change_action`                       | string                                                                                            |
| `current`                             | [InvestigativeAction](https://workbench.expel.io/api/v2/docs/#tag/investigative_action_histories) |
| `previous`                            | [InvestigativeAction](https://workbench.expel.io/api/v2/docs/#tag/investigative_action_histories) |
| `created_by_actor`                    | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `vendor`                              | [Vendor](https://workbench.expel.io/api/v2/docs/#tag/vendors)                                     |
| `vendor_id`                           | Vendor Event ID                                                                                   |
| `organization`                        | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                         |
| `previous_assigned_to_actor`          | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `current_assigned_to_actor`           | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `previous_analysis_assigned_to_actor` | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `current_analysis_assigned_to_actor`  | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `investigation`                       | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)                       |
| `completed_by_organization`           | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                         |
| `file`                                | [File](https://workbench.expel.io/api/v2/docs/#tag/files)                                         |
| `uploaded_by_actor`                   | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `completed_by_actor`                  | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `updated_by_actor`                    | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                       |
| `lead_expel_alert`                    | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alert_thresholds)                  |

### Remediation Action Event

| Key                                         | Value                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `remediation_action_id`                     | string                                                                                                                                                                                                                                                                                                                                 |
| `change_action`                             | string                                                                                                                                                                                                                                                                                                                                 |
| `current`                                   | [RemediationAction](https://workbench.expel.io/api/v2/docs/#tag/remediation_actions)                                                                                                                                                                                                                                                   |
| `previous`                                  | [RemediationAction](https://workbench.expel.io/api/v2/docs/#tag/remediation_actions)                                                                                                                                                                                                                                                   |
| `created_by_actor`                          | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `created_by_organization`                   | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `updated_by_actor`                          | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `updated_by_organization`                   | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `completed_by_actor`                        | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `completed_by_organization`                 | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `organization`                              | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `previous_assigned_to_actor`                | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `current_assigned_to_actor`                 | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `previous_assigned_to_org`                  | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `current_assigned_to_org`                   | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `investigation`                             | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)                                                                                                                                                                                                                                                            |
| `remediation_action_assets`                 | array of [RemediationActionAsset](https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets)                                                                                                                                                                                                                               |
| `remediation_asset_context_label_tags`      | <p>array of:<br></p><p>{</p><p>remediation\_action\_asset\_id: string,</p><p>context\_label\_tag\_descriptions: array of string</p><p>}</p>                                                                                                                                                                                            |
| `remediation_action_assets_by_device_names` | <p>array of:<br></p><p>{</p><p>\<device name 1>: array of<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets"> RemediationActionAsset</a>,</p><p>\<device name 2>: array of<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets"> RemediationActionAsset</a>,</p><p>…</p><p>}</p> |
| `lead_expel_alert`                          | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alert_thresholds)                                                                                                                                                                                                                                                       |
| `is_awaiting_checks`                        | boolean                                                                                                                                                                                                                                                                                                                                |
| `previous_is_awaiting_checks`               | boolean                                                                                                                                                                                                                                                                                                                                |

### Remediation Action Asset Event

| Key                                         | Value                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `remediation_action_asset_id`               | string                                                                                                                                                                                                                                                                                                                                 |
| `change_action`                             | string                                                                                                                                                                                                                                                                                                                                 |
| `current`                                   | [RemediationActionAsset](https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets)                                                                                                                                                                                                                                        |
| `previous`                                  | [RemediationActionAsset](https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets)                                                                                                                                                                                                                                        |
| `remediation_action`                        | [RemediationAction](https://workbench.expel.io/api/v2/docs/#tag/remediation_actions)                                                                                                                                                                                                                                                   |
| `remediation_action_assigned_to_actor`      | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `remediation_action_assigned_to_org`        | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `created_by_actor`                          | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `created_by_organization`                   | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `updated_by_actor`                          | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `updated_by_organization`                   | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `completed_by_actor`                        | [Actor](https://workbench.expel.io/api/v2/docs/#tag/actors)                                                                                                                                                                                                                                                                            |
| `completed_by_organization`                 | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `organization`                              | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)                                                                                                                                                                                                                                                              |
| `investigation`                             | [Investigation](https://workbench.expel.io/api/v2/docs/#tag/investigations)                                                                                                                                                                                                                                                            |
| `remediation_asset_context_label_tags`      | <p>array of:<br></p><p>{</p><p>remediation\_action\_asset\_id: string,</p><p>context\_label\_tag\_descriptions: array of string</p><p>}</p>                                                                                                                                                                                            |
| `remediation_action_assets`                 | array of [RemediationActionAsset](https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets)                                                                                                                                                                                                                               |
| `remediation_action_assets_by_device_names` | <p>array of:<br></p><p>{</p><p>\<device name 1>: array of<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets"> RemediationActionAsset</a>,</p><p>\<device name 2>: array of<a href="https://workbench.expel.io/api/v2/docs/#tag/remediation_action_assets"> RemediationActionAsset</a>,</p><p>…</p><p>}</p> |
| `lead_expel_alert`                          | [ExpelAlert](https://workbench.expel.io/api/v2/docs/#tag/expel_alert_thresholds)                                                                                                                                                                                                                                                       |

### Security Device Event

| Key                  | Value                                                                          |
| -------------------- | ------------------------------------------------------------------------------ |
| `security_device_id` | string                                                                         |
| `change_action`      | string                                                                         |
| `current`            | [SecurityDevice](https://workbench.expel.io/api/v2/docs/#tag/security_devices) |
| `previous`           | [SecurityDevice](https://workbench.expel.io/api/v2/docs/#tag/security_devices) |
| `organization`       | [Organization](https://workbench.expel.io/api/v2/docs/#tag/organizations)      |


# A-C Integrations


# Abnormal AI Setup for Workbench

The Abnormal AI integration allows Expel to apply our detection strategy to your Abnormal AI alerts and pull them into the Workbench queue for investigation and remediation.

## Prerequisites

1. You must have the [Organization Admin role](/workbench-setup/get-started/add-and-manage-users/user-role-rights) in Workbench to set up this integration.
2. You must have admin access in Abnormal AI to create an API token.

## Step 1: Create an Access Token

To integrate the technology with Workbench, you need to create secure credentials to the API.

{% hint style="info" %}
Abnormal AI is requiring customers to migrate **legacy** REST API tokens to a new management system. Existing tokens are marked "Legacy" and continue to work during migration, but they cannot be rotated. For legacy tokens, you can only edit the IP safelist or revoke the token. **All legacy tokens automatically expire on April 30, 2027**. To maintain uninterrupted API access, create a new token using the steps below to replace each legacy token before the expiration date.
{% endhint %}

1. [Log in to Abnormal AI](https://portal.abnormalsecurity.com/) using an account with admin access.
2. Navigate to [**Settings > Integrations**](https://portal.abnormalsecurity.com/home/settings/integrations).
3. Scroll down to the **API Token Management** section and select **Create New Token**.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FbjX6nDUtQRExoTuWBEFr%2Fabnormal_AI_create_new_token.jpg?alt=media&amp;token=4cad22db-9a77-4453-879b-294e8c88ad80" alt="Abnormal API Token Management page with Create New Token button."><figcaption></figcaption></figure></div>
4. Select **REST API** as the integration type, and select **Next**.
5. Choose a token scope depending on your environment:
   * **Tenant (Single Tenant)** - select this to isolate the integration to a single tenant.
   * **Customer (All Current and Future Tenants)** - select this if your organization manages multiple tenants under a single Abnormal account.
6. Select **Next**.
7. Select **Custom Access**, and choose the following endpoints:
   * Threats - Read Access
   * Threats - Read Sensitive Access
   * Threats - Write Access
   * Messages - Read Sensitive Access
   * Employees - Read Sensitive Access
   * Vendors - Read Sensitive Access

{% hint style="info" %}
Both **Threats Read Access** and **Threats Read Sensitive Access** are required. Read Access covers alert polling and the health check, Read Sensitive covers attachments and links. Access levels are fixed at creation, so an under-scoped token has to be recreated rather than edited. **Threats Write Access** is needed for Expel email remediation actions.
{% endhint %}

8. Select **Next**.
9. Configure the following:
   * **Token Name** - enter an Expel-identifiable name, like "Expel MDR".
   * **Description** (optional) - note that this token is for the Expel integration.
   * **Token Expiry** - we recommend 365 days, unless your organization's policy requires shorter.&#x20;
     * When a token expires, Alerts will stop being ingested. Rotating a token in the Abnormal portal invalidates the previous value immediately, so the token must be updated on the Workbench device at the same time.
     * Abnormal returns a 403 error for an expired token, so Workbench will show "credentials don't have permission to connect" rather than an "expired credential" message.
     * To prevent access interruption, you may opt to receive email notifications before your token expires. Configure the API token expiry event type in the [Abnormal Portal Notification Settings](https://abnormalsecurity.my.site.com/support/s/article/Abnormal-Portal-Notifications-Settings).
   * **IP Safelist** - add the listed IP addresses from [Configure an IP Allow List](/workbench-setup/configure-an-ip-allow-list).
10. Select **Next**.
11. Review your token information, then select **Create Token**.<br>

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FtjUS6yEq9es7rgv0AfSL%2Fabnormal_AI_review_token_config.png?alt=media&amp;token=b4b89e9b-0fc0-4f9d-a727-d81c51b712ef" alt="Abnormal Create New Token screen displays a token expiry warning, configuration information, and an option to create the token." width="294"><figcaption></figcaption></figure></div>
12. **Copy and save** the token in a safe place for use in a later step. *This token value will only be shown once.*

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FXfKt6r40t94s60jJBZ8f%2Fabnormal_new_api_token_displayed.png?alt=media&amp;token=14ba0e95-0db6-4871-87a1-100b00bb7c68" alt="Abnormal Create New Token screen displays a notice the token will only be displayed once and provides your new API token value and a way to copy it." width="563"><figcaption></figcaption></figure></div>
13. Select **Done**.

## Step 2: Add Abnormal AI as a Security Device in Workbench

Now that you have an access token, you can configure the integration in Workbench.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, type “Abnormal” and then select the **Abnormal AI** integration.
5. A configuration pane displays. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Abnormal AI”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud.” This is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Abnormal Security API endpoint URL** - enter the base URL for your environment:
     * U.S.: `https://api.abnormalplatform.com`&#x20;
     * EU: `https://eu.rest.abnormalsecurity.com`
     * FedRAMP: `https://rest.abnormalsecurity.us`
   * **Abnormal Security API authentication token** - enter the API token you saved in [Step 1](#step-1-create-an-access-token).
6. Select **Save**.
7. On the console access screen, select **No thanks, I will not provide console access** from the dropdown.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Step 3: (Optional) Set Up Auto Email Deletion <a href="#h_01jsq7m96qw55b6v8gsp1nkw6c" id="h_01jsq7m96qw55b6v8gsp1nkw6c"></a>

The first two steps of this guide enable Expel to ingest the Abnormal AI alerts and investigate any malicious activity. This optional configuration lets us use detection strategy to immediately delete any email that Abnormal AI identifies as malicious *as soon as we ingest its associated alert*.

This means those emails will be assumed as correctly flagged by Abnormal AI as malicious, and then deleted for every email user without a SOC investigation. We will instead focus all of our SOC efforts on other types of Abnormal AI alerts. However, the Abnormal AI alert that references the deleted email will still be available to our SOC analysts and can be correlated to other suspicious activity where needed.

[Learn more about how remediation works](/connect-your-technology/about-integrations/about-mdr-for-email#h_01jrjp0rrke00fk9dm80bevyg8) in this process.

{% hint style="warning" %}
You must have Microsoft 365 or Google Workspace as your email provider to use this feature.
{% endhint %}

### Step 1: Enable Permissions in Your Email Provider

1. Set up appropriate permissions within your email provider by selecting one of the links below for instructions.\
   ***If you have already enabled the Remove Malicious Email auto remediation in support of a different integration, you can skip this step (because you will have already set this part up).***
   * [Microsoft 365](/workbench-setup/auto-remediations/remove-malicious-email/microsoft-365-remove-malicious-email#step-2-add-an-additional-api-permission): Follow *only* the Step 2 section of this guide, then return to this page and continue to step 2.&#x20;
   * [Google Workspace](/workbench-setup/auto-remediations/remove-malicious-email/google-workspace-formerly-g-suite-remove-malicious-email#h_01jh5zgcgw8ekzjnfd2tzwjvat): Follow *only* the Step 1 and Step 2 sections of this guide, then return to this page and continue to step 2.&#x20;

### Step 2: Enable the Auto Remediation in Workbench

1. Contact your Customer Success Manager (CSM) and ask that they enable the **Auto-Remediate Suspicious Delivered Email Alerts** (`org.preference.email.auto_remediate_delivered`) value in Workbench.


# Akamai Guardicore Segmentation (formerly Guardicore Centra) Setup for Workbench

## Step 1: Enable Console Access for Expel <a href="#uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25687" id="uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25687"></a>

Having read-only access to the interface of your technology allows Expel to dig deeper during incident investigations. Our device health team uses this access to investigate potential health issues with your tech. For more information, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access).

1. Log in to Guardicore Segmentation Centra and navigate to **Administration > User Management > Users** and then click **+ Add User**.
2. Complete the fields as follows:
   * **Username** - type Expel.
   * **Email Address** - leave blank.
   * **Description** (optional) - leave blank or enter a description of your choice.
   * **Permission Scheme** - select **Administrator**.
   * Create a Temporary Password.
   * Do **NOT** select **Enable 2-Step Verification**.
   * Do **NOT** select **Enable user to view passwords used in security incidents**.
3. Click **Save**.
4. Log in to Guardicore Segmentation Centra using the user credentials you just created and set a **new** **Password**. Make a note of the new password for later use.

## Step 2: Add Akamai Guardicore Segmentation as a Security Device in Workbench <a href="#uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25703" id="uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25703"></a>

Now that you have the correct access configured and noted the credentials, you can integrate your tech with Workbench.

1. [Log in to Workbench](https://workbench.expel.io/settings/security-devices?setupIntegration=guardicore).
2. Fill in these fields:<br>

   * **Name** - type "Expel API Access".
   * **Location** - type the geographic location of the server (or "cloud" for cloud servers).
   * **Server** - type the server URL address.
   * **Username** - type the username you created in [Step 1](#uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25687).
   * **Password** - type the new (not temporary) password you created in [Step 1](#uuid-ae54a985-4522-7442-3bc2-c702f654e9e3_bridgehead-25687).

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F99EetWS2j9MwIftcTeB9%2FScreenshot%202026-04-14%20at%205.11.04%E2%80%AFPM.png?alt=media&amp;token=dd4cfaca-05fb-4181-994a-e0c8f7c51afe" alt="Configuration page for Akamai Guardicore Segmentation integration in Workbench." width="375"><figcaption></figcaption></figure></div>
3. Click **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).


# Amazon/AWS


# AWS CloudTrail


# Get Started with AWS CloudTrail Setup

Integrating your AWS CloudTrail service with Workbench allows Expel to gain insight into the activities that are occurring within your AWS account and to effectively monitor for suspicious events on your behalf. To onboard successfully, you will need to create or leverage a trail and then make your S3 bucket available to Expel, which will enable us to access the event logs.

## Setup Options

You have several options for onboarding. Select a link to get started:

1. [Manually configure your integration with a new trail.](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail)
2. [Manually configure your integration with a new trail using GovCloud.](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-govcloud-cloudtrail-manual-setup-new-trail)
3. [Manually configure your integration using an existing trail.](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-existing-trail)
4. [Manually configure your integration using an existing trail with ControlTower.](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-with-control-tower-existing-trail)
5. [Automatically configure your integration with our Wizard.](https://workbench.expel.io/settings/security-devices?setupIntegration=aws) You may use a new trail or an existing trail; if you are using a new trail, you may also connect via a CloudFormation template (see below for more information).&#x20;

{% hint style="warning" %}
You cannot use the wizard for GovCloud.
{% endhint %}

### About the CloudFormation Template

As an alternative to manual setup of a new trail, Expel offers a CloudFormation template to perform the necessary AWS configurations for an organization or an individual account. Using a template does not run anything on your AWS account. Instead, the template populates CloudFormation with the appropriate steps, you review those steps, and then you decide whether or not to execute them.

For organizations, the template will create a stackset to configure the permissions on each of your accounts. The stackset can also be left in place to automatically run on any new accounts you create for your organization in the future.


# AWS CloudTrail Manual Setup - New Trail

This manual setup guide is for those who do not have an existing trail available for use in their CloudTrail service.

{% hint style="info" %}
&#x20;If you would like to use the Wizard instead, see [Setup Options](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/get-started-with-aws-cloudtrail-setup).&#x20;
{% endhint %}

This guide takes you through all required manual configurations when creating a new trail in AWS, to allow Expel to access your S3 bucket securely via an API. It also shows you how to add CloudTrail as a security device in Workbench, which completes the integration and enables you to monitor all activity.

## Scope and Limitations

When choosing to set up this integration, remember the following:

* The AWS setup described here is Expel’s recommended best practice.
* There are a number of ways to customize your AWS configurations based on your own environment or protocols. These steps are intended to show the necessary settings that must be configured in order for your Expel integration to work, with basic instructions for how to do so; they do not cover most of the optional settings or explain every possible option in AWS.

## Prerequisites

1. Verify you have the necessary permissions to create and modify IAM policies and roles for your AWS account.
2. Make sure you are in the management console and that you have your AWS Account ID if you are using AWS Organizations, or are in the proper AWS account if you manage more than one account.
3. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the AWS Organizational Unit (OU) ID for the subsidiary.
   * This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.
4. Check the AWS region in the top menu bar (i.e. us-east-2, us-west-1, etc.) and make sure you are in the home region you want to be in; you must use the same home region throughout the entire AWS configuration process, and you must later specify this region correctly in Workbench.
5. Make sure you can log into Workbench successfully, and are able to see your organization settings.
   * This is a good time to copy and save your Workbench GUID, which is a unique alphanumeric value assigned by Expel to your organization and found in the My Organization page; see the [Reference](#workbench-guid) for detailed instructions.
6. Create a new file or other space to keep track of all of the names, ARNs, and other values from the AWS configuration as you go (a list of all needed values is available in [Step 2](#step-2-make-note-of-your-needed-values), and additional help is available in the [Reference](#reference)).

## Step 1: Download the CloudFormation Templates

{% file src="/files/4Gr7oiY8TGD0UPyQRArO" %}

<table><thead><tr><th width="206.0078125">Template</th><th width="252.4375">Application</th><th>Actions</th></tr></thead><tbody><tr><td>CloudFormationTemplate_Accounts.json</td><td><ul><li>For those with a single AWS account and/or those who need to update the management account</li><li>Used when deploying a stack</li></ul></td><td><ul><li>Creates Expel's IAM role (ExpelAssumeRole) in your management account</li><li>Creates the required IAM policy (ExpelAccessPolicy); you will define the SQS queue, S3 bucket, and AWS KMS key ARN</li></ul></td></tr><tr><td>CloudFormationTemplate_Orgs.json</td><td><ul><li>For those using AWS Organizations</li><li>Used when deploying a stackset</li></ul></td><td><ul><li>Creates Expel's IAM role (ExpelAssumeRole) in your children accounts; you will create this role in your management account separately</li><li>Creates the required IAM policy (ExpelAccessPolicy) for your children accounts; you will grant additional access separately</li></ul></td></tr></tbody></table>

## Step 2: Make Note of Your Needed Values

During the AWS configuration process, you will need to copy out and save a number of values as they are added by you (e.g. the AWS KMS Alias) or generated by AWS (e.g. the SQS Queue ARN). Knowing each of these values is necessary to successfully complete all AWS configuration steps and to also add AWS as a security device in Workbench.&#x20;

{% hint style="info" %}
For examples of what some of these values look like or instructions on where to find them if you forget to save one of them, refer to the [Reference](#reference) section.
{% endhint %}

These values include, in the order they are created or generated:

* Workbench GUID (if you do not have it yet, [get it now](#workbench-guid))
* AWS Account ID (AWS organizations only; [get it now](#aws-organization-specific-values))
* AWS OU ID (only if you use a single S3 bucket for multiple subsidiaries; [get it now](#aws-organization-specific-values))
* AWS Region
* S3 Bucket Name
* AWS KMS Alias
* S3 Bucket ARN
* SNS Topic ARN
* AWS KMS Key ARN
* SQS Queue ARN
* SQS URL
* IAM Role ARN
* AWS OU Role ARN (only if you use a single S3 bucket for multiple subsidiaries and you choose to create a separate IAM Role with the additional permissions)

## Step 3: Create a New Trail

In this step, you will create a new trail, new S3 bucket, and new AWS KMS key within your chosen home region.

{% hint style="info" %}
Before you begin:

* Make sure you are in the **proper AWS account** (if you manage more than one AWS account)
* Make sure you are in the **management console** (if you use AWS Organizations).&#x20;
* Make sure you are in the **home region** you wish to set for the trail (e.g. us-west-1); you will need to be in the same home region throughout this guide, and also choose the correct region in Workbench in [Step 11](#step-11-add-aws-cloudtrail-as-a-security-device-in-workbench).
  {% endhint %}

1. Use the Search bar to quickly navigate to Cloudtrail, or find it in the Services menu.
2. Select **Create trail**.
3. Enter a trail name, such as "ExpelCloudTrail".
4. AWS Organizations only - select the “Enable for all accounts in my organization” checkbox.
5. In Storage location, leave **Create new s3 bucket** selected.
   * Use the default for the **Trail log bucket and folder**, or enter a new unique name. *Remember that if you choose to create your own name, it must be unique to ALL of AWS — not just to your instance — or the trail creation will fail. You can append your desired name with the alphanumeric values from the default name to ensure uniqueness.*
   * Make a note of your **S3 bucket name**, as you will need it in a later step.
   * Leave Log file SSE-KMS encryption as **Enabled**.
   * Leave the **New** radio button selected.
   * Enter a name for AWS KMS alias.
   * Make a note of your **AWS KMS alias**, as you will need it in a later step.
6. In Additional settings:
   * Leave Log file validation as **Enabled**.
   * Leave SNS notification delivery **unchecked**.
7. Leave the CloudWatch Logs and Tags section as is, unless you need to change them for your own protocols, and do not edit the Policy document.
8. Select **Next**.
9. Leave the Choose Log Events screen as is.
10. Select **Next**.
11. You can now review your trail’s settings before creating it, if you wish.
12. Select **Create trail**.
13. You will be taken to the Trails list and should see your new trail.

## Step 4: Edit the S3 Bucket Encryption Settings

In this step, you will set your default S3 bucket encryption to server-side encryption with AWS Key Management Service keys (SSE-KMS), and instruct Amazon to use your AWS KMS key’s encryption policy for your log files instead of using SSE-S3 encryption (Amazon’s default).&#x20;

{% hint style="info" %}
You will configure the key’s policy in a later step.
{% endhint %}

1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Look for your new S3 bucket in the list and select it.
3. Select the **Properties** tab.
4. First, copy the ARN and save it to a safe place as your **S3 Bucket ARN** (you will need it for the next section). The format should look something like this: arn:aws:s3:::YourS3BucketName
5. Next, scroll to Default encryption and select **Edit**.
6. Select **Server-side encryption with AWS Key Management Service keys (SSE-KMS)**.
7. Under AWS KMS key, select **Choose from your AWS KMS keys**.
8. Select the **AWS KMS key** you created earlier (the alias will display in small print below the key).
9. Leave the Bucket Key as **Enable**.
10. Select **Save changes**.

## Step 5: Create a New SNS Topic

Now, you will create an SNS topic and edit its access policy to give the S3 bucket permission to push events to the topic. These communications will eventually be sent from the SNS topic to an SQS queue (configured in a later section).

1. Use the Search bar to quickly navigate to Simple Notification Service (SNS), or find it in the Services menu.
2. Select **Topics**.
3. Select **Create topic**.
4. In the Details section:
   * Select **Standard** as the Type.
   * Enter a **topic name** in the Name field.
5. Expand the Encryption section:
   * Toggle Encryption to **on**.
   * Use the dropdown menu to select your AWS KMS Key (or search for the alias if you do not see it).
6. Expand the Access Policy section:
   * Leave the method as **Basic**.
   * Look at the JSON preview and scroll down to the `Resource` key.&#x20;
   * Copy the `Resource` value and save it to a safe place as your **SNS Topic ARN** (you will need it to configure the new access policy). The format should look something like this: `arn:aws:sns:us-east-1:123456789012:YourTopicName`
   * Now, select the **Advanced** button to define a new access policy.
   * Highlight and delete the existing policy and paste the below policy instead.&#x20;

{% hint style="warning" %}
Make sure to use your SNS Topic ARN as the `Resource` value and your S3 Bucket ARN as the `aws:SourceARN` value.
{% endhint %}

```
{
  "Version": "2008-10-17",
  "Id": "expel-topic-policy-ID",
  "Statement": [
    {
      "Sid": "expel-statement-ID",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": [
        "SNS:Publish"
      ],
      "Resource": "YOUR_SNS_TOPIC_ARN",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
        }
      }
    }
  ]
}

```

{% hint style="warning" %}
**Important:** Did you use your SNS Topic ARN and S3 bucket ARN in the new code? Check to be sure before continuing.
{% endhint %}

7. Leave the remaining sections as is and select **Create topic**.

## Step 6: Edit the AWS KMS Key Policy

In an earlier step, you configured your S3 bucket to use your AWS KMS key for encryption. Now, you must append the key’s encryption policy to allow the S3 bucket and SNS topic to communicate securely via encryption.

1. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
2. From the Customer Managed Keys list, select your AWS KMS alias.
3. First, copy the ARN and save it to a safe place as your **AWS KMS Key ARN** (you will need it in a later step). The format should look something like this: `arn:aws:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345`
4. In the Key policy section, select **Edit** and [append](#appending-json-files) these JSON objects to the code.&#x20;

{% hint style="warning" %}
Make sure to use your S3 Bucket ARN and SNS Topic ARN as the `aws:SourceARN` values.
{% endhint %}

```
,
{ 
 "Sid": "Allow cloudtrail bucket to encrypt/decrypt",
            "Effect": "Allow",
            "Principal": {
                "Service": "s3.amazonaws.com"
            },
       "Action": [
               "kms:GenerateDataKey",
               "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
                }
            }
        },
{
    "Sid": "Allow SNS to encrypt/decrypt",
    "Effect": "Allow",
    "Principal": {
        "Service": "sns.amazonaws.com"
    },
    "Action": ["kms:GenerateDataKey", "kms:Decrypt"],
    "Resource": "*",
    "Condition": {
        "StringLike": {
            "aws:SourceArn": "YOUR_SNS_TOPIC_ARN"
        }
    }
}

```

{% hint style="warning" %}
**Important:** Did you use your S3 bucket ARN and SNS Topic ARN in the appended code? Check to be sure before continuing.
{% endhint %}

5. Select **Save changes**.

## Step 7: Create the SQS Queue

Next, you will create a dedicated SQS queue to receive messages from the SNS topic, and edit the access policy to allow the SNS topic to send messages to it. Expel will use this queue to poll for notifications of new CloudTrail data, and then will update Workbench accordingly.

1. Use the Search bar to quickly navigate to Simple Queue Service (SQS), or find it in the Services menu.&#x20;
2. Select **Create queue**.
3. In the Details section:
   * Leave **Standard** as the Type.
   * Enter a **name** in the Name field.
4. In the Configuration section:
   * Change the Message Retention period to **7 days**.&#x20;
   * Leave all other defaults.
5. In the Encryption section:
   * Leave Server-side encryption as **Enabled**.
   * Choose **AWS Key Management Service key (SSE-KMS)** as the encryption key type.&#x20;
   * Choose your AWS KMS Alias from the **Customer master key** dropdown.&#x20;
   * Leave the data key reuse period as the default.
6. In the Access policy section:
   * Select **Advanced**.
   * First, go to the Resource value and copy the ARN, then save it to a safe place as your **SQS Queue ARN** (you will need it for your new access policy).
   * Highlight and delete the existing policy and paste the below policy instead.&#x20;

{% hint style="warning" %}
Make sure to use your SQS Queue ARN as the `Resource` value and your SNS Topic ARN as the `aws:SourceARN` value.
{% endhint %}

```
{
  "Version": "2012-10-17",
  "Id": "SQSDefaultPolicy",
  "Statement": [
    {
      "Sid": "Sid1572965666162",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "SQS:SendMessage",
      "Resource": "YOUR_SQS_QUEUE_ARN",
      "Condition": {
        "StringEquals": {
          "aws:SourceArn": "YOUR_SNS_TOPIC_ARN"
        }
      }
    }
  ]
}

```

{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN and SNS Topic ARN in the new code? Check to be sure before continuing.
{% endhint %}

7. Leave the remaining sections as is and select **Create queue**.
8. Before leaving the confirmation screen, copy the URL and save it to a safe place as your **SQS URL** (you will need it in a later step).

## Step 8: Create the SNS Subscription

Now that you have the SNS topic and SQS queue, and have also edited both of their access policies to allow for communication, you need to create a subscription within the SNS topic so that the topic can send events to the queue.

1. Use the Search bar to quickly navigate to Simple Notification Service (SNS), or find it in the Services menu.&#x20;
2. Select **Subscriptions**.
3. Select **Create subscription**.
4. In the Details section:
   * Select your **SNS Topic ARN**.
   * Select **Amazon SQS** as the protocol.
   * Select your **SQS Queue ARN** as the endpoint.
   * Select the **Enable raw message delivery** checkbox.&#x20;

{% hint style="info" %}
Selecting the raw message delivery option ensures SNS does not add metadata to the events it sends to SQS, so be sure it is enabled.
{% endhint %}

5. Leave the remaining sections as is and select **Create subscription**.

## Step 9: Enable S3 Event Notifications

Now that you've fully configured the communications between the SNS topic and SQS queue, you can create an event notification. This notification will tell the S3 bucket to send certain events (you will specify which ones) to the SNS topic whenever CloudTrail adds event logs to the bucket.&#x20;

1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Select your S3 bucket.
3. Select **Properties**.
4. Go to the Event Notifications section and select **Create event notification**. Then:
   * Enter an **event name**.
   * In the Event types section, use the checkbox to enable **All object create events**. Leave the rest of the boxes unchecked.
   * In the Destination section, select **SNS topic** and then choose your SNS topic from the dropdown.
5. Select **Save changes**.

## Step 10: Set Up CloudFormation

Expel will authenticate its credentials using an IAM Role, and will be granted permissions to your AWS account(s) based on a corresponding IAM policy. You can complete this step most efficiently by using **CloudFormation** instead of doing a manual configuration via IAM.

<details>

<summary>AWS Organizations Instructions</summary>

If you use AWS Organizations, you will first create a stackset in the management account (this is where the primary Expel role resides) using our CloudFormation template. Then you will create an additional stack, with a different CloudFormation template, that is just for the management organization.

{% hint style="info" %}
Before you begin, make sure you have downloaded and unzipped the CloudFormationTemplates.zip file from Step 1. Make sure you also have your SQS Queue ARN, S3 Bucket ARN, AWS KMS Key ARN, and Workbench GUID.
{% endhint %}

#### Step 1: Create a Stackset in the Management Account

This stackset allows AWS to automatically replicate and deploy the template's IAM role and policy via stacks to all of the other accounts in your organization. The permissions in the template enable Expel to perform all necessary [Investigative Actions](/workbench-reference/expel-terminology#investigative-action), and also prevent you from having to update or redo the configuration if a new account is added to your organization.&#x20;

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **StackSets**.
3. Select **Create StackSet**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For the template:
   * Leave Permissions as **Service-managed permissions**.
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Orgs.json** template file.
5. Select **Next**.
6. Configure your stackset details:
   * Enter a **name** for your stackset.
   * Enter your **Workbench GUID**.
7. Select **Next**.
8. Leave Tags and Execution configuration as is.
9. Select **Next**.
10. For your deployment options:
    * Scroll down to **Specify regions** and choose your AWS region.
    * Leave all other defaults on this page as is.
11. Select **Next**.
12. Review your configuration if desired, and select **Submit**.

#### Step 2: Create an Additional Stack

This stack will enable additional permissions related to the SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN.

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **Stacks**.
3. Select **Create stack**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For your stack:
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Accounts.json** template file.
5. Select **Next**.
6. Configure your stack details:
   * Enter a **name** for your stack.
   * Enter your **AWS KMS Key ARN**, **S3 Bucket ARN**, **SQS Queue ARN**, and **Workbench GUID**.
7. Select **Next**.
8. Leave all defaults for stack options as is.
9. Select **Next**.
10. Review your configuration if desired, and select **Submit**.
11. Now, you must grab your **IAM Role ARN** (you will need it for a later step). First, use the Search bar to quickly navigate to IAM, or find it in the Services menu.
12. Go to **Roles**.
13. Look for **ExpelAssumeRole** and select it.
14. In the Summary section, copy the ARN and save it to a safe place as your **IAM Role ARN**.

#### Step 3: Update the IAM Role

{% hint style="info" %}
Skip this step if the situation does not apply to you.
{% endhint %}

If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.&#x20;

The two additional permissions are:

* `organizations:ListAccountsForParent`
* `organizations:ListOrganizationalUnitsForParent`

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your **AWS OU Role ARN**. You will need it when you set up the security device in Workbench.

</details>

<details>

<summary>AWS Single Account Instructions</summary>

Creating a stack with our CloudFormation template is the recommended best practice for single accounts because it is a faster configuration process that is less likely to fail due to human error. However, you may use IAM to create your policy and role manually if you wish, and skip the below steps.

{% hint style="info" %}
Before you begin, make sure you have downloaded and unzipped the CloudFormationTemplates.zip file from Step 1. Make sure you also have your SQS Queue ARN, S3 Bucket ARN, AWS KMS Key ARN, and Workbench GUID.
{% endhint %}

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **Stacks**.
3. Select **Create stack**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For your stack:
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Accounts.json** template file.
5. Select **Next**.
6. Configure your stack details:
   1. Enter a **name** for your stack.
   2. Enter your **AWS KMS Key ARN**, **S3 Bucket ARN**, **SQS Queue ARN**, and **Workbench GUID**.
7. Select **Next**.
8. Leave all defaults for stack options as is.
9. Select **Next**.
10. Review your configuration if desired, and select **Submit**.
11. Now, you must grab your **IAM Role ARN** (you will need it for the next section). First, use the Search bar to quickly navigate to IAM, or find it in the Services menu.
12. Go to **Roles**.
13. Look for **ExpelAssumeRole** and select it.
14. In the Summary section, copy the ARN and save it to a safe place as your **IAM Role ARN**.

</details>

## Step 11: Add AWS CloudTrail as a Security Device in Workbench

Now, you can add a security device in Workbench to complete the integration.&#x20;

{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN and SQS URL. If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries).&#x20;

If you need additional help finding any of these values, see the [Reference](#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, enter “AWS” and then select the AWS CloudTrail integration.
5. Select the bullets as follows:
   * “Are you using AWS organizations?” - AWS Organizations should leave it as **Yes**; single accounts should select **No**.
   * “Do you have an existing CloudTrail that you want Expel to reuse?” - select **No**.
   * “How would you like to connect?” - select **Manual connection**.
6. Select **Save**.
7. On the next screen, complete the fields as follows:&#x20;
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName CloudTrail”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud” or “AWS cloud” or “on prem;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - enter the IAM Role ARN you saved earlier. Format: `arn:aws:iam::123456789012:role/RoleName`
   * **Role session name** - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
   * **AWS region** - choose the AWS region where you created your configuration in AWS.
   * **SQS URL** - enter the SQS URL you copied and saved in a previous step.
   * **Organization management account** - If you use AWS Organizations, input your AWS Account ID; single account users can leave this field blank.
   * **AWS OU ID** - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: `ou-abc1-defghi2j`); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.
   * **AWS OU Role ARN** - if you entered an AWS OU ID, you will also need to enter the IAM Role ARN that contains the appropriate permissions. If you chose to add these permissions to your existing IAM Role in [Step 10](#step-10-set-up-cloudformation), enter the IAM Role ARN again here. If you chose to create a new IAM Role with those permissions, enter your AWS OU Role ARN. Otherwise, leave this field blank.
8. Select **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Troubleshooting

### S3 Event Notification Errors (Step 9)

This error is encountered when selecting **Save changes** in Step 9. It generally displays for one of the following reasons:

* You left one of your ARN values out of a JSON object in a prior step, put an ARN in the wrong location, or formatted an ARN incorrectly.
* The JSON objects were copied, appended, or formatted incorrectly in a prior step.
* You used an S3 bucket name that someone else in the AWS ecosystem is already using (even if nobody at your organization is using it).
* You have forgotten to enable something, or have configured something incorrectly, in one of the prior steps. Examples: Not choosing your AWS KMS key from the dropdown menu when setting up default encryption in step 4, or not using the same region throughout your AWS configuration.

### S3 Bucket Naming

You must use an S3 bucket name that nobody else in the AWS ecosystem is using. You can avoid this problem by using the default name, or by appending your chosen name with the numerical values from the default name that is generated.

### Appending JSON Files

Make sure to put this JSON snippet in the correct place, using a comma, and make sure the final bracket is still there. Lines 78-133 of your JSON code should look like this (the appended part is highlighted, beginning with the `,`):

<pre><code>  {
            "Sid": "Enable cross account log decryption",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": [
                "kms:Decrypt",
                "kms:ReEncryptFrom"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "kms:CallerAccount": "484330702365"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws:cloudtrail:*:484330702365:trail/*"
                }
            }
<strong>        },
</strong><strong>        {
</strong><strong>            "Sid": "Allow cloudtrail bucket to encrypt/decrypt",
</strong><strong>            "Effect": "Allow",
</strong><strong>            "Principal": {
</strong><strong>                "Service": "s3.amazonaws.com"
</strong><strong>            },
</strong><strong>            "Action": [
</strong><strong>                "kms:GenerateDataKey",
</strong><strong>                "kms:Decrypt"
</strong><strong>            ],
</strong><strong>            "Resource": "*",
</strong><strong>            "Condition": {
</strong><strong>                "StringLike": {
</strong><strong>                    "aws:SourceArn": "arn:aws:s3:::S3BucketName"
</strong><strong>                }
</strong><strong>            }
</strong><strong>        },
</strong><strong>        {
</strong><strong>            "Sid": "Allow SNS to encrypt/decrypt",
</strong><strong>            "Effect": "Allow",
</strong><strong>            "Principal": {
</strong><strong>                "Service": "sns.amazonaws.com"
</strong><strong>            },
</strong><strong>            "Action": [
</strong><strong>                "kms:GenerateDataKey",
</strong><strong>                "kms:Decrypt"
</strong><strong>            ],
</strong><strong>            "Resource": "*",
</strong><strong>            "Condition": {
</strong><strong>                "StringLike": {
</strong><strong>                    "aws:SourceArn": "arn:aws:sns:us-east-1:123456789012:SNSTopicName"
</strong><strong>                }
</strong><strong>            }
</strong><strong>        }
</strong>    ]
</code></pre>

## Reference

### ARNs and URLs

This chart gives examples of ARNs and the SQS URL so you can check on the general formatting, and also tells you where to find any of the values if you’ve forgotten to copy and save them during the configuration process.&#x20;

<table><thead><tr><th width="186.234375">Value</th><th width="257.48046875">Where to Find</th><th>Example</th></tr></thead><tbody><tr><td>S3 Bucket ARN</td><td>S3 > Buckets > bucket name > Properties</td><td>arn:aws:s3:::MyS3BucketARN</td></tr><tr><td>SNS Topic ARN</td><td>Simple Notification Service > Topics > topic name > Details section</td><td>arn:aws:sns:us-east-1:123456789012:MyTopicName</td></tr><tr><td>AWS KMS Key ARN</td><td>Key Management Service > key alias > General configuration section</td><td>arn:aws:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345</td></tr><tr><td>SQS Queue ARN</td><td>Simple Queue Service > queue name > Details section</td><td>arn:aws:sqs:us-east-1:123456789012:MySQSQueueName</td></tr><tr><td>SQS URL</td><td>Simple Queue Service > queue name > Details section</td><td>https://sqs.us-west-1.amazonaws.com/123456789012/MySQSQueueName</td></tr><tr><td>IAM Role ARN</td><td>IAM > Access Management > Roles > role name > Summary section</td><td><p>arn:aws:iam::123456789012:role/RoleName</p><p><br></p><p>(most users will look for the ExpelAssumeRole)</p></td></tr></tbody></table>

### AWS Organization-Specific Values

This chart helps you locate the additional values you need if you are using AWS Organizations. The OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries.

<table><thead><tr><th width="186.40234375">Value</th><th width="257.33203125">Where to Find</th><th>Example</th></tr></thead><tbody><tr><td>AWS Account ID</td><td>AWS Organizations Console, upper right of screen</td><td>1234-5678-9012</td></tr><tr><td>AWS OU ID</td><td><a href="https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_ous.html">AWS Organizations Console</a></td><td><p>ou-abc1-defghi2j</p><p>(format is ou-rootid-ouid and this entire value should be entered into the Workbench security device)</p></td></tr></tbody></table>

### Workbench GUID

The Workbench GUID is a unique alphanumeric value assigned by Expel to your organization.

**Format**

`a123b456-7c89-0def-g1hi-2j3k45l6mn7o`

**Where to Find**

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Go to **Organization Settings > My Organization**.
3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.

{% hint style="info" %}
If you have multiple organizations, you must first select the organization name that will be associated with your integration to access the page with the Copy button. Or, you can stay on the page and highlight then copy the GUID shown for that organization in the GUID column.
{% endhint %}


# AWS CloudTrail Manual Setup - Existing Trail

This manual setup guide is for those who have an existing trail available for use in their CloudTrail service.

{% hint style="info" %}
If you would like to use the Wizard instead, see [Setup Options](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/get-started-with-aws-cloudtrail-setup).
{% endhint %}

This guide takes you through required manual configurations to allow Expel to access your S3 bucket securely via an API. It also shows you how to add CloudTrail as a security device in Workbench, which completes the integration and enables you to monitor all activity.

## Scope and Limitations

When choosing to set up this integration, remember the following:

* For those using AWS Organizations, this guide assumes your SNS Topic, SQS Queue and KMS Key encrypting SNS are stored in the same account as your S3 bucket. It also assumes you have encrypted both your CloudTrail and S3 bucket with KMS (Key Management Service). See the [Reference](#reference) for more information.
* The AWS setup described here is Expel’s recommended best practice.
* There are a number of ways to customize your AWS configurations based on your own environment or protocols. These steps are intended to show the necessary settings that must be configured in order for your Expel integration to work, with basic instructions for how to do so; they do not cover most of the optional settings or explain every possible option in AWS.

## Prerequisites

1. You must already have an existing trail that is configured to send CloudTrail events to an S3 bucket.
2. Verify you have the necessary permissions to create and modify IAM policies and roles for your AWS account.
3. Make sure you are in the management console and that you have your [AWS Account ID](#aws-organization-specific-values) if you are using AWS Organizations, or are in the proper AWS account if you manage more than one account.
4. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the [AWS Organizational Unit (OU) ID](#aws-organization-specific-values) for the subsidiary.
   * This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.
5. Check the AWS region in the top menu bar (i.e. us-east-2, us-west-1, etc.) and make sure you are in the home region you want to be in; you must use the same home region throughout the entire AWS configuration process, and you must later specify this region correctly in Workbench.
6. Make sure you can log into Workbench successfully, and are able to see your organization settings.
7. Note: This is a good time to copy and save your Workbench GUID, which is a unique alphanumeric value assigned by Expel to your organization and found in the My Organization page; see the [Reference](#workbench-guid) for detailed instructions.
8. Create a new file or other space to keep track of all of the names, ARNs, and other values from the AWS configuration as you go (a list of all needed values is available in [Step 2](#step-2-make-note-of-your-needed-values), and additional help is available in the [Reference](#reference)).

## Step 1: Download the CloudFormation Templates

{% file src="/files/4Gr7oiY8TGD0UPyQRArO" %}

<table><thead><tr><th width="173.140625">Template</th><th width="258.26171875">Application</th><th>Actions</th></tr></thead><tbody><tr><td>CloudFormationTemplate_Accounts.json</td><td><ul><li>For those with a single AWS account and/or those who need to update the management account</li><li>Used when deploying a stack</li></ul></td><td><ul><li>Creates Expel's IAM role (ExpelAssumeRole) in your management account</li><li>Creates the required IAM policy (ExpelAccessPolicy); you will define the SQS queue, S3 bucket, and AWS KMS key ARN</li></ul></td></tr><tr><td>CloudFormationTemplate_Orgs.json</td><td><ul><li>For those using AWS Organizations</li><li>Used when deploying a stackset</li></ul></td><td><ul><li>Creates Expel's IAM role (ExpelAssumeRole) in your children accounts; you will create this role in your management account separately</li><li>Creates the required IAM policy (ExpelAccessPolicy) for your children accounts; you will grant additional access separately</li></ul></td></tr></tbody></table>

## Step 2: Make Note of Your Needed Values

During the AWS configuration process, you will need to copy out and save a number of values as they are added by you (e.g. the AWS KMS Alias) or generated by AWS (e.g. the SQS Queue ARN). Knowing each of these values is necessary to successfully complete all AWS configuration steps and to also add AWS as a security device in Workbench.

{% hint style="info" %}
For examples of what some of these values look like or instructions on where to find them if you forget to save one of them, refer to the [Reference](#reference) section.
{% endhint %}

Values you should have already:

* Workbench Unique ID (if you do not have it yet, [get it now](#workbench-guid))
* AWS Account ID (AWS organizations only; [get it now](#aws-organization-specific-values))
* AWS OU ID (only if you use a single S3 bucket for multiple subsidiaries; [get it now](#aws-organization-specific-values))
* AWS Region
* S3 bucket ARN
* S3 Bucket KMS Key ARN (KMS ARN of the key set as default encryption of your S3 bucket)
* CloudTrail KMS Key ARN (KMS ARN of the key Cloudtrail uses to encrypt logs that are sent to S3 bucket)

Values you will acquire as you follow this guide:

* SNS SQS KMS Key ARN
* SNS Topic ARN
* SQS Queue ARN
* SQS URL
* S3 bucket account IAM Role ARN
* AWS OU Role ARN (only if you use a single S3 bucket for multiple subsidiaries and you choose to create a separate IAM Role with the additional permissions)

## Step 3: Create a New KMS Key

First you will create a KMS key to use to encrypt our SNS Topic and SQS queue.&#x20;

{% hint style="warning" %}
Create this key in the same account as the S3 bucket account.
{% endhint %}

1. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
2. Select **Create key**.
3. Leave the Configure key page as is and select **Next**.
4. Enter an **alias** or **display name** for the key.
5. Select **Next**.
6. Leave the Define key administrative permissions page as is and select **Next**.
7. Leave the Define key usage permissions page as is and select **Next**.
8. Review your configuration if desired.
9. Select **Finish**.
10. In the key list, select the key you just made.&#x20;
11. Copy the ARN and save it to a safe place as your **SNS SQS KMS Key ARN**.

## Step 4: Create a New SNS Topic

{% hint style="warning" %}
If you have already configured Amazon Simple Notification Service (SNS) as an event notifier for your existing CloudTrail bucket that includes the event type `All object create events`, skip to [Step 5](#step-5-edit-the-sns-sqs-kms-key-policy).&#x20;
{% endhint %}

In this step, you will create an SNS topic and edit its access policy to give the S3 bucket permission to push events to the topic. These communications will eventually be sent from the SNS topic to an SQS queue (configured in a later section).

1. Use the Search bar to quickly navigate to Simple Notification Service (SNS), or find it in the Services menu.
2. Select **Topics**.
3. Select **Create topic**.
4. In the Details section, select **Standard** as the Type.
5. Enter a **topic name** in the Name field.
6. Expand the Encryption section:
   * Toggle Encryption to **on**.
   * Use the dropdown menu to select the **SNS SQS KMS key** you created in [Step 3](#step-3-create-a-new-kms-key).
7. Expand the Access policy section:
   * Leave the method as **Basic**.
   * Look at the JSON preview and scroll down to the `Resource` key.
   * Copy the `Resource` value and save it to a safe place as your **SNS Topic ARN** (you will need it to configure the new access policy). The format should look something like this: `arn:aws:sns:us-east-1:123456789012:YourTopicName`
   * Next, select **Advanced** to define a new access policy.
   * Highlight and delete the existing policy and paste the below policy instead.

{% hint style="warning" %}
Make sure to use your SNS Topic ARN as the `Resource` value and your S3 bucket ARN as the `aws:SourceARN` value.
{% endhint %}

```
{
  "Version": "2008-10-17",
  "Id": "expel-topic-policy-ID",
  "Statement": [
    {
      "Sid": "expel-statement-ID",
      "Effect": "Allow",
      "Principal": {
        "Service": "s3.amazonaws.com"
      },
      "Action": [
        "SNS:Publish"
      ],
      "Resource": "YOUR_SNS_TOPIC_ARN",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
        }
      }
    }
  ]
}
```

{% hint style="warning" %}
**Important:** Did you use your SNS Topic ARN and S3 bucket ARN in the new code? Check to be sure before continuing.
{% endhint %}

8. Leave the remaining sections as is and select **Create topic**.&#x20;

## Step 5: Edit the SNS SQS KMS Key Policy

Next, you need to edit the SNS SQS KMS key policy to include proper permissions for the SNS topic and S3 bucket.

1. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
2. Select the key you created in [Step 3](#step-3-create-a-new-kms-key).
3. Under Key policy, select **Switch to policy view**.
4. Select **Edit**.
5. Append the following JSON snippet into the existing policy.&#x20;

{% hint style="warning" %}
Make sure to use your S3 bucket ARN and SNS Topic ARN where specified. If you need help appending your policy, go to the [Troubleshooting](#appending-json-code) section.
{% endhint %}

```
 ,
        {
            "Sid": "Allow cloudtrail bucket to encrypt/decrypt",
            "Effect": "Allow",
            "Principal": {
                "Service": "s3.amazonaws.com"
            },
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnLike": {
                    "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
                }
            }
        },
        {
            "Sid": "Allow SNS to encrypt/decrypt",
            "Effect": "Allow",
            "Principal": {
                "Service": "sns.amazonaws.com"
            },
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "ArnLike": {
                    "aws:SourceArn": "YOUR_SNS_TOPIC_ARN"
                }
            }
        }
```

{% hint style="warning" %}
**Important:** Did you use your S3 bucket ARN and SNS Topic ARN in the code? Check to be sure before continuing.
{% endhint %}

6. Select **Save changes**.

## Step 6: Create the SQS Queue

Next, you will create a dedicated SQS queue to receive messages from the SNS topic, and edit the access policy to allow the SNS topic to send messages to it. Expel will use this queue to poll for notifications of new CloudTrail data, and then will update Workbench accordingly.

1. Use the Search bar to quickly navigate to Simple Queue Service (SQS), or find it in the Services menu.
2. Select **Queues**.
3. Select **Create queue**.
4. In the Details section, select **Standard** as the type.
5. Enter a **name** in the Name field.
6. In the Configuration section:
   * Change the Message Retention period to **7 days**.
   * Leave all other defaults.
7. In the Encryption section:
   * Leave Server-side encryption as **Enabled**.
   * Choose **AWS Key Management Service key (SSE-KMS)** as the encryption key type.
   * Choose the **SNS SQS KMS key** you created in [Step 3](#step-3-create-a-new-kms-key).
   * Leave the data key reuse period as is.
8. In the Access policy section:
   * Select **Advanced**.
   * First, go to the Resource value and copy the ARN, then save it to a safe place as your **SQS Queue ARN** (you will need it for your new access policy).
   * Highlight and delete the existing policy and paste the below policy instead.&#x20;

{% hint style="warning" %}
Make sure to use your SQS Queue ARN as the `Resource` value and your SNS Topic ARN as the `aws:SourceARN` value.
{% endhint %}

```
{
  "Version": "2012-10-17",
  "Id": "SQSDefaultPolicy",
  "Statement": [
    {
      "Sid": "Sid1572965666162",
      "Effect": "Allow",
      "Principal": {
        "Service": "sns.amazonaws.com"
      },
      "Action": "SQS:SendMessage",
      "Resource": "YOUR_SQS_QUEUE_ARN",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "YOUR_SNS_TOPIC_ARN"
        }
      }
    }
  ]
}

```

{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN and SNS Topic ARN in the new code? Check to be sure before continuing.
{% endhint %}

9. Leave the remaining sections as is and select **Create Queue**.
10. Before leaving the confirmation screen, copy the URL and save it to a safe place as your **SQS URL** (you will need it in a later step).

## Step 7: Create the SNS Subscription

Now that you have an SNS topic and SQS queue, and have also edited both of their access policies to allow for communication, you need to create a new subscription within the SNS topic so that the topic can send events to the queue.

1. Use the Search bar to quickly navigate to Simple Notification Service (SNS), or find it in the Services menu.
2. Select **Subscriptions**.
3. Select **Create subscription**.
4. In the Details section, complete the fields as follows:
   * **Topic ARN** - Select the Topic ARN you obtained in [Step 4](#step-4-create-a-new-sns-topic).
   * **Protocol** - Amazon SQS.
   * **Endpoint** - Select your SQS Queue ARN.
   * Select **Enable raw message delivery**.&#x20;

{% hint style="info" %}
Selecting the raw message delivery option ensures SNS does not add metadata to the notifications it sends to SQS, so be sure this is enabled.
{% endhint %}

5. Leave the remaining sections as is and select **Create subscription**.

## Step 8: Enable S3 Event Notifications

{% hint style="warning" %}
If you have already configured Amazon Simple Notification Service (SNS) as an event notifier for your existing CloudTrail bucket that includes the event type `All object create events`, skip to [Step 9](#step-9-set-up-cloudformation).&#x20;
{% endhint %}

Now that you have fully configured the communications between the SNS topic and SQS queue, you can create an event notification. This notification will tell the S3 bucket to send certain events (you will specify which ones) to the SNS topic whenever CloudTrail adds event logs to the bucket.

1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Select your S3 bucket.
3. Select **Properties**.
4. Go to the Event Notifications section and select **Create event notification**. Then:
   * Enter a **name**.
   * In the Event types section, use the checkbox to enable **All object create events**. Leave the rest of the boxes unchecked.
   * In the Destination section, select **SNS topic** and choose your SNS topic from the dropdown.
5. Select **Save changes**.

## Step 9: Set Up CloudFormation

Expel will authenticate its credentials using an IAM Role and will be granted permissions to your AWS account(s) based on a corresponding IAM policy. You can complete this step most efficiently by using CloudFormation instead of doing a manual configuration via IAM.

<details>

<summary>AWS Single Account Instructions</summary>

Creating a stack with our CloudFormation template is the recommended best practice for single accounts because it is a faster configuration process that is less likely to fail due to human error. However, you may use IAM to create your policy and role manually if you wish, and skip the below steps.

{% hint style="info" %}
Before you begin, make sure you have downloaded and unzipped the CloudFormationTemplates.zip file from Step 1. Make sure you also have your SQS Queue ARN, S3 Bucket ARN, AWS KMS Key ARN, and Workbench GUID.
{% endhint %}

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **Stacks**.
3. Select **Create stack**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For your stack:
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Accounts.json** template file.
5. Select **Next**.
6. Configure your stack details:
   1. Enter a **name** for your stack.
   2. Enter your **AWS KMS Key ARN**, **S3 Bucket ARN**, **SQS Queue ARN**, and **Workbench GUID**.
7. Select **Next**.
8. Leave all defaults for stack options as is.
9. Select **Next**.
10. Review your configuration if desired, and select **Submit**.
11. Now, you must grab your **IAM Role ARN** (you will need it for the next section). First, use the Search bar to quickly navigate to IAM, or find it in the Services menu.
12. Go to **Roles**.
13. Look for **ExpelAssumeRole** and select it.
14. In the Summary section, copy the ARN and save it to a safe place as your **IAM Role ARN**.

</details>

<details>

<summary>AWS Organization Instructions (Trail + S3 Bucket in Same Account)</summary>

If you use AWS Organizations, you will first create a stackset in the management account (this is where the primary Expel role resides) using our CloudFormation template. Then you will create an additional stack, with a different CloudFormation template, that is just for the management organization.

{% hint style="info" %}
Before you begin, make sure you have downloaded and unzipped the CloudFormationTemplates.zip file from Step 1. Make sure you also have your SQS Queue ARN, S3 Bucket ARN, AWS KMS Key ARN, and Workbench GUID.
{% endhint %}

#### Step 1: Create a Stackset in the Management Account

This stackset allows AWS to automatically replicate and deploy the template's IAM role and policy via stacks to all of the other accounts in your organization. The permissions in the template enable Expel to perform all necessary [Investigative Actions](/workbench-reference/expel-terminology#investigative-action), and also prevent you from having to update or redo the configuration if a new account is added to your organization.&#x20;

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **StackSets**.
3. Select **Create StackSet**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For the template:
   * Leave Permissions as **Service-managed permissions**.
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Orgs.json** template file.
5. Select **Next**.
6. Configure your stackset details:
   * Enter a **name** for your stackset.
   * Enter your **Workbench GUID**.
7. Select **Next**.
8. Leave Tags and Execution configuration as is.
9. Select **Next**.
10. For your deployment options:
    * Scroll down to **Specify regions** and choose your AWS region.
    * Leave all other defaults on this page as is.
11. Select **Next**.
12. Review your configuration if desired, and select **Submit**.

#### Step 2: Create an Additional Stack

This stack will enable additional permissions related to the SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN.

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **Stacks**.
3. Select **Create stack**.&#x20;

{% hint style="info" %}
If you see a dropdown menu, choose the "With new resources" option.
{% endhint %}

4. For your stack:
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Accounts.json** template file.
5. Select **Next**.
6. Configure your stack details:
   * Enter a **name** for your stack.
   * Enter your **AWS KMS Key ARN**, **S3 Bucket ARN**, **SQS Queue ARN**, and **Workbench GUID**.
7. Select **Next**.
8. Leave all defaults for stack options as is.
9. Select **Next**.
10. Review your configuration if desired, and select **Submit**.
11. Now, you must grab your **IAM Role ARN** (you will need it for a later step). First, use the Search bar to quickly navigate to IAM, or find it in the Services menu.
12. Go to **Roles**.
13. Look for **ExpelAssumeRole** and select it.
14. In the Summary section, copy the ARN and save it to a safe place as your **IAM Role ARN**.

#### Step 3: Update the IAM Role

{% hint style="info" %}
Skip this step if the situation does not apply to you.
{% endhint %}

If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.&#x20;

The two additional permissions are:

* `organizations:ListAccountsForParent`
* `organizations:ListOrganizationalUnitsForParent`

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your **AWS OU Role ARN**. You will need it when you set up the security device in Workbench.

</details>

<details>

<summary>AWS Organization Instructions (Trail + S3 Bucket in Different Accounts)</summary>

{% hint style="warning" %}
These instructions assume that your SNS Topic, SQS Queue and KMS Key encrypting SNS/SQS are stored in the same account as your S3 bucket, with your CloudTrail in the management account. Resources existing in additional accounts will require additional configuration not provided in this guide. See the [Reference](#cross-account-configuration-resources) for additional information.
{% endhint %}

If your trail and S3 bucket are not in the same account, you must use CloudFormation templates to deploy a generic IAM policy via a stack in your management account and a generic IAM policy via a stackset to all of your children accounts, set additional policy permissions in the child account to enable communication with the S3 bucket, and update the KMS Key Policy in the management account.

{% hint style="info" %}
Before you begin, make sure you have downloaded and unzipped the CloudFormationTemplates.zip file from Step 1. Make sure you also have your SQS Queue ARN (from [Step 6](#step-6-create-the-sqs-queue)), S3 Bucket ARN (pre-existing), AWS KMS Key ARN your trail uses to encrypt S3 bucket logs (pre-existing), and [Workbench GUID](#workbench-guid).
{% endhint %}

#### Step 1: Create a Stack in the Management Account

The permissions in the CloudFormation templates contain generic IAM policies that enable Expel to perform all necessary [Investigative Actions](https://support.expel.io/hc/en-us/articles/34624474608275-Expel-Terminology#h_01JAR4HC555JP11HKDZS823753). In this step, you will create the generic IAM policies in the management account.

1. Log into your management account.
2. Make sure you are still in the same region as in previous steps.
3. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
4. Go to **Stacks**.
5. Select **Create stack**. If you see a dropdown menu, choose the "With new resources" option.
6. For your stack:
   * Leave the Prerequisite as **Choose an existing template**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Accounts.json** template file.
7. Select **Next**.
8. Configure your stack details:
   * Enter a **name** for your stack.
   * Enter the **KMS Key ARN** your trail uses to encrypt S3 bucket logs, **S3 Bucket ARN**, **SQS Queue ARN**, and **Workbench GUID**.
9. Select **Next**.
10. Leave all defaults for stack options as is.
11. Select **Next**.
12. Review your configuration if desired, and select **Submit**.&#x20;

#### Step 2: Create a Stackset in the Management Account

You will use the other CloudFormation template to create the generic IAM policies in all children accounts, including in the S3 bucket account.

1. Use the Search bar to quickly navigate to CloudFormation, or find it in the Services menu.
2. Go to **StackSets**.
3. Select **Create StackSet**. If you see a dropdown menu, choose the "With new resources" option.
4. For the template:
   * Leave Permissions as **Service-managed permissions**.
   * Leave the Prerequisite as **Template is ready**.
   * For the template source, choose **Upload a template file**.
   * Choose the **CloudFormationTemplate\_Orgs.json** template file.
5. Select **Next**.
6. Configure your stackset details:
   * Enter a **name** for your stackset.
   * Enter your **Workbench GUID**.
7. Select **Next**.
8. Leave Tags and Execution configuration as is.
9. Select **Next**.
10. For your deployment options:
    * Scroll down to Specify regions and choose your **AWS region**.
    * Leave all other defaults on this page as is.
11. Select **Next**.
12. Review your configuration if desired, and select **Submit**.

#### Step 3: Edit the S3 Bucket Role in the Child Account

You will now add a new inline policy to a role in the S3 bucket account, which will allow permissions to other resources.

1. Log into the child account containing the S3 bucket.
2. Use the Search bar to quickly navigate to IAM, or find it in the Services menu.
3. Select **Roles**.
4. In the Roles list, search for or select **ExpelAssumeRole**.
5. In the Summary section, copy the ARN and save it to a safe place as your **S3 bucket account IAM Role ARN**. You will need this value later when you set up the security device in Workbench.
6. In the Permissions policies section, select **Add permissions > Create inline policy**.
7. In the JSON editor section, select **JSON**.
8. Highlight and delete the existing policy, and paste the below policy instead.&#x20;

{% hint style="warning" %}
Make sure to enter your own values for the SQS ARN ([Step 6](#step-6-create-the-sqs-queue)), S3 bucket ARN, KMS ARN, SNS SQS KMS ARN ([Step 3](#step-3-create-a-new-kms-key)), and KMS ARN.
{% endhint %}

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage"
      ],
      "Resource": "YOUR_SQS_QUEUE_ARN"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "YOUR_S3_BUCKET_ARN/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "YOUR_SNS_SQS_KMS_ARN"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "YOUR_CLOUDTRAIL_KMS_KEY_ARN"
    }
  ]
} 
```

{% hint style="warning" %}
**Important:** Did you use your own resource values in the policy? Check to be sure before continuing.
{% endhint %}

9. Select **Next**.
10. Enter a **name** for your policy.
11. Select **Create policy**.

#### Step 4: Add or Edit an IAM Role

{% hint style="info" %}
Skip this step if the situation does not apply to you.
{% endhint %}

If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.&#x20;

The two additional permissions are:

* `organizations:ListAccountsForParent`
* `organizations:ListOrganizationalUnitsForParent`

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your **AWS OU Role ARN**. You will need it when you set up the security device in Workbench.

#### Step 5: Update the KMS Key Policy

You must now update the KMS Key Policy of the key that your trail uses to encrypt S3 bucket logs, so that the S3 bucket's Expel IAM Role has permission to decrypt.

1. Switch back to your management account.
2. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
3. Select the **KMS key** encrypting your CloudTrail.
4. In the Key policy section, select **Edit**.
5. [Append](#appending-json-code) the following JSON snippet to the Key policy.

{% hint style="warning" %}
Make sure to insert the account ID of the child account your S3 bucket resides in where specified
{% endhint %}

```
,
       {
           "Sid": "Allow Expel to use this KMS key to decrypt logs",
           "Effect": "Allow",
           "Principal": {
               "AWS": "arn:aws:iam::YOUR_S3_BUCKET_ACCOUNT_ID:role/ExpelAssumeRole"
           },
           "Action": "kms:Decrypt",
           "Resource": "*"
       }
```

{% hint style="warning" %}
**Important:** Did you use the S3 bucket's child account ID in the new code? Check to be sure before continuing
{% endhint %}

6. Select **Save changes**.

</details>

## Step 10: Add AWS CloudTrail as a Security Device in Workbench

Now, you can add a security device in Workbench to complete the integration.&#x20;

{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN and SQS URL.&#x20;

If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries). If you need additional help finding any of these values, see the [Reference](#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, enter “AWS” and then select the AWS CloudTrail integration.
5. Select the bullets as follows:
   * “Are you using AWS organizations?” - AWS Organizations should leave it as **Yes**; single accounts should select **No**.
   * “Do you have an existing CloudTrail that you want Expel to reuse?” - leave it as **Yes**.
   * “How would you like to connect?” - select **Manual connection**.
6. Select **Save**.
7. On the next screen, complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName CloudTrail”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud” or “AWS cloud” or “on prem;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - enter the IAM Role ARN you saved from an earlier step. Format: `arn:aws:iam::123456789012:role/RoleName`
   * **Role session name** - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
   * **AWS region** - choose the AWS region where you created your configuration in AWS.
   * **SQS URL** - enter the SQS URL you copied and saved in a previous step.
   * **Organization management account** - if you use AWS Organizations, input the AWS Account ID of the management account; single account users can leave this field blank.
   * **AWS OU ID** - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: `ou-abc1-defghi2j`); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.
   * **AWS OU Role ARN** - if you entered an AWS OU ID, you will also need to enter the IAM Role ARN that contains the appropriate permissions. If you chose to add these permissions [to your existing IAM Role](#step-9-set-up-cloudformation), enter the IAM Role ARN again here. If you chose to create a new IAM Role with those permissions, enter your AWS OU Role ARN. Otherwise, leave this field blank.
8. Select **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Troubleshooting

If you are encountering an error or your trail isn't connecting to Workbench, try checking for some common issues:

1. You left one of your ARN values out of a JSON object in a prior step, put an ARN in the wrong location, or formatted an ARN incorrectly.
2. The JSON objects were copied, appended, or formatted incorrectly in a prior step.
3. You have forgotten to enable something, or have configured something incorrectly, in one of the prior steps.
   * Examples include not choosing your AWS KMS key from the dropdown menu when setting up default encryption in [Step 4](#step-4-create-a-new-sns-topic), or not using the same region throughout your AWS configuration.

### Appending JSON Code

Make sure to put this JSON snippet in the correct place, using a comma, and make sure the final bracket is still there. Lines 13-47 of your JSON code should look like this (the appended part is highlighted, beginning with the `,`):

<pre><code>{
    "Version": "2012-10-17",
    "Id": "key-consolepolicy-3",
    "Statement": [
        {
            "Sid": "Enable IAM User Permissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::241008450902:root"
            },
            "Action": "kms:*",
            "Resource": "*"
<strong>        },
</strong><strong>       {
</strong><strong>           "Sid": "Allow cloudtrail bucket to encrypt/decrypt",
</strong><strong>           "Effect": "Allow",
</strong><strong>           "Principal": {
</strong><strong>               "Service": "s3.amazonaws.com"
</strong><strong>           },
</strong><strong>           "Action": [
</strong><strong>               "kms:GenerateDataKey",
</strong><strong>               "kms:Decrypt"
</strong><strong>           ],
</strong><strong>           "Resource": "*",
</strong><strong>           "Condition": {
</strong><strong>               "ArnLike": {
</strong><strong>                   "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
</strong><strong>               }
</strong><strong>           }
</strong><strong>       },
</strong><strong>       {
</strong><strong>           "Sid": "Allow SNS to encrypt/decrypt",
</strong><strong>           "Effect": "Allow",
</strong><strong>           "Principal": {
</strong><strong>               "Service": "sns.amazonaws.com"
</strong><strong>           },
</strong><strong>           "Action": [
</strong><strong>               "kms:GenerateDataKey",
</strong><strong>               "kms:Decrypt"
</strong><strong>           ],
</strong><strong>           "Resource": "*",
</strong><strong>           "Condition": {
</strong><strong>               "ArnLike": {
</strong><strong>                   "aws:SourceArn": "YOUR_SNS_TOPIC_ARN"
</strong><strong>               }
</strong><strong>           }
</strong><strong>       }
</strong>    ]
}
</code></pre>

## Reference

### Cross-Account Configuration Resources

The diagram below illustrates the relationship and location of AWS resources for a possible environment covered in this guide: an existing CloudTrail configuration involving AWS Organizations where the trail is in the management account and the S3 bucket, SNS topic, and SQS queue are all together in a child account. KMS encryption can be applied as illustrated and IAM roles are deployed to the accounts using CloudFormation Stacks and Stacksets.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fs4DbXvYJOW9m7lybQ6Ro%2FAWS%20Cloudtrail%20design%20schematic%20-%20Data%20flow%20%26%20IAM%20(1).png?alt=media&amp;token=e4fdd469-6dc4-43a1-b8d4-6f0edbff194b" alt="Image of a flow chart showing cross-account configuration resources."><figcaption></figcaption></figure>

For more information on configuring a cross-account environment, refer to these AWS developer guide pages:

* [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html)
* [Cross account KMS key access](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html#cross-account-key-policy)
* [Cross account SNS topic subscription](https://docs.aws.amazon.com/sns/latest/dg/sns-send-message-to-sqs-cross-account.html)
* [Example cases for Amazon SNS access control](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-use-cases.html)
* [Using custom policies with the Amazon SQS Access Policy Language](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-creating-custom-policies.html)
* [Permissions for AWS services in key policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-services.html)

### ARNs and URLs

This chart gives examples of ARNs and the SQS URL so you can check on the general formatting, and also tells you where to find any of the values if you’ve forgotten to copy and save them during the configuration process.&#x20;

<table><thead><tr><th width="172.96875">Value</th><th width="272.18359375">Where to Find</th><th>Example</th></tr></thead><tbody><tr><td>S3 Bucket ARN</td><td>S3 > Buckets > bucket name > Properties</td><td>arn:aws:s3:::MyS3BucketARN</td></tr><tr><td>SNS Topic ARN</td><td>Simple Notification Service > Topics > topic name > Details section</td><td>arn:aws:sns:us-east-1:123456789012:MyTopicName</td></tr><tr><td>AWS KMS Key ARN</td><td>Key Management Service > key alias > General configuration section</td><td>arn:aws:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345</td></tr><tr><td>SQS Queue ARN</td><td>Simple Queue Service > queue name > Details section</td><td>arn:aws:sqs:us-east-1:123456789012:MySQSQueueName</td></tr><tr><td>SQS URL</td><td>Simple Queue Service > queue name > Details section</td><td>https://sqs.us-west-1.amazonaws.com/123456789012/MySQSQueueName</td></tr><tr><td>IAM Role ARN</td><td>IAM > Access Management > Roles > role name > Summary section</td><td><p>arn:aws:iam::123456789012:role/RoleName</p><p><br></p><p>(most users will look for the ExpelAssumeRole)</p></td></tr></tbody></table>

### AWS Organization-Specific Values

This chart helps you locate the additional values you need if you are using AWS Organizations. The OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries.

<table><thead><tr><th width="172.52734375">Value</th><th width="272.26171875">Where to Find</th><th>Example</th></tr></thead><tbody><tr><td>AWS Account ID</td><td>AWS Organizations Console, upper right of screen</td><td>1234-5678-9012</td></tr><tr><td>AWS OU ID</td><td><a href="https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_ous.html">AWS Organizations Console</a></td><td><p>ou-abc1-defghi2j</p><p>(format is ou-rootid-ouid and this entire value should be entered into the Workbench security device)</p></td></tr></tbody></table>

### Workbench GUID

The Workbench GUID is a unique alphanumeric value assigned by Expel to your organization.

**Format**

`a123b456-7c89-0def-g1hi-2j3k45l6mn7o`

**Where to Find**

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Go to **Organization Settings > My Organization**.
3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.

{% hint style="info" %}
If you have multiple organizations, you must first select the organization name that will be associated with your integration to access the page with the Copy button. Or, you can stay on the page and highlight then copy the GUID shown for that organization in the GUID column.
{% endhint %}


# AWS GovCloud CloudTrail Manual Setup - New Trail

This setup guide is for those who wish to use the GovCloud CloudTrail service for their CloudTrail integration. The AWS setup described here is Expel’s recommended best practice.

This setup guide takes you through all required manual configurations when creating a new trail in AWS, to allow Expel to access your S3 bucket securely via an API. It also shows you how to add GovCloud CloudTrail as a security device in Workbench, which completes your portion of the setup. We will then manually enable event ingestion for the integration.

## Scope and Limitations

When choosing to set up this integration, remember the following:

* AWS GovCloud must be onboarded manually. You cannot onboard via CloudFormation.
* This integration supports a single AWS GovCloud account (AWS organizations are not supported), so you must manually create your IAM policy.
* These steps are intended to show the necessary settings that must be configured in order for your Expel integration to work, with basic instructions for how to do so; they do not cover most of the optional settings or explain every possible option in AWS. There are a number of ways to customize your AWS configurations based on your own environment or protocols.

## Prerequisites

1. Using a GovCloud environment requires completing a **legal addendum** before Expel can enable event ingestion for this integration. Please [contact Support](/support) for assistance in completing this addendum.
2. Verify you have the necessary permissions to create and modify IAM policies and roles for your AWS account.
3. Make sure you are in the proper AWS account if you manage more than one account.
4. Check the AWS GovCloud region in the top menu bar (i.e. us-gov-east-2, us-gov-west-1, etc.) and make sure you are in the GovCloud home region you want to be in; you must use the same GovCloud home region throughout the entire AWS configuration process, and you must later specify this region correctly in Workbench.
5. Make sure you can log into Workbench successfully, and are able to see your organization settings.
   * This is a good time to copy and save your Workbench GUID, which is a unique alphanumeric value assigned by Expel to your organization and found in the My Organization page; see the [Reference](#workbench-guid) for detailed instructions.
6. Create a new file or other space to keep track of all of the names, ARNs, and other values from the AWS configuration as you go (a list of all needed values is below, and additional help is available in the [Reference](#reference)).

## Before You Begin

During the AWS configuration process, you will need to copy out and save a number of values as they are added by you (e.g. the AWS KMS Alias) or generated by AWS (e.g. the SQS Queue ARN). Knowing each of these values is necessary to successfully complete all AWS configuration steps and to also add AWS as a security device in Workbench.

{% hint style="info" %}
For examples of what some of these values look like or instructions on where to find them if you forget to save one of them, refer to the [Reference](#reference).
{% endhint %}

These include, in the order they are created or generated:

* Workbench GUID (if you do not have it yet, [get it now](#workbench-guid))
* AWS GovCloud Region
* S3 Bucket Name
* AWS KMS Alias
* S3 Bucket ARN
* SQS Queue ARN
* SQS URL
* AWS KMS Key ARN
* IAM Access Policy ARN
* IAM Role ARN

## Step 1: Create a New Trail

{% hint style="warning" %}
Before you begin, make sure you are in the GovCloud management console.&#x20;

Also, check the top menu bar to be sure you are in the GovCloud home region you wish to set for the trail (e.g. us-gov-west-1). You will need to be in the same GovCloud home region throughout this guide, and also choose the correct region in Workbench in [Step 8](#step-8-add-aws-cloudtrail-as-a-security-device-in-workbench).
{% endhint %}

In this step, you will create a new trail, new S3 bucket, and new AWS KMS key within your chosen GovCloud home region.

1. Use the Search bar to quickly navigate to CloudTrail, or find it in the Services menu.
2. Select **Create trail**.
3. Enter a **trail name**, such as "GlobalCloudTrail".
4. **AWS Organizations only** - select the **Enable for all accounts in my organization** checkbox.
5. In Storage location, leave **Create new s3 bucket** selected.
   * Use the default for the **Trail log bucket and folder**, or enter a new unique name. *Remember that if you choose to create your own name, it must be unique to ALL of AWS — not just to your instance — or the trail creation will fail. You can append your desired name with the alphanumeric values from the default name to ensure uniqueness.*
   * Make a note of your **S3 bucket name**, as you will need it for a later step.
   * Leave Log file SSE-KMS encryption as **Enabled**.
   * Leave the **New** radio button selected.
   * Enter an **alias name** for the AWS KMS Key.
   * Make a note of your **AWS KMS Key alias**, as you will need it in later steps.
6. In Additional settings:
   * Leave Log file validation as **Enabled**.
   * Leave SNS notification delivery **unchecked**.
7. Leave the CloudWatch Logs and Tags section as is, unless you need to change them for your own protocols, and do not edit the Policy document.
8. Select **Next**.
9. Leave the Choose Log Events screen as is.
   * It should have **Management Events** selected, and both **Read** and **Write** selected for API activity.
10. Select **Next**.
11. You can now review your trail's settings before creating it, if you wish.
12. Select **Create trail**.
13. You will be taken to the Trails list and should see your new trail.

## Step 2: Edit the S3 Bucket Encryption Settings

In this step, you will set your default S3 bucket encryption to server-side encryption with AWS Key Management Service keys (SSE-KMS), and instruct Amazon to use your AWS KMS key’s encryption policy for your log files instead of using SSE-S3 encryption (Amazon’s default).&#x20;

{% hint style="info" %}
You will configure the key’s policy in a later step.
{% endhint %}

1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Look for your new S3 bucket in the list and select it.
3. Select the **Properties** tab.
4. First, copy the ARN and save it to a safe place as your **S3 Bucket ARN** (you will need it for a later step). The format should look something like this: `arn:aws-us-gov:s3:::YourS3BucketName`
5. Next, scroll to Default encryption and select **Edit**.
6. Select **Server-side encryption with AWS Key Management Service keys (SSE-KMS)**.
7. Under AWS KMS key, select **Choose from your AWS KMS keys**.
8. Select the **AWS KMS key** you created in [Step 1](#step-1-create-a-new-trail) (the alias will display in small print below the key).
9. Leave the Bucket Key as **Enable**.
10. Select **Save changes**.

## Step 3: Create the SQS Queue

Next, we'll create a dedicated SQS queue to receive messages from the S3 bucket, and edit the access policy to allow the S3 bucket to send messages to it. Expel will use this queue to poll for notifications of new CloudTrail data, and then will update Workbench accordingly.

1. Use the Search bar to quickly navigate to Simple Queue Service (SQS), or find it in the Services menu.&#x20;
2. Select **Create queue**.
3. In the Details section:
   * Leave **Standard** as the type.
   * Enter a **name** in the Name field.
4. In the Configuration section:
   * Change the Message Retention period to **7 days**.&#x20;
   * Leave all other defaults.
5. In the Encryption section:
   * Leave Server-side encryption as **Enabled**.
   * Choose **AWS Key Management Service key (SSE-KMS)** as the encryption key type.&#x20;
   * Choose your **AWS KMS Alias** from the Customer master key dropdown.&#x20;
   * Leave the data key reuse period as the default.
6. In the Access policy section:
   * Select **Advanced**.
   * First, go to the Resource value and copy the ARN, then save it to a safe place as your **SQS Queue ARN** (you will need it for your new access policy).
   * Highlight and delete the existing policy, and paste the below policy instead.

{% hint style="warning" %}
Make sure to use your SQS Queue ARN as the `Resource` value and your S3 Bucket ARN as the `aws:SourceARN` value.
{% endhint %}

```
{
  "Version": "2012-10-17",
  "Id": "__default_policy_ID",
  "Statement": [
    {
      "Sid": "__owner_statement",
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "SQS:SendMessage",
      "Resource": "YOUR_SQS_QUEUE_ARN",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
        }
      }
    }
  ]
}
```

{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN and S3 Bucket ARN in the new code? Check to be sure before continuing.
{% endhint %}

7. Leave the remaining sections as is and select **Create queue**.
8. Before leaving the confirmation screen, copy the URL and save it to a safe place as your **SQS URL** (you will need it in a later step).

## Step 4: Edit the AWS KMS Key Policy

In an earlier step, you configured your S3 bucket to use your AWS KMS key for encryption. Now, you must append the key’s encryption policy to allow the S3 bucket and SQS queue to communicate securely via encryption.

1. Use the Search bar to quickly navigate to Key Management Service, or find it in the Services menu.
2. From the Customer Managed Keys list, select your **AWS KMS alias**.
3. First, copy the ARN and save it to a safe place as your **AWS KMS Key ARN** (you will need it in a later step). The format should look something like this: `arn:aws-us-gov:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345`
4. In the Key policy section, select **Edit** and [append](#appending-json-code) these JSON objects to the code.

{% hint style="warning" %}
Make sure to use your S3 Bucket ARN as the `aws:SourceArn` value.
{% endhint %}

```
,
{
  "Sid": "Allow cloudtrail bucket to encrypt/decrypt SQS",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": [
    "kms:GenerateDataKey",
    "kms:Decrypt"
  ],
  "Resource": "*",
  "Condition": {
    "StringLike": {
      "aws:SourceArn": "YOUR_S3_BUCKET_ARN"
    }
  }
}
```

{% hint style="warning" %}
**Important:** Did you use your S3 bucket ARN and SNS Topic ARN in the appended code? Check to be sure before continuing.
{% endhint %}

5. Select **Save changes**.

## Step 5: Enable S3 Event Notifications

Now that we've fully configured the communications between the S3 bucket and SQS queue, we can create an event notification. This notification will tell the S3 bucket to send certain events (we will specify which ones) to the SQS queue whenever CloudTrail adds event logs to the bucket.&#x20;

1. Use the Search bar to quickly navigate to S3, or find it in the Services menu.
2. Select your S3 bucket.
3. Select **Properties**.
4. Go to the Event Notifications section and select **Create event notification**. Then:
   * Enter an **event name**.
   * In the Event types section, use the checkbox to enable **All object create events**. Leave the rest of the boxes unchecked.
   * In the Destination section, select **SQS queue** and then choose your SQS queue from the dropdown.
5. Select **Save changes**.

## Step 6: Create the IAM Policy

Expel will be granted permissions to your AWS account(s) based on a corresponding IAM policy.

1. Use the Search bar to quickly navigate to IAM service, or find it in the Services menu.
2. Navigate to **Access Management > Policies**.
3. Select **Create policy**.
4. Select the **JSON** tab.
5. Remove the existing policy and copy this one in instead.

{% hint style="warning" %}
Make sure to replace the SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN with your own.
{% endhint %}

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroups",
        "iam:List*",
        "iam:Get*",
        "rds:DescribeDBInstances",
        "rds:ListTagsForResource",
        "organizations:ListAccounts",
        "ec2:Describe volumes",
        "ecs:DescribeTaskDefinition",
        "ecs:ListTaskDefinitions",
        "lambda:GetFunction",
        "lambda:ListFunctions",
        "s3:ListAllMyBuckets",
        "s3:GetBucketNotification",
        "s3:GetEncryptionConfiguration",
        "cloudtrail:GetTrailStatus",
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrail",
        "cloudtrail:ListTrails",
        "config:ListDiscoveredResources",
        "config:GetDiscoveredResourceCounts",
        "eks:DescribeCluster",
        "eks:ListClusters",
        "ecs:ListContainerInstances",
        "ecs:DescribeContainerInstances",
        "ecs:DescribeClusters",
        "ecs:ListClusters",
        "organizations:DescribeOrganization"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage"
      ],
      "Resource": "YOUR_SQS_QUEUE_ARN"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "YOUR_S3_BUCKET_ARN/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "YOUR_KMS_KEY_ARN"
    }
  ]
}
```

{% hint style="warning" %}
**Important:** Did you use your SQS Queue ARN, S3 Bucket ARN, and KMS Key ARN in the new code? Check to be sure before continuing.
{% endhint %}

6. Select **Next**.
7. Enter "ExpelAccessPolicy" as the policy name.
8. Select **Create policy**.

## Step 7: Create the IAM Role

Expel will authenticate its credentials using an IAM Role. Before you begin, make sure you have your [Workbench GUID](#workbench-guid).

1. Use the Search bar to quickly navigate to IAM service, or find it in the Services menu.
2. Navigate to **Access Management > Roles**.
3. Select **Create Role**.
4. Select **Custom trust policy** as the trusted entity type.
5. Remove the existing policy and copy this one in instead.

{% hint style="warning" %}
Make sure to replace the Workbench GUID with your own.
{% endhint %}

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws-us-gov:iam::071857701673:user/ExpelCloudService"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "YOUR_WORKBENCH_GUID"
                }
            }
        }
    ]
}
```

6. Select **Next**.
7. Locate your **IAM policy** (from [Step 6](#step-6-create-the-iam-policy); this should be the ExpelAccessPolicy) in the Permissions Policies section, and select the checkbox next to it.
8. Select **Next**.
9. Enter "ExpelAssumeRole" as the role name.
10. Select **Create Role**.
11. Before you leave the page, copy and save your **IAM Role ARN**, as you will need it in the next step.

## Step 8: Add AWS CloudTrail as a Security Device in Workbench

Now, we can add a security device in Workbench to complete the integration.&#x20;

{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN, SQS URL, and AWS GovCloud region. If you need additional help finding any of these values, see the [Reference](#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, enter “AWS” and then select the AWS CloudTrail integration.
5. &#x20;Select the bullets as follows:
   * “Are you using AWS organizations?” - select **No**.
   * “Do you have an existing CloudTrail that you want Expel to reuse?” - select **No**.
   * “How would you like to connect?” - select **Manual connection**.
6. Select **Save**.
7. On the next screen, complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName GovCloud”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - paste in your IAM Role ARN.
   * **Role session name** - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
   * **AWS region** - select the AWS GovCloud region where your SQS queue resides.
   * **SQS URL** - paste in your SQS URL.
   * **Organization management account** - leave this field blank.
8. Select **Save**.
9. Select **Done** to close the window.
10. You must now [notify Support](/support) to let us know you have completed these steps. If you have not yet completed the required legal addendum so that we can enable GovCloud ingestion of events, please also work with support on this task.

A few reminders about monitoring your security device after we have enabled ingestion:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. You must refresh the page to see updates.
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check and select the Expel Alerts tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Troubleshooting

### S3 Event Notification Errors (Step 5)

This error is encountered when selecting **Save changes**. It generally displays for one of the following reasons:

1. You left one of your ARN values out of a JSON object in a prior step, put an ARN in the wrong location, or formatted an ARN incorrectly.
2. The JSON objects were copied, appended, or formatted incorrectly in a prior step.
3. You used an S3 bucket name that someone else in the AWS ecosystem is already using (even if nobody at your organization is using it).
4. You have forgotten to enable something, or have configured something incorrectly, in one of the prior steps.
   * Examples include not choosing your AWS KMS key from the dropdown menu when setting up default encryption in [Step 2](#step-2-edit-the-s3-bucket-encryption-settings), or not using the same GovCloud region throughout your AWS configuration.

### S3 Bucket Naming

You must use an S3 bucket name that nobody else in the AWS ecosystem is using. You can avoid this problem by using the default name, or by appending your chosen name with the numerical values from the default name that is generated.

### Appending JSON Code

Make sure to put this JSON snippet in the correct place, using a comma, and make sure the final bracket is still there. Lines 82-99 of your JSON code should look like this (the appended part is highlighted, beginning with the `,`):

<pre><code>  {
	"Version": "2012-10-17",
	"Id": "Key policy created by CloudTrail",
	"Statement": [
		{
			"Sid": "Enable IAM User Permissions",
			"Effect": "Allow",
			"Principal": {
				"AWS": [
					"arn:aws-us-gov:sts::241008450902:assumed-role/AWSReservedSSO_AdministratorAccess_34826aa3e04a2a86/elizabeth.haynes@expel.io",
					"arn:aws-us-gov:iam::241008450902:root"
				]
			},
			"Action": "kms:*",
			"Resource": "*"
		},
		{
			"Sid": "Allow CloudTrail to encrypt logs",
			"Effect": "Allow",
			"Principal": {
				"Service": "cloudtrail.amazonaws.com"
			},
			"Action": "kms:GenerateDataKey*",
			"Resource": "*",
			"Condition": {
				"StringEquals": {
					"aws:SourceArn": "arn:aws-us-gov:cloudtrail:us-east-1:241008450902:trail/echtrail070825"
				},
				"StringLike": {
					"kms:EncryptionContext:aws-us-gov:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
				}
			}
		},
		{
			"Sid": "Allow CloudTrail to describe key",
			"Effect": "Allow",
			"Principal": {
				"Service": "cloudtrail.amazonaws.com"
			},
			"Action": "kms:DescribeKey",
			"Resource": "*"
		},
		{
			"Sid": "Allow principals in the account to decrypt log files",
			"Effect": "Allow",
			"Principal": {
				"AWS": "*"
			},
			"Action": [
				"kms:Decrypt",
				"kms:ReEncryptFrom"
			],
			"Resource": "*",
			"Condition": {
				"StringEquals": {
					"kms:CallerAccount": "241008450902"
				},
				"StringLike": {
					"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
				}
			}
		},
		{
			"Sid": "Enable cross account log decryption",
			"Effect": "Allow",
			"Principal": {
				"AWS": "*"
			},
			"Action": [
				"kms:Decrypt",
				"kms:ReEncryptFrom"
			],
			"Resource": "*",
			"Condition": {
				"StringEquals": {
					"kms:CallerAccount": "241008450902"
				},
				"StringLike": {
					"kms:EncryptionContext:aws:cloudtrail:arn": "arn:aws-us-gov:cloudtrail:*:241008450902:trail/*"
				}
			}
<strong>		},
</strong><strong>		{
</strong><strong>			"Sid": "Allow cloudtrail bucket to encrypt/decrypt SQS",
</strong><strong>			"Effect": "Allow",
</strong><strong>			"Principal": {
</strong><strong>				"Service": "s3.amazonaws.com"
</strong><strong>			},
</strong><strong>			"Action": [
</strong><strong>				"kms:GenerateDataKey",
</strong><strong>				"kms:Decrypt"
</strong><strong>			],
</strong><strong>			"Resource": "*",
</strong><strong>			"Condition": {
</strong><strong>				"StringLike": {
</strong><strong>					"aws:SourceArn": "arn:aws-us-gov:s3:::S3BucketName"
</strong><strong>				}
</strong><strong>			}
</strong><strong>		}
</strong>	]
}


</code></pre>

## Reference

### ARNs and URLs

This chart gives examples of ARNs and the SQS URL so you can check on the general formatting, and also tells you where to find any of the values if you’ve forgotten to copy and save them during the configuration process.&#x20;

<table><thead><tr><th width="171.7890625">Value</th><th width="262.53125">Where to Find</th><th>Example</th></tr></thead><tbody><tr><td>S3 Bucket ARN</td><td>S3 > Buckets > bucket name > Properties</td><td>arn:aws-us-gov:s3:::MyS3BucketARN</td></tr><tr><td>AWS KMS Key ARN</td><td>Key Management Service > key alias > General configuration section</td><td>arn:aws-us-gov:kms:us-west-2:123456789012:key/123a4567-890b-1234-c5d6-7ef89012g345</td></tr><tr><td>SQS Queue ARN</td><td>Simple Queue Service > queue name > Details section</td><td>arn:aws-us-gov:sqs:us-east-1:123456789012:MySQSQueueName</td></tr><tr><td>SQS URL</td><td>Simple Queue Service > queue name > Details section</td><td>https://sqs.us-west-1.amazonaws.com/123456789012/MySQSQueueName</td></tr><tr><td>IAM Role ARN</td><td>IAM > Access Management > Roles > role name > Summary section</td><td><p>arn:aws-us-gov:iam::123456789012:role/RoleName</p><p><br></p><p>(most users will look for the ExpelAssumeRole)</p></td></tr></tbody></table>

### Workbench GUID

The Workbench GUID is a unique alphanumeric value assigned by Expel to your organization.

**Format**

`a123b456-7c89-0def-g1hi-2j3k45l6mn7o`

**Where to Find**

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Go to **Organization Settings > My Organization**.
3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.

{% hint style="info" %}
If you have multiple organizations, you must first select the organization name that will be associated with your integration to access the page with the Copy button. Or, you can stay on the page and highlight then copy the GUID shown for that organization in the GUID column.
{% endhint %}


# AWS CloudTrail with Control Tower - Existing Trail

This manual setup guide is for those who have an existing trail that includes Control Tower available for use in their CloudTrail service.

{% hint style="info" %}
This topic assumes you are using the default service control policies. If you encounter problems during setup, [contact Support](/support) for help.
{% endhint %}

## Prerequisites

1. You must already have an AWS Control Tower with Landing Zone.
2. You must have Administrator privileges in the AWS Control Tower management and Log Archive accounts.
3. You must download the attachment found at the end of this article, which includes the code blocks you need to complete this process.
4. If you use AWS Organizations, make sure you have your AWS Account ID.
5. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the AWS Organizational Unit (OU) ID for the subsidiary.
6. This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.

If you need help finding any of these values, see this [Reference](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail#reference) section.

## Before You Begin

{% file src="/files/EOngB5eoXAvafdGs7F1U" %}

Before you begin, download a zip file that contains all necessary JSON snippets you will need to complete this guide.

## Step 1: Set Up Expel IAM Role and Policy

In this step you will create a permissions policy to assign to the IAM Role. For AWS Control Tower, the primary Expel role is created within the organization’s Log Archive account where the CloudTrail S3 log bucket exists.

{% hint style="info" %}
The role and policy must be replicated across all the other accounts in the organization to allow Expel to perform investigative actions within your AWS environment. The policy replicated to the other non-Log Archive sub-accounts can be modified to exclude the policy elements providing access permissions to the S3 resources if necessary.
{% endhint %}

1. Create an IAM role and policy in the **management account**.
   * Navigate to the **CloudFormation > Stacks** service portal.
   * Select **Create Stack (with new resources)** and choose **Upload a template file** as the source.
   * Upload the **ControlTowerTemplate\_Step1.json** file (found in the zip file you downloaded in Step 1).
   * Provide a relevant **name** for the stack, such as "ExpelIAMStack".
   * In the WorkbenchExternalID parameter field, enter your [Workbench GUID](#user-content-fn-1)[^1], then click **Next**.
   * You can leave all defaults for configuring the stack options and click **Next**.
   * Verify the stack details, then check the acknowledgement and click **Submit**.
   * The new IAM role and attached policy should exist for Expel within the management account on completion of the stack.
2. Create IAM Role and Policy in all sub accounts.
   * Navigate to the **CloudFormation > Stacksets** service portal.
   * Select **Create StackSet** and choose **Upload a template file** as the source.
   * Follow the same process to fill out the stackset details as was done in deploying the stack above (Step 1.1).

{% hint style="warning" %}
If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.&#x20;

The two additional permissions are:

* `organizations:ListAccountsForParent`
* `organizations:ListOrganizationalUnitsForParent`

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your **AWS OU Role ARN**. You will need it when you set up the security device in Workbench.
{% endhint %}

## Step 2: Update CloudTrail CMK Policy If Applicable

{% hint style="info" %}
If your CloudTrail is *not* configured to encrypt the S3 logs using CMK, skip these steps and go directly to [Step 3](#step-3-confirm-s3-log-bucket-acl-settings). Otherwise, you must update the key policy to provide Workbench with the `kms:Decrypt` permission so that we can properly get objects from the S3 bucket containing the CloudTrail logs.

* You can determine if this step applies to you by navigating to Services > CloudTrail > Trails and then selecting the trail created by Control Tower in your management account. In the General details section you see a value under `Log file SSE-KMS encryption` and an associated `AWS KMS key` populated as well.
  {% endhint %}

1. Navigate to the **CMK key** used to encrypt the CloudTrail logs.
   * You can find the specific key arn by looking for **AWS KMS Key** in the **General details** section of the CloudTrail.
2. Select the **Key policy** tab and then choose **Edit** to change it.
3. Add the decrypt permission to the existing list of policy statements. You can find that code in **ControlTowerTemplate\_Step2.json** file (found in the zip file you downloaded in Step 1).

{% hint style="warning" %}
Make sure to update the principal value with the correct **ARN path** to the Expel Role created in the Log Archive account as a result of Step 1.2 via the StackSet.
{% endhint %}

4. Select **Save changes**.&#x20;

## Step 3: Confirm S3 Log Bucket ACL Settings

{% hint style="warning" %}
This step (through Step 8) must be performed from within your **AWS Control Tower Log Archive** account. See the [AWS documentation](https://docs.aws.amazon.com/controltower/latest/userguide/accounts.html) for any clarification.
{% endhint %}

Amazon S3 access control lists allow you to manage access to buckets and any objects contained within. We want to confirm that the S3 bucket created in your log archive account allows the bucket owner (Log Archive) and Expel by extension through the deployed role read permissions for the objects within.

1. Navigate to **Services > S3 > Buckets > \[Your S3 Log Bucket]** (usually follows the naming scheme “aws-controltower-logs-”.
2. Select the **Permissions** tab, then look at the **Object Ownership** section to confirm the current ACL setting.
3. If you keep ACLs enabled on the bucket, then confirm the current Object Ownership is set to **Bucket owner preferred**.

{% hint style="info" %}
AWS recommends that you disable ACLs on S3 for a majority of modern use cases, which will then delegate ownership to the bucket owner account ([source](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html)).
{% endhint %}

## Step 4: Set Up SNS Topic for S3 Notifications

<details>

<summary>Option 1: Use CloudFormation (Recommended)</summary>

1. Navigate to **Services > CloudFormation > Stacks** and select **Create stack (with new resources)**.
2. In the **Specify template** section, select **Upload a template file**, and upload the **ControlTowerTemplate\_Step4Option1.json** file. Then click **Next**.
3. Enter a **name** for the stack.
4. Enter the following required parameters:
   * **S3LogBucketARN** - the ARN associated with the S3 Bucket in your Log Archive account that retains the CloudTrail logs.
   * **CloudTrailKeyARN** - the ARN for the customer-managed kms key configured on your CloudTrail (in your management account).
5. Proceed through the rest of the wizard keeping the defaults, then select **Submit** to initiate the stack.
6. After the stack creation completes, make note of all values returned in the **Outputs** tab of the stack console. You need these returned values to complete setup in Workbench.
   * **RoleARN** - the IAM Role created in the log archive account needed to complete setup in Workbench.
   * **SqsURL** - the SQS url path needed to complete setup of in Workbench.
7. Skip to [Step 8: Enable S3 event notifications to SNS topic](#step-8-enable-s3-event-notifications-to-sns-topic).

</details>

<details>

<summary>Option 2: Manual Setup</summary>

{% hint style="warning" %}
Make sure to create the SNS topic in the same region that the S3 bucket CloudTrail events are being sent to.
{% endhint %}

1. Navigate to **Services > Simple Notification Service > Topics** and select **Create Topic**.
2. On the next screen, select **Standard** as the Type and create a **Topic Name**.
3. Under Access Policy, select **Advanced**.
4. In the JSON editor, paste the contents of the **ControlTowerTemplate\_Step4Option2.json** file, substituting the `YOUR_TOPIC_ARN` and `YOUR_S3_ARN` fields with your values. This policy allows S3 to publish notifications to the topic for your CloudTrail bucket.
5. Select **Create Topic**.

</details>

## Step 5: Set Up SQS Queue for SNS Notification

In this step, you will create a new SQS queue for the S3 notifications. Workbench polls notifications from this queue in order to know when new CloudTrail data is added.

{% hint style="warning" %}
Make sure you create the SQS queue in the same region as the SNS topic and S3 bucket.
{% endhint %}

1. Navigate to **Services > Simple Queue Service > Queues** and select **Create queue**.
2. On the next screen, select **Standard Queue** and enter a **name** for the new queue.
3. Set up the queue as follows:
   1. **Visibility timeout** - 30 Seconds.
   2. **Message retention perio**d - 7 days.
   3. **Delivery delay** - 0 Seconds.
   4. **Maximum message size** - 256 KB.
   5. **Receive message wait time** - 0 Seconds.
4. Under Access Policy, select **Advanced**.
5. In the JSON editor, paste the contents of the **ControlTowerTemplate\_Step5.json** file, substituting the `YOUR_SQS_QUEUE_ARN` and `YOUR_SNS_TOPIC_ARN` fields with your values.

## Step 6: Subscribe SQS to the SNS Topic

Now that you have created an SNS topic and SQS queue, you need to configure SNS to send events to the SQS queue.

1. Navigate to **Services > Simple Notification Service > Subscriptions** and select **Create subscription**.
2. On the next screen, configure the required fields to complete the subscription.

<table><thead><tr><th width="211.01171875">Field</th><th>Value</th></tr></thead><tbody><tr><td>Topic ARN</td><td>Your SNS Topic ARN</td></tr><tr><td>Protocol</td><td>Select Amazon SQS</td></tr><tr><td>Endpoint</td><td>Your SNS Queue ARN</td></tr><tr><td>Enable raw message delivery</td><td>Selecting enable raw message delivery makes sure SNS does not add extra metadata headers to the message when it sends to SQS. <strong>Make sure you select this.</strong></td></tr></tbody></table>

3. Select **Create subscription**.

## Step 7: Set Up KMS Encryption for SNS and SQS

{% hint style="warning" %}
This step must be performed from within your **AWS Control Tower Log Archive** account.
{% endhint %}

1. Navigate to S**ervices > Key Management Service (KMS) > Customer managed keys** and select **Create Key**.
2. Retain the default configuration values as shown below, then select **Next**.
3. Fill in values for the alias and description for the key, then select **Next**.
4. Select any additional key administrators for the new key, then select **Next** until you get to the Review page.
5. Look for the Key policy generated for this key in the Review page, and add the policies to the statement list to give S3 and SNS the right permissions they need to decrypt with this key. You can find that code in the **ControlTowerTemplate\_Step7.json** file.
6. Select **Finish** to complete the creation of the new key.
7. Enable Encryption on the SNS topic you created in [Step 3](#step-3-confirm-s3-log-bucket-acl-settings) using the new key:
   * Navigate to **Services > Simple Notification Service > Topics > YourTopic**.
   * Select **Edit**, then select **Encryption on**.
   * In the Customer master key (CMK) selection, select the **KMS key** you created above.
   * Select **Save changes**.
8. Enable Encryption on the SQS topic you created in [Step 4](#step-4-set-up-sns-topic-for-s3-notifications) using the new key:
   * Navigate to **Services > Simple Queue Service > Queues > YourQueue**.
   * Select **Edit**, then toggle the Encryption option **on**.
   * Set the Server-side encryption option to **Enabled**.
   * Set the Encryption key type to **SSE-KMS**.
   * In the Customer master key selection, select the **KMS key** you created above.
   * Select **Save**.

## Step 8: Enable S3 Event Notifications to SNS Topic

In this step, you will configure the CloudTrail S3 bucket to send SNS notifications when CloudTrail adds logs to the bucket.

1. Navigate to **Services > S3 > Your S3 CloudTrail Bucket**.
2. Open **Properties** for your S3 bucket and navigate to **Event notifications**.&#x20;
3. Select **Create event notification**.
4. On the next screen:
   * Enter a **name** for your notification rule.
   * Select **All object create events** from the Event types section.
   * Select **SNS topic** from the Destination section.
   * Select your **SNS topic** created in Step 3.
   * Select **Save changes**.

## Step 9: Grant the Expel IAM Role Necessary Access

{% hint style="warning" %}
If you set up the Expel resources using [CloudFormation](#option-1-use-cloudformation-recommended) in Step 4, skip these steps and go to [Step 10](#step-10-complete-workbench-setup).
{% endhint %}

At this point you have configured S3 notifications → SNS topic → SQS queue. The final step involves granting the existing ExpelIAM Role the necessary access to poll events from the SQS queue and the S3 bucket.

1. Navigate to **Services > IAM > Roles**.
2. Create and add a new inline policy to the Expel Role that was propagated to the Log Archive account as part of [Step 1](#step-1-set-up-expel-iam-role-and-policy). You can use the code provided in the **ControlTowerTemplate\_Step9.json** file. The policy grants the permissions.

{% hint style="info" %}
If you used the provided code, name it "**ExpelAssumeRole**".&#x20;
{% endhint %}

## Step 10: Add AWS CloudTrail as a Security Device in Workbench

Now, you can add a security device in Workbench to complete the integration.&#x20;

{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN and SQS URL. If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries) and OWS OU Role ARN.&#x20;

If you need help finding any of these values, see this [Reference](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, enter “AWS” and then select the AWS CloudTrail with Control Tower integration.
5. Select the bullets as follows:
   * “Are you using AWS organizations?” - AWS Organizations should leave it as **Yes**; single accounts should select **No**.
   * “Do you have an existing CloudTrail that you want Expel to reuse?” - leave it as **Yes**.
   * “How would you like to connect?” - select **Manual connection**.
6. Select **Save**.
7. On the next screen, complete the fields as follows:&#x20;
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName CloudTrail”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud” or “AWS cloud” or “on prem;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - enter the IAM Role ARN you saved earlier. Format: `arn:aws:iam::123456789012:role/RoleName`
   * **Role session name** - enter a text string to label your IAM role session, such as "orgname-expel-trail-session".
   * **AWS region** - choose the AWS region where you created your configuration in AWS.
   * **SQS URL** - enter the SQS URL you copied and saved in a previous step.
   * **Organization management account** - If you use AWS Organizations, input your AWS Account ID; single account users can leave this field blank.
   * **AWS OU ID** - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: `ou-abc1-defghi2j`); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.

     **AWS OU ID** - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: `ou-abc1-defghi2j`); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.
   * **AWS OU Role ARN** - if you entered an AWS OU ID, you will also need to enter the IAM Role ARN that contains the appropriate permissions. If you chose to add these permissions to your existing IAM Role, enter the IAM Role ARN again here. If you chose to create a new IAM Role with those permissions, enter your AWS OU Role ARN. Otherwise, leave this field blank.
8. Select **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Reference

### Permissions Description and Explanation

Expel requires these permissions when connecting to AWS CloudTrail. These permissions are set to Read, except as shown below.

<table><thead><tr><th width="244.109375">Permission</th><th>What it Does</th><th>Notes</th></tr></thead><tbody><tr><td>ec2:DescribeRegions</td><td>Dynamically list all enabled regions for a customer account</td><td> </td></tr><tr><td>ec2:DescribeInstances</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ec2:DescribeSecurityGroups</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>iam:List*</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>iam:Get*</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>lambda:GetFunction</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>rds:DescribeDBInstances</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>rds:ListTagsForResource</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>eks:DescribeCluster</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>eks:ListClusters</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ecs:ListContainerInstances</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ecs:DescribeContainerInstances</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ecs:DescribeClusters</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ecs:ListClusters</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>s3:GetBucketNotification</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>s3:GetEncryptionConfiguration</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>cloudtrail:GetTrail</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>cloudtrail:DescribeTrails</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>cloudtrail:GetTrailStatus</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>cloudtrail:ListTrails</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>organizations:ListAccounts</td><td>Enumerate accounts in an org</td><td></td></tr><tr><td>sqs:DeleteMessage</td><td>Remove Processed messages from the queue</td><td>Requires Write permission.</td></tr><tr><td>sqs:ReceiveMessage</td><td>Read messages</td><td> </td></tr><tr><td>s3:GetObject</td><td>Download cloudtrail log files</td><td> </td></tr><tr><td>ec2:DescribeVolumes</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>ecs:DescribeTaskDefinition</td><td>Inventory</td><td> </td></tr><tr><td>ecs:ListTaskDefinitions</td><td>Inventory</td><td></td></tr><tr><td>config:ListDiscoveredResources</td><td>Inventory</td><td></td></tr><tr><td>config:GetDiscoveredResourceCounts</td><td>Inventory</td><td></td></tr><tr><td>lambda:ListFunctions</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>lightsail:GetInstances</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>lightsail:GetRegions</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>s3:ListAllMyBuckets</td><td>Cloud investigative actions and inventory</td><td>Allows SOC analysts to triage issues and get additional content for the environment.</td></tr><tr><td>kms:Decrypt</td><td>Decrypt S3 buckets</td><td> </td></tr><tr><td>organizations:DescribeOrganization</td><td>Organization information</td><td>Retrieves information about the organization the user's account belongs to.</td></tr></tbody></table>

[^1]: 1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
    2. Go to **Organization Settings > My Organization**.
    3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.


# Troubleshoot AWS CloudTrail Errors

## AWS\_FILE\_READ\_FORBIDDEN

**Meaning**

The Expel role in your AWS environment does not have permission to read the CloudTrail log file.&#x20;

**Steps to Fix**

You will need to make sure the `s3:GetObject` permission is properly applied.

1. Log in to your AWS instance.
2. Navigate to your IAM service.
3. View your Expel role. This may be named "ExpelAssumeRole".
4. Examine the policy applied to the role. This may be named "expel-aws-CloudTrail-CloudTrail-manager-policy".
5. Check that the `s3:GetObject` permission is set to `Allow` and also has the correct S3 bucket resource ARN applied.

{% hint style="info" %}
[Read about applying permissions to policies (AWS)](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
{% endhint %}

Example JSON (formatting can vary):

```
{
            "Action": "s3:GetObject",
            "Effect": "Allow",
            "Resource": "insert S3 Key arn here"
       	},
```

6. Save your changes.
7. Wait a few minutes for the system to refresh, then check for the error again.

If you still see the error after the refresh is complete, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## AWS\_FILE\_DECRYPT\_FORBIDDEN

**Meaning**&#x20;

The Expel role within your AWS environment does not have permission to decrypt the CloudTrail log file.&#x20;

**Steps to Fix**

You will need to apply the correct permission to the Expel role.

1. Log in to your AWS instance.
2. Navigate to your IAM service.
3. View your Expel role. This may be named "ExpelAssumeRole".
4. Examine the policy applied to the role. This may be named "expel-aws-CloudTrail-CloudTrail-manager-policy".
5. View the permissions policy. Make sure the `kms:Decrypt` permission is set to `Allow` and that the resource contains the correct KMS Key ARN for your policy.

{% hint style="info" %}
[Read about the KMS Key ARN](https://docs.aws.amazon.com/kms/latest/developerguide/find-cmk-id-arn.html)
{% endhint %}

Example JSON:

```
{
            "Action": "kms:Decrypt",
            "Effect": "Allow",
            "Resource": "insert KMS Key ARN here"
       	},
```

6. Save your changes.
7. Wait a few minutes for the system to refresh, then check for the error again.

If you still see the error after the refresh is complete, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## AWS\_INVALID\_JSON

**Meaning**

The CloudTrail log file is not in JSON format.

**Steps to Fix**

You need to verify the format of your CloudTrail log records.

1. Log in to your AWS instance.
2. Navigate to your S3 service.
3. Open the bucket containing the CloudTrail logs.

{% hint style="info" %}
This is the bucket you selected when you set up CloudTrail. If you do not know it, navigate to your CloudTrail service on the CloudTrail service dashboard. Under general details, view the Trail log location. This shows the S3 bucket containing your CloudTrail logs. [Read about working with CloudTrail log files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)
{% endhint %}

4. Find the relevant logs within the bucket and make sure they are in JSON format.

If the format is correct and you are otherwise unable to determine the source of your issue, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## AWS\_NON\_TAR\_FILE

**Meaning**

The CloudTrail log file is not in the targ.gz format.&#x20;

**Steps to Fix**

You need to confirm the S3 bucket contains compressed JSON files with the .gz file extension.

1. Log in to your AWS instance.
2. Navigate to your S3 service.
3. Open the bucket containing the CloudTrail logs.\
   This is the bucket you selected when you set up CloudTrail.

{% hint style="info" %}
This is the bucket you selected when you set up CloudTrail. If you do not know it, navigate to your CloudTrail service on the CloudTrail service dashboard. Under general details, view the Trail log location. This shows the S3 bucket containing your CloudTrail logs. [Read about working with CloudTrail log files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)
{% endhint %}

4. Find the relevant logs within the bucket and make sure they are in the proper format. If they are in the wrong format, view AWS documentation (linked above) for help getting your log files into the tar.gz format.

If the format is correct and you are otherwise unable to determine the source of your issue, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## AWS\_NO\_RECORDS\_IN\_S3\_FILE

**Meaning**

No records were found in the S3 file. This error is caused by a configuration of CloudTrail that is not compatible with how Expel reads logs.

**Steps to Fix**

You need to confirm the CloudTrail is writing logs to the correct S3 log bucket.&#x20;

1. Log in to your AWS instance.
2. Navigate to your S3 service.
3. Open the bucket containing the CloudTrail logs.

{% hint style="info" %}
This is the bucket you selected when you set up CloudTrail. If you do not know it, navigate to your CloudTrail service on the CloudTrail service dashboard. Under general details, view the Trail log location. This shows the S3 bucket containing your CloudTrail logs. [Read about working with CloudTrail log files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)
{% endhint %}

4. Look in the folders and make sure they are not empty. If they are empty, check your CloudTrail configuration.

If you are unable to determine the source of your issue, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## AWS\_LOG\_FILE\_NOT\_FOUND

**Meaning**

No log file was found in the S3 bucket.&#x20;

**Steps to Fix**

You need to confirm the CloudTrail is writing logs to the correct S3 log bucket.

1. Log in to your AWS instance.
2. Navigate to your S3 service.
3. Open the bucket containing the CloudTrail logs.

{% hint style="info" %}
This is the bucket you selected when you set up CloudTrail. If you do not know it, navigate to your CloudTrail service on the CloudTrail service dashboard. Under general details, view the Trail log location. This shows the S3 bucket containing your CloudTrail logs. [Read about working with CloudTrail log files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html)
{% endhint %}

4. Look in the folders and make sure they are not empty. If they are empty, do the following:
   * Make sure the notification service is connected to the correct S3 log bucket.
   * Check your CloudTrail configuration.<br>
   * Check if the log file was deleted. *Expel cannot delete your log files, so a deletion would have happened on the AWS account owner's side. Check with your AWS console and team to determine why this happened.*

If you are unable to determine the source of your issue, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

## Botocore.exceptions.ClientError

**Full Error**

`Botocore.exceptions.ClientError: An Error Occurred (AccessDenied) When Calling the AssumeRole Operation: User: arn:aws:iam::012205512454:user/ExpelCloudService Is Not Authorized to Perform: sts:AssumeRole on Resource: arn:aws:iam::*****:role/ExpelCloudTrailAccessRole`

**Meaning**

Expel does not have permission to use the AssumeRole.

Steps to fix:

1. Log in to your AWS instance.
2. Navigate to your IAM service.
3. View your Expel role. This may be named "ExpelAssumeRole".
4. Examine the policy applied to the role. This may be named "expel-aws-CloudTrail-CloudTrail-manager-policy".
5. Verify the trust policy exists, in case it was omitted during configuration.
   1. If the trust policy does not exist, create the policy using the JSON code below.
   2. If the trust policy exists, make sure it has the correct [Workbench GUID](#user-content-fn-1)[^1] as the `sts:ExternalId`.&#x20;

The trust policy should look like this:

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111111111:user/ExpelCloudService"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "INSERT ORGANIZATION GUID"
                }
            }
        }
    ]
}
```

6. Wait a few minutes for the system to refresh, then check for the error again.

If you still see the error after the refresh is complete, [contact Support](/support). Be sure to document all the steps you tried, and list the error specifically.

[^1]: * [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
    * Go to **Organization Settings > My Organization**.
    * On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.


# Amazon Elastic Kubernetes Service Setup for Workbench

The Expel Amazon Elastic Kubernetes Service (EKS) consumes audit logs from the AWS platform through Kinesis. This visibility allows Workbench to identify activity of interest in EKS, investigate, and notify organizations if action is recommended.

<figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FaGlOLEYW1z7y51lWnt3X%2Famazon_EKS.png?alt=media&amp;token=050f829a-e17c-43a3-8183-e3bc19a97748" alt="An image of the Amazon EKS flow into Expel."><figcaption></figcaption></figure>

## Step 1: Enable Control Plane Logging for Each EKS Cluster

At a minimum, Workbench requires logging of the audit events for each cluster. This provides visibility into activity affecting resources in the cluster: the “who, what, and when” we need to detect and take action. After control plane logging is enabled, EKS begins sending logs to CloudWatch.

To complete this step, update the logging configuration **for each cluster in each region** with the AWS CLI:

```
CLUSTER_REGION=<your-cluster-region> ; \
CLUSTER_NAME=<your-cluster-name> ; \
aws eks update-cluster-config \
  --region ${CLUSTER_REGION} \
  --name ${CLUSTER_NAME} \
  --logging '{"clusterLogging":[{"types":["audit"],"enabled":true}]}'
```

For additional help, see the [Amazon reference guide](https://docs.aws.amazon.com/eks/latest/userguide/control-plane-logs.html).

## Step 2: Create a Kinesis Stream

Logs must be routed from CloudWatch to a Kinesis data stream so Workbench can consume the logs in real time.

1. Create a stream with the AWS CLI tool and note the following:
   * The value of `K_STREAM_NAME` must be different for each separate region.
   * We recommend creating an `“ON_DEMAND”` stream to allow the stream to adjust capacity based on demand.

```
CLUSTER_REGION=<your-cluster-region> ; \
K_STREAM_NAME=expel-aws-eks-kinesis-data-stream ; \
aws kinesis create-stream \
  --region ${CLUSTER_REGION} \
  --stream-name ${K_STREAM_NAME} \
  --stream-mode-details '{"StreamMode": "ON_DEMAND"}'
```

2. Note the `Kinesis Stream ARN` that the code CLI generates for use in later steps; the ARN is different for reach region:

```
CLUSTER_REGION=<your-cluster-region> ; \
K_STREAM_NAME=expel-aws-eks-kinesis-data-stream ; \
aws kinesis describe-stream-summary --stream-name=${K_STREAM_NAME} --region=${CLUSTER_REGION}
```

## Step 3: Create an IAM Role for CloudWatch Log Delivery

An IAM role is required to allow CloudWatch to deliver logs to your Kinesis stream.

{% hint style="info" %}
The sample code writes a policy JSON definition to **expel\_cw\_assume\_role\_trust**\
**\_policy\_doc.json** in the current directory. For convenience, the system creates a JSON document of the same name on the local machine.
{% endhint %}

1. Create a trust policy document that allows the CloudWatch service to assume the role:

```
AWS_REGION=<your-aws-region> ; \
AWS_ACCOUNT_ID=<your-aws-account-id> ; \
cat > expel_cw_assume_role_trust_policy_doc.json << EOF
{
  "Statement": {
    "Effect": "Allow",
    "Principal": { "Service": "logs.${AWS_REGION}.amazonaws.com" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringLike": { "aws:SourceArn": "arn:aws:logs:${AWS_REGION}:${AWS_ACCOUNT_ID}:*" }
    }
  }
}

EOF
```

2. Create the IAM role with the **expel\_cw\_assume\_role\_trust\_policy\_doc.json** document:

```
EXPEL_CW_ASSUME_ROLE_NAME=expel-aws-eks-cloudwatch-assume-role ; \
aws iam create-role \
  --role-name ${EXPEL_CW_ASSUME_ROLE_NAME} \
  --assume-role-policy-document file://expel_cw_assume_role_trust_policy_doc.json  
```

## Step 4: Update the IAM Policy for the Producer Role

1. Create an IAM policy document that grants the following role permissions to put records into your Kinesis stream:

```
K_STREAM_ARN=<kinesis stream ARN saved in earlier step> ; \
cat > expel_iam_policy_doc.json << EOF
{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "kinesis:PutRecord",
      "Resource": "${K_STREAM_ARN}"
    }
  ]
}

EOF
```

2. Apply the policy to the CloudWatch (producer) role:

```
EXPEL_CLOUDWATCH_ROLE_NAME=expel-aws-eks-cloudwatch-assume-role; \
EXPEL_IAM_POLICY_NAME=expel-aws-eks-producer-policy; \
aws iam put-role-policy \
   --role-name "${EXPEL_CLOUDWATCH_ROLE_NAME}" \
   --policy-name "${EXPEL_IAM_POLICY_NAME}" \
   --policy-document file://expel_iam_policy_doc.json
```

## Step 5: Route Logs From CloudWatch to Kinesis

Logs must be routed to Kinesis with a CloudWatch log group subscription filter. Create the filter with the AWS CLI:

```
K_STREAM_ARN=<kinesis stream ARN saved in earlier step> ; \
EKS_LOG_GROUP_NAME=<your choice of log group name> ; \
CLUSTER_AWS_REGION=<your-aws-region> ; \
EXPEL_CLOUDWATCH_ROLE_NAME=expel-aws-eks-cloudwatch-assume-role ; \
aws logs put-subscription-filter \
  --region ${CLUSTER_AWS_REGION} \
  --log-group-name ${EKS_LOG_GROUP_NAME} \
  --filter-name "AllEKSLogs" \
  --filter-pattern "" \
  --destination-arn ${K_STREAM_ARN} \
  --role-arn ${EXPEL_CLOUDWATCH_ROLE_NAME}
```

## Step 6: Create an IAM Role for Expel

{% hint style="warning" %}
If you already have an IAM role for another integration (like CloudWatch or Amazon GuardDuty), the existing role can be reused and you can skip to [Step 7](#step-7-grant-the-iam-role-permissions).
{% endhint %}

To authenticate to your AWS account and retrieve logs, Expel requires an IAM role.&#x20;

{% hint style="info" %}
For convenience, the system creates a JSON document named **expel\_wb\_iam\_role\_policy\_doc.json** on the local machine.
{% endhint %}

1. Create a trust policy document that allows Workbench to assume the role. Make sure to use your own [Workbench GUID](#user-content-fn-1)[^1]:

```
ORG_GUID=<Your workbench org_guid(formerly customer id)> ; \
cat > expel_wb_iam_role_policy_doc.json << EOF
{
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "arn:aws:iam::012205512454:user/ExpelCloudService" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "${ORG_GUID}" }
      }
    }
  ]
}

EOF
```

2. Create the IAM role with the **expel\_wb\_iam\_role\_policy\_doc.json** document:

```
EXPEL_ASSUME_ROLE_NAME=ExpelServiceAssumeRole ; \
      aws iam create-role \
        --role-name ${EXPEL_ASSUME_ROLE_NAME} \
        --assume-role-policy-document file://expel_wb_iam_role_policy_doc.json
```

## Step 7: Grant the IAM Role Permissions

We require certain IAM permissions to retrieve logs from Kinesis and to investigate the activity of interest affecting your EKS clusters.

1. Create an IAM policy document that grants Workbench the required permissions for Kinesis and EKS:

```
K_STREAM_ARN=< kinesis stream ARN saved in earlier step > ; \
cat > expel_k8s_ro_policy_doc.json << EOF
{
    "Version": "2012-10-17",
    "Statement": [
      {
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeLimits",
                "kinesis:DescribeStream",
                "kinesis:DescribeStreamSummary",
                "kinesis:GetRecords",
                "kinesis:GetShardIterator",
                "kinesis:ListShards"
            ],
          "Resource": "${K_STREAM_ARN}"
        },
        {
            "Effect": "Allow",
            "Action": [
                "eks:AccessKubernetesApi",
                "eks:DescribeCluster",
                "eks:DescribeNodegroup",
                "eks:ListClusters",
                "eks:ListNodegroups",
                "eks:ListUpdates",
                "sts:GetCallerIdentity",
                "ec2:DescribeRegions",
                "autoscaling:DescribeAutoScalingGroups"
            ],
            "Resource": "*"
        }
    ]
}

EOF
```

2. Apply the policy to the Expel IAM role:

```
EXPEL_ASSUME_ROLE_NAME=ExpelServiceAssumeRole ; \
EXPEL_EKS_CONSUMER_POLICY_NAME=expel-aws-eks-eks-consumer-policy ; \
aws iam put-role-policy \
  --role-name ${EXPEL_ASSUME_ROLE_NAME} \
  --policy-name ${EXPEL_EKS_CONSUMER_POLICY_NAME} \
  --policy-document file://expel_k8s_ro_policy_doc.json
```

## Step 8: Add Amazon EKS as a Security Device in Workbench

In this step we will add Amazon EKS as a security device and then enable network access by allowing specific IP addresses in AWS.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. Scroll down or search "Kubernetes (EKS)" and select Kubernetes Service (EKS).
5. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName EKS”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - enter the ARN for the cluster role you created in [Step 6](#step-6-create-an-iam-role-for-expel).
   * **Role Session Name** - we recommend "ExpelSession", but you may enter any name you like.
   * **Region** - enter the AWS region containing the Kubernetes cluster.
   * **Kinesis Stream Name** - enter the log stream name you created in [Step 2](#step-2-create-a-kinesis-stream).
6. Select **Save**.
7. Next, enable network access by adding [the IP addresses listed in this article](/workbench-setup/configure-an-ip-allow-list) to your allow list in AWS.

## Reference

This integration requires configuration of certain resources in order to function. Refer to the following list for details:

<table><thead><tr><th width="274.08203125">Resource</th><th>Purpose</th></tr></thead><tbody><tr><td>Kinesis Stream</td><td>MDR</td></tr><tr><td>Kinesis Stream Filter</td><td>MDR</td></tr><tr><td>IAM Role</td><td>MDR</td></tr><tr><td>IAM Policy “Puts” (binds)</td><td>Inventory/metrics</td></tr><tr><td>Network Allow Rule</td><td>All Workbench investigation access</td></tr></tbody></table>

[^1]: * [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
    * Go to **Organization Settings > My Organization**.
    * On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.


# AWS GuardDuty


# AWS GuardDuty Setup for Workbench

This setup guide helps you connect AWS GuardDuty to Workbench.

## Prerequisites

1. You must have an AWS account with permissions to create and change IAM roles.
2. If you use AWS Organizations, make sure you have your AWS Account ID.
3. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the AWS Organizational Unit (OU) ID for the subsidiary.
   * This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.

If you need help finding any of these values, see this [Reference](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail#reference) section.

## Before You Begin

Choose your onboarding method:

* **If you prefer to use a wizard,** which leverages CloudFormation templates, skip to [Step 3](#step-3-add-aws-guardduty-as-a-security-device-in-workbench). You will need your AWS account ID and AWS region. &#x20;
* **If you prefer to follow the manual setup instructions**, continue to [Step 1.](#step-1-create-an-aws-iam-policy)

## Step 1: Create an AWS IAM Policy

{% hint style="warning" %}
**This step is only for those choosing manual setup.** In addition:

* **AWS GuardDuty Delegated Admin accounts:** complete the following steps in the account's primary region (you will only add one security device in Workbench).
* **All other account types:** complete the following steps for *each account* you want monitored (every account will need its own security device in Workbench).
  {% endhint %}

In this step, you will create a permissions policy to assign to the IAM Role.

1. Log into the AWS console and navigate to the **IAM service**.
2. Go to **Policies** and select **Create Policy**.
3. Add the following permissions using the JSON tab:

```
{
   "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "guardduty:GetFindings",
                "guardduty:ListDetectors",
                "ec2:DescribeRegions",
                "guardduty:ListFindings",
                "guardduty:GetDetector"
            ],
             "Resource": "*"
        }      
    ]
}
```

4. Review the policy and give it a name.

## Step 2: Create an IAM Role

{% hint style="warning" %}
**This step is only for those choosing manual setup.** In addition:

* **AWS GuardDuty Delegated Admin accounts:** complete the following steps in the account's primary region (you will only add one security device in Workbench).
* **All other account types:** complete the following steps for *each account* you want monitored (every account will need its own security device in Workbench).
  {% endhint %}

In this step, you will create an IAM role to connect to your AWS GuardDuty Service.

1. From within the IAM service, navigate to **Roles** and select **Create Role**.
2. Select **Another AWS account** and fill out the required fields:
   * **Account ID** - enter `012205512454` (the Expel AWS account ID).
   * **External ID** - this is your [Workbench GUID](#user-content-fn-1)[^1].
3. Attach the IAM policy from Step 1 to the role.
4. Give the role a name and then select **Create Role**.
5. Navigate to the role you just created and copy the following information, as you will need it in the next step.
   * Role ARN
   * External ID Value (on the Trust relationships tab)

{% hint style="warning" %}
If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, you will need to either edit this IAM Role to add two additional permissions for Expel, or create a separate IAM role with those permissions.&#x20;

The two additional permissions are:

* `organizations:ListAccountsForParent`
* `organizations:ListOrganizationalUnitsForParent`

If you wish to create a separate IAM Role with the two permissions, make sure to save that IAM Role ARN as your **AWS OU Role ARN**. You will need it when you set up the security device in Workbench.
{% endhint %}

## Step 3: Add AWS GuardDuty as a Security Device in Workbench

{% hint style="info" %}
Before you begin, make sure you have your IAM Role ARN and Role Session Name. If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries). If you need additional help finding any of these values, see this [Reference](/connect-your-technology/a-c-integrations/amazon-aws/aws-cloudtrail/aws-cloudtrail-manual-setup-new-trail#reference) for detailed instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. Scroll down or search "AWS" and select AWS GuardDuty.
5. Do one of the following:
   * Select **Connect manually >>** and continue to step 6.
   * Select **Connect with wizard >>** and follow the on-screen instructions to complete the setup.
6. For manual setup, complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName GuardDuty”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud;” this is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **Role ARN** - enter the Role ARN from [Step 2](#step-2-create-an-iam-role).
   * **Role session name** - enter a unique name to identify the role.
   * **AWS region** - select the region of the primary AWS GuardDuty account.
   * **AWS OU ID** - if you use AWS Organizations to centralize CloudTrail logs from multiple subsidiaries into a single S3 bucket, enter the AWS OU ID for the relevant subsidiary (format: `ou-abc1-defghi2j`); otherwise, leave this field blank. This field tells our system to filter the logs based on that ID, ensuring that each subsidiary's Workbench instance only ingests and analyzes the logs relevant to its own accounts, which helps prevent any overlap of data.
   * **AWS OU Role ARN** - if you entered an AWS OU ID, you will also need to enter the IAM Role ARN that contains the appropriate permissions. If you chose to add these permissions to your existing IAM Role, enter the IAM Role ARN again here. If you chose to create a new IAM Role with those permissions, enter your AWS OU Role ARN. Otherwise, leave this field blank.
7. Select **Save**.

{% hint style="warning" %}
If you are *not* using a GuardDuty Delegated Admin account, you must repeat these steps for each account you want monitored.
{% endhint %}

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

[^1]: - [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
    - Go to **Organization Settings > My Organization**.
    - On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.


# AWS GuardDuty GovCloud Setup for Workbench

This topic helps you connect AWS GuardDuty GovCloud to Workbench.

## Scope and Limitations

When choosing to set up this integration, remember the following:

* You cannot set up this integration via CloudFormation templates or terraform; you must use the manual steps as described in this guide.
* The AWS GuardDuty account must be in a GovCloud region (for example, us-gov-east-1).

## Prerequisites

1. Make sure you know your **Workbench GUID** (you will need it when you create the IAM role).
   * If you need help finding this value, see the [Reference](#workbench-guid) section.
2. You must have an AWS account with permissions to create and change IAM roles.
3. If you use AWS Organizations, make sure you have your AWS Account ID.
4. If your organization centralizes CloudTrail logs from multiple subsidiaries into a single S3 bucket, make sure you know the **AWS Organizational Unit (OU) ID** for the subsidiary.
   * This is an optional prerequisite that enables us to filter logs so that only the relevant data is sent to each subsidiary's Workbench instance, preventing data overlap.

## Before You Begin

Determine whether or not you are using an **AWS GuardDuty Delegated Admin account**.

* If so, you can complete the steps in this guide once, and add a single security device within Workbench for the delegated admin account's primary region.
* If not, you must complete the steps in this guide for each account you want monitored, and add separate security devices within Workbench for each account.

## Step 1: Create an IAM Policy

1. Log in to the AWS GovCloud console and navigate to the **IAM service**. *Make sure you are in GovCloud; you cannot perform this step in GuardDuty.*
2. Go to **Policies** and select **Create Policy**.
3. Add the following permissions using the JSON tab:

```
{
   "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "guardduty:GetFindings",
                "guardduty:ListDetectors",
                "ec2:DescribeRegions",
                "guardduty:ListFindings",
                "guardduty:GetDetector"
            ],
             "Resource": "*"
        }      
    ]
}
```

4. Review and name the policy. *Make a note of the policy name, as you will need to attach it to the IAM role in the next step.*

## Step 2: Create an IAM Role

Before you begin, make sure you have your [Workbench GUID](#workbench-guid).

1. Still in GovCloud and from within the IAM service, navigate to **Roles**.
2. Select **Create Role**.
3. Create a new role, and use the following custom trust policy (make sure to add your Workbench GUID where indicated):

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws-us-gov:iam::071857701673:user/ExpelCloudService"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<YOUR_WORKBENCH_GUID>"
                }
            }
        }
    ]
}
```

4. Attach the IAM policy you created in Step 1 to the role.
5. Copy and save the **Role ARN**, as you will need it for the security device in Workbench.

## Step 3: Add AWS GuardDuty as a Security Device in Workbench

{% hint style="info" %}
You will use the AWS GuardDuty device for your GovCloud integration.
{% endhint %}

Before you begin, make sure you have your IAM Role ARN and Role Session Name. If you use AWS Organizations, you will also need your AWS Account ID as well as the subsidiary's AWS Organizational Unit (OU) ID (the OU ID is only necessary if you use a single S3 bucket for multiple subsidiaries). If you need additional help finding any of these values, see the Reference for detailed instructions.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings** > **Security Devices**. If you have multiple organizations, you must select the appropriate organization name from the list.
3. Select **Add Security Device**.
4. In the search box, enter “GuardDuty” and then select the AWS GuardDuty integration.
5. Select the **Connect manually** option.
6. You will then see the following fields, which you should complete as follows:
   * **Name** - enter the host name of the AWS GuardDuty device.
   * **Location** - enter the geographic location of the appliance.
   * **Role ARN** - enter the Role ARN from Step 2.
   * **Role session name** - enter a unique name to identify the role.
   * **AWS Region** - enter the GovCloud region of the AWS GuardDuty account (for example, us-gov-east-1).
   * **AWS OU ID** - leave this field blank unless it applies to you.
   * **AWS OU Role ARN** - leave this field blank unless it applies to you.
7. Select **Save**.
8. You should now [contact Support](/support/how-to-reach-us/technical-support) so that we can manually enable event ingestion.

{% hint style="warning" %}
**Important:** If you are *not* using an AWS GuardDuty Delegated Admin account, you must now repeat **all** of the steps in this guide (beginning at [Step 1](#step-1-create-an-iam-policy)) for each account you want monitored.
{% endhint %}

## Reference <a href="#reference" id="reference"></a>

### Workbench GUID

The **Workbench GUID** is a unique alphanumeric value assigned by Expel to your organization. To find it:

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. Go to **Organization Settings > My Organization**.
3. On the organization's page, look for the Organization GUID and select the **Copy** button to copy the GUID.

If you have multiple organizations, you must first select the organization name that will be associated with your integration to access the page with the Copy button. Or, you can stay on the page and highlight then copy the GUID shown for that organization in the GUID column.


# Anthropic Claude Enterprise Compliance API Setup for Workbench

Integrating your Anthropic Claude Enterprise Compliance API with Workbench allows Expel to access necessary activity fields to provide security coverage for your Claude.AI / Claude App Enterprise, Claude Cowork, and Claude Code instances. After the integration is configured and the t device onboarded, Expel will be able to filter through your data programmatically, add context, enrich it with intel, assess risk, and alert an Expel analyst for further investigation.

Expel will support Claude Code and Cowork as separate products in late 2026.

Learn more about [Expel MDR for AI](/more-features/expel-mdr-for-ai/about-expel-mdr-for-ai).

## About the Anthropic Compliance API

Expel will be able to ingest activity fields, prompt messages, and tool calls for Claude.ai, Claude Code, and Claude Cowork for this API. However, the coverage Expel provides depends on the SKU purchased. These three products have inherently different capabilities and function differently in relation to the machine a user is using with these products. These reasons dictate that the detection coverage between all three are slightly different, implying different levels of security value and cost.

If your organization primarily uses Claude.ai and other tooling similar to that, then the **MDR for AI** product may be the best fit for you. However, if your organization uses Claude Cowork and Claude Code products heavily, then purchasing **MDR for AI Security + AI Workflow and Development** is likely a better fit because it would entitle you to receive detections for all Anthropic products and products similar to them in the future.

## Scope and Limitations

* When provisioning a Claude Compliance Access Key, Expel will require an admin to create an API Key with up to two permission scopes.&#x20;
  * Required for **control plane** detections: `read:compliance_activities` scope. This will allow detections to be triggered off the activity fields in the API.&#x20;
  * Required for **content plane** detections: `read:compliance_user_data` scope. This will allow Expel to monitor prompts being input by users and resulting agent tool calls and interactions to detect suspicious or malicious commands ,attempts, and processes.

## Prerequisites

1. You must have admin access in Workbench to set up this integration.
2. You must have an active SKU with Expel MDR for On-Prem as well as MDR for SaaS Applications and Identity coverage to receive alerts from this integration.
3. You must have an MDR for AI SKU.
4. You must have the Claude Enterprise plan. This integration does not cover Claude free, Team, or Pro plans.
5. You must have access to an Anthropic account with either the Organizational Admin or Primary Owner role in order to create API keys with the appropriate scope(s).
6. You must have the Anthropic Compliance API enabled for your organization.

## Step 1: Create Compliance API Credentials for Expel

1. [Log in to Claude](https://claude.ai/login) as an Organization Admin or Primary Owner.
2. Navigate to **Organization settings > API**.
3. In the **Keys** section, select **Create Key**.
4. For **Name**, enter "expel-key".
5. Select the following **Scopes**:
   * `read:compliance_activities`&#x20;
   * `read:compliance_user_data` <br>

     <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fpdl3rVc5BiBEpRf6EzrZ%2Fanthropic_claude_creatAPIkey.png?alt=media&amp;token=8fc32c46-f2cb-480c-a097-6aae71e7c002" alt="Create API key dialog shows &#x22;expel-key&#x22; entered as the key name, and has the two specified scopes selected." width="375"><figcaption></figcaption></figure></div>
6. Select **Create**.
7. **Copy and save** the displayed API key in a safe place for use in a later step. *The full secret is only shown once.*

## Step 2: Add Claude Anthropic (Compliance API) as a Security Device in Workbench

Now that you have the necessary credentials, you can configure the integration in Workbench.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, type “Anthropic” and then select the **Anthropic (Compliance API)** integration.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F4S91EViyMASlpN0itl1j%2Fwb_anthropic_claude_add_security_device.png?alt=media&amp;token=a585f693-1555-49b4-a854-5b302839e6b2" alt="Add Security Device screen for Claude Anthropic (Compliance API) includes fields Name, Location, and API key." width="328"><figcaption></figcaption></figure></div>
5. A configuration pane displays. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Anthropic Claude Compliance API”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud.” This is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * **API key** - enter the API Key you generated in [Step 1](#step-1-create-compliance-api-credentials-for-expel).
6. Select **Save**.
7. On the console access screen, select **No thanks, I will not provide console access.** from the dropdown.
8. Select **Save**.
9. Your device should be created successfully within a few seconds. A few reminders:
   * After your connection is healthy, it will take some time for your device to begin polling and receiving data.
   * To check on the status, select the downward arrow for your device in the first column and choose **View details**.
   * Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
   * If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team](/support) for help.
   * To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

## Step 3: (Optional) Create Allow Lists for Workbench

If you would like to opt to receive DUET notifications for unsanctioned Model Content Protocol (MCP) servers, Plugins, or Claude Skills, you can do so by supplying Expel with three distinct allow lists for us to enable in Expel Workbench. **Activity outside of these lists will be flagged by our detections.**

You will provide the values for the allow lists to your Customer Success Manager (CSM) or Implementation Engineer and they will configure them in Workbench on your behalf.

{% hint style="warning" %}
Activity **not** allowed-listed will be detected and could result in noise.
{% endhint %}

1. Download the .xlsx file provided below and open it in spreadsheet software like Excel or Google Sheets. Use the following instructions to find and input the values required to create your allow lists.

{% file src="/files/VPLfBULkzMcpiQO2Rmsr" %}

2. Create your **MCP Server Hosts Allowlist**:

* In Claude, navigate to **Settings > Connectors** and select an available Connector.
* Use the three dots menu in the upper right to select **View Details**.
* Locate the **Connector URL** value in the Details section.
* Provide only the **domain name(s)**, and insert each in column A of the spreadsheet.

  <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FP7hwLt0CttxtCffE4ddx%2Fanthropic_claude_url_connector_domain_highlight.png?alt=media&amp;token=21b8ebbb-f32e-43d2-b3d5-57b1769c3ae4" alt="In the example, just the domain is highlighted: &#x22;drivemcp.googleapis.com&#x22;." width="329"><figcaption></figcaption></figure></div>

3. Create your **Plugins Allowlist**:
   * In Claude, navigate to **Settings > Plugins**.
   * Provide the plugin names in column B of the spreadsheet. Note that multi-word names should be hyphenated and lowercase, for example: `pdf-viewer` or `bio-research`.
   * Plugins also install **skills**, so be sure to add those to your **skills allow list** in the next step.
4. Create your **Skills Allowlist**:
   1. In Claude, navigate to **Settings > Skills**.
   2. Provide the skill names in column C of the spreadsheet.
5. Your resulting spreadsheet may look something like this:<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2Fuf9WOFgeQv9ua3sKwCtv%2Fanthropic_claude_csv_example.png?alt=media&amp;token=96495a67-b2e1-4999-8a0e-09d263ac804e" alt="Screenshot of spreadsheet shows values in columns titled MCP Server Hosts Allowlist, Plugins Allowlist, Skills Allowlist." width="563"><figcaption></figcaption></figure></div>

   \
   **Save and send** this file to your Expel CSM or Implementation Engineer via your preferred communication method. They will input your lists into Workbench and confirm when it is complete.


# Arista NDR (via Webhook) Setup for Workbench

## Prerequisites

1. You must have admin access in Workbench to set up this integration.
2. You must have user and role creation privileges in Arista NDR.

## Step 1: Add a New User Account in Arista NDR

1. Log in to Arista NDR.
2. Select the **Settings** (gear) icon in the top right.
3. Select **Users** from the dropdown.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FviOCIqDR16ruo60VmIqo%2Funknown.png?alt=media&amp;token=1e633df0-6f32-473e-993d-799f3c9f9601" alt="Select Users in the Settings dropdown." width="117"><figcaption></figcaption></figure></div>
4. On the Manage Users & Roles page, select **Add New User**.
5. Configure the New User as follows:
   * **Username** - enter "expel\_analyst".
   * **Display Name** - enter "Expel Analyst".
   * **Email** - enter "soc+\<Your\_Organization\_Name>@expel.io".
     * For example, if your organization were Acme Corp, the format would be "<soc+acme_corp@expel.io>".
   * **Initial Password** - specify a password for the new account.
   * **Confirm Password** - confirm the new account password.
6. Still in the New User window, select the **Roles & Capabilities** tab.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FDdnz6Wl6YeTivScb76Oa%2Funknown.png?alt=media&amp;token=174a2d98-3698-482c-a59d-c0f63b851e28" alt="Tier 3 Analyst is selected in the dropdown in the Roles &#x26; Capabilities tab." width="375"><figcaption></figcaption></figure></div>
7. Clear the default role and use the dropdown to assign the **Tier 3 Analyst** role.
8. Select **Save**.

## Step 2: Add Arista NDR as a Security Device and Obtain Webhook Credentials in Workbench

Now that you have the necessary credentials, you can configure the integration in Workbench.

{% hint style="warning" %}
For On-Prem, you need to add each Nucleus individually based on the below instructions.
{% endhint %}

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, type “Arista” and then select the **Arista NDR (via Webhook)** integration.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F6uFI07YLb6vuw6P6uMgE%2Funknown.png?alt=media&amp;token=41480c6c-1153-4ed8-b6fa-866dfa80c2cc" alt="Arista NDR Add a Device screen in Workbench." width="327"><figcaption></figcaption></figure></div>
5. A configuration pane displays. Complete the fields as follows:
   * **Where is your device?** - select **Cloud** or **On-Prem** (on-premises) installation.
     * **For On-Prem**, choose the assembler that will be forwarding the logs.
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Arista NDR”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   * **Location** - enter the location of your integration, for example “cloud.” This is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   * For now, **skip the Webhook fields**.
   * **Console URL** - enter the URL used to log in to Arista NDR.
   * **Arista NDR API login username** - enter the username created in [Step 1](#step-1-add-a-new-user-account-in-arista-ndr).
   * **Arista NDR API login password** - enter the password created in [Step 1](#step-1-add-a-new-user-account-in-arista-ndr).
6. Select **Save**.
7. On the console access screen, select **Set up now (recommended)** from the dropdown and provide your Arista console URL and the user credentials from [Step 1](#step-1-add-a-new-user-account-in-arista-ndr).
8. Select **Save**.
9. On the Security Devices page, select the dropdown arrow for the Arista NDR device you just onboarded and select **Edit**.<br>

   <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FUFBdfmjMX3YHWXG0Y877%2Funknown.png?alt=media&amp;token=48321e2d-73b8-425d-8f53-75dcf2a36530" alt="Select Edit in the device dropdown." width="186"><figcaption></figcaption></figure></div>
10. In the Connection Settings section, webhook credentials have been automatically generated and  populated. **Copy and save the URL and credentials** for use in the next step.<br>

    <div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F7a4WFycbZmjT6tdbV4eg%2Funknown.png?alt=media&amp;token=01bde050-e80d-4b14-b6c1-becdbed15f27" alt="Webhook credentials will be populated in the Connection Settings section of the Security Device." width="375"><figcaption></figcaption></figure></div>

## Step 3: Configure Forwarding Alerts from Arista NDR to Expel

Now that you have the webhook credentials, you can configure alert forwarding to Expel's Workbench by adding a new Skill in Arista NDR.

{% hint style="warning" %}
If your device is on-prem, you will need to configure the skill on each Nucleus for each Security Device integration.
{% endhint %}

1. In Arista NDR, use the sidebar to navigate to **Manage Detections > Skills**.
2. Select **+ Create**.
3. On the **Add Skill** page, configure the fields as follows:
   * **Expression** - enter the code snippet provided below, substituting `<TOKEN>` and `<PATH>` according to your webhook credentials.\
     \
     For `<PATH>`, capture the URI from the generated **webhook URL**: \
     `https://push-ingest.opsv2.expel.io/`**`<PATH>`**\
     \
     For `<TOKEN>`, you will need to generate a base64 encoded TOKEN from the webhook username and password. See below for instructions:

{% tabs fullWidth="false" %}
{% tab title="Windows" %}
In Powershell, run the following command:\
`[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))`
{% endtab %}

{% tab title="Unix-Like Systems" %}
In Terminal, run the following command:\
`echo -n "username:password" | base64`
{% endtab %}
{% endtabs %}

**Use the two values in the code below:**

{% hint style="info" %}
Be sure to include “Basic “ in front of the token as well as the leading forward slash in front of the PATH. (Do not include the < >).
{% endhint %}

```
integrations.json.https 
  true  
  { headers: [{fst: "Authorization", snd: "Basic <TOKEN>" }] // Content-Type: application/json is added by default 
  , host: "push-ingest.opsv2.expel.io"
  , path: "/<PATH>" 
  , port: 443 
  }
```

Resulting code example:

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FnGhax5xRN0eIM67qJBtW%2Fcode_Example_3.png?alt=media&amp;token=66371eee-94c9-45a4-9a58-91ee44872b6c" alt="Expression shows the code with the token included in line 3 and the path in line 5."><figcaption></figcaption></figure></div>

* **Name** - enter "Send alerts to Expel".
* **Reference Identifier** - enter a unique identifier of your choice.

4. Select **Save**.
5. If possible, trigger an alert in Arista or ensure an alert is received in Workbench to verify the configuration was successful.

To check if alerts are coming through in Workbench, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).

To check on the status of the device in Workbench, navigate to **Organization Settings > Security Devices**. Select the downward arrow for your device in the first column and choose **View details**.


# Aurora Endpoint Security (formerly Cylance PROTECT AV) Setup for Workbench

## Step 1: Enable Console Access for Expel <a href="#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26487" id="uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26487"></a>

Having read-only access to the interface of your technology allows Expel to dig deeper during incident investigations. Our device health team uses this access to investigate potential health issues with your tech. For more information, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access).

1. Log in to the Aurora Endpoint Security Console as an administrator.
2. Click **Settings > Users**.
3. Add a user for Expel with a Read-Only role.

## Step 2: Generate API Credentials <a href="#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492" id="uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492"></a>

To integrate the technology with Workbench, we need to create secure credentials to the API.

1. Log in to the Aurora Endpoint Security Console **as an administrator**. Only administrators can create an application integration.
2. Select **Settings > Integrations**.
3. Click **Add Application**.
4. Type an **Application Name**. This must be unique within your organization.
5. Select **Threats READ**, **Devices READ**, and **Users READ** privileges.
6. Click **Save**. The application credentials appear.
7. Copy the **Tenant ID** located in the **Integrations** page and save for onboarding in Workbench.
8. Note your Cylance Service Endpoint. This can be found by mapping your CylanceENDPOINT in the table below.

| URL                                 | Service endpoint                       |
| ----------------------------------- | -------------------------------------- |
| <https://protect-apne1.cylance.com> | <https://protectapi-apne1.cylance.com> |
| <https://protect-euc1.cylance.com>  | <https://protectapi-euc1.cylance.com>  |
| <https://protect-au.cylance.com>    | <https://protectapi-au.cylance.com>    |
| <https://protect-sae1.cylance.com>  | <https://protectapi-sae1.cylance.com>  |
| <https://protect.us.cylance.com>    | <https://protectapi.us.cylance.com>    |
| <https://protect.cylance.com>       | <https://protectapi.cylance.com>       |

## Step 3: Add Aurora Endpoint Security as a Security Device in Workbench <a href="#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26516" id="uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26516"></a>

Now that you have the correct access configured and noted the credentials, you can integrate your tech with Workbench.

1. [Log in to Workbench](https://workbench.expel.io/).
2. On the console page, navigate to **Settings** and click **Security Devices**.
3. At the top of the page, click **Add Security Device**.
4. Search for and select **Aurora Endpoint Security**.
5. Configure the fields as follows:
   * **Name** - type the hostname of the Aurora Endpoint Security device.
   * **Location** - type the geographic location of the appliance.
   * **Tenant ID** - type the Tenant ID generated in [Step 2](#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492).
   * **Application ID** - type the Application ID generated in [Step 2](#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492).
   * **Application secret** - type the application secret generated in [Step 2](#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492).
   * **Service Endpoint** - type your correct Service Endpoint from the table in [Step 2](#uuid-c0e6298e-b3ae-2cf8-a222-34f54f60f7d3_bridgehead-26492).

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2FkYF0qqfaxlO4jvxPi7QQ%2FScreenshot%202026-04-14%20at%205.22.59%E2%80%AFPM.png?alt=media&amp;token=149e3260-9dd3-450e-b2ad-195f7df7069e" alt="Aurora Endpoint Security add security device page in Workbench." width="375"><figcaption></figcaption></figure></div>

6. Click **Save**.
7. On the console access screen, select **Set up now**.
8. Provide these details:
   * **Console URL** - enter the console URL from the **Server address** in the **Connection Settings** area in the Workbench security device configuration window. At the end of the URL, type **/login**.
   * **Username** - enter the user name you created above.
   * **Password** - enter the password you created above.
   * **Two-factor secret key (32-character code)** - depending on how your organization enforces log-ins, this field may not apply to you. In these cases, you can leave it blank. This field is optional and if you have questions or concerns, reach out to your Customer Success Manager or to support.
9. Click **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).


# Box Setup for Workbench

## Prerequisites <a href="#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671" id="uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671"></a>

1. You must have a Box enterprise admin user with access to the [Developer Console](https://app.box.com/developers/console) and [Admin Console](https://app.box.com/master/custom-apps) to build and authorize a Custom App.

## Step 1: Enable API Access for Workbench <a href="#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671" id="uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671"></a>

1. Sign in to your Developer Console.
2. Select **Create New App**.
3. Select **Server Authentication (Client Credentials Grant)**.
4. Name your custom app "Expel" and click **Create App**.
5. Click **Fetch Client Secret** and make note of the **Client ID** and **Client Secret** as you only see it one time.
6. Select the app access level **App + Enterprise Access**.
7. Select the following application scopes:
   * Read all files and folders stored in Box.
   * Manage enterprise properties.
8. On the **Authorization** tab, select **Review and Submit for app authorization**. The app status now reads `Pending Authorization`.
9. Authorize the app through email or sign in to your Admin Console and click **Apps** on the top-left side of the page.
10. Under Custom Apps, find the app that was submitted and select **Authorize App**.
11. Navigate to **Account & Billing** from the top left side of the page and take note of your **Enterprise ID**.

## Step 2: Configure the Technology in Workbench <a href="#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23705" id="uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23705"></a>

Now that you have the correct access configured and noted the credentials, you can integrate your tech with Workbench.

1. [Log in to Workbench](https://workbench.expel.io/).
2. Navigate to **Settings > Security Devices**.
3. At the top of the page, click **Add New Device**.
4. Search for and select **Box**.
5. A configuration pane displays. Complete the fields as follows:
   1. **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Box”; this name will display in Workbench under the Name column, and is a text string that you can filter on.
   2. **Location** - enter the location of your integration, for example “cloud.” This is also a text string that you can filter on, so we recommend being consistent with location naming across your Expel integrations.
   3. **Client ID** - enter the client ID you saved in [Step 1](#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671-1).
   4. **Client secret** - enter the secret you saved in [Step 1](#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671-1).
   5. **Enterprise ID** - enter the Enterprise ID you saved in [Step 1](#uuid-86af3bf2-d920-f98a-54c2-9055e60c39ad_bridgehead-23671-1).

<div align="left"><figure><img src="https://2371323735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F82234aPbNfd179j5U4ti%2Fuploads%2F43dKKtc9uAR1XNQzRBl5%2FScreen%20Shot%202021-03-17%20at%206.56.18%20PM.png?alt=media&amp;token=6fa96d97-4f67-4af1-b239-2aa85fdce6ca" alt="Box Add Security Device page in Workbench." width="329"><figcaption></figcaption></figure></div>

6. Click **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).


# Broadcom


# Broadcom Carbon Black Cloud (formerly CB ThreatHunter and CB Defense) Setup for Workbench

## Step 1: Enable Console Access <a href="#h_01hye94nfpavrh2jmb5w2e2fnq" id="h_01hye94nfpavrh2jmb5w2e2fnq"></a>

This procedure creates a user account for Expel that keeps the Expel activity separate from other activity on the Carbon Black Cloud console.

Expel requires console access to allow analysts to perform investigation and triage. Without this additional level of information, alerts cannot be verified by our analysts and an investigation cannot be initiated. For more information, see [Why Expel Asks for Console Access](/connect-your-technology/about-integrations/why-expel-asks-for-console-access).

1. Navigate to the gear icon on the left side and click **Users**. Then click **Add User** on the top right of the screen.
2. Configure the user as follows:
   * **First name** - enter "Expel".
   * **Last name** - enter "SOC".
   * **Email** - enter "soc+\<Your\_Organization\_Name>@expel.io".
     * For example, if your organization were Acme Corp, the format would be "<soc+acme_corp@expel.io>".
   * **Role** - select **Level 2 Analyst**.
3. Click **Save**.

## Step 2: Generate API Credentials <a href="#h_01hye94nfq2ht2x678yg28vr70" id="h_01hye94nfq2ht2x678yg28vr70"></a>

To integrate the technology with Workbench, we need to create secure credentials to the API with the proper permissions.

1. In the Carbon Black Cloud console, navigate to **Settings > Roles**.
2. Navigate to **Settings > API Keys**.
3. Create a new API key by selecting **Add API Key** in the upper right corner.
4. Type a name for the new key. We suggest "Expel SOC".
5. From the Access Level list, select **Custom**.
6. From the Custom Access Level list, select either the **View All** role or the role you created above.
7. Complete the rest of the information and click **Save** to create the new key.
8. Take note of the **API ID** and **API Secret Key** for use in the next step.

## Step 3: Add Broadcom Carbon Black Cloud as a Security Device in Workbench <a href="#h_01hye94nfqder1mpc1hjjrnd8g" id="h_01hye94nfqder1mpc1hjjrnd8g"></a>

Now that you have the correct access configured and noted the credentials, you can integrate your tech with Workbench.

1. [Log in to Workbench](https://workbench.expel.io/auth/login?orig=%2F).
2. In the side menu, navigate to **Organization Settings > Security Devices**.
3. Select **Add Security Device**.
4. In the search box, type “Carbon Black” and then select the **Broadcom Carbon Black Cloud (formerly CB ThreatHunter and CB Defense)** integration.
5. Configure these details:
   * **Name** - enter the host name of the device.
   * **Location** - enter the geographic location of the appliance.
   * **Server Address** - enter the Carbon Black Cloud server address, usually <https://defense-prod05>. conferdeploy.net/
   * **Org ID** - enter your **CB Organization ID**.
   * **Org Key**- enter the **Org Key**.
   * **API ID** - enter the **API ID** created in [Step 2](#h_01hye94nfq2ht2x678yg28vr70).
   * **API Key** - enter the **API Secret Key** created in [Step 2](#h_01hye94nfq2ht2x678yg28vr70).
6. Click **Save**.
7. On the console access screen, select **Set up later**. Expel will complete configuration with the user you created in [Step 1](#h_01hye94nfpavrh2jmb5w2e2fnq).
8. Click **Save**.

Your device should be created successfully within a few seconds. A few reminders:

* After your connection is healthy, it will take some time for your device to begin polling and receiving data.
* To check on the status, select the downward arrow for your device in the first column and choose **View details**.
* Polling will happen first; data will be received after that. **You must refresh the page to see updates.**
* If your device does not begin polling within 15 minutes, and does not begin receiving data within 30 minutes, [contact our support team for help](/support).
* To check if alerts are coming through, navigate to **Dashboards > Alert Analysis**. Scroll to the device you want to check, and select the **Expel Alerts** tab to reveal more alert information. It can take 36 to 72 hours for alerts to appear after setup, as we [tune your device](/workbench-reference/alerts/how-expel-alerts-work#device-tuning).




---

[Next Page](https://docs.expel.io/llms-full.txt/1)