Lacework API Quickstart

This topic helps you get started with the Lacework API. It describes how to set up your API keys in the Lacework Console and then guides you through a few simple API calls using Postman.

Prerequisites

The Lacework Postman workspace includes API request templates, environment settings, and a script that uses your API keys to obtain authentication bearer tokens needed by the API. To follow these steps, you'll fork the Lacework workspace collection and environment settings.

Before starting, make sure you have a Postman account.

Generate API Keys

To generate Lacework API keys, as an administrator in the Lacework Console:

1. Log in to your Lacework account at Lacework Security.
2. Go to Settings > Configuration > API keys.
3. Click Add New.
4. Enter a name for the key and an optional description.
5. Click Save.
6. Click the ellipsis (...) and download the generated API key file.

Now set up Postman.

Fork the Lacework Postman Environment

The environment contains the global environment variables for accessing the Lacework API. You can read more about environments in Postman’s setting up an environment with variables article.

Fork the Lacework environment as follows:

1. Sign in to Postman and go to Lacework’s Postman Workspace.
2. Go to the Environments tab.
3. Click the ellipsis (...) next to LaceworkEnvironment.
4. Select Create a Fork from the menu, as shown below:
5. Give your fork a name, such as My Lacework Environment.
6. For the workspace, choose My Workspace.
7. Click Fork Environment.

This creates a copy of the Lacework environment settings in your own workspace, which you can customize.

Fork the Lacework Postman Collection:

A Postman collection contains a set of requests for an API.

Fork the Lacework collection as follows:

1. Go to Lacework’s Postman Workspace.

2. From the Collections tab, click the ellipsis (...) next to Lacework APIv2.

3. Select Create a Fork, as shown below:

4. Give your fork a name, such as My Lacework API.

5. For the workspace, choose My Workspace.

   info

   Be sure to leave the watch option enabled. By doing so, you’ll be notified when Lacework makes changes to the collection, which you can pull into your fork.

6. Click Fork Collection.

This creates a copy of the Lacework collection in your own workspace, which you will customize next.

Configure the Environment Configuration

Configure your Lacework environment variables using values in the Lacework API key file you downloaded:

1. Go to your Postman workspace and click the Environments tab.

2. Select LaceworkEnvironment.

3. Edit the following environment variables by copying the values from the Lacework API Key file you downloaded earlier:

   • AccessKeyID: keyId value from your API key file.
   • SecretAccessKey: secret value from your API key file.
   • baseUrl: Replace the URL, minus https://, with the account value from your API key file.

   To avoid errors, set the values for both the initial value and the current value for the AccessKeyID, SecretAccessKey, and baseUrl. Your configuration should look something like this:

   

4. Click Save.

Next, make your first call to the Lacework API!

Send a Request

The UserProfile endpoint returns all sub-accounts in the addressed account.

1. In your Lacework collection, choose your custom environment from the top-right environment menu.

2. Expand the UserProfile API folder from the Lacework APIv2 tree and select List Sub-accounts.

3. Click Send.

4. Verify that the request results in a 200 OK status code and a response body like this one:

   {
       "data": [
           {
               "username": "diana@lacework.net",
               "orgAccount": true,
               "url": "customerdemo.lacework.net",
               "orgAdmin": true,
               "orgUser": false,
               "accounts": [
                   {
                       "admin": true,
                       "accountName": "CUSTOMERDEMO",
                       "custGuid": "CUSTOMER_721595854C42...",
                       "userGuid": "CUSTOMER_2FA43544DA84...",
                       "userEnabled": 1
                   }
               ]
           }
       ]
   }
   

Create an LQL Query

As a more advanced example, try using Query endpoints to create and run a custom query. Creating a custom query involves validating the proposed query, loading it in Lacework, and then executing it. Custom queries are useful for building custom policies and for performing ad hoc investigations.

Step 1: Validate the Query

Before attempting to load and execute a query, it's a good idea to validate it as follows:

1. In the Lacework APIv2 tree, navigate to the POST Validate Queries endpoint under the Queries folder in the Lacework APIv2 tree.

2. Set the body of a request for the endpoint to the following:

   {
        "queryText": "QUICKSTART_AWS_CTA_UsageOfRootAccountSevHigh {source {CloudTrailRawEvents} filter {UPPER(EVENT:userIdentity.\"type\"::String) = 'ROOT' AND EVENT:userIdentity.invokedBy::String IS NULL AND EVENT:eventType::String <> 'AwsServiceEvent' AND ERROR_CODE IS NULL} return distinct {INSERT_ID, INSERT_TIME, EVENT_TIME, EVENT}}"
   }    

   This query checks for use of the root user account.

3. Send the request.

4. Verify that the response returns a 200 OK status code and a response body similar to the one in the following figure:

   

Step 2: Create a Query

In this step, you load your named query on Lacework:

1. Go to the POST Create Queries endpoint.

2. Set the body of the request to the following:

   {
       "queryText": "QUICKSTART_AWS_CTA_UsageOfRootAccountSevHigh {source {CloudTrailRawEvents} filter {UPPER(EVENT:userIdentity.\"type\"::String) = 'ROOT' AND EVENT:userIdentity.invokedBy::String IS NULL AND EVENT:eventType::String <> 'AwsServiceEvent' AND ERROR_CODE IS NULL} return distinct {INSERT_ID, INSERT_TIME, EVENT_TIME, EVENT}}",
       "queryId": "QUICKSTART_AWS_CTA_UsageOfRootAccountSevHigh"
   }
   

3. Send the request.

4. Verify that the response is as expected and you get a 201 Created status code:

   

Step 3: Execute the Query

Run the query, as follows:

1. Under the {query id} folder, select the POST Execute Queries by ID endpoint.

2. For the path variable, specify the name of your query, QUICKSTART_AWS_CTA_UsageOfRootAccountSevHigh, as follows:

   

3. Set the body of the request to the following:

   {
       "arguments": [ { "name": "StartTimeRange", "value": "2022-10-19T00:00:00Z" }, { "name": "EndTimeRange", "value": "2022-10-20T00:00:00Z" } ]
   }
       

   Adjust the dates specified for the StartTimeRange and EndTimeRange to match the time range during which the activity occurred in your environment.

4. Send the request

5. Verify the response. If your account is fresh, the result may be empty, as is the case here. Either way, ensure the result is a 200 OK status code.

   

For detailed information on the fields returned, review our Queries API reference documentation.

Next steps

Now that you’ve tested out a simple flow, be sure to:

• Get more familiar with the API by browsing the Lacework API documentation.
• Also, check out the Lacework CLI.