Using Scanner Search Commands

Use scanner to return log events

The scanner command executes a search query via the Scanner API and returns the results as events. In Splunk parlance, this is an events generating command.

Example. Get ECS FireLens log events that contain the string token ERROR in any field.

| scanner q="%ingest.source_type: 'aws:ecs_firelens' ERROR"

The scanner command returns results as log events

Use scannertable to return a table

The scannertable command also executes a search query via the Scanner API, but instead of returning the results as events, it returns the results as a table. In Splunk parlance, this is a report generating command.

This command is helpful in contexts where you want to generate a report, set up a dashboard widget, or manipulate statistical tables.

Example. Compute aggregated counts of CloudTrail log events by eventSource:

| scannertable q="%ingest.source_type: 'aws:cloudtrail' | stats by eventSource"

The scannertable command returns results as a table

Example queries

Since scanner and scannertable are generating commands, they must be used at the beginning of the search string or at the beginning of a subsearch.

Search - View log events

Use the scanner command to run a query with the Scanner API and return a list of log events. By default, Scanner returns up to 1000 log events. These log events will be those with the most recent timestamp.

For example, here is how to search for all GetObject events in CloudTrail logs indexed by Scanner.

| scanner q="%ingest.source_type: 'aws:cloudtrail' and eventName: GetObject"

Here's how to look for a set of indicators of compromise that are IP addresses:

| scanner q="%ingest.source_type: 'aws:cloudtrail' and sourceIPAddress: (
  23.105.182.19 or 104.251.211.122 or 202.59.10.100 or 162.210.194.35 or
  198.16.66.124 or 198.16.66.156 or 198.16.70.28 or 198.16.74.203 or
  198.16.74.204 or 198.16.74.205 or 198.98.49.203 or 2.56.164.52
)"

Search - View a table

Use the scannertable command to run a query with the Scanner API and return a table. By default, Scanner returns up to 1000 rows.

For example, here is how you can query Cisco Umbrella DNS logs to find the top internal IP addresses with the term "Malware" appearing in the categories column.

| scannertable q="%ingest.source_type: 'cisco:umbrella' 
  and categories: 'Malware' 
  | stats by internal_ip, external_ip"

You can pipe the results of a query into additional Splunk functions to transform the results. In this example, we use rename to change the names some of the fields.

| scannertable q="%ingest.source_type: 'cisco:umbrella' 
  and categories: 'Malware' 
  | stats by internal_ip, external_ip"
| rename internal_ip as src_ip

Join Splunk index with Scanner search results

Here is how you can use Scanner in a sub-search. Let's say you have a Splunk index called threat_intel_ip_addresses containing threat intelligence about malicious IP addresses. You might query for malicious IP addresses above a certain threat score, and then join them with a sub-search that users the scanner command. This query would allow you to determine if any recent AWS console login events came from a high threat IP address.

index=threat_intel_ip_addresses threat_score > 10
| join left=L right=R where L.ip_addr = R.sourceIPAddress
  [scanner q="%ingest.source_type: 'aws:cloudtrail' and eventName: 'ConsoleLogin'"]

Note: The inner search command [scanner q="..."] runs before the join occurs, and it will return up to 1000 log events. This will not perform a join between the entire Splunk index and the entire Scanner index.

Ingest Scanner search results into a Splunk index

You can use the collect command in Splunk to load Scanner search results into a Splunk summary index. This can be helpful when you want to collect preliminary data and trigger a more complex alerts when a threat seems sufficiently clear.

In this example, we look for failed AWS API calls from IAM users and load them into a Splunk index called cloud_api_errors.

| scanner q="%ingest.source_type: 'aws:cloudtrail' and
  userIdentity.type: 'IAMUser' and
  errorCode: *"
| collect index=cloud_api_errors