1. Expel Help Center
  2. Connect Your Technology
  3. Network Integrations
  4. Zscaler ZIA

Zscaler ZIA (via Webhook) Setup for Workbench

This setup guide is for Zscaler ZIA users connecting via a webhook. If you are connecting via a SIEM, go to the Zscaler ZIA (via SIEM) setup guide.

In this guide, you will generate the webhook credentials in Workbench and then add them to your Zscaler console. This allows our SOC analysts to gain access to your Zscaler events.

Prerequisites

  1. You must have a Zscaler account with a Super Admin role (or equivalent), as you must be able to configure and activate changes in the Zscaler console.
  2. You must have the Nanolog Streaming Service (NSS) from Zscaler, and specifically Cloud NSS Feeds.
  3. You must not have an existing Cloud NSS Feed already set up for your web logs, as Zscaler currently only supports a single Cloud NSS feed per type (web/firewall).

Quick Links

Setup includes the following steps (select any step for detailed instructions):

  1. Add Zscaler (via Webhook) as a Security Device in Workbench
  2. Obtain the Webhook Credentials
  3. Set Up the Webhook Connection in Zscaler
  4. Verify the Webhook Connectivity
  5. Enable Console Access in Zscaler
  6. Enable Console Access in Workbench
  7. Troubleshooting

Step 1: Add Zscaler (via Webhook) as a Security Device in Workbench

You must first add the security device in Workbench so that Expel can generate your webhook credentials. You will need to come back to your device at the very end of this process to enable console access (you will find instructions later in this guide).

  1. Log in to Workbench.
  2. In the side menu, navigate to Organization Settings > Security Devices.
  3. Select Add Security Device.
  4. In the search box, type “Zscaler” and then select the Zscaler (via Webhook) integration.
  5. Complete the fields as follows:
    • Name - enter a name that might help you more easily identify this integration, such as “CompanyName Zscaler”; 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.
    • Connection Settings cannot be edited and will be empty; you will find your webhook credentials here after you have added the device.
    • Select Save.
  6. Select Set up later from the console access dropdown.
  7. Select Save. You will receive a message stating that your credentials are being generated.
  8. Select Done to close the window.

Step 2: Obtain the Webhook Credentials

Your new security device now has its webhook credentials available. You'll need to copy and save them, and then also convert the login credentials to a base64-encoded string (our webhook endpoint requires the HTTP authorization header).

  1. Still on the Security Devices page, locate the device you created in the prior section.
  2. Select the arrow beside the device name, and then select View details from the dropdown menu (if you need help with this process, see View Security Device Details).
  3. Select the Information screen, and then look for Connection Settings.
  4. View and save the following values, which you will need when you configure the Cloud NSS feed in the next section:
    • Webhook Password
    • Webhook URL
    • Webhook Username
  5. Now, format your login credentials as a base64-encoded string and save the output. You can achieve this through one of the following methods, replacing username:password with your values (for security reasons, we do NOT recommend using an online Base64 encoding website):
    • On Windows systems, open PowerShell and run: 
      [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))
    • On UNIX-like systems, open Terminal and run: 
      printf "%s" "username:password" | base64
    • The output should look something like this: dGVzdHVzZXI6dGVzdHBhc3N3b3Jk

Step 3: Set Up the Webhook Connection in Zscaler

You will now add the webhook to Zscaler so that it can send events to Workbench. You'll do this via your Cloud NSS feed. 

Note

Remember that you must not have already set up Cloud NSS for your web logs.

  1. In the ZIA Admin Portal, navigate to Administration > Settings > Cloud Configuration > Nanolog Streaming Service.
  2. Select the Cloud NSS Feeds tab.
  3. Select Add Cloud NSS Feed.
  4. In the General section, complete the fields as follows:
    • Feed Name - enter "EXPEL_SECURITY".
    • NSS Type - select NSS for Web.
    • Status - select Enabled.
    • SIEM Rate - select Unlimited.
  5. In the SIEM Connectivity section, complete the fields as follows:
    • SIEM Type - select Other.
    • OAuth 2.0 Authentication - make sure this is set to Disabled.
    • Max Batch Size - make sure this is set to 512 KB.
    • API URL - enter the webhook URL you saved in Step 2.
    • HTTP Header Key 1 - enter "Content-Encoding".
    • HTTP Header Value 1 - enter "gzip".
    • HTTP Header Key 2 - enter "Authorization".
    • HTTP Header Value 2 - enter "Basic" and then a space, and then add your base64-encoded credentials you saved in Step 2. The entry should look like something like: Basic dGVzdHVzZXI6dGVzdHBhc3N3b3Jk
  6. In the Formatting section, complete the fields as follows:
    • Log Type - select Web Log.
    • Feed Output Type - select JSON.
    • JSON Array Notation - make sure this is set to Disabled.
    • Feed Escape Character - enter ,\"
    • Feed Output - copy and paste the following code: 
      \{"event":\{"datetime": "%d{yy}-%02d{mth}-%02d{dd} %02d{hh}:%02d{mm}:%02d{ss}","vendor": "Zscaler","product": "NSS","feed": "WebLogs","vendorversion": "%s{productversion}","event_id": "%d{recordid}","user": "%s{elogin}","department": "%s{edepartment}","appname": "%s{appname}","appclass": "%s{appclass}","app_status": "%s{app_status}","fileclass": "%s{fileclass}","filetype": "%s{filetype}","filename": "%s{efilename}","transactionsize": "%d{totalsize}","responsesize": "%d{respsize}","requestsize": "%d{reqsize}","requestmethod": "%s{reqmethod}","status": "%s{respcode}","refererURL": "%s{ereferer}","useragent": "%s{eua}","fqdn": "%s{ehost}","url": "%s{eurl}","contenttype": "%s{contenttype}","srcip": "%s{cip}","srcpubip": "%s{cintip}","srcport": "%d{clt_sport}","dstip": "%s{sip}","dstport": "%d{srv_dport}","protocol": "%s{proto}","location": "%s{elocation}","ruletype": "%s{ruletype}","reason": "%s{reason}","action": "%s{action}","filehash": "%s{bamd5}","score": "%d{riskscore}","threatseverity": "%s{threatseverity}","threatname": "%s{threatname}","threatcategory": "%s{malwarecat}","threatclass": "%s{malwareclass}","urlclass": "%s{urlclass}","urlsupercategory": "%s{urlsupercat}","urlcategory": "%s{urlcat}","deviceowner": "%s{deviceowner}","devicehostname": "%s{edevicehostname}"\}\}
    • Timezone - leave as GMT.
  7. No web log filters are required, so you can now select Save.
  8. Make sure to activate the changes so that they are propagated through the Zscaler cloud. If you need help with this step, see Saving and Activating Changes in the ZIA Admin Portal in the Zscaler documentation.

Step 4: Verify the Webhook Connectivity

First, check the webhook connectivity within the ZIA Admin Portal:

  1. Still on the Cloud NSS Feeds tab, locate your newly created "EXPEL_SECURITY" Cloud NSS Feed.
  2. In the Last Connectivity Test column, check for a "Last Validation Successful on <timestamp>" message.
    • If you do not see a validation message or if it is not yet showing as valid, select the cloud icon to test the connection.
    • If you are unable to validate the connection, go to Troubleshooting for help.

Next, check to make sure the corresponding Expel Alerts are showing up in Workbench:

  1. Log in to Workbench.
  2. In the side menu, navigate to Dashboards > Alert Analysis.
  3. 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.
    • If you still do not see any activity after device tuning, go to Troubleshooting for help.

Step 5: Enable Console Access in Zscaler

Enabling console access is a multi-step process. The first two steps are performed in Zscaler. Why do we need console access?

Create the Administrator Role

The first step is to create an administrator role for Expel in Zscaler.

  1. Still in the ZIA Admin Portal, navigate to Administration > Administration Controls > Role Management.
  2. Select Add Administrator Role.
  3. In the Administrator Role and Permissions sections:
    • Enter "Expel" for the name.
    • Do not enable Permissions for Executive Insights.
    • Make sure the Logs Limit is set to Unrestricted.
    • Enable View-Only access for Reporting, Alerts, Dashboard, and Insights.
    • Make sure Device Information and User Names are set to Visible.

  1. Scroll down to Policy & Components and verify the following settings within each sub-tab:
    • Security - set to View-Only access.
    • Access Control - set both Policy Control and Policy Components to View-Only access.
    • Data Protection - set both Policy Control and Policy Components to View-Only access.
    • Decryption - set both Policy Control and Policy Components to View-Only access.
    • URL Categories - set to View-Only access.
    • Shared Policy Components - set to View-Only access.
  2. Select Cloud Configuration & Integration, and verify the following settings within each sub-tab:
    • Integrations - set to View-Only access.
    • Cloud Configuration - set to View-Only access.
  3. Select Traffic Forwarding, and verify the following settings:
    • Set Traffic Forwarding, Traffic Forwarding Methods, and Traffic Forwarding Components to View-Only access.
  4. Select Administration Controls, and verify the following settings:
    • Set Administration Controls and Backup Controls to View-Only access.
  5. Select Reporting Data, and verify the following settings:
    • Set Reporting Data to View-Only access.
  6. Save and activate your changes.

Create the Expel User

Now, you must create a new Expel user and assign the administrator role you just created.

Note

These steps describe the process for creating a new local user, which is our recommended option. If you would like to use your own identity provider (IdP) instead, refer to the Zscaler documentation for instructions.

  1. Still in the ZIA Admin Portal, navigate to Administration > Administration Controls > Administrator Management.
  2. Select Add Administrator.
  3. Configure the credentials as follows:
    • Login ID - enter "Expel" and leave the domain as is (it should be your domain). Make note of this login ID, as you will need it in the next section.
    • Email - enter "soc+<Your_Organization_Name>@expel.io" (the final format should look like soc+ExampleCompany@expel.io).
    • Name - enter "Expel".
    • Role - select Expel (this is the role you created in the previous section).
    • Status - select Enabled.
    • Scope - select Organization.
    • Executive Insights App Access - leave it as disabled.
    • Choose to Receive Updates - leave all as disabled.
    • Set Password - enter a password. Make note of this password, as you will need it in the next section.
  4. Select Save.

Step 6: Enable Console Access in Workbench

The next step is to edit the security device and add the new Expel user's credentials. Make sure you have the login ID and password from the previous section before you begin.

  1. Back in Workbench, navigate to Organization Settings > Security Devices.
  2. Locate the Zscaler ZIA (via Webhook) device you added in Step 1.
  3. Use the device's dropdown menu to select Edit. If you need help with this step, see Manage Security Devices.
  4. Complete the Console Login fields as follows:
    • Console URL - enter your Zscaler console URL
    • Username - enter the Expel user's Login ID.
    • Password - enter Expel user's password.
    • Two-factor secret key - leave blank.
  5. Select Save.

Troubleshooting

If your Cloud NSS Feed will not connect and validate, first check your feed configuration.

  1. Make sure your feed status is set to Enabled.
  2. Make sure you have copied the webhook URL correctly. If necessary, go back into the security device in Workbench to verify that you have the correct URL.
  3. Make sure your HTTP header key and token values are entered correctly.
  4. Make sure you copied the feed output correctly.

Next, check your base-64 encoded credentials.

  1. Go back into the security device in Workbench and verify that you have the correct webhook username and password.
  2. Decode your base-64 encoded credentials and make sure they match the webhook credentials.
    • On Windows systems, open PowerShell and run:
      [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('your-base64-string'))
    • On UNIX-like systems, open Terminal and run:
      printf "%s" "your-base64-string" | base64 -d

If you are still unable to successfully connect via the webhook, or if you have successfully verified your webhook but your device is showing no alerts in Workbench after 72 hours, contact Support for help.

Related articles