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.

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.

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.

1. Go to Settings > Log Management > Variables.
2. Click Create Variable.
3. Enter a name and description for the variable.
   • Note: Variable names are case sensitive.
4. Enter the value or values (including any spaces). If you're creating a list variable, separate the values by commas.
5. 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:

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.

For a list of all LEQL operators and their descriptions, read Components for Building a Query.