Enrichment
Overview
Enrichment is a set of actions created to power up playbook capabilities.
Configuration
In the configuration screen, add the Chronicle SOAR API to enrich entities from Explorer. To retrieve an API key, go to Settings -> Advanced -> API Keys.
Parameter | Type | Default Value | Is Mandatory | Description |
API Key | String | N/A | No | Specify the Chronicle SOAR API key, which is required to enrich entities from Explorer. |
Actions
Enrich Entity from Explorer Attributes
Description
Enriches entities with historic enrichment data using the entity explorer.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description |
Field Name | String | N/A | No | Specify the fields from the entity explorer that will be used to enrich the target entity. Supports comma delimited string. |
Use field Name as Allowlist | Checkbox | Checked | No | If checked, entities will be enriched with fields from the “Field Name” parameter. If unchecked, the list will be used as a blocklist and other fields added. |
Example
In this scenario, we’re enriching all entities with data from entity explorer. All available fields are listed in “Entity Details” within Entity Explorer. Return JSON result of the key/value pairs in entity details.
Action Configurations
Parameter | Value |
Entities | All entities |
Field Name | Blank |
User Field Name as Allowlist | Unchecked |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | JSON Result | Result Shown below |
-
JSON Result
{ "193.0.0.44": {}, "ATTACHMENT.TXT": {"Source": "Added by
", "size": "64", "extension": "txt", "hash_md5": "6529d73ba8183760ad174644e75684fe", "hash_sha1": "dd88508cda7bcfc71ffdbc0e26afe97d3fb9a0b6", "hash_sha256": "1f209f1560df8cb6e983dff99d7a7d2db8dc3e439226abd38ef34facdffd82ec", "hash_sha512": "310d2df6f770dafdf4f84d9851e3fad011d4eb0c5a8af9a5f6d237fb733bca41d41ad6b00efdc2b5c218207 f1a1ac99339923d3c389368f0c1d2ba58e8e1893a", "mime_type": "ASCII text, with no line terminators", "mime_type_short": "text/plain", "ole_data_1_id": "ftype", "ole_data_1_value": "Unknown file type", "ole_data_1_name": "File format", "ole_data_1_description": "", "ole_data_1_risk": "info", "ole_data_1_hide_if_false": "true", "ole_data_2_id": "container", "ole_data_2_value": "Unknown Container", "ole_data_2_name": "Container format", "ole_data_2_description": "Container type", "ole_data_2_risk": "info", "ole_data_2_hide_if_false": "true", "ole_data_3_id": "encrypted", "ole_data_3_value": "", "ole_data_3_name": "Encrypted", "ole_data_3_description": "The file is not encrypted", "ole_data_3_risk": "none", "ole_data_3_hide_if_false": "", "ole_data_4_id": "vba", "ole_data_4_value": "Yes", "ole_data_4_name": "VBA Macros", "ole_data_4_description": "This file contains VBA macros. No suspicious keyword was found. Use olevba and mraptor for more info.", "ole_data_4_risk": "Medium", "ole_data_4_hide_if_false": "", "ole_data_5_id": "xlm", "ole_data_5_value": "No", "ole_data_5_name": "XLM Macros", "ole_data_5_description": "This file does not contain Excel 4/XLM macros.", "ole_data_5_risk": "none", "ole_data_5_hide_if_false": "", "ole_data_6_id": "ext_rels", "ole_data_6_value": "", "ole_data_6_name": "External Relationships", "ole_data_6_description": "External relationships such as remote templates, remote OLE objects, etc", "ole_data_6_risk": "none", "ole_data_6_hide_if_false": "", "ole_data_7_id": "ObjectPool", "ole_data_7_value": "", "ole_data_7_name": "ObjectPool", "ole_data_7_description": "Contains an ObjectPool stream, very likely to contain embedded OLE objects or files. Use oleobj to check it.", "ole_data_7_risk": "none", "ole_data_7_hide_if_false": "true", "ole_data_8_id": "flash", "ole_data_8_value": "", "ole_data_8_name": "Flash objects", "ole_data_8_description": "Number of embedded Flash objects (SWF files) detected in OLE streams. Not 100% accurate, there may be false positives.", "ole_data_8_risk": "none", "ole_data_8_hide_if_false": "true", "content_header_content-type_1": "text/plain; name=\"attachment.txt\"", "content_header_content-transfer-encoding_1": "base64", "content_header_content-disposition_1": "attachment; filename=\"attachment.txt\"", "level": "", "attachment_id": "18"} }
Whois
Description
Queries WHOIS servers for domain registration information. Supports IP Addresses, URLs, Email, Domains. Supports creation of Domain entities linked to target entity and a domain age threshold to set the entity to suspicious.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description |
Create Entities | Checkbox | Checked | No | Specify whether you want to create and link domain entities to URL Email/User Names. |
Domain Age Threshold | Integer | Checked | No | If the domain's age is less than the supplied number of days, it will be marked as suspicious. |
Example
In this scenario, any external hostname entities attached to a case with a domain age of less than 365 days will be marked as suspicious.
Action Configurations
Parameter | Value |
Entities | External hostnames |
Create Entities | Checked |
Domain Age Threshold | 365 |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | True/False | true |
-
JSON Result
{ "Entity": "badsite.com", "EntityResult": {"id": ["32621649_DOMAIN_COM-VRSN"], "status": ["clientDeleteProhibited https://icann.org/epp#clientDeleteProhibited", "clientRenewProhibited https://icann.org/epp#clientRenewProhibited", "clientTransferProhibited https://icann.org/epp#clientTransferProhibited", "clientUpdateProhibited https://icann.org/epp#clientUpdateProhibited"], "creation_date": ["2000-08-09T11:17:46"], "expiration_date": ["2023-08-09T11:17:46"], "updated_date": ["2022-09-18T23:31:54"], "registrar": ["GoDaddy.com, LLC"], "whois_server": ["whois.godaddy.com"], "nameservers": ["NS49.DOMAINCONTROL.COM", "NS50.DOMAINCONTROL.COM"], "emails": ["abuse@godaddy.com"], "contacts": {"registrant": null, "tech": null, "admin": null, "billing": null}, "age_in_days": 8092} }
Enrich Entity from List with Field
Description
Enriches list of supplied entities with a field and a value. This action is often used with “Entity Selection” action to list the entities.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description |
List of Entities | String | N/A | Yes | Specify a list of entities of the same type. |
Entity Type | String | N/A | Yes | Specify the type of entity. |
Entity Delimiter | String | , | Yes | Specify delimiter of list entities. |
Enrichment Field | String | N/A | Yes | Specify the field name that will be added to the entity. |
Enrichment Value | String | N/A | Yes | Specify the value of the field that will be enriched to the entity. |
Example
In this scenario, we’re selecting IP Address entities using the EntitySelection action and passing the results to the “List of Entities” field for enrichment.
Action Configurations (EntitySelection)
Parameter | Condition | Value |
Entity.Type | = | ADDRESS |
Action Configurations (Enrich Entities from List with Field)
Parameter | Value |
Entities | All entities |
List of Entities | [Entity Selection_1.SelectedEntities] |
Entity Type | ADDRESS |
Entity Delimiter | , |
Enrichment Field | is_risky |
Enrichment Value | yes |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | Number of entitled successfully enriched | 3 |
Enrich Entity from Event Field
Description
Extracts fields from an event and adds them to the entity fields.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description |
Fields to enrich | String | N/A | Yes | Specify the name of the field(s) in the event that will be used to enrich the entity. Supports comma separated list. |
Example
In this scenario, fields payload_id and event_description are extracted from a case event and added to entity fields for all file name entities.
Action Configurations
Parameter | Value |
Entities | All file names entities |
Fields to enrich | payload_id, event_description |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | Number of entitled successfully enriched | 1 |
Enrich Entity With Field
Description
Adds enrichment fields to the entity based on a list of key values.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description | Example |
Fields to enrich | JSON | N/A | Yes | Specify a list of key value pairs that will be used to enrich the entity. It needs to be in JSON format. | [ { "entity_field_name": "Title", "entity_field_value": "SalseManager" }, { "entity_field_name": "City", "entity_field_value": "NewYork" } ] |
Example
In this example we’re enriching user entities with two fields: Title and City.
Action Configurations
Parameter | Value |
Entities | All file names entities |
Fields to enrich | [ { "entity_field _name": "Title", "entity_field_value":
"Manager"}, { "entity_field _name": "City", "entity_field_value": "Newyork"}] |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | Number of entities successfully enriched | 13 |
Mark Entity as Suspicious
Description
Marks entities in scope as suspicious.
Parameters
Specify the entity scope you want to mark as suspicious.
Example
In this scenario, we’re marking all external IP entities suspicious. Entity field “is_suspicious” in entity explorer is updated to “true”.
Action Configurations
Parameter | Value |
Entities | External IP addresses |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | Number of entitled marked as suspicious | 3 |
Enrich FileName Entity With Path
Description
Parses path, file name and extension from an entity and enriches it with file_path, file_name, and file_extensions.
Parameters
Specify the file entity scope you want to parse the fields from.
Example
In this scenario, we’re looping through all file name entities and parsing any paths, file names and extensions from the entity identifier.
Action Configurations
Parameter | Value |
Entities | All file name entities |
Action Results
- Script Result
Script Result Name | Value options | Example |
ScriptResult | List of entities enriched. | WORD/THEME/THEME1.XML,WORD/DOCUMENT.XML |
Enrich Source and Destinations
Description
Adds the source and destination links to IPs and Hostnames in an alert.
Parameters
Specify the entity scope you want to parse the fields from.
Example
In this scenario, we’re looping through all IP and hostname entities and enriching them with source and destination links. Even if the entity scope is set to "All entities", it will automatically select IP and hostname entities.
Action Configurations
Parameter | Value |
Entities | All entities |
Action Results
- Script Result
Script Result Name | Value options | Example |
N/A | N/A | N/A |
Enrich Entity from JSON
Description
Adds the source and destination links to IPs and Hostnames in an alert.
Parameters
Parameter | Type | Default Value | Is Mandatory | Description |
Enrichment JSON | JSON | N/A | Yes | Specify the JSON to enrich an entity. |
Identifier KeyPath | String | N/A | Yes | Specify the keypath to the entity identifier in the JSON |
Separator | String | . | Yes | Specify the key path separator/delimiter. |
PrefixForErichment | String | N/A | No | Specify a prefix to use for the enrichment. |
Enrichment JSON Path | String | N/A | No | Specify the JSON |
Example
In this scenario, we’re using an entity identifier of a hash value with field “sha1” to enrich it with data in the Enrichment JSON field. Note the entity needs to exist in the alert before running this action.
Action Configurations
Parameter | Value |
Entities | All entities |
Enrichment JSON | [ { "EntityResult": {"permalink": "https://www.virustotal.com/file/275a021bbfb6489e54d4718 99f7db9d1663fc695ec2fe2a2c4538aabf651fd0f/analysis/15 49381312", "sha1": "3395856ce81f267382dee72602f798b642f14140", "resource":"275A021BBFB6489E54D471899F7DB9D1663 FC695EC2FE2A24538AABF651FDOF","response_code":1, "scan_date":"2019-02-05 15:41:52", "scan_id":"275a021bbfb6489e54d471899f7db9d1663fc695 ec2fe2a2c453Saab651fd0f-1549381312","verbose_msg" : "Scan finished,information embedded","total": 60,"positives": 54, "sha256":"75a021bbfb6489e54d471899f7db9d1663fc695e c2fe2a2c4538aabf651fd0f", "Mas":"44d88612fea8a8f36de82e1278abb02f", "Bkav": {"detected": true,"result": "DOS. Eirac A.Trojan","MicroWorld-eScan": {"version": "14.0.297.0","update": "20190205""scans": {"version":"1.1.1.1","update": "20190201" "detected": true,"result*: "EICAR-Test-File","Entity": "275A021BBFB6489E54D471899F7DB9D1663FC695EC2 FE2A24538AABF651FD0F" }] |
Identifier KeyPath | EntityResult.sha1 |
Separator | . |
PrefixForEnrichment | Blank |
Enrichment JSON Path | Blank |
Action Results
- Script Result
Script Result Name | Value options | Example |
Script Result | # of entities enriched | 1 |