Skip to main content

Create a Query

This topic describes how to create a query with the Lacework API.

All Lacework endpoints require an API access (bearer) token to be specified when you invoke the endpoint. If you already have a secret key, you can use the POST /api/v2/access/tokens endpoint to generate an access token. For details, see API Access Keys and Tokens.

Configure the Query​

This example query checks for unrestricted ingress to TCP port 445. 

{
   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
   }
}

The above is the content of queryText, which you use later with the POST endpoint.

Configure the example using the following guidelines:

  • source: Specify the datasource(s) where the query looks for data. The example specifies LW_CFG_AWS_EC2_SECURITY_GROUPS. To get a list of all available datasources, use the GET /api/v2/Datasources endpoint.
  • filter: Specify the query's records of interest. The example filters the records available in LW_CFG_AWS_EC2_SECURITY_GROUPS.
  • return: List the fields the query exposes. The example adds the distinct modifier, which returns deduped event details because there may be unwanted duplicates among result records.

Format for Use by POST​

After you configure the query, you must format it for use by the POST /api/v2/Queries endpoint. Remove all line breaks from the queryText. The queryText shouldn't include a query ID.

Add a custom queryId. The example's queryId could be LW_Custom_UnrestrictedIngressToTCP445. Custom queryIds cannot start with LW_Global_ because they are reserved for Lacework-authored queries.

Example
{   
    "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}}",
    "queryId": "LW_Custom_UnrestrictedIngressToTCP445"
}
Notice of Deprecation

Including the query ID in the queryText is now deprecated. Lacework recommends omitting the query ID from the queryText.

Create the Query​

To create this query in your Lacework instance, use the POST /api/v2/Queries endpoint and pass in the query using the body input parameter.

If successful, it returns a response:

{
    "data": {
        "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}}",
        "owner": "test@lacework.net",
        "lastUpdateTime": "2022-01-14T01:28:54.000Z",
        ...
    }
}

Update the Query​

If you want to update a query that exists in your Lacework instance, use the PATCH /api/v2/Queries/{queryId} endpoint.

Next Steps​

Create a new alert profile. See Create a Custom Alert Profile.