threatlookup Search Operator

The threatlookup search operator allows you to search logs for matches in threat intelligence, providing security analytics to help you to detect threats in your environment.

note

You can also use the threatip search operator to search threat intelligence data based on IP addresses.

Syntax

threatlookup [singleIndicator] [source="<source_value>"] [include="<all|active|expired>"] <indicator> [,<optional_indicator>, …]

Where:

• singleIndicator returns the single best matching indicator. (In the response, num_match indicates how many actual matches there are.) If singleIndicator is not specified, all matching indicators are returned.

  Specifying singleIndicator sorts the list of matching indicators using the following priority order, then returns the indicator at the top of the list:

  1. Active indicators over expired indicators (if you use include="all").
  2. Higher confidence indicators.
  3. More malicious indicators.
  4. Most recently updated indicators.

  If there's still a tie at this point, the system picks the indicator the back-end database returned first.

• source is the source to search for the threat intelligence indicator. If source is not specified, all sources are searched.

• include includes either all, only active, or only expired threat intelligence indicators. If include is not specified, only active matching indicators are returned.

• <indicator> is the indicator to look up for a field name. At least one field name is required. <optional_indicator> is used to add more indicators to look up. Allowed in the filtering are parentheses (); OR and AND boolean operators; and comparison operators =, <, >, =<, =>, !=.
  You can filter on the following indicator attributes:

  • actors
  • confidence
  • id
  • indicator
  • killChain
  • source
  • threatType
  • type
  • validFrom
  • validUntil

Response fields

Query responses return the following fields:

• confidence
• fields
• imported
• indicator
• valid_from
• valid_until
• source
• threat_type
• type
• updated
• num_match (if singleIndicator is used)

Examples

Simple examples

_index=sec_record*
| threatlookup srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

_index=sec_record*
| threatlookup singleIndicator srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

_index=sec_record*
| threatlookup source="mysource" srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

_index=sec_record*
| threatlookup dstDevice_ip, srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

_index=sec_record*
| threatlookup source="mysource" dstDevice_ip, srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

_index=sec_record*
| threatlookup source="mysource" include="active" dstDevice_ip, srcDevice_ip
| where _threatlookup.confidence > 50
| timeslice 1h
| count by _timeslice

Complex examples

Client IP threat info

_sourceCategory=AWS/WAF {{client_ip}}
| parse "\"httpMethod\":\"*\"," as httpMethod,"\"httpVersion\":\"*\"," as httpVersion,"\"uri\":\"*\"," as uri, "{\"clientIp\":\"*\",\"country\":\"*\"" as clientIp,country, "\"action\":\"*\"" as action, "\"matchingNonTerminatingRules\":[*]" as matchingNonTerminatingRules, "\"rateBasedRuleList\":[*]" as rateBasedRuleList, "\"ruleGroupList\":[*]" as ruleGroupList, "\"httpSourceId\":\"*\"" as httpSourceId, "\"httpSourceName\":\"*\"" as httpSourceName, "\"terminatingRuleType\":\"*\"" as terminatingRuleType, "\"terminatingRuleId\":\"*\"" as terminatingRuleId, "\"webaclId\":\"*\"" as webaclId nodrop
| threatlookup singleIndicator clientip
| where (_threatlookup.type="ipv4-addr" or _threatlookup.type="ipv6-addr") and !isNull(_threatlookup.confidence)

All IP threat count

_sourceCategory=Labs/AWS/DynamoDB account=* namespace=* "\"eventSource\":\"dynamodb.amazonaws.com\""
| json "eventName", "awsRegion", "requestParameters.tableName", "sourceIPAddress", "userIdentity.userName" as event_name, Region, entity, ip_address, user
| where Region matches "*" and tolowercase(entity) matches "*"
| where ip_address != "0.0.0.0" and ip_address != "127.0.0.1"
| count as ip_count by ip_address
| threatlookup singleIndicator ip_address
| where (_threatlookup.type="ipv4-addr" or _threatlookup.type="ipv6-addr") and !isNull(_threatlookup.confidence)
| if (isEmpty(_threatlookup.actors), "Unassigned", _threatlookup.actors) as Actor
| sum (ip_count) as threat_count

Use threatlookup in a subquery

_sourceCategory=weblogs
[subquery:_sourceCategory="Labs/SecDemo/guardduty" "EC2 Instance" "communicating on an unusual server port 22"
| json field=_raw "service.action.networkConnectionAction.remoteIpDetails" as remoteIpDetails
| json field=_raw "service.action.networkConnectionAction.connectionDirection" as connectionDirection
| where connectionDirection = "OUTBOUND"
| json field=remoteipdetails "ipAddressV4" as src_ip
| threatlookup singleIndicator threat| if (_threatlookup.confidence >= 85, "high", if (_threatlookup.confidence >= 50, "medium", if (_threatlookup.confidence >= 15, "low", if (_threatlookup.confidence >= 0, "unverified", "Unknown")))) as malicious_confidence
| where malicious_confidence = "high"
| compose src_ip]

Format timestamp results

Timestamps for the following response fields return results as an integer because they use Unix time (also known as epoch time):

• _threatlookup.imported
• _threatlookup.valid_from
• _threatlookup.valid_until
• _threatlookup.updated

To convert the timestamp results to a readable output, you must format it in the search itself with formatDate. For example:

_index=sec_record*
| threatlookup source="mysource" device_ip
| formatDate(_threatlookup.valid_until, "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'") as valid_until