> For the complete documentation index, see [llms.txt](https://docs.expel.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.expel.io/connect-your-technology/q-z-integrations/wiz-setup-for-workbench.md).

# Wiz Setup for Workbench

Expel analyzes over 380 Wiz Issue types for evidence of post-exploit behavior, including issues from Wiz’s Kubernetes runtime sensor. Integrating your Wiz tenant with Workbench allows Expel to create a bi-directional service integration that provides our analysts with access to your Wiz service environments. 

This means Expel will be able to do all of the following on your behalf:

* Retrieve issues from Wiz related to control and threat detection investigations for the Cloud environments
* Collect necessary data from the Wiz platform, as needed, to perform certain MDR assessments
* Enhance certain Wiz Issues with Expel updates by adding information about the MDR analysis and related investigative activities that are taking place
* Change the Wiz status for certain Issues from “Open” to “In Progress” (active investigation is ongoing) or “Rejected” (suppressed or found to be benign)
* Access your Wiz service from the Expel Workbench in order to perform additional triage activities, assess specific types of Wiz Issues, and validate verifiable threats by conducting advanced querying and utilizing log data

{% hint style="info" %}
Expel requires you to set specific permissions during the Wiz Service Account setup as described in this guide. Make sure to do the Wiz setup first; the Workbench setup will ask for the client ID, client secret, and API URL from the Wiz setup. 

In addition, while not required, Expel recommends also adding AWS, Azure, GCP, and OCI integrations as log sources to assist in providing more advanced and in-depth investigations within Workbench.
{% endhint %}

## Prerequisites

1. You must have a **Wiz Advanced Tier License** so that you can grant us access to your cloud services data.
2. You must have access to Wiz as a role with **W(rite) permissions** on the **Settings > Deployments** (Integrations) page. This account will be used to configure the webhook.
3. You must be able to **add Expel as a new user** in Wiz, which will grant us access to your console. This account is required for Expel to be able to triage and investigate Wiz issues.
4. If you are using Wiz in a **GovCloud environment**, please [contact Support](/support/how-to-reach-us.md) for assistance in completing a required legal addendum to allow GovCloud ingestion of events for your integration.

## Step 1: Add an Expel API Integration in Wiz

The first step is to create a service account so that Expel can connect to your Wiz account via an API.

1. [Log in to Wiz](https://app.wiz.io/) and using the left side menu, navigate to **Settings > Deployments**.
2. Select **Add Deployment**.
3. In the search bar, enter "Expel" and select **Expel API**.
4. On the New Expel API Integration page, configure the settings as follows:
   * **Name** - enter "Expel Workbench".
   * **Scope** - leave **All Projects** selected. *This is recommended to ensure Expel receives data from all of your Wiz environment.*
   * **Permissions** - review the permissions required for the service account for this integration. These are not editable.
     * **Note:** If you plan to enable alert **status syncing** between Wiz and Workbench, please ensure the following permissions are included. See [Required Permissions](#h_01m00wwpg3aarnhyez1t23rq85) for more information.
       * read:issues
       * write:issue\_comments
       * write:threat\_issue\_comments
       * write:threat\_issue\_status
5. Select **Add Integration**.
6. On the New Service Account Credentials page, copy and save the **Client ID**, **Client Secret**, **API Endpoint URL**, and **API Authentication URL** to a safe place for use in a later step. *These credentials will not be accessible again, so be sure to record them now.*

<div align="left"><figure><img src="/files/1MmObGQCyWi1RLe7WT6S" alt="Image showing the four credentials you need to copy and save." width="318"><figcaption></figcaption></figure></div>

7. Select **Done**.
8. Confirm your new integration was added to the **Integration** tab of the Deployments page.&#x20;

{% hint style="info" %}
It may take up to 24 hours for the status of your integration to transition to Active or Inactive.
{% endhint %}

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

Now that you have created a new API Integration for Expel in Wiz, 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 the **Add Security Device** button.
4. In the search box, enter “Wiz” and then select the Wiz integration.
5. Complete the fields as follows:
   * **Name** - enter a name that might help you more easily identify this integration, such as “CompanyName Wiz”; 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.
   * **Wiz API Endpoint URL** - enter the API Endpoint URL you saved from your Wiz settings.
   * **Client ID** - enter the Client ID you received when creating the service account in Wiz.
   * **Client secret** - enter the Client Secret you received when creating the service account in Wiz.
6. Select **Save**.
7. Next, set up console access.&#x20;
   * From the dropdown that displays on the next screen, under “How will you access the console?”, choose **Set Up Now**.
   * Select **Save**.
8. A confirmation message displays indicating your device has been created. Select **Done**.

{% hint style="info" %}
If you are using Wiz in a GovCloud environment and have not done so already, please [contact Support](/support/how-to-reach-us.md) for assistance in completing the required legal addendum. Once complete, Expel will manually enable event ingestion for the integration and the device will appear healthy in Workbench.
{% endhint %}

## Step 3: Set Up Wiz Console Access for Expel

Expel requires Wiz 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.md).

To configure Wiz console access properly, you will need to add Expel as an accepted domain in your Wiz tenant and then create a user account for Expel in your Wiz tenant. These steps must be performed in the correct order, and by following the instructions given below.

<details>

<summary>Step 1: Add Expel as an Accepted Domain</summary>

1. In the Wiz side menu, hover over the round **Settings** icon.
2. Then, select **Access Management** and choose **SSO & Login Security**.
3. Use the **Copy** button to copy the Wiz Domain Verification Code (this is an SPF record that is unique to each Wiz tenant). Save it to a safe place, as you will need to send it to Expel.

<figure><img src="/files/swvfHuBEs7I9ov60GFeD" alt="Image showing the Wiz Domain Verification Code and how to copy it."><figcaption></figcaption></figure>

4. Select **Save**.
5. Send the code via email to <support@expel.com> with the subject line of “Wiz Integration,” or open a ticket through Zendesk (accessed through Workbench). We will need to validate this record internally before you can continue, so pause here until you hear back from us.
6. After Expel notifies you that the record has been validated, you can continue on to Step 2.

{% hint style="danger" %}
If you move on to Step 2 before the SPF record has been validated, the integration will not work. Please wait to hear back from our support team before continuing.
{% endhint %}

</details>

<details>

<summary>Step 2: Add a User Account for Expel</summary>

1. If you are not still logged in to your Wiz console, [log back in](https://app.wiz.io/) and select the round **Settings** icon.
2. Then, select **Access Management** and choose **SSO & Login Security**.
3. Add “expel.io” to your list of domains that can access the Wiz portal.
4. In the left menu bar, select **User Management**.
5. Select the **Invite User** button.
6. Configure the user with the following information:
   * **Name** - enter “Expel Analyst”.
   * **Email** - enter an email address using the format of `soc+<Your_Organization_Name>@expel.io`. For example, if your organization were Acme Corp, the email would be `soc+acme_corp@expel.io`.
   * **Identity Provider** - leave as is; it should default to “Wiz” and not be editable.
   * **Role** - select “Global Incident Response Analyst” from the dropdown menu.
   * **Expiration Date** - leave as is; do not select an expiration date.
7. Select **Invite User**.
8. An invite will be sent to Expel, and a member of the support team will accept the invite.

The support team will then set up two-factor authentication for the user account and update the Wiz security device in Workbench on your behalf.

</details>

## Step 4: Configure Wiz Status Syncing

Expel supports alert status syncing between Workbench and Wiz security devices. If status syncing is enabled, when an ingested Wiz Issue triggers the creation of an Expel Alert, the Expel Alert status (e.g. Open, Investigating, Closed) is reflected back into the Wiz device as Expel’s SOC works the Expel Alert. Comments are also included for every state change, or for any action taken by Expel’s SOC (e.g. a Verify Action is sent).

Syncing is currently one-way and Workbench serves as the source of truth. This means statuses in Wiz are updated by Workbench, but Workbench is not informed or updated by status changes made in Wiz.

Workbench status syncing is available for any Wiz security device configured in Workbench.&#x20;

### Configuring Wiz Status Syncing <a href="#h_01m00w87jy7ejzpnr4y4q78paq" id="h_01m00w87jy7ejzpnr4y4q78paq"></a>

Syncing can be enabled or disabled by editing your Wiz Security Device in Workbench.&#x20;

1. Navigate to **Organization Settings > Security Devices**.
2. Select the dropdown for your Wiz device.
3. Select **Edit** to open the Edit Security Device screen.
4. For **Enable 1-way status syncing & comments for Expel alerts?**, select **Yes** to enable or **No** to disable.

<div align="left"><figure><img src="/files/orWW3rQxu0yfkF95B5HP" alt="Radio button in Workbench reads Enable 1-way status syncing &#x26; comments for Expel Alerts? With options for Yes or No." width="374"><figcaption></figcaption></figure></div>

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

Status syncing requires both “Read” and “Write” permissions in order to function. Please ensure the Expel API Integration you configured in Wiz in [Step 1](#step-1-add-an-expel-api-integration-in-wiz) includes the following:

| Permission                    | Enables Workbench to…                                                      |
| ----------------------------- | -------------------------------------------------------------------------- |
| read:issues                   | Query Wiz API for Issue information                                        |
| write:issue\_comments         | Add comments for CLOUD CONFIGURATION and TOXIC COMBINATION Issues          |
| write:threat\_issue\_comments | Add comments for THREAT\_DETECTION issues                                  |
| write:threat\_issue\_status   | Update issue status & resolution reason field for THREAT\_DETECTION issues |

If you are experiencing status syncing errors, Expel strongly advises you to validate the above permissions. If permission errors occur, Expel will disable status syncing for your Wiz device.

### Additional Information <a href="#h_01m00wyyyjxvk0fgdqpjxec555" id="h_01m00wyyyjxvk0fgdqpjxec555"></a>

See the [Reference](#h_01m00wzk9wwf0h13fqj8d8sa7e) section to learn more about Wiz Issues, limitations, mappings, and more.

## Step 5: Obtain the Webhook Credentials in Workbench

1. In the Workbench side menu, navigate to **Organization Settings > Security Devices**.
2. Locate your existing Wiz security device.
3. Select the arrow beside the device name, then select **Edit** from the dropdown menu.
4. Copy and save the following values to a safe place, as you will need to provide these in Wiz in a later step:
   * `Webhook URL`
   * `Webhook username`
   * `Webhook password`

## Step 6: Add an Expel Webhook Integration in Wiz

1. In the Wiz side menu, navigate to **Settings > Deployments**.
2. Select **Add Deployment**.
3. In the search bar, enter "Expel" and select **Expel Webhook**.
4. On the New Expel Webhook Integration page, configure the settings as follows:
   * **Name** - enter "Expel Webhook".
   * **Scope** - leave All Projects selected. This is recommended to ensure Expel receives data from all of your Wiz environment.
   * **URL** - enter the Webhook URL value from Step 5.
   * **Username** - enter the Webhook username value from Step 5.
   * **Password** - enter the Webhook password value from Step 5.
5. Select **Add Integration**.&#x20;

{% hint style="info" %}
It may take up to 24 hours for the new integration's status to transition to Active or Inactive.
{% endhint %}

## Step 7: Add an Automation Rule for Expel in Wiz

1. In the Wiz side menu, navigate to **Policies > Response > Automation Rules**.
2. Select **Add Rule**.
3. On the New Automation Rule page, configure the settings as follows:
   * **Name** - enter "Expel Webhook Rule".
   * **Description (optional)** - provide a description of the rule.
   * **Scope** - leave All Projects selected.
4. Configure the Rule Conditions section as follows:

<table data-header-hidden><thead><tr><th width="179.4140625"></th><th></th><th></th></tr></thead><tbody><tr><td>WHEN the following trigger occurs</td><td><ul><li>For Wiz Cloud: select <strong>Risk Issues</strong> from the dropdown, then leave only <strong>Created</strong> checked in the second dropdown.</li><li>For Wiz Defend: select <strong>Detection</strong> from the dropdown. <em>Created will be automatically selected along with this option.</em></li></ul></td><td></td></tr><tr><td>IF all of the following match</td><td>Select <strong>Add Filter > Severity</strong> and then select every severity level checkbox.</td><td><img src="/files/R9EoNyWbM0moA1qlgQmj" alt="Image showing severity levels, with all of them checked."></td></tr><tr><td>THEN perform the following actions</td><td>Select <strong>Add Action</strong> and then choose the Webhook integration you just created.</td><td><img src="/files/5xpCrdjC2msO0z4K8mIP" alt="Image showing the rule condition settings."></td></tr></tbody></table>

5. Select **Continue**.
6. On the **Add Action** page, select **Test** to verify a successful result.

{% hint style="info" %}
If the test fails, please make sure your configurations from [Step 6](#step-6-add-an-expel-webhook-integration-in-wiz) and [Step 7](#step-7-add-an-automation-rule-for-expel-in-wiz) are correct.
{% endhint %}

7. Select **OK**.
8. Select **Add Action.**
9. Scroll to the bottom of the page to preview the existing Detections that match the selected "IF" filters, and verify that the filter results match your expectations.
10. Select **Add Rule**.

To verify that the Integration is working correctly, check the **Integrations** tab on the Deployments page of the Wiz console.&#x20;

* The Expel Webhook Integration should show an "Active" status (the status make take up to 24 hours to update after configuring).&#x20;
* This page should also indicate the Automation Rule you configured. The rule will tell you which Detections match the condition you have created, so you can anticipate what will be sent through the Webhook.
* Once the integration is in "Active" status, detections that trigger in your environment will typically appear in Workbench within 3 to 5 minutes.
* To check if alerts are coming through, navigate to the **Alerts Analysis** page in Workbench. Wiz Cloud alerts will be prepended with "Wiz Cloud" in the alert name, and Wiz Defend alerts will be prepended with "Wiz Defend".

## Reference <a href="#h_01m00wzk9wwf0h13fqj8d8sa7e" id="h_01m00wzk9wwf0h13fqj8d8sa7e"></a>

### About Wiz Issues <a href="#h_01m00wztbdjj1qdw40058n2kh5" id="h_01m00wztbdjj1qdw40058n2kh5"></a>

Workbench ingests security findings from both Wiz Issues and Wiz Detections to create Expel Alerts. Note that automated status syncing and comment updates are only supported for those Expel Alerts linked directly to a Wiz Issue.

Every Issue has a type:

* CLOUD CONFIGURATION: a misconfiguration finding from agentless scanning. Wiz auto-resolves these when a re-scan finds the problem fixed.&#x20;
* TOXIC COMBINATION: a graph-based control finding combining multiple risk signals. Expel cannot manually resolve these via the API.
* THREAT DETECTION: a runtime threat detection which is resolved manually. Expel can update status and resolution reasons via the API. Only available for Security Devices with a Wiz Defend license.

For Wiz Defend users, real-time Wiz Detection events can be sent to Expel via webhook. Each individual detection event is linked to a specific activity within a broader parent THREAT\_DETECTION Issue. Once ingested through this webhook, Wiz Detections can trigger the creation of Expel Alerts. However, it is important to note that if an analyst acts on an Expel Alert tied to a Wiz Detection, status syncing does not extend to the parent THREAT\_DETECTION Issue. Wiz Detections themselves lack a status for updates or the ability to receive comments.

Expel supports these ingestion methods:

* Expel queries Wiz every 30 minutes for all open issues across all types.
* Wiz pushes individual Detection events in real time via webhook. Each has a detection ID and a parent Issue ID.&#x20;
* Wiz pushes issues in real time via webhook.

### Limitations <a href="#h_01m00x1mbtthvpz2dcgvsk7ngq" id="h_01m00x1mbtthvpz2dcgvsk7ngq"></a>

* Syncing only applies to Wiz Issues and Threats that generate an Expel Alert. If a Wiz alert is ingested but does not meet our detections threshold (i.e. remains a vendor alert), then nothing “happens” in Wiz. We acknowledge this creates a possible blind spot into knowing what our SOC is or is not triaging, and are committed to supporting this use case in the future.
* Status syncing behaviors are limited to alert status and commenting. Expel Alert assignment metadata (i.e. assigned to Expel, assigned to your organization) does **not** map back to Wiz Issues.

### Object Mappings <a href="#h_01m00x382x8fzj6ftwca71y4da" id="h_01m00x382x8fzj6ftwca71y4da"></a>

| Workbench Object | Syncing Key  | Wiz Object |
| ---------------- | ------------ | ---------- |
| Expel Alert      | Wiz Issue ID | Issue      |
| Investigation\*  | N/A          | N/A        |
| Incident\*       | N/A          | N/A        |

*\*Expel updates the Wiz Issue associated with an Investigation or Incident.*

### Status Mappings <a href="#h_01m00x5vfsgwq0e1yzptzy02j4" id="h_01m00x5vfsgwq0e1yzptzy02j4"></a>

#### THREAT\_DETECTION Issues (seen under Threats in Wiz console) <a href="#h_01m00x5ye3ns77kfh5kgadjswr" id="h_01m00x5ye3ns77kfh5kgadjswr"></a>

External tools like Expel utilize the [Update Issue API to modify Wiz Threats](https://docs.wiz.io/dev/threats-and-detections), allowing for status adjustments or the inclusion of investigative and remediation notes. Expel updates the status of a Wiz Issue to match the current status of the corresponding Expel Alert based on the below mapping table.

Note that Wiz does not permit using the REJECTED closure state for THREAT\_DETECTION issues.

| Expel Alert Status  | Threat Detection Issue Status |
| ------------------- | ----------------------------- |
| New / Reopened      | Open                          |
| Investigating       | In Progress                   |
| Closed (any reason) | RESOLVED                      |

#### Resolution Reason Mapping <a href="#h_01m00x9rge6zc2k4j15ds6drww" id="h_01m00x9rge6zc2k4j15ds6drww"></a>

All THREAT\_DETECTION closes with RESOLVED and the resolution reason is set based on Expel close reason.

<table><thead><tr><th width="292.16015625">Expel Alert (Close Reason)</th><th>Threat Detection Issue Status</th><th>Threat Detection Issue Resolution Reason</th></tr></thead><tbody><tr><td>[NO CLOSE REASON SET]*</td><td>RESOLVED</td><td>INCONCLUSIVE_THREAT</td></tr><tr><td>Closed (Activity Blocked)<br>Closed (Attack Failed)<br>Closed (Incident)<br>Closed (True Positive)</td><td>RESOLVED</td><td>MALICIOUS_THREAT</td></tr><tr><td>Closed (Testing)</td><td>RESOLVED</td><td>SECURITY_TEST_THREAT</td></tr><tr><td>Closed (Benign)<br>Closed (False Positive)<br>Closed (IT Misconfiguration)<br>Closed (Possible Policy Violation)<br>Closed (PUP/PUA)<br>Closed (Other)<br>Closed (Suppressed)<br>Closed (Suppressed - New Device)<br>Closed (Suppressed - Threshold Exceeded)</td><td>RESOLVED</td><td>NOT_MALICIOUS_THREAT</td></tr></tbody></table>

#### CLOUD CONFIGURATION and TOXIC COMBINATION Issues <a href="#h_01m00xe7855025nrs599xyp3fj" id="h_01m00xe7855025nrs599xyp3fj"></a>

Wiz utilizes agentless scanning to automatically resolve these specific Issue types. Consequently, Wiz prevents integrations like Expel from modifying these statuses [via the Wiz API.](https://docs.wiz.io/docs/cloud-risk-assessment#lifecycle-and-management) For these Issues, Expel’s actions are restricted to providing comments only.

| Expel Alert Status  | CLOUD CONFIGURATION and TOXIC COMBINATION Issue Status |
| ------------------- | ------------------------------------------------------ |
| New / Reopened      | No Status change - comment only                        |
| Investigating       | No Status change - comment only                        |
| Closed (any reason) | No Status change - comment only                        |

### Comments <a href="#h_01m00xh90mbsh302m6f13eq19c" id="h_01m00xh90mbsh302m6f13eq19c"></a>

In addition to the above state syncing, the “close reason” and associated analysis is added as a comment to the relevant Wiz Issue or Threat upon closure.

### Supported Events <a href="#h_01m00xhpktj0h14pgb990fkewa" id="h_01m00xhpktj0h14pgb990fkewa"></a>

| Event                                  | Triggers Status Sync? | Triggers Comment? |
| -------------------------------------- | --------------------- | ----------------- |
| Expel Alert Created                    | ✅                     | ✅                 |
| Expel Alert Closed                     | ✅                     | ✅                 |
| Expel Alert Reopened                   | ✅                     | ✅                 |
| Investigation Created                  | ✅                     | ✅                 |
| Investigation Closed                   | ✅                     | ✅                 |
| Investigation Reopened                 | ✅                     | ✅                 |
| Incident Created                       | ✅                     | ✅                 |
| Incident Closed                        | ✅                     | ✅                 |
| Incident Reopened\*                    |                       | ✅                 |
| ***Investigative Actions***            |                       |                   |
| Comment Created                        |                       | ✅                 |
| Expel Alert Assigned                   |                       | ✅                 |
| Investigation Assigned                 |                       | ✅                 |
| Investigation Alert Added              |                       | ✅                 |
| Incident Assigned                      |                       | ✅                 |
| Incident Downgraded                    |                       | ✅                 |
| Investigative Action Analysis Assigned |                       | ✅                 |
| Investigative Action Manual Action     |                       | ✅                 |
| Investigative Action Assigned          |                       | ✅                 |
| Notify Action Assigned                 |                       | ✅                 |
| Verify Action Assigned                 |                       | ✅                 |
| Verify Action Approved                 |                       | ✅                 |
| Verify Action Denied                   |                       | ✅                 |
| Incident Finding Created               |                       | ✅                 |
| Incident Finding Updated               |                       | ✅                 |
| Incident Finding Completed             |                       | ✅                 |
| Remediation Action Automated           |                       | ✅                 |
| Remediation Action Assigned            |                       | ✅                 |
| Remediation Action Completed           |                       | ✅                 |
| Remediation Action Automated Failed    |                       | ✅                 |

*\*Currently, re-opening a Workbench Incident does not re-open the child Expel Alert(s). As a result, syncing is not triggered.*


---

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

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

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

```
GET https://docs.expel.io/connect-your-technology/q-z-integrations/wiz-setup-for-workbench.md?ask=<question>&goal=<endgoal>
```

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

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

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