Customize indicator types, fields, and layouts

Customize indicator types, fields, and layouts in Cortex XSOAR 8.10 On-prem.

Cortex XSOAR provides out-of-the-box indicator types, fields, and layouts. However, you may need to customize indicators to suit your use case, either by editing existing indicator types, fields, or layouts or by creating new ones to help investigate and respond to potential security threats specific to your organization.

Custom indicators can provide more accurate and efficient identification of potential cyber security threats. For example, you can customize indicators to monitor and detect unusual activity within your organization's internal network. This can include creating indicators to flag unauthorized access attempts or unusual data transfers, or identifying insider threats or compromised accounts.

Before customizing an indicator, review the ingested indicator and then customize it as needed. After ingesting incidents and indicators, check the indicator information associated with your incident. From an incident, review the context data (from Side panels). If there is information in the context data that you don't see in the indicator, map it into indicator fields and display it in the layout.

You can customize the following:

Option	Description
Indicator type	Customize an indicator type by setting the relevant fields, display layout, scripts to run, and reputation command for the indicator type. You can create a new indicator type or you can edit an out-of-the-box indicator type. For more information, see Create an indicator type.
Indicator fields	Custom indicator fields add specific details or attributes to indicators, helping to better classify and understand the nature of potential security threats. You can edit an existing indicator field or create a new one. After creating a new indicator field, map the field to the relevant context data. You can add the field to an indicator type and view it in an indicator layout. For more information, see Create an indicator field. Note Cortex XSOAR has a limit of 1000 indicator fields, including system fields, fields you create manually, and any fields in installed content packs.
Indicator layout	Custom indicator layouts enable you to organize and display specific details about potential threats in a way that makes sense for your organization, making it easier to quickly understand and respond to security issues. You can view, customize, import and export indicator layouts as well as add a custom layout to an indicator type. Note If you do not have a TIM license, you cannot edit the Indicator Summary layout. You can only edit the Quick view and the New/Edit form tabs. For more information, see Indicator layout customization.

Create an indicator type

Indicators are categorized by indicator type, which determines the indicator layout and fields that are displayed and which scripts are run on indicators of that type. Cortex XSOAR includes several out-of-the-box indicator types, such as:

• IP Address
• Domain
• URL
• File

  For more information about file indicators and how to configure the file hash, see File indicators.

When you create a new indicator type, you define its properties, including whether and how to format the indicator data and how the verdict is calculated.

1. Go to Settings & Info → Settings → Object Setup → Indicators → Types.
2. Click New.
3. In the Settings tab, add the required indicator profile, such as name and Regex.

   For more information, see Indicator type profile.
4. In the Custom Fields tab, map the fields, as required.

   For more information, see Map custom indicator fields.

See this video for an example of creating a custom indicator type: Indicators and Enrichment.

Example 33. Create a company email indicator type

The following example describes how to create a new indicator type to manage employee emails, for example for resource management or inside threat investigation.

Create a new indicator type for the employee email addresses which contain the “our_company.com” company domain.

1. Under Settings & Info → Settings → Object Setup → Indicators → Types → New, in the Settings tab, define the following.

   • Name: Company email
   • Regex: .*?@our_company.com (simplified to capture all the email addresses using the our_company.com domain).
   • Reputation command: Not relevant for this example, since we don't want any external enrichment.
   • Formatting script: If more formatting is needed, you can use a formatting script to edit the saved value.
   • Reputation script: If needed, you can create a reputation script to affect the DBot score given to the new custom indicator.
2. In the Custom Fields tab, map custom fields for the new indicator type.

   You can map fields returned using an integration such as Active Directory to obtain more data about the actual user to whom the email belongs. You can also collect data using integrations such as Okta (MFA, SSO), SIEM, and email security. Fields such as Username, Full name, and various groups the user is part of as well as other identifiers are returned to context and mapped into the indicator using the custom fields.

   

   use-case-custom-indicator-type-mapping.png

   Note

   If you miss mapping any field, you can create additional new indicator fields and either relate them to all indicator types, or relate them only to the new indicator type (recommended).
3. Design a custom layout for the new indicator type.

   You can use the Dynamic section in the indicator layout to run python scripts and return results from within the layout itself.

Indicator type profile

Each indicator type has its own profile that enables Cortex XSOAR to recognize it across the platform. During the indicator extraction flow, the order of execution is regex, formatting script, reputation command, and reputation script. You can update the following fields when updating an indicator type.

Field	Description
Name	A meaningful name for the indicator type.
Reputation script	The output of the reputation script is a verdict score, which is used as the basis for the indicator verdict. Reputation scripts must be tagged reputation to appear in the list for the indicator type. For more information, see Reputation scripts The results of reputation scripts do not print to the War Room in the extraction flow.
Formatting script	Modifies how the indicator displays in Cortex XSOAR. Formatting scripts must be tagged indicator-format to appear in the list for the indicator type. For more information, see Formatting scripts.
Enhancement script	The enhancement script is not part of the indicator extraction flow and is run manually on the indicator type. Examples of enhancement scripts include an enrichment script and a script that runs a search in an SIEM for the indicator. After indicators are identified, you can go to the Indicator Quick View page, click the Actions button, and run an enhancement script directly on an indicator. For these scripts to be available in the menu, they need the enhancement tag. For more information, see Enhancement scripts. When you run an enhancement script, it is the equivalent of running the script in the CLI. The script can write to context, return an entry, etc.
Reputation command	Calculates the reputation of indicators of this type. The verdict (reputation) is only associated with the specific indicator value on which it’s run (not the indicator type). The command returns the reputation of the indicator value as an entry with entry context and in some cases also returns context values that can be mapped to the indicator type custom fields. The results of the reputation command do not print to the War Room in the indicator extraction flow. For more information, see Reputation commands.
Regex	The regular expression (regex) to identify indicators for this indicator type.
Layout	Select the indicator layout to use.
Exclude these integrations for the reputation command	Integrations to exclude when calculating the verdict, evaluating, and enriching indicators of this indicator type. Excluding an integration here prevents it from triggering during automated enrichment processes such as indicator extraction, the enrichIndicators command, or the Enrich button. This setting does not prevent the integration from running if you explicitly execute its command (for example, !url or !ip). Tip To control which integrations run when explicitly executing a command (and not during enrichment), add the using-brand argument to specify only the integrations you want to use. For example: !url url="https://www.google.com" using-brand="AutoFocus V2,VirusTotal"
Indicator Expiration Method	The method by which to expire indicators of this type. The expiration method that you select is the default expiration method for indicators of this indicator type. The expiration can also be assigned when configuring a feed integration instance, which overrides the default method. Never Expire: indicators of this type never expire. Time Interval: indicators of this type expire after the specified number of days or hours. For more information, see Configure indicator expiration.
Context path for verdict value (Advanced)	When an indicator is extracted, the entry data from the command is mapped to the incident context. This path defines where in context the data is mapped.
Context value of verdict (Advanced)	The value of this field defines the actual data that is mapped to the context path.
Cache expiration in minutes (Advanced)	The amount of time (in minutes) after which the cache for indicators of this type expire. The default is 4,320 minutes (three days). The cache enables you to limit API requests by only updating indicators after a specific time period has passed. The cache cannot be cleared manually. Note Indicator cache expiration rules only apply to standard enrichment (for example, running the enrichIndicators command). If you run a reputation command, such as !ip, the commands executes even if the cache has not expired.

File indicators

Cortex XSOAR uses a single File indicator for file objects. As a result, files that appear with their SHA256 hash and all other hashes associated with the file, (MD5, SHA1, and SSDeep) are listed as properties of the same indicator. In addition, when ingesting an incident through an integration, all file information is presented as one object.

When investigating an incident, in the Indicators field (Investigation or Case info tabs), click a File indicator. You can see additional information for that indicator, including:

• SHA256
• MD5
• SHA1
• SSDeep
• Associated File Names

  The File.Name values associated with the indicator hash, based on File context objects created in Cortex XSOAR (automatically populated).
• Modified

  The date and time the File indicator was last modified.
• First Seen

  The date and time the file was first seen in Cortex XSOAR.

If the file appears in a different incident with a different name and has any of the same hash values, it automatically associates with the original indicator.

Note

A new File indicator only affects new indicators ingested to the Cortex XSOAR platform. Indicators that were already in Cortex XSOAR continue to appear as their respective hash-related indicators.

Configure each file hash to appear as a separate indicator

By default, Cortex XSOAR uses a single file indicator for file objects. As a result, files that appear with their SHA256 hash and all other hashes associated with the file, (MD5, SHA1, and SSDeep) are listed as properties of the same indicator. In addition, when ingesting an incident through an integration, all file information is presented as one object.

If the file appears in a different incident with a different name, and has any of the same hash values, it automatically associates with the original indicator.

If you want to have each file hash appear as its own indicator, do the following:

1. Go to Settings & Info → Settings → Objects Setup → Indicators → Types.
2. Select the File indicator and click Disable.
3. Select the following required hashes:

   • File SHA-256
   • File SHA-1
   • File MD5
   • SSDeep
4. Click Enable.

The file indicator merging method

When a file is created in the system, whether from a feed, indicator extraction or manually added, its original value is created as the indicator’s value, while its complementing hashes are saved as fields.

For example, if a SHA256 indicator is extracted from an email and enriched, an indicator with the SHA256 hash as the value will be created, and any other hash that is found in the enrichment phase (such as MD5, SHA1) will be added as a field. If in the future a file indicator with the same MD5 is created in the system, Cortex XSOAR automatically identifies it and merges the two indicators together into one.

For example, the executable cmd.exe’s SHA256 FF79D3C4A0B7EB191783C323AB8363EBD1FD10BE58D8BCC96B07067743CA81D5 was found in an incident and extracted. It also went through enrichment, which provided the information that the file’s MD5 is D7AB69FAD18D4A643D84A271DFC0DBDF.

The file indicator includes:

ID: 1
Type: File
Value: FF79D3C4A0B7EB191783C323AB8363EBD1FD10BE58D8BCC96B07067743CA81D5
SHA256: FF79D3C4A0B7EB191783C323AB8363EBD1FD10BE58D8BCC96B07067743CA81D5
MD5: D7AB69FAD18D4A643D84A271DFC0DBDF

Afterwards, through a custom feed, the cmd.exe’s MD5 D7AB69FAD18D4A643D84A271DFC0DBDF hash is brought in, and Cortex XSOAR creates an indicator of type File with the MD5 hash as its value.

A new file indicator is created:

ID: 2
Type: File
Value: D7AB69FAD18D4A643D84A271DFC0DBDF
MD5: D7AB69FAD18D4A643D84A271DFC0DBDF

The automatic merging flow for the File indicator type identifies that the two indicators are the same file and merges them together.

The final file indicator is a consolidation of the two, and is the same as the first example above:

ID: 1
Type: File
Value: FF79D3C4A0B7EB191783C323AB8363EBD1FD10BE58D8BCC96B07067743CA81D5
SHA256: FF79D3C4A0B7EB191783C323AB8363EBD1FD10BE58D8BCC96B07067743CA81D5
MD5: D7AB69FAD18D4A643D84A271DFC0DBDF

Formatting scripts

A formatting script has the following main functions:

• Validate inputs, for example, to check that the top-level domain (TLD) is valid.
• Modify how the indicator appears in Cortex XSOAR such as the War Room.

After indicator values are extracted according to the defined regex, the formatting script can be used to modify how the indicator value appears in the War Room and reports. For example, the IP indicator type uses the UnEscapeIPs formatting script, which removes any defanged characters from an IP address, so 127[.]0[.]0[.]1 is formatted to 127.0.0.1. When you click the IP address in the War Room, you see the formatted IP address. This extracted indicator value is then added to the Threat Intel database.

Out-of-the-box Formatting Scripts

You can create a new script, or you can use an out-of-the-box formatting script on the Scripts page, for example:

• UnEscapeIPs: Removes escaping characters from IP addresses. For example, 127[.]0[.]0[.]1 transforms to 127.0.0.1.
• ExtractDomainAndFQDNFromUrlAndEmail: Extracts domains and FQDNs from URLs and emails, used by the Domain indicator. It removes prefixes such as proofpoint or safelinks, removes escaped URLs, and extracts the FQDN.
• ExtractEmailV2: Verifies that an email address is valid and only returns the address if it is valid.

Formatting Script example

In the following example, the RemoveEmpty script removes empty items, entries, or nodes from an array.

// pack version: 1.2.30
const EMPTY_TOKENS = argToList(args.empty_values);

function toBoolean(value) {
    if (typeof(value) === 'string') {
        if (['yes', 'true'].indexOf(value.toLowerCase()) != -1) {
            return true;
        } else if (['no', 'false'].indexOf(value.toLowerCase()) != -1) {
            return false;
        }
        throw 'Argument does not contain a valid boolean-like value';
    }
    return value ? true : false;
}

function isObject(o) {
    return o instanceof Object && !(o instanceof Array);
}

function isEmpty(v) {
    return (v === undefined) ||
           (v === null) ||
           (typeof(v) == 'string' && (!v || EMPTY_TOKENS.indexOf(v) !== -1)) ||
           (Array.isArray(v) && v.filter(x => !isEmpty(x)).length === 0) ||
           (isObject(v) && Object.keys(v).length === 0);
}

function removeEmptyProperties(obj) {
    Object.keys(obj).forEach(k => {
        var ov = obj[k];
        if (isObject(ov)) {
            removeEmptyProperties(ov);
        } else if (Array.isArray(ov)) {
            ov.forEach(av => isObject(av) && removeEmptyProperties(av));
            obj[k] = ov.filter(x => !isEmpty(x));
        }
        if (isEmpty(ov)) {
            delete obj[k];
        }
    });
}

var vals = Array.isArray(args.value) ? args.value : [args.value];

if (toBoolean(args.remove_keys)) {
    vals.forEach(v => isObject(v) && removeEmptyProperties(v));
}
return vals.filter(x => !isEmpty(x));

Formatting Script input

The formatting script requires a single input argument named input that accepts a single indicator value or an array of indicator values. The input argument should be an array to accept multiple inputs and return an entry-result per input.

Argument

Description

input

Accepts a string or array of strings representing the indicator value(s) to be formatted. Will be accessed within the script using demisto.args().get(‘input’, []). In the script settings, the Is Array checkbox must be selected (see screenshot below).The script code must be able to handle a single indicator value (as string), multiple indicator values in CSV format (as string) and an array of single indicator values (array).

formatting-8-input.png

Formatting Script outputs

The indicators appear in a human-readable format in Cortex XSOAR. The output should be an array of formatted indicators or an array of entry results (an entry result per indicator to be created). The entry result per input can be a JSON array to create multiple indicators. If the entry result is an empty string, it is ignored and no indicator is created.

Use the return_results function to generate the script output. For more information, see https://xsoar.pan.dev/docs/integrations/code-conventions#return_results.

Single-value result:

results = CommandResults(
    outputs_prefix='VirusTotal.IP',
    outputs_key_field='Address',
    outputs={
        'Address': '8.8.8.8',
        'ASN': 12345
    }
)
return_results(results)

Multiple-value results:

results = [
    CommandResults(
        outputs_prefix='VirusTotal.IP',
        outputs_key_field='Address',
        outputs={
            'Address': '8.8.8.8',
            'ASN': 12345
        }
    ), 
    CommandResults(
        outputs_prefix='VirusTotal.IP',
        outputs_key_field='Address',
        outputs={
            'Address': '1.1.1.1',
            'ASN': 67890
        }
    )]
return_results(results)

Add a Formatting Script to an indicator type

1. Go to Settings & Info → Settings → Indicators → Types.
2. Select the indicator type and click Edit.
3. Select the desired formatting script.

   Note

   Formatting scripts must have the indicator-format tag to appear in the list.

Note

Formatting scripts for out-of-the-box indicator types are system-level, which means that the formatting scripts for these indicator types are not configurable. To create a formatting script for an out-of-the-box indicator type, you need to disable the existing indicator type and create a new (custom) indicator type. If you configured a formatting script before this change and updated your content, this configuration reverts to content settings (empty).

Run a Formatting script in the CLI

You can run out-of-the-box or custom formatting scripts in the CLI to check the extracted indicator data is properly formatted.

The following are examples of the syntax for running the out-of-the-box UnEscapeIPs formatting script in the CLI.

• !UnEscapeIPs !UnEscapeIPs input=127.0.0[.]1
• !UnEscapeIPs input=127.0.0[.]1,8.8.8[.]8
• !UnEscapeIPs input=${contextdata.indicators} (where the key contextdata.indicators in the context object is an array)

Enhancement scripts

Enhancement scripts enable you to gather additional data about the highlighted entry in the War Room. They can enrich indicators, search a SIEM for a specific indicator, write indicator details to context, and return entries to the War Room.

Enhancement scripts are run manually from the Indicator Quick View window or the CLI after indicators are extracted to allow you to collect additional information about an indicator. If you have an incident that contains an IP indicator and you want to run one or more enhancement scripts, go to Indicator Quick View → Actions and under Run Scripts, select the desired script.

Note

Enhancement scripts are different from reputation commands. A reputation command runs every integration that has that command within it, to enrich the indicator. The reputation command ip , for example, runs every IP integration command in your enabled integrations, to collect data from multiple sources. An enhancement script is manually run after the initial extraction and enrichment for the indicator type is complete.

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

The enhancement script output depends on its input because the script is run manually. If you want the output to be added to indicator enrichment or the Threat Intelligence screen, it should follow the DBotScore convention in the content output as described in https://xsoar.pan.dev/docs/integrations/dbot.

output =
   {
       'Type': entryTypes['note'],
       'ContentsFormat': formats['json'],
       'Contents': ‘this is the enrichment data’,
       'EntryContext': {
           'Email': ‘[e-mail]’, 
           ‘DBotScore’: {}},
   }

return_results(output)

Add an enhancement script to an indicator type

1. Go to Settings & Info → Settings → Indicators → Types.
2. Select the indicator type and click Edit.
3. Select one or more desired enhancement scripts.

   Note

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

Run an enhancement script in the CLI

You can run out-of-the-box or custom enhancement scripts in the CLI to enrich specific indicator values.

The following are examples of the syntax for running the out-of-the-box IPReputation and URLReputation enhancement scripts in the CLI.

• !IPReputation ip=8.8.8.8
• !URLReputation url=cardcom.com

Reputation scripts

Reputation scripts are used to assess and assign reputation scores to indicators. These scripts integrate external threat intelligence or internal data sources to evaluate the reputation of indicators (such as IP addresses, URLs, or file hashes). Reputation scripts enable you to implement custom logic and algorithms for determining the reputation of indicators.

Reputation scripts return the verdict of an indicator as a number. The number overrides the verdict returned from the reputation command and any default settings for the indicator that relates to the verdict, but does not override a manually set verdict.

The system automatically executes the reputation script in the following cases:

• During enrichment: When enrichment is triggered (via indicator extraction, the enrichIndicators command, or the Enrich button), the system runs the reputation command and then the reputation script for the specific indicator type.
• If a verdict changes not via the enrichment process: When explicitly running a reputation command such as !file, if the result changes the indicator's verdict the reputation script runs to finalize the decision. This happens even if you use the using argument to target a specific integration.

The reliability of the score from a reputation script is by default A++ - Reputation script. You can modify the reliability by navigating to Settings & Info → Settings → System → Server Settings → + Add Server Configuration and adding the server configuration enrichment.reputationScript.reliability with the desired reliability score.

Out-of-the-box reputation scripts

You can create a new reputation script, or you can use an out-of-the-box reputation script in the Scripts page, for example:

• CertificateReputation
• cveReputation
• MaliciousRatioReputation
• SSDeepReputation

Reputation Script input

The reputation requires a single input argument named input that accepts an indicator value.

Argument	Description
input	The indicator value.

reputation-script-8-set.png

Reputation Script outputs

Either a number or a dbotScore. It can either be a raw number which is the score, or a full entry with DBotScore.

from CommonServerPython import *


def main():
    url_list = argToList(demisto.args().get('input'))
    entry_list = []

    for url in url_list:
        entry_list.append({
            'Type': entryTypes['note'],
            'ContentsFormat': formats['json'],
            'Contents': 2,
            'EntryContext': {
                'DBotScore': {
                    'Indicator': url,
                    'Type': 'Onion URL',
                    'Score': 2,  # suspicious
                    'Vendor': 'DBot'
                }
            }
        })

    demisto.results(entry_list)


if __name__ in ('__main__', 'builtin', 'builtins'):
    main()

Values for Common.DbotScore

Constant	Value
Common.DbotScore.NONE	NONE = 0
Common.DbotScore.GOOD	GOOD = 1
Common.DbotScore.SUSPICIOUS	SUSPICIOUS = 2
Common.DbotScore.BAD	BAD = 3

Add a Reputation Script to an indicator type

1. Go to Settings & Info → Settings → Object Setup → Indicators → Types.
2. Select the indicator type and click Edit.
3. Select the relevant reputation script.

   Note

   Reputation scripts must have the reputation tag applied to appear in the list.

Run a Reputation Script in the CLI

You can run out-of-the-box or custom reputation scripts in the CLI to set the verdict for a specific indicator.

The following are examples for running the out-of-the-box CertificateReputation and MalicioiusRationReputation reputation scripts in the CLI.

• !CertificateReputation input=<value of the indicator>
• !MalicioiusRationReputation input=<value of the indicator>

Reputation commands

Reputation commands are built-in or custom commands that use integrations such as Unit 42 to provide predefined functionalities for obtaining an indicator verdict for specific indicator types. These commands simplify the process of fetching reputation data from external services or threat intelligence feeds without requiring extensive scripting. Reputation commands come with preconfigured parameters and settings for commonly used threat intelligence sources.

You can set an indicator type to run reputation commands. The command returns the verdict of the indicator as an entry with entry context and may also return context values that can be mapped to the custom fields of the indicator.

Note

Running a reputation command directly (such as !ip) might not apply the result to an indicator, nor does it use the enrichment cache. To ensure an indicator is enriched, and to take advantage of caching, use the enrichIndicators command or the Enrich button in the UI. This runs the appropriate reputation command/script based on the indicator type settings. Note that extracted indicators are enriched in the same way.

Out-of-the-box reputation commands

You can create a new reputation command, or you can use an out-of-the-box reputation command, for example:

• ip
• file
• url
• email
• domain

For more details on using out-of-the-box reputation commands or developing new reputation commands, see Generic Commands Reputation.

Reputation command input

The reputation command uses the indicator value as the input argument.

Arguments	Description
The value of the indicator	For example ip, email, url. Inputs are based on different integrations. Basic inputs are common to all reputation commands. For example, the !ip command has the following basic inputs: - name: ip arguments: - name: ip default: true description: List of IPs. isArray: true

In this example, the ip script uses ip, as the input, with the is array field checked.

ip-script-8.png

Reputation command output

Outputs return a dbotScore.

Run a Reputation command in the CLI

The following are examples of the syntax for running the ip , domain, and file reputation commands in the CLI.

• !ip ip=<value of the indicator>
• !domain domain=<value of the indicator>
• !file file=<value of the indicator>

Map custom indicator fields

Indicator mapping enables you to automatically update the value of an indicator field without having to manually change it. For example, the IP indicator automatically maps the Country field. If it was not mapped, each time the IP address changes country the analyst would have to update the country every time that indicator type is ingested.

The value of an indicator field is determined by the value of the key in context data the field is mapped to in Cortex XSOAR.

When you start ingesting indicators, the incoming fields are automatically mapped to the relevant indicator fields. Sometimes you may want to change the default settings or map custom indicator fields to specific context data. Before you map custom indicator fields, you need to create the indicator field and add it to the relevant indicator type layout.

Note

Some integrations have indicator mappers and classifiers, such as AWS. If you want to use an integration mapper or classifier, see Indicator classification and mapping.

To map custom fields to the indicator type, you need to enrich the indicator either by using the !enrichindicators command in the CLI, in a playbook, or by opening an indicator and click Enrich indicator. Enrichment returns an entry, with the EntryContext property as the source of the mapping process. When editing an indicator type, in the Custom Fields tab, type the name of the indicator exactly how it appears (in the Threat Intel page) and click Load.

For the enrichment data to be considered valid, EntryContext must include a DBotScore with the fields: Indicator, Score, Vendor , and Type. If DBotScore has those fields, all the data of EntryContext is used as the source for the mapping, and not only the data under EntryContext.DBotScore.

How to map indicator fields

1. Go to Settings & Info → Settings → Object Setup → Indicators → Types
2. Select the indicator type and click Edit.
3. Click the Custom Fields tab.

   The custom fields associated with this indicator type are listed in the table. If you do not see a custom field in the list, verify that you associated the custom field with this indicator type.
4. (Optional) In the Indicator Sample panel, enter an indicator relevant to the indicator type to load sample data.
5. Click Choose data path to map the custom field to a data path.

   1. (Optional) Click the curly brackets to map the field to a context path.
   2. (Optional) From the Indicator Sample panel, select a context key to map to the field.
6. Save the indicator type.

Source reliability and custom indicator field mapping

Custom indicator fields are mapped and populated according to source reliability hierarchy. When there are two different values for a single custom indicator field, the field is mapped and populated with the value provided by the integration instance with the highest source reliability score. For example, if an instance with a higher source reliability has no mapping for a specific custom indicator field, the field will display No entries in the dashboard even though the integration instance with the lower reliability score contains mapping for that field.

To ensure your custom indicator field populates correctly, the integration instance you want to use to map the data must be the primary source used by the system. You can do this by:

• Editing the Source reliability setting of the integration instance you want to use for mapping and data so that its reliability score is higher than all other active enrichment integrations.
• Disabling other enrichment integration instances with equal or higher source reliability and setting them to Do not use by default. This prevents them from competing for priority, allowing your integration to map and populate custom indicator fields correctly.

Create an indicator field

Indicator fields are used to add specific indicator information to incidents. When you create an indicator field, you can associate the field to a specific indicator type or all indicator types. You can then map the custom field to the relevant indicator type. You can also add an indicator field trigger script.

Note

Cortex XSOAR IOC fields are based on the STIX 2.1 specifications. For more information, see Indicator field structure.

Field types

Field type	Description
Boolean	Checkbox
Date picker	Adds the date to the field.
Grid (table)	Include an interactive, editable grid as a field type for selected indicator types or all indicator types. To see how to create a grid field and to use a script, see Add an indicator field trigger script to an indicator field. When you select Grid (table) you can format the table and determine if the user can add rows.
HTML	Create and view HTML content, which can be used in any type of indicator. Note The following HTML tags are not permitted: blockquote, del, dd, div, dl, dt, fieldset, form, h1, h2, h3, h4, h5, h6, hr, iframe, ins, li, math, noscript, ol, pre, p, script, style, table, ul, address, article, aside, canvas, details, dialog, figcaption, figure, footer, header, hgroup, main, nav, output, progress, section, video. The following CSS tags are not permitted: background-color, text-align, font-size, font-family, font-weight, color, line-height, border-style, border, page-break-inside, tablelayout, padding, background-size, display, padding-top, padding-right, padding-bottom, padding-left, text-size-adjust, break-inside, word-break, width, height, -ms-text-size-adjust, -webkit-text-size-adjust.
Long text	Long text is analyzed and tokenized, and entries are indexed as individual words, enabling you to perform advanced searches and use wildcards. Long text fields can't be sorted and used in graphical dashboard widgets. While editing a long text field, pressing enter will create a new line (case is insensitive). Add a placeholder, if required.
Markdown	Add markdown formatted text as a template, which will be displayed to users in the field after the indicator is created. Markdown lets you add basic formatting to text to provide a better end-user experience.
Multi select/Array	Select the following options: Multi-select from a prefilled (static) list An empty array field for the user to add one or more values as a comma-separated list Add a placeholder, if required.
Number	Can contain any number. Default is 0.
Role	The role assigned to the indicator. Determines which users (by role) can view the indicator.
Short text	Short text is treated as a single unit of text and is not indexed by word. Advanced search, including wildcards, is not supported. Short text fields are case-sensitive by default but can be changed to case-insensitive when creating the field. While editing a short text field, pressing enter will save the change. Maximum length 60,000 characters Recommended use is one-word entries, such as username and email address. Select a placeholder, if required.
Single select	Select a value from a list of options. Add comma-separated values.
Tags	Accepts a single tag or a comma-separated list, not case-sensitive. Add a placeholder, if required.
URL	Add a URL when completing the field.
User	A user in Cortex XSOAR.

How to create a field

1. Select Settings & Info → Settings → Object Setup → Indicators → Fields → New Field.
2. Select the relevant field type.
3. Complete the following fields (if relevant):

   Parameter	Description
   Mandatory	If selected, this field is mandatory when used in a form.
   Field Name	A meaningful display name for the field. After you type a name, you will see below the field that the Machine name is automatically populated. The field’s machine name is applicable for searching and the CLI.
   Tooltip	An optional tooltip for the field.

4. In the Basic Settings tab, define the values (according to the selected field type).
5. In the Attributes tab define the following:

   Field	Description
   Script to run when field value changes	The script dynamically changes the field value when script conditions are met. For a script to be available, it must have the field-change-triggered-indicator tag when defining the script. For more information, see Indicator field trigger scripts.
   Add to all indicator types	This option is selected by default, which means this field is available to use in all indicator types. Clear the checkbox to associate this field with a subset of indicator types.
   Make data available for search	The values for this field can be returned in searches.

6. Save the field.

   If you subsequently edit the field, you can optionally select Don't show in the indicators layout. If you select this, the indicator field does not appear in the layout but the data is displayed in the context data.
7. (Optional) Add a custom field to a section in the indicator layout.

   If you select Don't show in the indicators layout, the field will not appear in the layout.
8. (Optional) In the indicator type, map custom indicator fields, so an indicator field is automatically updated, without the analyst having to manually change it.

Indicator fields structure

Cortex XSOAR IOC fields are based on the STIX 2.1 specifications. These fields provide a guideline for the fields we recommend you maintain within an IOC. None of the fields are mandatory, except the value field. Maintaining this field structure enables you to share and export IOCs to additional threat intel based systems as well as to other cybersecurity devices.

Like STIX, Cortex XSOAR indicators are divided into two categories, STIX Domain Objects (SDOs) and STIX Cyber-observable Objects (SCOs). The category determines which fields are presented in the layout of that specific IOC. In Cortex XSOAR, all SCOs can be used in a relationship with either SDOs or SCOs.

Each IOC table of fields is separated into three parts:

• System fields - Fields created and managed by Cortex XSOAR.
• Custom core fields - Custom fields shared by all IOCs of the same time (SDO or SCO). Fields may be empty.
• Custom unique fields - Fields unique to a specific type of IOC. If a user associates more fields with the IOC, the additional fields are also treated as unique.

STIX Cyber-observable Objects (SCO)

Account

Similar to STIX User Account Object, this indicator type represents a user account in various platforms such as operating system, social media accounts, and Active Directory. The value for the object is usually the username for logging in.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of account--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Account Type	Specifies the type of the account, comes from account-type-ov by STIX.
Creation Date	The date the account was created (not the date the indicator was created).
Display Name	The display name of the account as it is shown in the UI.
Groups	The groups the account is a member of.
User ID	The account's unique ID, according to the system it was taken from.

Domain / DomainGlob

Network domain name, similar to the STIX Domain Name object. The value is the domain address.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of domain--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Creation Date	The date the domain was created.
DNS Records	All types of DNS records with a timestamp and their values (GRID).
Expiration Date	The domain expiration date.
Certificates	Any certificates issued for the domain.
WHOIS Records	Any records from WHOIS about the domain (GRID).

Email

A single user email address.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of email--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique
None

File

Represents a single file. For backward compatibility, the indicator has multiple fields for different types of hashes. New hashes, however, should be stored under the Hashes grid field. The file value should be its hash (either MD5, SHA-1, SHA-256, or SHA-512, in that order).

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of file--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Creation Date	The file creation date.
File Extension	The file extension.
Associated File Names	Names the file is associated with.
File Type	The type of the file.
Hashes	Any hashes not specified in a separate field.
imphash	The imphash.
MD5	The MD5 hash.
Modified Date	When the file was modified on the origin.
Path	The path to the file.
Quarantined	Was the file quarantined?
SHA1	The SHA1 hash.
SHA256	The SHA256 hash.
SHA512	The SHA512 hash.
Size	The file size.
SSDeep	The SSDeep hash.

IPv4 / IPv6 / CIDR / IPv6CIDR

Represents an IP address and its subnet (CIDR). If no subnet is provided, the address is treated as a single IP (same as a /32 subnet).

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of type--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Geo Country	The country where the object is located.
Geo Location	A set of geographic coordinates for the object.
WHOIS records	Any records from WHOIS about the domain (GRID).

URL

Represents the properties of a uniform resource locator.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Blocked	A Boolean switch to mark the object as blocked in the user environment.
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of url--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Certificates	Any certificates issued for the domain.

STIX Domain Objects (SDO)

Attack Pattern

Attack patterns are a type of TTP (Tactics, Techniques, and Procedures) that describe ways adversaries attempt to compromise targets. Attack patterns help categorize attacks, generalize specific attacks to the patterns that they follow, and provide detailed information about how attacks are performed. An example of an attack pattern is spear phishing, where an attacker sends a carefully crafted email message with the intent of getting the target to click a link or open an attachment that delivers malware. Attack patterns can also be more specific, such as spear phishing by a particular threat actor (for example, an email saying the target won a contest).

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of attack-pattern--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Kill Chain Phases	The list of kill chain phases this Attack Pattern is used for.
External References	List of external references consisting of a source and ID. For example, {source: mitere, id: T1189}

Campaign

A campaign is a grouping of adversarial behaviors that describes a set of malicious activities or attacks (sometimes called waves) that occur over a period of time against a specific set of targets. Campaigns usually have well-defined objectives and may be part of an intrusion set.

Campaigns are often attributed to an intrusion set and threat actors. The threat actors may reuse known infrastructure from the intrusion set or may set up new infrastructure specifically for conducting that campaign.

Campaigns can be characterized by their objectives and the incidents they cause, the people or resources they target, and the resources (such as infrastructure, intelligence, and malware, tools) they use.

For example, a campaign can describe a crime syndicate's attack using a specific variant of malware and new C2 servers against the executives of ACME Bank during the summer of 2020 to gain secret information about an upcoming merger with another bank.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of campaign--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Aliases	Alternative names used to identify this campaign.
Objective	The campaign’s primary goal, objective, desired outcome, or intended effect.

Course of action

A course of action is an action taken either to prevent an attack or to respond to an attack that is in progress. It may describe technical, automatable responses (applying patches, reconfiguring firewalls), but can also describe higher-level actions such as employee training or policy changes. For example, a course of action to mitigate a vulnerability could describe applying the patch that fixes it.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of course-of-action--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Action	Reserved to capture structured/automated courses of action.

CVE

To preserve backward compatibility, our vulnerability indicator is referred to as CVE, but it is equivalent to the Vulnerability object defined by STIX. Unlike STIX, in TIM the object is identified by its CVE number. A vulnerability is a weakness or defect in the requirements, designs, or implementations of the computational logic (code) found in software and some hardware components (firmware) that can be directly exploited to negatively impact the confidentiality, integrity, or availability of that system.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of vulnerability--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
CVSS Version	The version of the CVSS scoring system.
CVSS Score	The score given to the CVE.
CVSS Vector	The full CVSS vector.
CVSS Table	All CVSS data by metric-value pairs.

Infrastructure

The Infrastructure SDO represents a type of TTP and describes any systems, software services, and any associated physical or virtual resources that support some purpose (for example, C2 servers used as part of an attack, a device or server that is part of a defense, and database servers targeted by an attack). While elements of an attack can be represented by other SDOs or SCOs, the Infrastructure SDO represents a named group of related data that constitutes the infrastructure.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of infrastructure--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Aliases	Alternative names used to identify this infrastructure.
Infrastructure types	The type of infrastructure being described. Values should come from STIX infrastructure-type-ov open vocabulary.

Intrusion set

An intrusion set is a grouped set of adversarial behaviors and resources with common properties that is believed to be orchestrated by a single organization. An intrusion set may capture multiple campaigns or other activities that are all tied together by shared attributes indicating a commonly known or unknown threat actor. New activity can be attributed to an intrusion set even if the threat actors behind the attack are not known. Threat actors can move from supporting one intrusion set to supporting another, or they may support multiple intrusion sets.

Whereas a campaign is a set of attacks over a period of time against a specific set of targets to achieve an objective, an intrusion set is the entire attack package and may be used over a very long period of time in multiple campaigns to achieve potentially multiple purposes.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of intrusion-set--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Aliases	Alternative names used to identify this intrusion set.
Goals	The high-level goals of this intrusion set, what it is trying to do.
Primary Motivation	The primary reason, motivation, or purpose behind this intrusion set. Values should come from STIX attack-motivation-ov open vocabulary.
Secondary Motivation	The secondary reason, motivation, or purpose behind this intrusion set. Values should come from STIX attack-motivation-ov open vocabulary.
Resource level	Specifies the organizational level at which this intrusion set typically works. Values should come from STIX attack-resource-level-ov open vocabulary.

Malware

Malware is a type of TTP that represents malicious code. It generally refers to a program that is inserted into a system, usually covertly. The intent is to compromise the confidentiality, integrity, or availability of the victim's data, applications, or operating system (OS) or otherwise annoy or disrupt the victim.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of malware--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Aliases	A list of other names the malware is known as.
Architecture	The processor architectures (for example, x86, ARM) on the malware instance or family are executable on. The values should come from the STIX processor-architecture-ov open vocabulary.
Capabilities	Any of the capabilities identified for the malware instance or family. The values should come from STIX malware-capabilities-ov open vocabulary.
Implementation Languages	The programming language(s) used to implement the malware instance or family. The values should come from the STIX implementation-language-ov open vocabulary.
Is Malware Family	Whether the object represents a malware family (if true) or a malware instance (if false).
Malware Types	Types of malware. Values should come from STIX malware-type-ov open vocabulary.
Operating System Refs	Identifier of a software object.

Report

Reports are collections of threat intelligence focused on one or more topics, such as a description of a threat actor, malware, or attack technique, including context and related details. They are used to group related threat intelligence together so that it can be published as a comprehensive cyber threat story.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of report--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Publications	Links to publications of the report.

Threat actor

Threat actors are individuals, groups, or organizations believed to be operating with malicious intent. A threat actor is not an intrusion set but may support or be affiliated with various intrusion sets, groups, or organizations over time.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of threat-actor--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Alias	A list of other names the threat actor is known as.
Geo country	The country the threat actor is associated with.
Goals	The high-level goals of this threat actor, what it is trying to do.
Resource Level	The organizational level at which this threat actor typically works. Values for this property should come from STIX attack-resource-level-ov open vocabulary.
Primary Motivation	The primary reason, motivation, or purpose behind this threat actor. Values for this property should come from STIX attack-motivation-ov open vocabulary.
Secondary Motivation	The secondary reasons, motivations, or purposes behind this threat actor. Values for this property should come from STIX attack-motivation-ov open vocabulary.
Sophistication	The skill, specific knowledge, special training, or expertise a threat actor must have to perform the attack. Values for this property should come from STIX threat-actor-sophistication-ov open vocabulary.
Threat actor type	The type(s) of this threat actor. Values should come from STIX threat-actor-type-ov open vocabulary.

Tool

Tools are legitimate software used by threat actors to perform attacks. Knowing how and when threat actors use such tools can help understand how campaigns are executed. Unlike malware, these tools or software packages are often found on a system and have legitimate purposes for power users, system administrators, network administrators, or even regular users. Remote access tools such as RDP and network scanning tools such as Nmap are examples of tools that may be used by a threat actor during an attack.

System Fields	Description
Value	Defines the indicator on Cortex XSOAR. The value is the main key for the object in the system.
Verdict	Malicious, Suspicious, Benign, or Unknown.
Expiration	The expiration date of the object.
Source Time Stamp	When the object was created in the system.
Modified	When the object was last modified.

Custom Fields - Core	Description
Community Notes	Comments and free-form notes regarding the indicator.
Description	The description of the object.
STIX ID	The STIX ID for the object in the format of tool--<UUID>.
Tags	Tags attached to the object.
Traffic Light Protocol	Red, Amber, Green, or White.

Custom Fields - Unique	Description
Alias	Alternative names used to identify this tool.
Tool Types	The kind(s) of tool(s) being described. Values for this property should come from STIX tool-type-ov open vocabulary.
Tool Version	The version identifier associated with the tool.
Kill Chain Phases	The list of kill chain phases this attack pattern is used for.

Indicator field trigger scripts

Indicator field trigger scripts are automated responses that are triggered by a change in an indicator field value. In the script, you define the change in the indicator field value to check for and the actions to take when the change occurs. For example, you can:

• Create a script that runs when the Verdict field of an indicator changes. For example, the script will fetch all incidents related to the indicator and take any action that is configured, such as reopening or changing severity.
• Create a script that runs when the Expiration Status field changes. For example, you can define a script that will immediately update the relevant allow/block list and not wait for the next iteration, as seen in the following sample script:

  indicators = demisto.args().get('indicators')
  new_value = demisto.args().get('new')
  
  indicator_values = []
  for indicator in indicators:
      current_value = indicator.get('value')
      indicator_values.append(current_value)
  
  if new_value == "Expired":
      # update allow/block list regarding expired indicators
  else:
      # update allow/block list regarding active indicators

Note

You must have a TIM license to run field change-triggered scripts on indicator fields.

Indicator field trigger script arguments

Scripts can be created in Python, PowerShell, or JavaScript on the Scripts page. To use a field trigger script, you need to add the field-change-triggered-indicator tag when creating the script. You can then add the script in the Attributes tab when you edit or Create a Custom Indicator Field. If you did not add the tag when creating the script, the script will not be available for use.

Indicator field trigger scripts have the following triggered field information available as arguments (args):

Argument	Description
associatedToAll	Whether the field is associated with all or some indicators. Value: true or false.
associatedTypes	An array of the indicator types the field is associated with.
cliName	The name of the field when called from the CLI.
description	The description of the field.
indicators	A list of indicators that have the current change.
isReadOnly	Specifies whether the field is non-editable. Value: true or false.
name	The name of the field.
new	The new value of the field.
old	The old value of the field.
ownerOnly	Specifies that only the creator of the field can edit. Value: true or false.
placeholder	The placeholder text.
required	Specifies whether this is a mandatory field. Value: true or false.
selectValues	If this is a multi-select type field, these are the values the field can take.
system	Whether it is a Cortex XSOAR defined field.
type	The field type.
user	The username of the user who triggered the script.

Indicator field trigger script best practices

• Indicator field trigger scripts react to changes that have already occurred to the field and cannot validate or block changes to the field.
• Indicator field trigger scripts can be configured on the Verdict, Related Incidents, Expiration Status, and Indicator Type fields, as well as any custom indicator fields.
• Indicator field trigger scripts work in all TIM (Threat Intelligence Management) scenarios and workflows, except for feed ingestion.
• Fields that can hold a list (related incidents, multi-select/tag/role type custom fields) will provide an array of the delta. For example, if a multi-select field value has changed from ["a"] to ["a", "b"], the new argument of the script will get a value of ["b"].
• Indicator field trigger scripts run as a batch. This means that if multiple indicators are changed in the same way and are set to trigger the same action, it will happen in one batch.

  For example, in the following scenario for a configured indicator field trigger script named myTriggerScript on the Verdict indicator field:

  • The Threat Intel Library has two existing Malicious indicators: 1.1.1.1 and 2.2.2.2.
  • The user runs the following command !setIndicators indicatorsValues="1.1.1.1,2.2.2.2" verdict=Benign.
  • The myTriggerScript script will run just once, with the following parameters:

    • new - "Benign"
    • old - "Malicious"
    • indicators - "[{<indicator_1.1.1.1>},{<indicator_2.2.2.2}]"
• When writing indicator field trigger scripts, avoid scenarios that call the scripts endlessly (for example, a change in field A triggers script X, which changes field B's value, which in turn calls script Y, which changes field A's value).

Add an indicator field trigger script to an indicator field

After creating an indicator field trigger script in the Scripts page in Python, PowerShell, or JavaScript, you can then associate it with an indicator field.

1. Go to Settings & Info → Settings → Indicators → Fields.
2. Select the indicator field and click Edit.
3. In the Attributes tab, under Script to run when field value changes, select the desired indicator field trigger script.

   Note

   Indicator field trigger scripts must have the field-change-triggered-indicator tag to appear in the list.

Indicator layout customization

Each indicator type has a unique set of data relevant to that specific indicator type, including layouts. It is important to display the most relevant data for users. Each out-of-the-box indicator comes with a layout. You can customize almost every aspect of the layout, including which tabs appear, in which order they appear, who has permission to view the tabs, what information appears, and how it is displayed.

You can see which indicator type uses the indicator layout in the Types tab under Settings & Info → Settings → Object Setup → Indicators. The indicator layout name appears in the Layout column.

You can customize the display information including fields for existing indicators, by modifying the sections and fields for the following views:

Section	Description
Indicator Summary	You can customize almost every aspect of the layout, including which tabs appear, the order they appear, and who has permission. In each field or tab, you can add filters by clicking the eye icon, which enables you to add conditions that show specific fields or tabs relevant to the indicator. You can add a script in the indicator layout, such as a mapping script, which determines where an IP address originates and displays it on a map. Note Only available if you have a TIM license.
Quick View	Add, edit, and delete sections, fields, and filters in the Quick View section from an incident.
"New"/"Edit" form	Add, edit, and delete fields and buttons to be displayed when creating or editing an indicator.

Note

By default, when editing a list or text values in an incident/indicator layout, the changes are not saved until you confirm your changes (clicking the checkmark icon in the value field). These icons are designed to give you additional security when updating fields in incidents and indicators.

You can change this default behavior by adding a server configuration. For more information, see Configure inline value fields.

Create an indicator layout

1. Select Settings & Info → Settings → Object Setup → Indicators → Layouts → New Layout.

   You can see that you can customize the Indicator Summary section, Quick View, and the New/Edit form.
2. Add a meaningful name for the layout.
3. Customize the tabs by clicking the settings wheel icon and then doing the following:

   Note

   You can click and drag a tab to reorder the tabs.

   Action	Description
   Rename	You can also edit a tab’s name by clicking the tab.
   Duplicate	Copies the existing tab.
   Delete	Deletes the tab.
   Show empty fields	The setting that you configure in the layout becomes the default value seen in the report for the specific tab, which can then be overridden. You can also set a global default value using the UI.summary.page.hide.empty.fields server configuration, which can also be overridden for a specific tab.
   Hide tab	Hides the tab. Rather than deleting the tab, you may want to use the tab again for future use.
   Format for exporting	Build your layout based on A4 proportions to match the format used for exporting. Selecting this option hides the tab by default, but the tab will remain available for export.
   Viewing Permissions	Select which roles can view the tabs.
   Display Filter	Add or view a filter applied to the tab. If the filters apply, the specific fields or tabs are shown in the layout. If the mandatory field is not shown in the layout, the user is not obliged to complete it.

4. Do the following:

   • Drag and drop the required sections, fields, buttons, and tabs.
   • Customize sections and create buttons.
   • Add any required filters.
   • Create new tabs
5. Repeat step 3 for the Quick View tab.
6. In the New/Edit Form, drag and drop the required fields and buttons.

   You can also edit the Basic Information and the Custom Field sections.
7. Save the indicator layout and add it to the indicator type.

Edit an indicator layout

1. Go to Settings & Info → Settings → Object Setup → Indicators → Layouts.
2. Click the name of the indicator type layout you want to edit.

   You are presented with the current layout, which is populated with demo data so you can see how the fields fit.
3. If using a Content Pack Indicator Type Layout, detach or duplicate the layout.

   Note

   If you duplicate the layout, you need to update the indicator type to add the new layout.

   While an indicator layout is detached, it does not receive content pack updates. If you detach an indicator type layout, edit, and later want to receive content pack updates for that layout, we recommend you duplicate the indicator layout before reattaching the original to protect your changes from content pack updates. When detached, you can also edit the layout from the Indicator Type tab.

   1. Select the checkbox for the indicator layout you want to detach.
   2. Right-click and select Detach.

Customize sections

1. Create or edit a layout.
2. From the Sections tab in the Library, drag and drop the following sections:

   Section	Description
   New Section	After creating a new section, click the Fields and Buttons tab and drag and drop the fields as needed.
   Cortex XSOAR out-of-the-box sections	Out-of-the-box sections such as Expiration Status and Verdict.
   General Purpose Dynamic Section	You can add a script in the indicator layout. For example, to assign a script that determines and displays the Geolocation of an IP address on a map. For more information, see Set up Google Maps.

   Note

   To remove or duplicate a section, select the section, click and then select Duplicate, or Remove.
3. Define the section properties, by clicking and then Edit section settings.

   Tip

   Limit the number of incident fields to 50 in each section. You can create additional sections as needed.

   You can determine how a section in the layout appears in the layout. For example, you may want a section header, or configure the fields to appear in rows or as cards. If some of the field values will be very long, use rows instead of cards. If the field values are short, you might want to use cards so you can fit more fields into a section.

   To add a long description in the Description field, click Scrollable description to add a scrollbar to enable the displayed information to grow to fit the content.
4. Drag and drop fields, and add any filters as required.
5. If relevant, create a new tab and repeat the steps as required.

Add a script to the layout

You can add content to the Indicator Summary tab, based on a script, by adding the script in the General Purpose Dynamic Section. The script can return simple text, markdown, or an HTML, the results of which appear in the General Purpose Dynamic Section.

You can add any required information from a script. For example:

• Add a mapping script that determines where an IP address originates and displays it on a map.
• Add a custom widget to the indicator page. The procedure is similar for indicators and incidents.
• Add the FeedRelatedIndicator script from the Scripts page, which contains information about the relationship between an indicator, entity (such as malware), and other indicators (such as a MITRE ATT&K indicator), and connects externally to those indicators, if relevant.

Before you begin, you need to create a script.

Note

Ensure that you have added the dynamic-indicator-section tag, otherwise, you can't select it when adding a script

1. Go to Settings & Info → Settings → Objects Setup → Indicators → Layouts.
2. Click on the indicator layout you want to edit.

   The layout must either be custom content (a layout you created), a layout duplicated from a content pack layout, or a detached layout from a content pack. You cannot edit a layout that is attached. To detach an attached layout, select the indicator layout and click Detach. The layout must either be custom content (a layout you created) or a detached layout from a content pack. You cannot edit a layout that is attached.
3. Drag and drop the General Purpose Dynamic Section onto the page.
4. Select the General Purpose Dynamic Section, click , and then click Edit section settings.
5. In the Name and Description fields, add a meaningful name and a description for the dynamic section that explains what the script displays.
6. In the Automation script field, select the script that returns data for the dynamic section.
7. Click OK.

Create custom buttons

You can add existing buttons or create buttons and then drag and drop them in the layout.

To add a custom button, create a script and then add the new button to the indicator layout and choose the script, as described in the example below. These buttons can simplify and assist an analyst in carrying out various tasks. For example, you can create a button to run an enrichment script on an identified indicator.

For fields (script arguments) that are optional, you can define whether to show them to analysts when they click on buttons. To expose an optional field, select the Ask User checkbox next to the script arguments in the button settings page.

Note

When creating a script for use in an indicator layout, the indicator-action-button tag must be assigned for the script to be available for custom buttons.

In the following example, create a button that adds the indicator to a Hunt incident type so the Threat Intel team can review it.

1. Save the following script on your computer. On the Scripts page, click the upload script icon and upload the file.

   commonfields:
     id: d3716514-4c2b-453c-8072-4fd4807bca0a
     version: 30
   vcShouldKeepItemLegacyProdMachine: false
   name: newIncidentFromIndicator
   script: |+
     from pprint import pformat
   
     args = demisto.args()
   
     fields = {}
     fields['type'] = args['type']
     fields['details'] = args['indicator']['value']
     fields['name'] = args['type'] + " for " + args['indicator']['value']
   
     res = demisto.executeCommand('createNewIncident', fields)
   
   
   
     newID = res[0]['EntryContext']['CreatedIncidentID']
   
     demisto.executeCommand("associateIndicatorsToIncident", {"indicatorsValues": args['indicator']['value'], "incidentId":int(newID)})
   
   
   type: python
   tags:
   - indicator-action-button
   enabled: true
   args:
   - name: type
     required: true
     description: Incident Type
   scripttarget: 0
   subtype: python3
   pswd: ""
   runonce: false
   dockerimage: demisto/python3:3.8.5.11789
   runas: DBotWeakRole

   When uploading to Cortex XSOAR the newIncidentFromIndicator name and the indicator-action-button is already populated.
2. Go to Settings & Info → Settings → Object Setup → Indicators → Layouts and click the relevant indicator type layout.
3. From the Fields and Buttons tab, drag the +New Button and drop into the relevant section.
4. Click to configure.
5. Enter a descriptive name for the button. For this example, we call it Send to the Threat Hunt Team.
6. Select a color.
7. Select the script we added above: newIncidentFromIndicator.
8. In the Script Arguments field, under the type field, add Hunt.

   

   indicator-button.png
9. Save the button.

   When you view an indicator and click this button, an incident is created with the Hunt incident type.

   To test the button, add the layout to the indicator type, go to the Threat Intel (Indicators) page, create a new indicator, and assign it to the relevant indicator type. View the indicator, click the Pass to Threat Hunt Team button, and verify that a new incident has been created.

Add the layout to the indicator type

1. Go to Settings & Info → Settings → Object Setup → Indicators → Types.
2. Select the indicator type and click Edit.
3. In the Layout field, from the dropdown list, add the customized layout.
4. (Optional) For a customized layout, you can contribute it to the Marketplace.

   1. In the Layouts page, select the new layout and then click Contribute to Marketplace.
   2. In the dialog box select either Save and submit your contribution or Save and download your contribution for later use, which you can view in the Contributions tab in Marketplace.

      If you select Save and submit your contribution, your layout is validated and you are prompted to submit to review. You can also view your contribution in Marketplace.