Enhancement Scripts

Configure scripts that enhance indicators on demand.

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 View → Actions and under Run Scripts, select the IP Reputation script.

To add an enhancement script to an indicator type:

1. Go to Settings → OBJECTS SETUP → Indicators → Types.
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 a number 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.

enhancement-settings.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 https://xsoar.pan.dev/docs/integrations/dbot.

Output Code Examples

output =
   {
       'Type': entryTypes['note'],
       'ContentsFormat': formats['json'],
       'Contents': ‘this is the enrichment data’,
       'EntryContext': {
           'Email': ‘[e-mail]’, 
           ‘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__())