Installing and Configuring the Zscaler Internet Access Content Pack

Installing the Zscaler Internet Access Content Pack

Follow the steps in this section to install the Zscaler Internet Access™ Integration Content Pack through TC Exchange™ in ThreatConnect^®.

1. Log into ThreatConnect with a System Administrator account.
2. On the top navigation bar, hover over Settingsand select TC Exchange Settings. The Installed tab of the TC Exchange Settings screen will be displayed.
3. Click the Catalog tab. The Catalog screen will be displayed.
4. Select Content Packs from the dropdown to the left of the search bar to display all Content Packs in the TC Exchange catalog (Figure 1).

   

    

5. Click Installin the Options column for the Zscaler Internet Access Content Pack. A drawer showing all items in the Content Pack will be displayed, including a description of the Content Pack, a list of all items (i.e., Apps, Artifact types, Attribute Types, Playbooks, and Workflows) that the Content Pack contains, and an indication of whether each item is already installed on your ThreatConnect instance.
6. Click the + Install button at the top of the drawer to install the Content Pack and any items it contains that are not already installed or created on your ThreatConnect instance.

After the Content Pack is installed, the following items will be installed at the System level in TC Exchange (new Apps, Playbook Templates, and Workflow Templates) or created at the System level (new Attribute types and Artifact Types) on your ThreatConnect instance if they do not already exist there:

• Playbook App:
  • Zscaler Internet Access
• Playbook Templates:
  • Zscaler Content Pack - Add URL or Host to ZIA Security Exceptions
  • Zscaler Content Pack - Add URL or Host to ZIA Blocked Malicious URLs
  • Zscaler Content Pack - Remove URL or Host from ZIA Blocked Malicious URLs
  • Zscaler Content Pack - Remove URL or Host from ZIA Security Exceptions

Configuring the Zscaler Internet Access Content Pack

Import, Configure, and Activate Playbooks

The Zscaler Internet Access Content Pack leverages the Zscaler Internet Access Playbook App and four Playbooks to accomplish its use cases. Follow these instructions to import the Playbook Templates as Playbooks, configure the variables within the Playbooks, and activate the Playbooks.

1. On the top navigation bar, hover over Playbooks and select Templates. The Templates screen will be displayed.
2. Enter “zscaler” (without the quotation marks) in the search bar. The four Playbook Templates in Figure 2 will be displayed.

   

    

3. For each Playbook Template, click the vertical ellipsison the right side of the row and select Import as Playbook from the dropdown.
4. The Import Playbook drawer will be displayed (Figure 3).

   

    

   • zscaler_api_key: Enter the Zscaler Internet Access API key used for authentication.
     Note

     Use the instructions in the “Retrieve Your Base URL and API Key/Token” section of the “Getting Started” page of the Zscaler API Developer & Reference Guide to retrieve your Zscaler Internet Access API key.
   • zscaler_password: Enter the Zscaler Internet Access password associated with the username entered in the next field (zscaler_username).
   • zscaler_username: Enter the Zscaler Internet Access username that you use to log into the Zscaler host. 
   • zscaler_host: The Zscaler Internet Access host URL that matches your login URL for Zscaler (e.g., zsapi.zscalerbeta.net).
     Note

     Use the instructions in the “Retrieve Your Base URL and API Key/Token” section of the “Getting Started” page of the Zscaler API Developer & Reference Guide to retrieve your Zscaler Internet Access API key.
     Important

     When entering the base URL, do not enter any trailing slashes. Entering those characters or any other text that provides an incorrect base URL will result in a 404 error when you try to run Playbooks that call this variable.
     Note

     Once you enter these variables during the first Playbook’s import, you will not be prompted to enter them for subsequent imports, as all four Playbooks take the same variables. Each variable will be saved in your Organization and can be edited on the Variables tab of the Organization Settings screen if necessary. See the “Variables” section of ThreatConnect Organization Administration Guide for more information.
5. The Playbook will be displayed in the Playbook Designer. Set the log level of the Playbook to DEBUG or TRACE by clicking theicon at the upper right of the Playbook Designer and selecting the desired log level from the Log Level dropdown. This setting will enable you to verify the contents of the Zscaler Security Exceptions and Blocked Malicious URLs list in the Outputs tab when viewing the Playbook’s execution details.
6.  Activate the Playbook by hovering the cursor over the MODE dropdown at the upper-right corner of the Playbook Designer and selecting Active.
7. Repeat this process for each of the four Playbook Templates.

You should now have the following four active Playbooks in your Organization:

• ZScaler Content Pack - Add URL or Host to ZIA Security Exceptions
• Zscaler Content Pack - Add URL or Host to ZIA Blocked Malicious URLs
• Zscaler Content Pack - Remove URL or Host from ZIA Security Exceptions
• Zscaler Content Pack - Remove URL or Host from ZIA Blocked Malicious URLs

Zscaler Internet Access Playbook App

The four Playbooks use the Zscaler Internet Access Playbook App. For more information on this App, see the “Zscaler Internet Access Playbook App” section of Zscaler Internet Access Integration User Guide.

Updating the Zscaler Internet Access Content Pack

When an update for the Zscaler Internet Access Content Pack is available in TC Exchange, follow these steps to ensure that all items provided by the Content Pack are updated on your ThreatConnect instance:

1. Click Updatein the Options column for the Zscaler Internet Access Content Pack on the TC Exchange Settings screen.
2. After the Content Pack has updated successfully, navigate to the Playbooks screen, search for “zscaler”, and delete all four Playbooks provided by the previous version of the Content Pack:
   • ZScaler Content Pack - Add URL or Host to ZIA Security Exceptions
   • Zscaler Content Pack - Add URL or Host to ZIA Blocked Malicious URLs
   • Zscaler Content Pack - Remove URL or Host from ZIA Security Exceptions
   • Zscaler Content Pack - Remove URL or Host from ZIA Blocked Malicious URLs
3. Reimport and activate all four Playbook Templates as described in the “Import, Configure, and Activate Playbooks” section. You will not be prompted to enter any of the variables, as they will already have been saved as Organization-level variables when you imported the Playbook Templates during the initial installation of the Content Pack.

Troubleshooting Frequently Asked Questions (FAQ)

Why didn’t the four Zscaler Playbooks update after I updated the Zscaler Internet Access Content Pack?

When you update the Content Pack on the TC Exchange Settings screen, the four Playbook Templates will be updated. However, updates to Playbook Templates do not apply to Playbooks that were previously imported from the Templates. As such, in order to add the updated Playbooks in your Organization, you must import them from the updated Templates. The Playbooks themselves will not update when the Content Pack is updated.

Why do I now have eight Playbooks from the Zscaler Internet Access Content Pack in my Organization?

If you have a duplicate copy of each of the four Playbooks, but with a “1” at the end of the name (e.g., Zscaler Content Pack - Add URL or Host to ZIA Security Exceptions 1), then you did not delete the existing Playbooks before importing them from the updated Playbook Templates. If the Playbooks exist in your Organization when you import from the updated Templates, then the newly imported versions will not replace the existing versions, but rather be imported as a new version, with a “1” at the end of their name to distinguish them from the existing version.

I ran one of the Playbooks from the Zscaler Internet Access Content Pack from an Indicator’s Details screen, but the operation timed out. When I checked my browser’s console feedback, I saw 404 errors. Why did this happen?

You may have included unnecessary text (e.g., a trailing slash) when entering the zscaler_host variable during the first Playbook Template import. Navigate to the Variables tab of the Organization Settings screen, edit the zscaler_host variable to remove the unnecessary text and ensure that the correct base URL is entered, and then save the edited variable.

ThreatConnect^® is a registered trademark, and TC Exchange™ is a trademark, of ThreatConnect, Inc.
Zscaler™ and Zscaler Internet Access™ are trademarks of Zscaler, Inc.

20157-02 v.01.A