Use Variables in Queries
A variable is a placeholder in a LEQL query that represents one or more values.
By storing and reusing values, you can streamline your queries to make them shorter and easier to enter. Also, by keeping queries shorter, you reduce the chance of syntax errors.
Variables are particularly useful in cases where:
- You want to check for the presence of a value in a long string or in a set of complicated identifiers
- You want to search across VIP users' assets
- You want to identify a specific user agent, which is usually a complicated search pattern, containing many characters, names, and numbers
Rapid7 provides sample variables that you can copy and reuse, but you also have the option to create and edit variables of your own. The sample variables that Rapid7 provides were designed to be broadly applicable across most customer environments, so they will be useful to you if your data contains IP addresses, timestamps, or cheap VPNs, for example.
Although Rapid7 provides sample variables, you have the flexibility to curate the variables yourself based on the data that exists in your own environment. For example, you can build a list of VIP users, such as C-suite users, or a list of assets that have a particular regulatory need, such as HIPAA.
Note: Currently, variables can be referenced only in the where() clause and support only a select number of operators. Read more about the limitations.
Example use cases for variables
Searching complex strings
For example, you want to check for the presence of a value in a list of IP addresses. Rather than entering a long query that contains multiple IP addresses, such as:
where(source_ip NOT IN [ IP(10.0.0.0/8), IP(172.27.0.0/16), IP(169.254.0.0/16), IP(192.168.0.0/16), IP(172.16.0.0/16) ])
You can use a Rapid7 variable and your query can look like this:
where(source_ip NOT IN [${private_ip}])
The key source_ip can appear in log sets such as Firewall, Ingress Authentication, and Web Proxy Activity.
Searching regions
If you are searching for log entries from a specific region of the world, then you can use a variable for that region to avoid entering multiple country codes.
So, rather than entering a query like this to search the data from countries that aren't in Canada, the USA, or Mexico:
where(geoip_country_code NOT IN ["CA", "US", "MX"])
You can use a Rapid7 sample variable and your query can look like this:
where(geoip_country_code NOT IN [${na_region}])
The key geoip_country_code can appear in log sets such as Firewall, Ingress Authentication, and Web Proxy Activity.
Variables can be used in these areas of InsightIDR:
- Log Search
- Dashboards
- Searching logs in Investigations
- Basic detection rules
How to use variables
Variables can be referenced in Log Search, Dashboards, Investigations, basic detection rules, and custom detection rules by typing the characters ${ within a where() clause.
Syntax for referencing LEQL variables
A key is not required when you reference a single-value variable. To reference a single-value variable, use this format ${single-value variable name}. However a key and operator are required when you reference a list variable. To reference a list variable, use this format: where(key OPERATOR [${list variable name}]).
In Log Search, you can reference variables when building a query. You must enter the where() clause into the query bar and then reference the variable, for example, where (${single_low_cost_vpn})..
Type the characters ${ to open the variables dropdown menu, where you can select the variable you want to use in your query.
Because variables help you to streamline your queries, they make queries highly reusable. Therefore, it's a good idea to save queries as you create them for easy reference later. To do so, click the Save button at the end of the query bar.
Note: Variables are only supported for use with some LEQL operators and functions at this time. For more information, read about the limitations.
In Investigations, you can reference variables when you are adding raw log data to an investigation. In Investigation Details, click Explore Contextual Data > Search Logs. In the Log Search panel, you can select logs and enter a query to find and select log data that is relevant to the investigation. Variables are supported in this log search view and can be referenced in a where() clause by typing the characters ${.
In Dashboards, you can reference variables when you are filtering dashboards or when you are building a custom card. Variables are supported in the filter query bar and when you create a custom card with a full query on the data source. They can be referenced in a where() clause by typing the characters ${.
Create variables
If you are unable to find an existing variable in InsightIDR that fits your use case, you can create your own variable.
- Go to Settings > Log Management > Variables.
- Click Create Variable.
- Enter a name and description for the variable.
- Note: Variable names are case sensitive.
- Enter the value or values (including any spaces). If you're creating a list variable, separate the values by commas.
- Click Save.
Sample variables
These sample variables are provided for you by Rapid7 and can be found by clicking Settings > Log Management > Variables or by opening the Variables dropdown menu in the Search bar:
| Variable name | Description | Example |
|---|---|---|
private_ip_sample | Includes a list of IANA defined private IP ranges. For example, use this variable to determine if an event came from an internal or external IP range by searching the source_address key in the Firewall Activity log set. | where(connection_status = DENY and source_address not in [${private_ip_sample}]) |
eu_region_sample | Includes a list of country codes from countries in the European Union. For example, use this variable to search the geoip_country_code key in the Firewall Activity log set. | where(geoip_country_code in [${eu_region_sample}]) |
na_region_sample | Includes a list of country codes from North American countries. For example, use this variable to search the geoip_country_code key in the Firewall Activity log set. | where(geoip_country_code) in [${na_region_sample}]) |
low_cost_vpns_sample | Includes a list of low-cost VPN providers. For example, use this variable to search the geoip_organization key in the Ingress Authentication log set. | where(geoip_organization IIN [${low_cost_vpns_sample}]) |
remote_access_solutions_sample | Includes a list of remote access solutions. For example, use this variable to search the process.exe_file.product_name key in the Process Start Events log. | where(process.exe_file.product_name IIN [${remote_access_solutions_sample}]) |
cloud_storage_solutions_sample | Includes a list of cloud storage solutions. For example, use this variable to search the process.exe_file.description in the Process Start Events log. | where(process.exe_file.description IIN [${cloud_storage_solutions_sample}]) |
Limitations
Variables are supported only in the where clause, and can be used only to search strings. For this reason, only a specific set of LEQL operators support variables.
| Search Type | Example | Description |
|---|---|---|
| Keyphrase | where (${single_low_cost_vpn}) | Search for a phrase or part of a phrase that appears anywhere in the log data. |
| Key-value pair (KVP) | where (geoip_organization=${single_low_cost_vpn}) | Search for values that pertain to a key (or field) in the log data using one of these operators: CONTAINSICONTAINSSTARTS-WITHISTARTS-WITH |
| List | where (geoip_organization IN [${all_low_cost_vpns}]) | Search a list of values or compare values using one of these comparison operators:INIINNOT INNOT IINCONTAINS-ANYICONTAINS-ANYCONTAINS-ALLICONTAINS-ALLSTARTS-WITH-ANYISTARTS-WITH-ANYNOCASE() |
For a list of all LEQL operators and their descriptions, read Components for Building a Query.