Enhancement Scripts - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Administrator Guide

Product
Cortex XSOAR
Version
8
Creation date
2023-11-02
Last date published
2024-04-11
Category
Administrator Guide
Solution
Cloud
Abstract

Enhancement scripts are run manually and can enrich indicators, write to context, return entries to the War Room, etc.

Enhancement scripts are run on demand. These scripts are not part of the indicator extraction flow, but can be run manually from the Indicator Quick View window or from the CLI. Examples of enhancement scripts include an enrichment script, a script that runs a search in a SIEM for the indicator, etc.

A use case for using an enhancement script, is for example, when reaching your limit for extracting indicators, in an indicator feed such as the VirusTotal, you can run the enhancement script manually. The script can write to context, return an entry in the War Room, etc.

Note

Enhancement scripts are different from running a reputation command. Reputation commands, such as ip are run on the specific indicator and are not run on the indicator type. For example, the IP Reputation script enables you to add a specific IP address to look up. If you have an incident that contains an IP indicator and you have not extracted it, go to Indicator Quick ViewActions and under Run Scripts, select the IP Reputation script.

To add an enhancement script to an indicator type:

  1. Go to Settings & InfoSettingsIndicatorsTypes.

  2. Select the indicator type and click Edit.

  3. Select the desired enhancement script.

    Enhancement scripts must have the enhancement tag applied appear in the list.

For each indicator type you can add a reputation command and enhancement script. If indicator extraction is turned on, indicator extraction occurs automatically according to the incident type. You can still run a reputation command on demand, provided it is defined in the indicator type. For example, the IP indicator uses the ip reputation command for IP indicator types.

When indicators are extracted, run an enhancement script which further enriches the indicator. For example, use the DomainReputation script to retrieve detailed information about a domain.

Out-of-the-box Enhancement Script Examples

In the Scripts page, there are several of out-of-the box enhancement scripts, including:

  • IPReputation

  • DomainReputation

  • EmailReputation

  • FileReputation

  • URLReputation

CLI Execution Examples
  • !IPReputation ip=8.8.8.8

  • !URLReputation url=cardcom.com

Enhancement Script Input

The enhancement script requires the indicator value as the input argument.

Argument

Description

The value of the indicator

For example ip, email, url.The argument name should match the indicator type in lower case. For example, the IPReputation script requires the ip input. For an EmailReputation script the input is email.

In the following example, the DomainReputation script uses domain as the input.

domain-rep-8-input.png
Enhancement Script Outputs

Depends on the script. Since it is run manually, the output depends on the input. If you want the output to be added to indicator enrichment/TI screen/etc it should follow the DBotScore convention in the content output, as described in Reputation and DBotScore.

Output Code Examples

output =
   {
       'Type': entryTypes['note'],
       'ContentsFormat': formats['json'],
       'Contents': ‘this is the enrichment data’,
       'EntryContext': {
           'Email': ‘xsoar@test.com’, 
           ‘DBotScore’: {}},
   }

return_results(output)

Complete Enhancement Script Example

script: |
  register_module_line('EmailReputation', 'start', __line__())

  def email_reputation():
      results = demisto.executeCommand('email', {'email': demisto.get(demisto.args(), 'email')})

      for item in results:
          if isError(item):
              item['Contents'] = item['Brand'] + ' returned an error.\n' + str(item['Contents'])

      demisto.results(results)


  def main():
      email_reputation()


  if __name__ in ('__main__', '__builtin__', 'builtins'):  # pragma: no cover
      main()

  register_module_line('EmailReputation', 'end', __line__())