|
| 1 | +--- |
| 2 | +id: threatlookup |
| 3 | +title: threatlookup Search Operator |
| 4 | +sidebar_label: threatlookup |
| 5 | +--- |
| 6 | + |
| 7 | +import useBaseUrl from '@docusaurus/useBaseUrl'; |
| 8 | + |
| 9 | +<head> |
| 10 | + <meta name="robots" content="noindex" /> |
| 11 | +</head> |
| 12 | + |
| 13 | +<p><a href={useBaseUrl('docs/beta')}><span className="beta">Beta</span></a></p> |
| 14 | + |
| 15 | +The `threatlookup` operator identifies suspicious indicators of compromise in your data which match your [threat intelligence](/docs/security/threat-intelligence/about-threat-intelligence/) sources. Using this operator provides security analytics to help you to detect threats in your environment. |
| 16 | + |
| 17 | +This operator supersedes the more limited [`threatip`](/docs/search/search-query-language/search-operators/threatip/) search operator, allowing matches against multiple sources for multiple kinds of indicators. |
| 18 | + |
| 19 | +## Syntax |
| 20 | + |
| 21 | +``` |
| 22 | +threatlookup [singleIndicator] [source="<source_value>"] <indicator> |
| 23 | +``` |
| 24 | + |
| 25 | +Where: |
| 26 | +* `singleIndicator` returns the single best matching threat intelligence entry. (In the response, `num_matches` indicates how many total matches across your sources there are.) If `singleIndicator` is not specified, all matching entries from your intelligence sources are returned in separate rows. |
| 27 | + |
| 28 | + Note that `singleIndicator` returns the most recent, highest confidence entry from your sources. If there's a tie, the winning entry is whichever the backend storage returned first. |
| 29 | +* `source` is the [threat intelligence source](/docs/security/threat-intelligence/about-threat-intelligence/#threat-intelligence-sources) to search for the threat intelligence indicator. If `source` is not specified, all sources are searched. |
| 30 | +* `<indicator>` is the [field name](https://github.com/SumoLogic/cloud-siem-content-catalog/blob/master/schema/full_schema.md) containing an [indicator](/docs/security/threat-intelligence/upload-formats/#normalized-json-format) to look up. At least one field name is required. |
| 31 | + |
| 32 | +### Response fields |
| 33 | + |
| 34 | +Query responses return the following [normalized indicator](/docs/security/threat-intelligence/upload-formats/#normalized-json-format) fields, which will all be null if no matching record is found: |
| 35 | +* `actors` |
| 36 | +* `confidence` |
| 37 | +* `fields` |
| 38 | +* `id` |
| 39 | +* `imported` |
| 40 | +* `indicator` |
| 41 | +* `kill_chain` |
| 42 | +* `num_matches` (if `singleIndicator` is used) |
| 43 | +* `source` |
| 44 | +* `threat_type` |
| 45 | +* `type` |
| 46 | +* `updated` |
| 47 | +* `valid_from` |
| 48 | +* `valid_until` |
| 49 | + |
| 50 | +## Examples |
| 51 | + |
| 52 | +```sql title="Single best match for srcDevice_ip with confidence greater than 50" |
| 53 | +_index=sec_record* |
| 54 | +| threatlookup singleIndicator srcDevice_ip |
| 55 | +| where _threatlookup.confidence > 50 |
| 56 | +| timeslice 1h |
| 57 | +| count by _timeslice |
| 58 | +``` |
| 59 | + |
| 60 | +```sql title="Matches in a 'mysource' custom source for srcDevice_ip with confidence greater than 50" |
| 61 | +_index=sec_record* |
| 62 | +| threatlookup source="mysource" srcDevice_ip |
| 63 | +| where _threatlookup.confidence > 50 |
| 64 | +| timeslice 1h |
| 65 | +| count by _timeslice |
| 66 | +``` |
| 67 | + |
| 68 | +<!-- Per DOCS-643, add this after sumo://threat/cs is replaced by threatlookup": |
| 69 | +## Threatlookup queries in dashboards |
| 70 | +The `threatlookup` search operator is used for queries in some dashboards, including dashboards in the [Threat Intel Quick Analysis app](/docs/integrations/security-threat-detection/threat-intel-quick-analysis/). These queries provide great examples of how to use the operator. |
| 71 | +To see `threatlookup` used in a query: |
| 72 | +1. Open the Threat Intel Quick Analysis app. |
| 73 | +1. Navigate to a dashboard, such as **Overview**. |
| 74 | +1. Click the three-dot kebab in the upper-right corner of the dashboard panel. |
| 75 | +1. Select **Open in Log Search**. |
| 76 | +1. Look for `threatlookup` used in the query. |
| 77 | +For example, here is the query used for the **Threat Count** panel in the **Threat Intel Quick Analysis - IP** dashboard: |
| 78 | +``` |
| 79 | +_sourceCategory=<source-category-name> |
| 80 | +| parse regex "(?<ip_address>\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})" |
| 81 | +| where ip_address != "0.0.0.0" and ip_address != "127.0.0.1" |
| 82 | +| count as ip_count by ip_address |
| 83 | +| threatlookup singleIndicator ip_address |
| 84 | +// normalize confidence level to a string |
| 85 | +| if (_threatlookup.confidence >= 85, "high", if (_threatlookup.confidence >= 50, "medium", if (_threatlookup.confidence >= 15, "low", if (_threatlookup.confidence >= 0, "unverified", "unknown")))) as threat_confidence |
| 86 | +// filter for threat confidence |
| 87 | +| where threat_confidence matches "*" |
| 88 | +//rename to match threat_<foo> convention |
| 89 | +| %"_threatlookup.actors" as threat_actors |
| 90 | +| %"_threatlookup.type" as type |
| 91 | +| %"_threatlookup.threat_type" as threat_type |
| 92 | +//convert threat valid from to human readable time |
| 93 | +| toLong(%"_threatlookup.valid_from" * 1000) as %"_threatlookup.valid_from" |
| 94 | +| formatDate(%"_threatlookup.valid_from", "MM-dd-yyyy") as threat_valid_from |
| 95 | +| where type matches "ipv4-addr*" and !isNull(threat_confidence) |
| 96 | +| if (isEmpty(threat_actors), "Unassigned", threat_actors) as threat_actors |
| 97 | +|sum (ip_count) as threat_count |
| 98 | +``` |
| 99 | +--> |
| 100 | + |
| 101 | +## Format timestamp results |
| 102 | + |
| 103 | +Timestamps for the following response fields return results as an integer because they use Unix time (also known as *epoch time*): |
| 104 | +* `_threatlookup.imported` |
| 105 | +* `_threatlookup.valid_from` |
| 106 | +* `_threatlookup.valid_until` |
| 107 | +* `_threatlookup.updated` |
| 108 | + |
| 109 | +To convert the timestamp results to a readable output, you must format it in the search itself with [`formatDate`](/docs/search/search-query-language/search-operators/formatdate). For example: |
| 110 | + |
| 111 | +``` |
| 112 | +_index=sec_record* |
| 113 | +| threatlookup source="mysource" device_ip |
| 114 | +| formatDate(_threatlookup.valid_until, "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'") as valid_until |
| 115 | +``` |
| 116 | + |
| 117 | +<!-- Per DOCS-35, add this back once we have support for the cat search operator: |
| 118 | +## Run threatlookup with the cat search operator |
| 119 | +You can run the `threatlookup` search operator with the [`cat` search operator](/docs/search/search-query-language/search-operators/cat/) by using the `sumo://threat-intel` path. This lets you search the entire store of threat intelligence indicators, or just a portion. For example: |
| 120 | +``` |
| 121 | +cat sumo://threat-intel | where _threatlookup.indicator = "192.0.2.0" |
| 122 | +``` |
| 123 | +``` |
| 124 | +cat sumo://threat-intel | where _threatlookup.source = "TAXII2Source" and _threatlookup.indicator = "192.0.2.0" |
| 125 | +``` |
| 126 | +In the `cat` output, timestamp fields (like `valid_until`) will appear as integers. You can use the `formatDate()` function to convert them back to timestamps. For example: |
| 127 | +``` |
| 128 | +cat sumo://threat-intel | formatDate(toLong(_threatlookup.valid_until), "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", "UTC") as valid_until |
| 129 | +``` |
| 130 | +:::note |
| 131 | +You cannot use the cat search operator with the `SumoLogic_ThreatIntel` source. |
| 132 | +::: |
| 133 | +--> |
0 commit comments