> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/investigate-and-respond-to-threats/threat-intel-management/indicator-configuration/customize-indicator-types-fields-and-layouts.md).
# Customize indicator types, fields, and layouts
Customize indicators in Cortex XSOAR On-prem 8.7 (EoL).
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](#UUID-88723ccc-3ff9-b905-e57a-d9b13bdcc72f). |
| 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.
|
| 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](#UUID-14898d6c-1b62-a3e4-9e38-f10636f8e52c).
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](#UUID-42e0c673-e0e4-6353-5ea1-5c6daac72e83).
4. In the **Custom Fields** tab, map the fields, as required.
For more information, see [Map custom indicator fields](#UUID-033966c2-8a37-16bb-2595-2323d1a51a8b).
See this video for an example of creating a custom indicator type: [Indicators and Enrichment](https://www.youtube.com/watch?v=DVGWeYJMDQQ).
Example 29. 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.
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).
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](#UUID-3559720e-af91-6dea-b2a0-ddfa72c64d5c) 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="" using-brand="AutoFocus V2,VirusTotal"
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.
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:
```programlisting
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:
```programlisting
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:
```programlisting
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.
```programlisting
// 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 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 .
Single-value result:
```programlisting
results = CommandResults(
outputs_prefix='VirusTotal.IP',
outputs_key_field='Address',
outputs={
'Address': '8.8.8.8',
'ASN': 12345
}
)
return_results(results)
```
Multiple-value results:
```programlisting
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.
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.
{% hint style="info" %}
### 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.
{% endhint %}
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 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 .
```programlisting
output =
{
'Type': entryTypes['note'],
'ContentsFormat': formats['json'],
'Contents': ‘this is the enrichment data’,
'EntryContext': {
'Email': ‘xsoar@test.com’,
‘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 outputs
Either a number or a [dbotScore](https://xsoar.pan.dev/docs/integrations/dbot). It can either be a raw number which is the score, or a full entry with DBotScore.
```programlisting
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=`
* `!MalicioiusRationReputation input=`
### 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.
{% hint style="info" %}
### 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.
{% endhint %}
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](https://xsoar.pan.dev/docs/integrations/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.
**Reputation command output**
Outputs return a [dbotScore](https://xsoar.pan.dev/docs/integrations/dbot).
**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=`
* `!domain domain=`
* `!file file=`
### 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.
{% hint style="info" %}
### 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](/cortex-xsoar-8-on-prem/8.7/investigate-and-respond-to-threats/threat-intel-management/indicator-configuration/indicator-classification-and-mapping.md).
{% endhint %}
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.
{% hint style="info" %}
### Note
Cortex XSOAR IOC fields are based on the STIX 2.1 specifications. For more information, see [Indicator field structure](#UUID-c5f95099-485f-88be-4005-d3f950f7dd95).
{% endhint %}
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 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](#UUID-ebf3d861-059a-7158-3ae1-96a2f2da0e31). |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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--`. |
| 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:
```programlisting
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
```
{% hint style="info" %}
### Note
You must have a TIM license to run field change-triggered scripts on indicator fields.
{% endhint %}
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 - "\[{\},{\
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.
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.
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.
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](https://xsoar.pan.dev/docs/reference/articles/google-maps). |
Note
To remove or duplicate a section, select the section, click 
and then select Duplicate, or Remove.
Tip
Limit the number of incident fields to 50 in each section. You can create additional sections as needed.
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 **Script**s 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.
{% hint style="info" %}
### Note
Ensure that you have added the **`dynamic-indicator-section`** tag, otherwise, you can't select it when adding a script
{% endhint %}
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.
{% hint style="info" %}
### 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.
{% endhint %}
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.
```programlisting
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**.
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.7/investigate-and-respond-to-threats/threat-intel-management/indicator-configuration/customize-indicator-types-fields-and-layouts.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.