Author: Accelerynt
For any technical questions, please contact info@accelerynt.com
This playbook will use an Azure blob storage file to maintain a Zscaler custom URL category of your choice. The logic app is set to run every 5 minutes polling this blob storage file for changes. If any changes are made to the blob storage file, the Zscaler URL category values will be updated to match the file exactly. This will enable you to manage your Zscaler custom URL categories entirely from Microsoft Sentinel. Blob storage was opted for because unlike Microsoft Sentinel watchlists, the lastModified time attribute reflects changes to the contents of the file.
The following items are required under the template settings during deployment:
- The root domain of your Zscaler organization
- A configured Zscaler admin account
- A Zscaler API key
- The name of the Zscaler custom URL category you wish to add the Microsoft Sentinel incident domains to
- A Microsoft Azure key vault secret containing your Okta API Token
- A Microsoft Azure integration account
- A Microsoft Azure blob storage file
Navigate to https://www.zscaler.com/ and expand the dropdown list under "Sign In". The value you enter for the "Zscaler Root Domain" deployment parameter should exactly match the format of the options shown here. Select your appropriate domain and log in.
After logging into your account, you will need to configure your Zscaler API roles and API admin account.
For this Playbook to modify your Zscaler custom domain list, you will need a local Zscaler admin account that has access to the read and modify policy. To limit the access this account has to only what is needed, you will need to make a custom administrator role.
In the Zscaler administration console hover over Administration then click on Role Management.
Click on Add Administrator Role.
Create a Name for the Administrator Role and use the settings exactly as depicted in the image below. Then click the Save button.
Hover over the Activation button and click Activate to enable the new Role.
Next, hover over Administration and click on Administrator Management.
Click on Add Administrator.
Enter a Login ID for the API administrator account you want to create.
In the Email box you can enter a preexisting service account, or simply make up an email address which you will not use in your domain. There is no need for email access for this account.
Enter a name for the account and in the drop-down box below, select the Role you created in the previous step.
Make sure Password Based Login is checked and create a secure password for this API account.
Take note of the email address and password, as it will be needed during deployment.
Click Save, then hover over the Activation button and click Activate. This will enable the new administrator account.
To get your API key hover over the Administration button and click on API Key Management.
Here you will find you API Key as well as Zscaler Instance Name. You will need both of these when deploying this playbook. The typical instance names are Zscaler, ZscalerOne, ZscalerTwo, ZscalerThree, and ZsCloud.
Lastly, you will need to note the custom URL category you want the domains from Microsoft Sentinel incidents added to.
Hover over the Administration button and click on URL Categories.
Take note of the name of your desired URL category, as it will be needed during deployment.
In the example below we use name of our Custom category AS_Blocklist. This category in our test environment configured to a Zscaler access policy that disallows users access to any domain in in that list.
You will need to add you Zscaler API key and Zscaler password to an Azure key vault.
Navigate to the Azure key vaults page: https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults
Select an existing key vault or create a new one. From the key vault overview page, click the "Secrets" menu option on the key vault page menu. Click "Generate/Import".
Choose a name for the secret, such as "AS-Blob-Storage-Add-Domains-to-Zscaler-URL-Category-API-Key” and enter the Zscaler API key copied previously in the "Value" field. All other settings can be left as is. Click "Create".
Repeat this process for your Zscaler password.
Once both secrets have been added to the vault, navigate to the "Access policies" menu option. Leave this page open, as you will need to return to it once the playbook has been deployed. See Granting Access to Azure Key Vault.
You will need an integration account before this playbook can be deployed, as it is a requirement for executing JavaScript code, which is an operation used in the logic app.
Navigate to the Azure integration accounts page: https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.Logic%2FintegrationAccounts
From the "Overview" page, select an existing integration account and take note of its name, or click "Create".
Select the subscription and resource group that this playbook will be deployed to and a name for the integration account, such as "AS-Zscaler-Integration". Review the region and select a pricing tier, then click "Review + create".
From the "Review + create" page, review the information, then click "Create".
From the deployment page, take note of the resource name of your integration account, as it will be needed for deployment.
A blob storage file is needed for maintaining the Zscaler URL category values. Note the name and location of an existing one, or to create one, navigate to https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.Storage%2FStorageAccounts
Create a storage account or select an existing one, then click the "Containers" menu option. Click the "Container" button and enter a name for the new container, such as "zscaler-url-categories", then click Create".
Once your container has been created, you will need to upload a .csv file with the initial values of your Zscaler URL category. Click on your new container, then click "Upload" to open the dialogue box allowing you to upload your initial Zscaler URL category values in .csv format.
You can easily view and edit the items in your file by clicking the ellipsis icon to the far right of the file and clicking "View/edit".
Items can be added or removed on from the editable list. Once finished, click "Save".
The logic app is set to run every 5 minutes polling this blob storage file for any changes. Because the logic app needs additional configuring after deployment, complete all deployment steps before testing any changes to this list, otherwise, time lapsed from now until then will likely put the last updated time outside of the polling window.
To configure and deploy this playbook:
Open your browser and ensure you are logged into your Microsoft Sentinel workspace. In a separate tab, open the link to our playbook on the Accelerynt GitHub Repository:
https://github.com/Accelerynt-Security/AS-Blob-Storage-Add-Domains-to-Zscaler-URL-Category
Click the “Deploy to Azure” button at the bottom and it will bring you to the custom deployment template.
In the Project Details section:
- Select the “Subscription” and “Resource Group” from the dropdown boxes you would like the playbook deployed to.
In the Instance Details section:
-
Playbook Name: This can be left as "AS-Blob-Storage-Add-Domains-to-Zscaler-URL-Category" or you may change it.
-
Integration Account Name: Enter the name of the Microsoft integration account this playbook will use. Please note that the playbook and integration account must share the same resource group.
-
Zscaler Root Domain: Enter your Zscaler root domain here.
-
Zscaler Username: Enter the username of the Zscaler Admin account.
-
Zscaler Custom URL Category Name: Enter a Zscaler Custom URL Category Name.
-
Key Vault Name: Enter the name of the Key Vault that stores your Zscaler API key and Zscaler password.
-
Zscaler API Key: Enter the name of the Key Vault Secret that contains the value of your Zscaler API key.
-
Zscaler Password: Enter the name of the Key Vault Secret that contains the value of your Zscaler password.
Towards the bottom, click on “Review + create”.
Once the resources have validated, click on "Create".
The resources should take around a minute to deploy. Once the deployment is complete, you can expand the "Deployment details" section to view them. Click the one corresponding to the Logic App.
Click on the “Edit” button. This will bring us into the Logic Apps Designer.
Before the logic app can run successfully, some additional steps will need to be added. Click the "+" directly below the trigger labeled "Recurrence" and select "Add an action".
Paste "Blob" into the search bar, and click the "Get Blob Metadata (V2)" action for "Azure Blob Storage".
You will be prompted to either create a connection to a storage container or select an existing one if it exists. Make sure the connection is for the storage container your Zscaler URL category values have been uploaded to. Next, click the file icon in the "Blob" field and select the folder containing your Zscaler URL categories file.
After selecting the appropriate file, expand the ninth step labeled "Condition". Click in the input field with the placeholder "Choose a value" text. Select "LastModified" from the "Dynamic content" window.
An additional step must be added after the second step in the true branch. Click the "+" directly below the step labeled "Get Secret API Key" and select "Add an action".
Paste "Blob" into the search bar, and click the "Get blob content (V2)" action for "Azure Blob Storage".
As previously done, select the proper connection and file for your Zscaler URL categories.
Next, expand the step directly below labeled "For each- URLs" and click the function in the top field. In the dialogue box to the right, place your replace the two single quotes inside the trim()" function with the following: "body('Get_blob_content_(V2)')". Click "Update".
Lastly, expand the step labeled "Condition- URL parsing remove https protocol". Click inside the input box and select "Current item" under "For each - URLs".
Be sure to save the changes before exiting the logic app editor.
Before the Logic App can run successfully, the key vault connection created during deployment must be granted access to the key vault storing your Zscaler API key and password.
From the key vault "Access policies" page, click "Create".
Select the "Get" checkbox under "Secret permissions", then click "Next".
Paste "AS-Blob-Storage-Add-Domains-to-Zscaler-URL-Category" into the principal search box and click the option that appears. Click "Next" towards the bottom of the page.
Navigate to the "Review + create" section and click "Create".
