Skip to main content

LQL Queries

To provide customizable specification of datasets, Lacework provides the Lacework Query Language (LQL).

LQL is a SQL-like query language for specifying the selection, filtering, and manipulation of data. Queries let you interactively request information from specified curated datasources. Queries have a defined structure for authoring detections.

Lacework offers a set of default LQL queries that are available in your account.

To view all LQL queries in your Lacework account.

lacework query ls

To show a query.

lacework query show <query_id>

To delete a query.

lacework query delete <query_id>
note

LQL syntax may change.

Create a Query​

There are multiple ways you can create a query:

  • Type the query into your default editor (via $EDITOR)
  • Pipe the query to the Lacework CLI command (via $STDIN)
  • From a local file on disk using the flag --file
  • From a URL using the flag --url

There are two formats you can use to define a query:

  • Javascript Object Notation (JSON)
  • YAML Ain't Markup Language (YAML)

To launch your default editor and create a new query.

lacework lql create

The following example checks for unrestricted ingress to TCP port 445.:

---
queryId: LW_Custom_UnrestrictedIngressToTCP445
queryText: |-
  {
     source {
         LW_CFG_AWS_EC2_SECURITY_GROUPS a,
         array_to_rows(a.RESOURCE_CONFIG:IpPermissions) as (ip_permissions),
         array_to_rows(ip_permissions:IpRanges) as (ip_ranges)
     }
     filter {
         ip_permissions:IpProtocol = 'tcp'
         and ip_permissions:FromPort = 445
         and ip_permissions:ToPort = 445
         and ip_ranges:CidrIp = '0.0.0.0/0'
     }
     return distinct {
         ACCOUNT_ALIAS,
         ACCOUNT_ID,
         ARN as RESOURCE_KEY,
         RESOURCE_REGION,
         RESOURCE_TYPE,
         SERVICE
     }
  }

This query specifies an identifier of LW_Custom_UnrestrictedIngressToTCP445, and identifies AWS EC2 security groups with unrestricted access to TCP port 445. The queryText is expressed in Lacework Query Language (LQL) syntax, which is delimited by '{ }' and contains three sections:

  • Source data is specified in the 'source' clause. The source of data is the LW_CFG_AWS_EC2_SECURITY_GROUPS datasource. LQL queries generally refer to other datasources, and customizable policies always target a suitable datasource.

  • Records of interest are specified by the filter clause. In the example, the records available in LW_CFG_AWS_EC2_SECURITY_GROUPS are filtered for those whose IP protocol is tcp, whose from and to port is 445, and CidrIP is 0.0.0.0/0. The syntax for this filtering expression strongly resembles SQL.

  • The fields this query exposes are listed in the return clause. Because there may be unwanted duplicates among result records when Lacework composes them from just these columns, the distinct modifier is added. This behaves like a SQL SELECT DISTINCT. Each returned column in this case is just a field that is present in LW_CFG_AWS_EC2_SECURITY_GROUPS, but we can compose results by manipulating strings, dates, JSON and numbers as well.

The resulting dataset is shaped like a table. The table's columns are named with the names of the columns selected. If desired, you could alias them to other names as well.

Run a Query​

To run an LQL query via editor.

lacework query run --range today

Run a query via ID (uses active profile):

lacework query run MyQuery --start "-1w@w" --end "@w"

Start and end times are required to run a query.

  • Specify start and end times in one of the following formats:
    • A relative time specifier
    • RFC3339 date and time
    • Epoch time in milliseconds
  • Specify start and end times in one of the following ways:
    • As StartTimeRange and EndTimeRange in the ParamInfo block within the query
    • As start_time_range and end_time_range if specifying JSON
    • As --start and --end flags
  • Start and end time precedence:
    • CLI flags take precedence over JSON specifications
    • JSON specifications take precedence over ParamInfo specifications

Update a Query​

There are multiple ways you can update a query:

  • Type the query into your default editor (via $EDITOR)
  • Pass the query ID to load it into your default editor
  • From a local file on disk using the flag --file
  • From a URL using the flag --url

There are two formats you can use to define a query:

  • Javascript Object Notation (JSON)
  • YAML Ain't Markup Language (YAML)

To launch your default editor and update a query.

lacework query update <query_id>

Explore Data Sources​

Several questions arise as you begin to write LQL queries.

What are the data sources I can query?

lacework query list-sources

What fields within the data source are available to me?

lacework query show-source <datasource_id>

How can I see a sample event from a specified datasource?

lacework query preview-source <datasource_id>
Last updated on