Cortex XSOAR for Developers (Formerly Demisto)

Zscaler

Use the Zscaler integration to block manage domains using whitelists and blacklists.

In order that the integration will work properly, one must use a Zscaler user with admin permissions.

Category ID is the same as the category name, except all letters are capitalized and each word is separated with an underscored instead of spaces. For example, if the category name is Other Education, then the Category ID is OTHER_EDUCATION.

Custom category ID has the format CUSTOM_01 , which is not indicative of the category. Use the using zscaler-get-categories command to get a custom category and its configured name.

Configure the Zscaler Integration on Demisto

  1. Navigate to Settings > Integrations > Servers & Services .
  2. Search for Zscaler.
  3. Click Add instance to create and configure a new integration instance.
    • Name : a textual name for the integration instance.
    • Cloud Name
    • Credentials
    • Password
    • API Key
  4. Click Test to validate the URLs and token.

Commands

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

  1. Return information for a URL: url
  2. Return information for an IP address: ip
  3. Add URLs to the whitelist: zscaler-whitelist-url
  4. Add URLs to the blacklist: zscaler-blacklist-url
  5. Add IP addresses to the whitelist: zscaler-whitelist-ip
  6. Add IP addresses to the blacklist: zscaler-blacklist-ip
  7. Remove URLs from the whitelist: zscaler-undo-whitelist-url
  8. Remove URLs from the blacklist: zcaler-undo-blacklist-url
  9. Remove IP addresses from the whitelist: zscaler-undo-whitelist-ip
  10. Remove IP addresses from the blacklist: zscaler-undo-blacklist-ip
  11. Add a URL address to a category: zscaler-category-add-url
  12. Add an IP address to a category: zscaler-category-add-ip
  13. Remove a URL address from a category: zscaler-category-remove-url
  14. Remove an IP address from a category: zscaler-category-remove-ip
  15. Return a list of categories: zscaler-get-categories
  16. Return the default blacklist: zscaler-get-blacklist
  17. Return the default whitelist: zscaler-get-whitelist
  18. Get a report for an MD5 hash: zscaler-sandbox-report

1. Return information for a URL: url

Returns information about a specified URL.

Base Command

url

Input
Path Description
url URL to return information for

Context Output
Path Description
URL.Address URL that was searched
URL.urlClassifications URL classification
URL.urlClassificationsWithSecurityAlert Classifications with security alert of the URL
URL.Malicious.Vendor For malicious URLs, the vendor that made the decision
URL.Malicious.Description For malicious URLs, the reason for the vendor to make the decision
DBotScore.Indicator The tested indicator
DBotScore.Type Indicator type
DBotScore.Vendor Vendor used to calculate the score
DBotScore.Score The actual score

Raw Output 
[
{
"url": "facebook.com",
"urlClassifications": "SOCIAL_NETWORKING",
"urlClassificationsWithSecurityAlert": ""
}
]

2. Return information for an IP address: ip

Returns information about a specified IP address.

Base Command

ip

Input
Path Description
ip IP to return information for

Context Output
Path Description
IP.Address IP address that was searched
IP.urlClassifications IP address classification
IP.urlClassificationsWithSecurityAlert Classifications with security alert of the IP address
IP.Malicious.Vendor For malicious IP addresses, the vendor that made the decision
IP.Malicious.Description For malicious IP addresses, the reason for the vendor to make the decision
DBotScore.Indicator The tested indicator
DBotScore.Type Indicator type
DBotScore.Vendor Vendor used to calculate the score
DBotScore.Score The actual score

Raw Output 
[  
   {  
      "ip":"8.8.8.8",
      "ipClassifications":"WEB_SEARCH",
      "ipClassificationsWithSecurityAlert":""
   }
]

3. Add a URL to the whitelist

Comma-separated list that adds specified URLs to the whitelist.

Base Command

zscaler-whitelist-url

Input
Path Description
url Comma-separated list of URLs to add to the whitelist

Context Output

There is no context output for this command.

Raw Output 
Added the following URLs to the whitelist successfully:
phishing.com
malware.net

4. Add a URL to the blacklist

Comma-separated list that adds specified URLs to the blacklist.

Base Command

zscaler-blacklist-url

Input
Path Description
url Comma-separated list of URLs to add to the blacklist

Context Output

There is no context output for this command.

Raw Output 
Added the following URLs to the blacklist successfully:

phishing.com

malware.net 

 

5. Add IP addresses to the whitelist

Comma-separated list that adds specified IP addresses to the whitelist.

Base Command

zscaler-whitelist-ip

Input
Path Description
ip Comma-separated list of IP addresses to add to the whitelist

Context Output

There is no context output for this command.

Raw Output 
Added the following IP addresses to the whitelist successfully:
2.2.2.2
3.3.3.3

6. Add IP addresses to the blacklist: zscaler-blacklist-ip

Comma-separated list that adds specified IP addresses to the blacklist.

Base Command

zscaler-blacklist-ip

Input
Path Description
ip Comma-separated list of IP addresses to add to the blacklist

Context Output

There is no context output for this command.

Raw Output 
Added the following IP addresses to the blacklist successfully:
2.2.2.2
3.3.3.3

7. Remove URLs from the whitelist

Comma-separated list that removes specified URLs from the whitelist.

Base Command

zscaler-undo-whitelist-url

Input
Path Description
url Comma-separated list of URLs to remove from the whitelist

Context Output

There is no context output for this command.

Raw Output 
Removed the following URLs from the whitelist successfully:
phishing.com
malware.net

8. Remove URLs from the blacklist: zcaler-undo-blacklist-url

Comma-separated list that removes specified URLs from the blacklist.

Base Command

zscaler-undo-whitelist-url

Input
Path Description
url Comma-separated list of URLs to remove from the blacklist

Context Output

There is no context output for this command.

Raw Output 
Removed the following URLs from the blacklist successfully:
phishing.com
malware.net

9. Remove IP addresses from the whitelist

Comma-separated list that removes specified IP addresses from the whitelist.

Base Command

zscaler-undo-whitelist-ip

Input
Path Description
url Comma-separated list of IP addresses to remove from the whitelist

Context Output

There is no context output for this command.

Raw Output 
Removed the following IP addresses from the whitelist successfully:
2.2.2.2
3.3.3.3

10. Remove IP addresses from the blacklist

Comma-separated list that removes specified IP addresses from the blacklist.

Base Command

zscaler-undo-blacklist-ip

Input
Path Description
url Comma-separated list of IP addresses to remove from the blacklist

Context Output

There is no context output for this command.

Raw Output 
Removed the following IP addresses from the whitelist successfully:
2.2.2.2
3.3.3.3

11. Add a URL address to a category

Adds a URL address to a specified category.

Base Command

zscaler-category-add-url

Input
Argument Name Description Required
category-id Category ID to add the URL to, for example RADIO_STATIONS Required
url URL address to add to the category. Comma separated values supported, for example, pandora.com,spotify.com Required

Context Output
Path Type Description
Zscaler.Category.CustomCategory boolean True if category is custom
Zscaler.Category.Description string Category description
Zscaler.Category.ID string Category ID
Zscaler.Category.URL unknown List of category URL addresses

Command Example

!zscaler-category-add-url category-id=MUSIC url=demisto.com,apple.com

Context Example 
{
    "Zscaler": {
      "Category": {
        "CustomCategory": false,
        "Description": "MUSIC_DESC",
        "ID": "MUSIC",
        "URL": [
            "demisto.com",
            "apple.com"
        ]
      }
    }
}

Human Readable Output

Added the following URL addresses to category MUSIC:

  • demisto.com
  • apple.com

12. Add an IP address to a category

Adds an IP address to a specified category.

Base Command

zscaler-category-add-ip

Input
Argument Name Description Required
category-id Category ID to add IP to, for example RADIO_STATIONS Required
ip IP address to add to the category. Comma separated values supported, for example 8.8.8.8,1.2.3.4 Required

Context Output
Path Type Description
Zscaler.Category.CustomCategory boolean True if category is custom
Zscaler.Category.Description string Category description
Zscaler.Category.ID string Category ID
Zscaler.Category.URL unknown List of category URL addresses

Command Example

!zscaler-category-add-ip category-id=REFERENCE_SITES ip=1.2.3.4,8.8.8.8

Context Example 
{
    "Zscaler": {
      "Category": {
        "CustomCategory": false,
        "Description": "REFERENCE_SITES_DESC",
        "ID": "REFERENCE_SITES",
        "URL": [
            "1.2.3.4",
            "8.8.8.8"
        ]
      }
    }
}

Human Readable Output

Added the following IP addresses to category REFERENCE_SITES:

  • 1.2.3.4
  • 8.8.8.8

13. Remove a URL address from a category

Removes a URL address from a specified category.

Base Command

zscaler-category-remove-url

Input
Argument Name Description Required
category-id Category ID to remove URL from, for example RADIO_STATIONS Required
url URL address to remove from the category. Comma separated values supported, for example pandora.com,spotify.com Required

Context Output
Path Type Description
Zscaler.Category.CustomCategory boolean True if category is custom
Zscaler.Category.Description string Category description
Zscaler.Category.ID string Category ID
Zscaler.Category.URL unknown List of category URL addresses

Command Example

!zscaler-category-remove-url category-id=MUSIC url=apple.com

Context Example 
{
    "Zscaler": {
      "Category": {
        "CustomCategory": false,
        "Description": "MUSIC_DESC",
        "ID": "MUSIC",
        "URL": [
            "demisto.com"
        ]
      }
    }
}

Human Readable Output

Removed the following URL addresses to category MUSIC:

  • apple.com

14. Remove an IP address from a category

Removes an IP address from a specified category.

Base Command

zscaler-category-remove-ip

Input
Argument Name Description Required
category-id Category ID to remove IP from, for example RADIO_STATIONS Required
ip IP address to remove from the category. Comma separated values supported, for example 8.8.8.8,1.2.3.4 Required

Context Output
Path Type Description
Zscaler.Category.CustomCategory boolean True if category is custom
Zscaler.Category.Description string Category description
Zscaler.Category.ID string Category ID
Zscaler.Category.URL unknown List of category URL addresses

Command Example

!zscaler-category-remove-ip category-id=REFERENCE_SITES ip=1.2.3.4

Context Example 
{
    "Zscaler": {
      "Category": {
        "CustomCategory": false,
        "Description": "REFERENCE_SITES_DESC",
        "ID": "REFERENCE_SITES",
        "URL": [
            "8.8.8.8"
        ]
      }
    }
}

Human Readable Output

Removed the following IP addresses to category REFERENCE_SITES:

  • 1.2.3.4

15. Return a list of categories

Returns a list of all categories.

Base Command

zscaler-get-categories

Input

There is no input for t his command.

Context Output
Path Type Description
Zscaler.Category.ID string Category ID
Zscaler.Category.CustomCategory boolean True if category is custom, else false.
Zscaler.Category.URL string List of category URL addresses
Zscaler.Category.Description string Category description
Zscaler.Category.Name string Category name
Command Example

!zscaler-get-categories

Context Example 
{  
   "Zscaler":{  
      "Category":{  
         "ID":"INTERNET_SERVICES",
         "Description":"INTERNET_SERVICES_DESC",
         "URL":[  
            "google.com",
            "facebook.com"
         ],
         "CustomCategory":"false"
      },
      "ID":"CUSTOM_01",
      "Name":"CustomCategory",
      "URL":[  
         "demisto.com",
         "apple.com"
      ],
      "CustomCategory":"true"
   }
}

Human Readable Output

Zscaler Categories

CustomCategory Description ID Name URL
false INTERNET_SERVICES_DESC INTERNET_SERVICES google.com,facebook.com
true CUSTOM_01 CustomCategory demisto.com,apple.com

16. Return the default blacklist

Returns the default Zscaler blacklist.

Base Command

zscaler-get-blacklist

Input
Context Output
Path Type Description
Zscaler.Blacklist string Default Zscaler blacklist
Command Example

!zscaler-get-blacklist

Context Example 
{
    "Zscaler": {
        "Blacklist": [
            "malicious.com,
            "bad.net"
        ]
    }
}
Human Readable Output

Zscaler blacklist

  • malicious.com
  • bad.net

17. Return the default whitelist

Returns the default Zscaler whitelist.

Base Command

zscaler-get-whitelist

Context Output
Path Type Description
Zscaler.Whitelist string Defualt Zsclaer whitelist
Command Example

!zscaler-get-whitelist

Context Example 
{
    "Zscaler": {
        "Whitelist": [
            "demisto.com,
            "apple.com"
        ]
    }
}
Human Readable Output

Zscaler whitelist

  • demisto.com
  • apple.net

18. Get a report for an MD5 hash

Gets a full report or a summary detail report for an MD5 hash of a file that was analyzed by Zscaler Sandbox.

Base Command

zscaler-sandbox-report

Input
Argument Name Description Required
md5 MD5 hash of a file. Required
details Report type (full or summary). Required

Context Output
Path Type Description
File.MD5 string MD5 hash of the file.
File.Malicious.Vendor string For malicious files, the vendor that made the decision.
File.Malicious.Description string For malicious files, the reason that the vendor made the decision.
File.DetectedMalware string Malware that was detected.
File.FileType string The file type.
DBotScore.Indicator string The indicator that was tested.
DBotScore.Type string Indicator type.
DBotScore.Vendor string Vendor used to calculate the score.
DBotScore.Score number The actual score.

Command Example

!zscaler-sandbox-report md5=3FD0EA0AE759D58274310C022FB0CBBA details=summary

Context Example 
{
    "DBotScore": {
        "Vendor": "Zscaler", 
        "Indicator": "3FD0EA0AE759D58274310C022FB0CBBA", 
        "Score": 3, 
        "Type": "file"
    }, 
    "File": {
        "Zscaler": {
            "FileType": null, 
            "DetectedMalware": ""
        }, 
        "Malicious": {
            "Vendor": "Zscaler", 
            "Description": "Classified as Malicious, with threat score: 100"
        }, 
        "MD5": "3FD0EA0AE759D58274310C022FB0CBBA"
    }
}
Human Readable Output

Full Sandbox Report

Category Indicator Vendor Score Zscaler Score Type
MALWARE_BOTNET 3FD0EA0AE759D58274310C022FB0CBBA Zscaler 3 100 file
None

More information

Screenshots

image

image

Edit this page
Report an Issue