Extract IOCs
LAST UPDATED: NOV 5, 2024
Extracts indicators of compromise (IOCs) from the provided plain text, converts them to JSON format, and, if Incident IDs are specified, maps each IOC to a D3 artifact and links it to the designated incident.
READER NOTE
D3 artifacts are uniquely defined by their Artifact Type and Artifact Name attributes.
When no D3 artifact can be mapped to an IOC, predefined mapping logic will first create a D3 artifact, then associate the IOC with it.
Implementation | Python |
Command Category | Cyber Utility |
Tags | ARTIFACT |
Inputs
Parameter Name | Required/Optional | Description | Sample Data |
---|---|---|---|
Input Text | Required | The plain text containing potential IOCs for extraction. The maximum allowed character limit is 50000. |
TEXT
|
IOC Types | Optional | The types of IOCs for which to create artifacts. Available types include: URL, XMPP address, Email address, IP address (IPv4, IPV4 CIDR, IPv6), Domain, Cryptographic Hash (Import Hash, Authentication Hash, SHA1, SHA256, SHA512, MD5, SSDEEP), ASN, CVE, Registry Key Path, Google AdSense Publisher ID, Google Analytics Tracker ID, Cryptocurrency Address (Bitcoin, Monero), MAC address, User Agent, MITRE ATT&CK Data (ATT&CK Tactic, ATT&CK Technique, ATT&CK Mitigation),TLP Label, and File Location. By default, artifacts for all recognized IOC types will be created. This parameter applies only when the Incident IDs parameter is specified. |
JSON
|
Incident IDs | Optional | The IDs corresponding to incidents to which the artifacts should be linked. |
JSON
|
Output
Remote Command API
The D3 command API allows you to send requests to D3 SOAR to execute this utility command via REST API.
Request
POST
https://{base_url}/{api_namespace}/api/Command/ExtractIOCs
Headers
Please refer to the page Webhook Configuration Guide - Authentication Method: API Keys for more details.
Request Body
{
"Username": <Username here>,
"Site": <Site here>,
"CommandParams": {
"Input Text": <Input Text here>,
"IOC Types": <IOC Types here>,
"Incident IDs": <Incident IDs here>
}
}
Body Parameters
Parameter Name | Type | Required/Optional | Description |
---|---|---|---|
Username |
| Required | The username of your D3 SOAR account. |
Site |
| Required | The D3 SOAR site to run the remote command. |
Input Text |
| Required | The plain text containing potential IOCs for extraction. The maximum allowed character limit is 50000. |
IOC Types |
| Optional | The types of IOCs for which to create artifacts. Available types include: URL, XMPP address, Email address, IP address (IPv4, IPV4 CIDR, IPv6), Domain, Cryptographic Hash (Import Hash, Authentication Hash, SHA1, SHA256, SHA512, MD5, SSDEEP), ASN, CVE, Registry Key Path, Google AdSense Publisher ID, Google Analytics Tracker ID, Cryptocurrency Address (Bitcoin, Monero), MAC address, User Agent, MITRE ATT&CK Data (ATT&CK Tactic, ATT&CK Technique, ATT&CK Mitigation),TLP Label, and File Location. By default, artifacts for all recognized IOC types will be created. This parameter applies only when the Incident IDs parameter is specified. |
Incident IDs |
| Optional | The IDs corresponding to incidents to which the artifacts should be linked. |
Sample Request
SAMPLE DATA
{
"Username": "Admin",
"Site": "Security Operations",
"CommandParams": {
"Input Text": "Visit our website: https://example.com/store For support, contact us via XMPP at user@xmpp.example.com or email at admin@company.com\r\nOur network segment: 192.168.100.0/24 \r\nOur main office is located at 192.168.1.101 \r\nIPv6 address for our server: 3ffe:1900:4545:3:200:f8ff:fe21:67cf \r\nChecksum for verification: e3b0c44298fc1c149afbf4c8996f04725daac5675fbb3b1458bacf7907cb3a44, da39a3ee5e6b4b0d3255bfef95601890afd80709, d41d8cd98f00b204e9800998ecf8427e, 6f9c15fa7f93a253d0fc9d9d3458b9a2 \r\nFor deeper analysis, our fuzzy hash is 200:f8ff:fe21 \r\nOur network ASN is ASN12345 \r\nStay updated with security patches, notably CVE-2021-3456 \r\nConfigure using registry at HKEY_LOCAL_MACHINE\\SOFTWARE\\Example \r\nTrack our site traffic with Google Analytics UA-1234567-8 \r\nContribute via Bitcoin at 1BoatSLRHtKNngkdXEeobR76b53LETtpyT \r\nOur device MAC address is 00:1A:2B:3C:4D:5E \r\nOur recommended browser settings are Mozilla/5.0 (Windows NT 10.0; Win64; x64) \r\nAppleWebKit/537.36 (KHTML, like Gecko) \r\nChrome/58.0.3029.110 Safari/537.36 \r\nCheck our file at C:\\Users\\Public\\Documents\\example_file.txt \r\nFor advanced users, explore our system mitigation techniques like T1001 and T1055 in our enterprise systems. \r\nInternet domain names. \r\nThis can be standard web domains(example.com), subdomains for updates or downloadable content updates.example.com/latest-update.zip\r\ninformational subdomains for blogs and resources(blog.example.org), internationalized domains(xn--fsq.com)",
"IOC Types": [
"URL",
"XMPP Address",
"Email Address",
"IP Address",
"IPv4 CIDR",
"IPv4",
"IPv6",
"Domain",
"Cryptographic Hash",
"Import Hash",
"Authentication Hash",
"SHA1",
"SHA256",
"SHA512",
"MD5",
"SSDEEP",
"ASN",
"CVE",
"Registry Key Path",
"Google AdSense Publisher ID",
"Google Analytics Tracker ID",
"Cryptocurrency Address",
"Bitcoin",
"Monero",
"MAC Address",
"User Agent",
"TLP Label",
"File Location",
"ATT&CK Mitigation",
"ATT&CK Technique",
"ATT&CK Tactic",
"MITRE ATT&CK Data"
],
"Incident IDs": [
"20240829-5"
]
}
}
Response
Response Fields
Field Name | Type | Description |
---|---|---|
error |
| The error message if the API request has failed. |
returnData |
| The return data from the API request. |
Sample Response
{
"error": "",
“returnData”: {
"Status": "Successful",
"Data": {
"IOCExtraction": {
"urls": [
"https://example.com/store",
"updates.example.com/latest-update.zip"
],
"xmpp_addresses": [
"user@xmpp.example.com"
],
"email_addresses": [
"admin@company.com"
],
"ipv4_cidrs": [
"192.168.100.0/24"
],
"imphashes": [],
"authentihashes": [],
"domains": [
"updates.example.com",
"xn--fsq.com",
"example.com",
"xmpp.example.com",
"blog.example.org",
"company.com",
"latest-update.zip"
],
"ipv4s": [
"192.168.1.101",
"192.168.100.0"
],
"ipv6s": [
"3ffe:1900:4545:3:200:f8ff:fe21:67cf"
],
"sha512s": [],
"sha256s": [
"e3b0c44298fc1c149afbf4c8996f04725daac5675fbb3b1458bacf7907cb3a44"
],
"sha1s": [
"da39a3ee5e6b4b0d3255bfef95601890afd80709"
],
"md5s": [
"d41d8cd98f00b204e9800998ecf8427e",
"6f9c15fa7f93a253d0fc9d9d3458b9a2"
],
"ssdeeps": [
"200:f8ff:fe21"
],
"asns": [
"ASN12345"
],
"cves": [
"CVE-2021-3456"
],
"registry_key_paths": [],
"google_adsense_publisher_ids": [],
"google_analytics_tracker_ids": [
"UA-1234567-8"
],
"bitcoin_addresses": [
"1BoatSLRHtKNngkdXEeobR76b53LETtpyT"
],
"monero_addresses": [],
"mac_addresses": [
"00:1A:2B:3C:4D:5E"
],
"user_agents": [
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Check our file at"
],
"tlp_labels": [],
"attack_mitigations": {
"enterprise": [],
"mobile": []
},
"attack_tactics": {
"pre_attack": [],
"enterprise": [],
"mobile": []
},
"attack_techniques": {
"pre_attack": [],
"enterprise": [
"T1001",
"T1055"
],
"mobile": []
},
"file_paths": [
"C:\\Users\\Public\\Documents\\example_file.txt"
],
"attack_mitigations enterprise": [],
"attack_mitigations mobile": [],
"attack_tactics pre_attack": [],
"attack_tactics enterprise": [],
"attack_tactics mobile": [],
"attack_techniques pre_attack": [],
"attack_techniques enterprise": [
"T1001",
"T1055"
],
"attack_techniques mobile": []
},
"Artifacts": [
{
"ArtifactType": "URL",
"ArtifactDetails": {
"URL": "https://example.com/store",
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "URL",
"ArtifactDetails": {
"URL": "updates.example.com/latest-update.zip",
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "XMPP Address",
"ArtifactDetails": {
"Identity": "user@xmpp.example.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Email Address",
"ArtifactDetails": {
"EmailAddr": "admin@company.com",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "IPv4 CIDR",
"ArtifactDetails": {
"Identity": "192.168.100.0/24",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "updates.example.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "xn--fsq.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "example.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "xmpp.example.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "blog.example.org",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "company.com",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External Endpoint Domain Name",
"ArtifactDetails": {
"Identity": "latest-update.zip",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Internal IP",
"ArtifactDetails": {
"Identity": "192.168.1.101",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Internal IP",
"ArtifactDetails": {
"Identity": "192.168.100.0",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "External IP",
"ArtifactDetails": {
"Identity": "3ffe:1900:4545:3:200:f8ff:fe21:67cf",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Hash SHA256",
"ArtifactDetails": {
"Identity": "e3b0c44298fc1c149afbf4c8996f04725daac5675fbb3b1458bacf7907cb3a44",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Hash SHA1",
"ArtifactDetails": {
"Identity": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Hash MD5",
"ArtifactDetails": {
"Identity": "d41d8cd98f00b204e9800998ecf8427e",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Hash MD5",
"ArtifactDetails": {
"Identity": "6f9c15fa7f93a253d0fc9d9d3458b9a2",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Hash SSDeep",
"ArtifactDetails": {
"Identity": "200:f8ff:fe21",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Autonomous System Number",
"ArtifactDetails": {
"Identity": "ASN12345",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Common Vulnerabilities and Exposure",
"ArtifactDetails": {
"Identity": "CVE-2021-3456",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Google Analytics Tracker ID",
"ArtifactDetails": {
"Identity": "UA-1234567-8",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Bitcoin Address",
"ArtifactDetails": {
"Identity": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "MAC Address",
"ArtifactDetails": {
"Identity": "00:1A:2B:3C:4D:5E",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "User Agent",
"ArtifactDetails": {
"Identity": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Check our file at",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "File Location",
"ArtifactDetails": {
"Identity": "C:\\Users\\Public\\Documents\\example_file.txt",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Enterprise Attack Technique",
"ArtifactDetails": {
"Identity": "T1001",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
},
{
"ArtifactType": "Enterprise Attack Technique",
"ArtifactDetails": {
"Identity": "T1055",
"Additional": {},
"Reputation": "N/A",
"IsNew": true
},
"IncidentIDs": [
"20240829-5"
]
}
]
}
}