Search macros

The Splunk App for Enterprise Security includes a variety of search macros that can be used to create custom searches and notable events. Search macros can be found in the /default directory of the Domain Add-ons (DA) and Supporting Add-ons (SA) listed here.

Some of these search macros provide data. For example:

`authentication`
`malware`
`ids_attack`
`communicate`
`get_summary`
`get_category`

Some search macros bring in lookup table data. For example:

`assets`
`identities`
`categories`

Other search macros perform lookups. For example:

`get_asset`
`get_identities4events`
`get_correlationsearches`

There are also utility search macros. For example:

 `ctime(<timestamp>)`
`get_vendor_product`
`uitime`
`uptime2string`

The back ticks (`) denote the start and the end of a search macro definition when used in the Splunk search language. The values (<timestamp>) following the search macro name denote the type and number of arguments used with the macro. Overloaded macros are macros with the same name, but a different number of required arguments.

To learn more about the syntax used in macros see "Define search macros in Settings" and "macros.conf" in the Splunk Enterprise documentation.

New macros

Note: Need to figure out if we want to document them, where they belong, and how to use them.

Macro	Intended purpose	Expected data types
(new macro?) `useother`

Access Protection

These search macros are part of SA-AccessProtection.

Search macro	Intended purpose	Expected data types
`authentication`	used to report on access events	system access logs, such as ssh, Windows, or database audit
`authentication(<action>)`	used to validate success or failure of authentication access	system access logs, such as ssh, Windows, or database audit
`account_management`	used to report on account management events, such as Create, Update, or Delete actions	system audit logs, such as Active Directory or OpenLDAP
`default_local_accounts`	used to report usage of default local accounts	Special user accounts table and system access logs
`all_default_account_usage(<default_account>,<default_account_system>)	Provides a list of logins to the given host using the given user name
`inactive_account_usage`	tracks and reports on account usage of inactive accounts	From search macros in the Settings menu: `access_tracker` | stats values(dest) as dest,values(tag) as tag,min(firstTime) as firstTime,max(second2lastTime) as second2lastTime,max(lastTime) as lastTime by user | eval _time=lastTime | eval inactiveDays=(lastTime-second2lastTime)/86400 | sort 0 - inactiveDays
`inactive_account_usage(<greaterThan>,<lessThan>)`	wrapper for `inactive_account_usage", requires two variables	From search macros in the Settings menu: `inactive_account_usage` | search inactiveDays>=$greaterThan$ | `hoursago($lessThan$)`

Audit and Data Protection

These search macros are part of SA-AuditAndDataProtection.

Search macro	intended purpose	expected data types
`splunkd_utilization`	reports resource utilization of the Splunk data engine process	Splunk's internal logs
`splunkd_startmode`	reports start mode of the Splunk data engine process	Splunk's internal logs
`index_thruput(<data_source>)`	reports throughput of data by index, source, sourcetype, or host	Splunk's internal logs (metrics.log)
`license_info`	reports license utilization level	Splunk's internal logs (license_audit.log)
`search_activity`	reports search audit activity	Splunk's internal logs (_audit index)
`view_activity`	reports usage of Splunk apps	Splunk's internal logs (_internal index, sourcetype splunk_web_access
`audit_validation`	reports audited events for validation testing	Splunk's internal logs (_audit index)

Common Information Model

These search macros are part of SA-CommonInformationModel.

Macro	Intended purpose	Expected data types
(new macro) `drop_dm_object_name(<object_name>)`
(new macro) `add_dm_object_name(<object_name>)`

Endpoint Protection

These search macros are part of SA-EndpointProtection.

Search macro	intended purpose	expected data types
`cputime`	report all processor usage level records	performance monitoring data, such as data from Windows or Unix endpoints
`cputime(<machine_name>)`	report all processor usage level records for a single machine (cputime(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`cputime(<machine_name>, <top_N_processor_usage_records>)`	report the top N processor usage level records for a single machine (cputime(ACME-001,10))	performance monitoring data, such as data from Windows or UNIX endpoints
`disk`	report all disk space usage level records	performance monitoring data, such as data from Windows or Unix endpoints
`disk(<machine_name>)`	report all disk space usage level records for a single machine (disk(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`disk(<machine_name>, <disk_space_usage_level>)`	report the top N disk space usage level records for a single machine (disk(ACME-001,10))	performance monitoring data, such as data from Windows or Unix endpoints
`endpoint_change`	report system change events	endpoint audit logs, such as data from Windows or Unix endpoints
`listeningports`	report all records of listening network ports on endpoints	performance monitoring data, such as data from Windows or Unix endpoints
`listeningports(<machine_name>)`	report all records of listening network ports on a single machine (listeningports(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`listeningports(<machine_name>, <top_N_listening_network_ports>)`	report the top N records of listening network ports on a single machine (listeningports(ACME-001,10))	performance monitoring data, such as data from Windows or Unix endpoints
`malware`	report malware discovery and cleanup events	endpoint protection data, such as from McAfee or Symantec
`memory`	report all RAM usage level records	performance monitoring data, such as data from Windows or Unix endpoints
`memory(<machine_name>)`	report all RAM usage level records for a single machine (disk(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`memory(<machine_name>, <ram_usage_level>)`	report the top N RAM usage level records for a single machine (disk(ACME-001,10))	performance monitoring data, such as data from Windows or Unix endpoints
`localprocesses`	report all records of running processes on endpoints	performance monitoring data, such as data from Windows or Unix endpoints
`localprocesses(<machine_name>)`	report all records of running processes on a single machine (localprocesses(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`localprocesses(<machine_name>, <top_N_running_processes>)`	report the top N records of running processes on a single machine (localprocesses(ACME-001,10))	performance monitoring data, such as data from Windows or Unix endpoints
`selinuxconfig`	report all SE Linux configuration status records for all machines	system audit data from Linux endpoints
`selinuxconfig(<machine_name>)`	report all SE Linux configuration status records for a single machine (selinuxconfig(ACME-001))	system audit data from Linux endpoints
`selinuxconfig(<machine_name>, <top_N_conf_status_records>)`	report the top N SE Linux configuration status records for a single machine (selinuxconfig(ACME-001,10))	system audit data from Linux endpoints
`service`	report all records of running services on endpoints (note that "service" is used generically to refer to Windows or UNIX system services)	performance monitoring data, such as data from Windows or Unix endpoints
`service(<machine_name>)`	report all records of running services on a single machine (service(ACME-001))	performance monitoring data, such as data from Windows or Unix endpoints
`service(<machine_name>, <top_N_running_services>)`	report the top N records of running services on a single machine (service(ACME-001,10))	performance monitoring data, such as data from Windows or Unix endpoints
`sshdconfig`	report all SSHD configuration status records for all machines	system audit data from UNIX or Linux endpoints
`sshdconfig(<machine_name>)`	report all SSHD configuration status records for a single machine (sshdconfig(ACME-001))	system audit data from UNIX or Linux endpoints
`sshdconfig(<machine_name>, <top_N_SSHD_config_status_records>)`	report the top N SSHD configuration status records for a single machine (sshdconfig(ACME-001,10))	system audit data from UNIX or Linux endpoints
`time_sync`	report all time synchronization status records from all endpoints	system audit data, such as data from Windows or Unix endpoints
`time_sync(<action>)`	report successful or failed time synchronization status record from all endpoints (time_sync(success))	system audit data, such as data from Windows or Unix endpoints
`index_time_delta`	report time synchronization problems on endpoints by evaluating difference between reported time and actual time at indexing events	Splunk internal logs
`ntp_startmode`	report all time synchronization service start mode records from all endpoints (note that any service tagged "time" will be reported, not just ntpd)	system audit data, such as from Windows or UNIX endpoints
`ntp_startmode(<endpoint_name>)`	report all time synchronization service start mode records from a single endpoint. Note that any service tagged "time" will be reported, not just UNIX ntpd. (ntp_startmode(ACME-001))	system audit data, such as from Windows or UNIX endpoints
`system_update`	report patching status on endpoints	system audit data, such as from Windows or UNIX endpoints
`update_startmode`	report patching service status records from all endpoints (note that any service tagged "update" will be reported)	system audit data, such as from Windows or UNIX endpoints
`update_startmode(<endpoint_name>)`	report all patching service status records from a single endpoint. Note that any service tagged "update" will be reported. (update_startmode(ACME-001))	system audit data, such as from Windows or UNIX endpoints
`uptime`	report all OS uptime records from all endpoints	system audit data, such as from Windows or UNIX endpoints
`uptime(<endpoint_name>)`	report all OS uptime records from a single endpoint. (uptime(ACME-001))	system audit data, such as from Windows or UNIX endpoints
`uptime(<endpoint_name>, <top_N_OS_uptime_records>)`	report the top N OS uptime records from a single endpoints. (uptime(ACME-001,10))	system audit data, such as from Windows or UNIX endpoints
`useraccounts`	reports all user account status records, management events, and password information records gathered from all endpoints	system audit data, such as from Windows or UNIX endpoints
`useraccounts(<endpoint_name>)`	reports all user account status records, management events, and password information records gathered from a single endpoint. (useraccounts(ACME-001))	system audit data, such as from Windows or UNIX endpoints
`useraccounts(<endpoint_name>, <top_N_user_account_status_records>)`	reports the top N user account status records, management events, and password information records gathered from a single endpoint. (useraccounts(ACME-001,10))	system audit data, such as from Windows or UNIX endpoints
`system_version`	report all raw events that operating system names and versions have been discovered from	vulnerability scanners such as Nessus or OSSEC, and/or system audit data, such as from Windows or UNIX endpoints

Identity Correlation

These search macros are part of SA-IdentityManagement.

Macro	Intended purpose	Expected data types
`get_bunit(<business_unit_name>)`	Filter results to only show the selected business unit. For instance, sourcetype="Snare:Security"|search `get_bunit(emea)` Provides the ability to search for hosts within the given business unit	Assets and Identities lookups must be populated with business unit information.
`get_category(<category_name>)`	Filter results to only show the selected category. For instance, sourcetype="Snare:Security"|search `get_category(email_servers)` Provides the ability to search for hosts within the given category	Assets and Identities lookups must be populated with category information.
`asset_search(<asset_name>)`	Find all records associated with a single asset by searching the asset-related fields and leveraging unspecified asset correlation information. For instance, asset_search(ACME-001) can find records via the machine's IP or MAC address, using source or destination fields.	The Assets lookup must be populated with enough information about the asset to identify non-directly related fields.
`get_events4identity(<name_compound>, <string_to_match>)`	Return the events associated with a given identity using any field from the Identities table. For instance, get_events4identity(email,jdoe@acmetech.com) can find records associated with the identity that the email address is associated with. Stack the command for more precise usage, such as get_events4identity(first,John) get_events4identity(last,Doe)	The Identities lookup must be populated with enough information about the identity to identify non-directly related fields.
`identity_search(<identity_field_name>)`	Find all records associated with a single identity specified with any field by searching the identity-related fields and leveraging unspecified identity correlation information. For instance, identity_search(jdoe@acmetech.com) can find records via the person's email address, Active Directory login, SAP account name, or phone number, using applicable fields.	The Identities lookup must be populated with enough information about the identity to identify non-directly related fields.
`identity_search(<first_name>, <last_name>)`	Find all records associated with a single identity specified with first and last name by searching the identity-related fields and leveraging unspecified identity correlation information. For instance, identity_search(John,Doe) can find records via the person's email address, Active Directory login, SAP account name, or phone number, using applicable fields.	The Identities lookup must be populated with enough information about the identity to identify non-directly related fields.
`sessions`	Reports all discovered network sessions. Sessions are tracked for VPN and DHCP logs.	VPN or DHCP logs.

Network Protection

These search macros are part of SA-NetworkProtection.

Macro	Intended purpose	Expected data types
`communicate`	Display networking data.	Firewall logs
`communicate(<action>)`	Display networking data by action (allowed or blocked).	Firewall logs
`network_change`	Display records of network change events	Operational logs from network infrastructure devices
`ids_attack`	Display all detected intrusion event records	Intrusion Detection System and Intrusion Prevention System logs, (including network-based, host-based, and other types).
`proxy`	Display web proxy events	Web proxy server logs
`vulnerability`	Display discovered vulnerability data.	Vulnerability scanners, such as Nessus.

Threat Intelligence

These search macros are part of SA-ThreatIntelligence.

Macro	Intended purpose	Expected data types
`filter`	Suppress Notable Events that have been tagged for suppression	The Notable Event Suppression feature needs to be used for this to have effect.
`notable`	Displays Notable Events with proper rendering	the app's _notable index
`suppression_audit`	Reports suppression events from audit logs	The Notable Event Suppression feature needs to be used for this to have effect.
`suppression_audit-expired`	Reports suppression expirations	The Notable Event Suppression feature needs to be used for this to have effect.
`suppressed_notables`	Reports suppressed Notable Events	The Notable Event Suppression feature needs to be used for this to have effect.

Utilities

These search macros are part of SA-Utils.

Macro	Intended purpose	Expected data types
Boolean
`str_to_bool(<field_name>)`	Wrapper for str_to_bool(<string>,<boolean>), which converts the field in-place to "true" or "false"	field name from `str_to_bool`
`str_to_bool(<string>,<boolean>)`	Normalizes values like "T", "f" to "true" or "false" respectively	string and boolean
Date/Time
`get_date(<field_name>)`	Create a new field named "date" in the format "mm-dd-yyyy" from another field containing a UNIX epoch timestamp.	field containing UNIX timestamp
`ctime(<timestamp>)`	Convert an epoch time (UNIX timestamp) to date string in format mm/dd/yyyy hh:mm:ss. Wrapper for ctime(2)	UNIX timestamp
`ctime(<timestamp>, <time_format_specifier>)`	Convert an epoch time (UNIX timestamp) to date string in format mm/dd/yyyy hh:mm:ss, but allows specification of any format.	UNIX timestamp and time format specification
`uitime(<time_field>)`	Same as ctime(1), but leaves the underlying field data as-is. This macro is only used for displaying fields in the UI in a human-readable format, while still permitting accurate sorting. See the core Splunk search command "fieldformat" for additional details.	timestamp
`uitime(<time_field>, <time_specifier>)`	Same as ctime(2), but leaves the underlying field data as-is. This macro is only used for displaying fields in the UI in a human-readable format, while still permitting accurate sorting. See the core Splunk search command "fieldformat" for additional details.	timestamp and time format specification
`uptime2string(<input_field_name>, <output_field_name>)`	Turns an integer number of seconds into a string like "3 days, 10 hours, 25 minutes". Accepts an input field name and output field name as arguments, in that order.	input field (integer) and output field (string)
`get_TimeEpoch(<firstTime>, <lastTime>)`	Takes a firstTime and lastTime as input, and increments the last time so that at least a one-second interval exists between the two. This is used primarily to circumvent errors in drilldowns where lastTime must be strictly greater than (versus greater than or equal to) the firstTime.	timestamp and timestamp
`timeDiff`	Gets time difference in seconds between now and the event timestamp	timestamp
`hourDiff`	Same as timeDiff, but in hours (real-numbered values returned)	timestamp
`dayDiff`	Same as timeDiff, but in days (real-numbered values returned)	timestamp
`hoursago(<number_of_hours>, <comparator>)`	Search for events a certain number of hours offset (before or after) from the input time. Accepts an integral number of hours and a comparator (<, >, >=, <=, =) as input parameters.	timestamp, comparator
`hoursago(<hoursago>)`	Wrapper for hoursago(<number_of_hours>, <comparator>), which defaults to searching for events before (less than) the input time.	value from `hoursago`
`daysago(<number_of_days>, <comparator>)`	Same as hoursago(<number_of_hours>, <comparator>), but for days.	timestamp and comparator
`daysago(<daysago>)`	Same as hoursago(<number_of_hours>, <comparator>), but for days.	value from `daysago`
Event ID
`get_event_hash`	Create the "event_hash" field as the md5sum of the "_raw" field	value of "_raw field"
`get_event_id`	Create the "event_hash" field as the md5sum of the "_time" and "_raw" fields.	value of "_time field" and value of "_raw field"
`parse_event_id(<event_id>)`	Dissect the unique event identifier ("event_id") into "orig_splunk_server", "orig_index", "orig_event_hash". Parses an event_id compatible with real-time (no _cd).	event_id data
Post Process
`postprocess_audit`	To get postprocess_audit eventtype events	eventtype
`postprocess_transact`	To get postprocess events as transactions by "parent" search ID	transaction host, invocation_id
REST
`rest_handler_transactions`	Macro for getting transactions' REST handler calls; used in rest_audit dashboard	REST handler transaction data
Summary Indexing
`get_summary(<index>, <search_name>)`	retrieve summary events by the specific index and name of the search that generated the summary	summary index name and search name
Transformations
`get_namespace`	Look up the namespace (app) for the given source type. Enterprise Security and PCI generate many custom log files, in several dozen Splunk applications. These logs are themselves indexed by Splunk. This macros is used to identify the application that "owns" a particular source type and is primarily used for internal Splunk use.	local lookup data
`get_vendor_product`	Concatenates the vendor and product field values for easier reference.	vendor field and product field values
`lower(<field_value>)`	Lowercases the given field value.	field value (string)
`truncate(<field_name>)`	Truncates the given field value.	field name (string)