CLI Documentation

The Lacework Command Line Interface is a tool that helps you manage the Lacework cloud security platform. You can use it to manage compliance reports, external integrations, vulnerability scans, and other operations.

Installation

Bash:

curl https://raw.githubusercontent.com/lacework/go-sdk/main/cli/install.sh | bash

Powershell:

Set-ExecutionPolicy Bypass -Scope Process -Force;
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/lacework/go-sdk/main/cli/install.ps1'))

Homebrew:

brew install lacework/tap/lacework-cli

Configuration

The lacework configure command is the fastest way to set up your Lacework CLI installation. The command prompts you for three things:

account: Account subdomain of URL (i.e. <ACCOUNT>.lacework.net)
api_key: API Access Key
api_secret: API Access Secret

To create an API access key, log in to your Lacework account via WebUI and navigate to Settings > API Keys and click + Create New. Enter a name for the key and an optional description, then click Save. To get the secret key, download the generated API key file.

NOTE: Use the argument --json_file to preload the downloaded API key file.

The following example shows sample values. Replace them with your own.

$ lacework configure
Account: example
Access Key ID: EXAMPLE_1234567890ABCDE1EXAMPLE1EXAMPLE123456789EXAMPLE
Secret Access Key: **********************************

You are all set!

The result of this command is the generation of a file named .lacework.toml inside your home directory ($HOME/.lacework.toml) with a single profile named default.

Multiple Profiles

You can add additional profiles that you can refer to with a name by specifying the --profile option. The following example creates a profile named prod.

$ lacework configure --profile prod
Account: prod.example
Access Key ID: PROD_1234567890ABCDE1EXAMPLE1EXAMPLE123456789EXAMPLE
Secret Access Key: **********************************

You are all set!

Then, when you run a command, you can specify a --profile prod and use the credentials and settings stored under that name.

lacework integration list --profile prod

If there is no --profile option, the CLI will default to the default profile.

To list all available profiles configured in the workstation use:

$ lacework configure list
    PROFILE   |    ACCOUNT    |                         API KEY                          |            API SECRET
--------------+---------------+----------------------------------------------------------+------------------------------------
    prod      | prod-account  | PRODACCT_0C66EF03A0694E16D3203E553C9B13E36E39239FB0FCEBF | *****************************8520
    qa1       | qa1-account   | QA1ACCOT_038B1395C1B5B9BD1C5DEA849DF62FCB95D7697C58C4942 | *****************************9ad8
    qa2       | qa2-account   | QA2ACCOT_0362BF5146FBE18A9CD0AB0259FBEE912EBB1A429A0A213 | *****************************a3cb
  > default   | dev-account   | DEVACCOT_03C8910D0BDCDBD2AFD4355A1C5284104AAA2AE5253938C | *****************************98f1

Organizational Accounts

An organization can contain multiple accounts so you can manage components such as alerts, resource groups, team members, and audit logs at a more granular level inside an organization. A team member may have access to multiple accounts and can easily switch between them.

Note: To enroll your account in an organization follow the Organization Enrollment Process documentation.

Use the global flag --subaccount to switch to a different account inside your organizational account.

For example, having a default profile that has access to your primary account named my-company:

[default]
  account = "my-company"
  api_key = "my-api-key"
  api_secret = "my-api-secret"
  version = 2

To access your sub-account named business-unit you would pass the flag --subaccount business-unit to any command.

There are two ways to set a sub-account persistently:

Exporting the environment variable LW_SUBACCOUNT="<YOUR_SUBACCOUNT>". This will only make the sub-account configuration persist for the active terminal.
Reconfigure your profile with the command lacework configure. This command will prompt you to select any sub-account that you have access to in your organizational account.

To list all accounts in your organization:

lacework account list

Output Formats

The Lacework CLI supports the following output formats:

Human-readable: Default output that presents the information in a "human-readable" or "human-friendly" format, which is much easier to read, but not as useful for automation purposes.
JSON: To switch the output of any command to be formatted as a JSON string, add the flag --json.

There are a few specific commands that have additional formats available:

PDF: For compliance reports, it is possible to download a report in PDF format by adding the flag --pdf. (lacework compliance [provider] get-report)
HTML: For container vulnerability assessments, use the --html flag to render the assessment results in HTML format. (lacework vulnerability container)
CSV: For compliance reports (lacework compliance [provider] get-report) and host vulnerability data (lacework vulnerability host), you can pass the flag --csv to switch the output to CSV format.

Environment Variables

Default configuration parameters found in the .lacework.toml may also be overridden by setting environment variables prefixed with LW_.

To override the account, api_key, and api_secret configurations:

export LW_ACCOUNT="<YOUR_ACCOUNT>"
export LW_API_KEY="<YOUR_API_KEY>"
export LW_API_SECRET="<YOUR_API_SECRET>"

To switch to a different profile permanently in your current terminal:

export LW_PROFILE=prod

For org admins only, to switch to a different sub-account permanently in your current terminal:

export LW_SUBACCOUNT=business-unit

This is a list of all environment variables that can be used to modify the operation of the Lacework CLI.

Environment Variable	Description
`LW_NOCOLOR=1`	turn off colors
`LW_NOCACHE=1`	turn off caching
`LW_DEBUG=1`	turn on debug logging
`LW_JSON=1`	switch commands output from human-readable to JSON format
`LW_NONINTERACTIVE=1`	disable interactive progress bars (i.e. spinners)
`LW_UPDATES_DISABLE=1`	disable daily version checks
`LW_TELEMETRY_DISABLE=1`	disable sending telemetry data
`LW_PROFILE="<name>"`	switch between profiles configured at `~/.lacework.toml`
`LW_ACCOUNT="<account>"`	account subdomain of URL (i.e. `<ACCOUNT>.lacework.net`)
`LW_API_KEY="<key>"`	API access key id
`LW_API_SECRET="<secret>"`	API secret access key
`LW_SUBACCOUNT="<sub-account>"`	sub-account name inside your organization (org admins only)

Manage External Integrations

The lacework integration command will help you manage the external integrations in your Lacework account.

To list all configured integrations in your account:

lacework integrations list

To show details about a specific integration:

lacework integration show <int_guid>

To delete an existing integration:

lacework integration delete <int_guid>

To create a new integration:

lacework integration create

NOTE: This command will open an interactive prompt that will guide you through the creation of an integration.

Create Slack Alert Channel

Agent Management

To analyze application, host, and user behavior, Lacework uses a lightweight agent, which securely forwards collected metadata to the Lacework platform for analysis. The agent requires minimal system resources and runs on most Linux distributions.

Use the command lacework agent install <[user@]host[:port]> for single-host installation of the Lacework agent via Secure Shell (SSH). When this command is executed without any additional flag, an interactive prompt will be launched to help gather the necessary authentication information to access the remote host.

NOTE: For a complete list of supported installation methods, see Agent Install Options

To authenticate to the remote host with a username and password.

lacework agent install <host> --ssh_username <your-user> --ssh_password <secret>

To authenticate to the remote host with an identity file instead.

lacework agent install <user@host> -i /path/to/your/key

lacework-cli-agent-install-release

To provide an agent access token of your choice, use the command lacework agent token list, select a token and pass it to the --token flag.

To authenticate to the remote host on a non-standard SSH port use the '--ssh_port' flag or pass it directly via the argument.

lacework agent install <user@host:port>

To bypass the question to add unknown host keys to the ~/.ssh/known_hosts file, use the flag --trust_host_key.

Agent Access Token Management

To list all agent access tokens:

lacework agent token list

IMPORTANT: Agent tokens should be treated as secret and not published. A token uniquely identifies a Lacework customer. If you suspect your token has been publicly exposed or compromised, generate a new token, update the new token on all machines using the old token. When complete, the old token can safely be disabled without interrupting Lacework services.

To create a new agent access token:

lacework agent token create <name> [description]

NOTE: The [description] is an optional argument.

You can use the agent token name to logically separate your deployments, for example, by environment types (QA, Dev, etc.) or system types (CentOS, RHEL, etc.).

To show details about an agent access token:

lacework agent token show <token>

WARNING: By design, agent tokens cannot be deleted.

To disable an agent access token:

lacework agent token update <token> --disable

To enable an agent access token:

lacework agent token update <token> --enable

You can also update the name and/or description of any agent access token with the command:

lacework agent token update <token> --name dev --description "k8s deployment for dev env"

Lacework Event Insights

The command lacework event helps you do an initial discovery and analysis of events happening in your Lacework account.

You can quickly see the list of all the events from the last 7 days in your account with their severity:

lacework events list

NOTE: This command is limited to displaying 7 days of data.

There are three different options to filter results by time periods:

Specify a start time with the flag --start
Specify both, start and end times with the flags --start and --end
Filter on a specific number of days with the flag --days

For example, to show all events from the past day:

lacework events list --days 1

To show all the events from a specific start time that has severity medium and above (Critical, High, and Medium):

lacework events list --start 2020-08-26T23:28:29Z --severity medium

To drill into an event and show its details, use the command:

lacework event show <event_id>

To open an event in the Lacework Console for further investigation:

lacework event open <event_id>

Manage Compliance Reports

Compliance Reports run automatically within the Lacework platform on a regular basis, typically once a day. You can use the lacework compliance command to interact with the three major cloud providers we support, AWS, Google Cloud, and Azure Cloud.

To list all AWS accounts configured in your account:

lacework compliance aws list-accounts

To visualize a compliance report for an AWS account:

lacework compliance aws get-report <account_id>

You can extend the details of a compliance report by providing the --details flag, you can also download the report in PDF format by specifying the --pdf flag. You can filter the recommendations table with --category, --severity, --status, --service flags.

To use filtering flags on a compliance report:

lacework compliance aws get-report <account_id> --category s3 --status non-compliant --severity high

To run an ad-hoc compliance assessment use the command:

lacework compliance aws run-assessment <account_id>

NOTE: You can view reports and run assessments for Azure Cloud with the sub-command lacework compliance azure, and for Google Cloud with the sub-command lacework compliance google.

Container Vulnerability Assessments

The Lacework Platform provides the capability to scan container images for vulnerabilities at both build time and runtime. The Lacework CLI provides the lacework vulnerability container sub-command with a number of capabilities to retrieve data about container vulnerability assessments, which is designed for individuals or teams responsible for tracking and remediating vulnerabilities by providing relevant data to help with prioritization through the ability to sort assessments by what is actively running in the environment, and by filtering on vulnerabilities that have available fixes.

To view all of the container vulnerability assessments for your Lacework account for the last 7 days (default):

$ lacework vulnerability container list-assessments

Additionally, you can filter results with the following flags:

--active will display only vulnerabilities that are active within your environment
--fixable will display only vulnerabilities with fixes
--repository will display assessments for the specific repository (Note: you may pass this flag multiple times to filter on multiple repositories)
--start specify the start of the time range in UTC (format: yyyy-MM-ddTHH:mm:ssZ)
--end specify the end of the time range in UTC (format: yyyy-MM-ddTHH:mm:ssZ)

To view all of the containers active in your environment with vulnerabilities that have fixes:

lacework vulnerability container list-assessments --active --fixable

To view a specific container vulnerability assessment use the command:

lacework vulnerability container show-assessment <sha256:hash>

By default, this command expects a sha256 image digest or tag. To lookup an assessment by its image id, use the flag --image_id followed by the sha256 image id.

You can extend the details of a vulnerability assessment by providing the flag --details.

Additionally, there are a few more flags you can use to modify the output of the assessment:

--fixable will display only fixable vulnerabilities
--packages modify the output format to show a list of packages with CVE count
--html will generate a vulnerability assessment in HTML format

To request an on-demand container vulnerability scan run the command:

lacework vulnerability container scan <registry> <repository> <tag|digest>

Where:

<registry> is the container registry where the container image has been published
<repository> is the repository name that contains the container image
<tag|digest> could be, either a tag or an image digest to scan (digest format: sha256:1ee...1d3b)

Scans can take up to 15 minutes to return results, to verify the status of the container vulnerability scan and view the assessment results, use the command:

lacework vulnerability container scan-status <request_id>

The following is an example of integrating the lacework vulnerability container command into a CI pipeline. The specific example requests an on-demand container vulnerability scan and waits for the scan to complete (results will be displayed in the terminal):

lacework vulnerability container scan <registry> <repository> <tag|digest> --poll --noninteractive

The --noninteractive flag disables interactive progress bars. ⏲️

When the flag --poll is specified, there are a few other flags you can use to modify the output of the assessment:

--fixable will display only fixable vulnerabilities
--packages modify the output format to show a list of packages with CVE count
--html will generate a vulnerability assessment in HTML format

Generate Static HTML Vulnerability Assessment

To provide developers with clear, actionable, insights to understand and remediate vulnerabilities, the Lacework CLI has the ability to generate static HTML files of container vulnerability assessments.

Use the flag --html in the following commands:

lacework vulnerability container scan
lacework vulnerability container scan-status
lacework vulnerability container show-assessment

The result is a standalone HTML file that can be downloaded and shared with other teams without additional artifacts, it looks exactly like the Lacework Console! 🖥️

Host Vulnerability Assessments

Lacework provides the ability to assess, identify, and report vulnerabilities found on Linux hosts within your environment. This means you can identify and take action on software vulnerabilities in your VMs and manage that risk proactively.

The Lacework CLI provides the lacework vulnerability host command to retrieve data on host vulnerability assessments with the intention of providing fast, accurate, and actionable data via Lacework's APIs. This includes the ability to list all CVEs found on hosts in your environment, search for hosts in your environment that have a specific CVE, show the assessment for a specific host, and the ability to submit a package-manifest.json for on-demand scanning of vulnerabilities.

To list the CVEs found in the hosts in your environment:

lacework vulnerability host list-cves

Additionally, you can filter results with the following flags:

--active will display only vulnerabilities that are active within your environment
--fixable will display only vulnerabilities with fixes
--packages modify the output format to show a list of packages with CVE count

To list the hosts that contain a specific CVE in your environment:

lacework vulnerability host list-hosts <cve_id>

Additionally, you can filter results with the following flags:

--online only show hosts that are online
--offline only show hosts that are offline

To request an on-demand host vulnerability assessment of your software packages to determine if the packages contain any common vulnerabilities and exposures:

lacework vulnerability host scan-pkg-manifest '{
    "os_pkg_info_list": [
        {
            "os":"Ubuntu",
            "os_ver":"18.04",
            "pkg": "openssl",
            "pkg_ver": "1.1.1-1ubuntu2.1~18.04.5"
        }
    ]
}'

NOTE:

Only packages managed by a package manager for supported OS's are reported.

Calls to this operation are rate limited to 10 calls per hour, per access key.

This operation is limited to 10k packages per command execution.

To generates a package-manifest formatted for usage with the Lacework scan package-manifest API:

lacework vulnerability host generate-pkg-manifest

To automatically generate a package manifest from the localhost and send it directly to the Lacework scan package-manifest API:

lacework vulnerability host scan-pkg-manifest --local

To show the results of a host vulnerability assessment:

lacework vulnerability host show-assessment <machine_id>

Additionally, you can filter results with the following flags:

--active will display only vulnerabilities that are active within your environment
--fixable will display only vulnerabilities with fixes
--packages modify the output format to show a list of packages with CVE count

LQL Queries and Policies Overview

To provide customizable specification of datasets, Lacework provides the Lacework Query Language (LQL). LQL is a human-readable text syntax for specifying selection, filtering, and manipulation of data. It overlaps with SQL in its syntax and what it allows.

Currently, Lacework has introduced LQL for the configuration of AWS CloudTrail policies and queries. This means you can use LQL to customize AWS CloudTrail policies only. For all other policies, use the previously existing methods.

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

For more information about LQL, visit:

https://support.lacework.com/hc/en-us/articles/4402301824403-LQL-Overview

To view all LQL queries in your Lacework account.

lacework query ls

To show a query.

lacework query show <query_id>

To execute a query.

lacework query run <query_id>

NOTE: LQL syntax may change.

To view all the policies in your Lacework account.

lacework policy ls

To view more details about a single policy.

lacework policy show <policy_id>

To view the LQL query associated with the policy, use the query id shown.

lacework query show <query_id>

Limitations:

The maximum number of records that each policy will return is 1000
The maximum number of API calls is 120 per hour for ad-hoc LQL query executions

Query Sources

Several instinctive questions arise as one begins 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>

Relative Time Specifiers for LQL Queries

The Lacework CLI is dedicated to making the execution of LQL queries as simple as possible. While the API requires a strict RFC3339 Date and Time specification, the Lacework CLI introduces the concept of relative time specifiers.

Relative times allow a user to represent time values dynamically by using specifiers to communicate how to offset from the current time. For instance, a relative time of -24h would produce a date/time that was 24 hours less the current time. Relative times can also snap to a particular time. For instance, a relative time of @d would represent the start of the current day.

A relative time has 3 components:

A signed (+/-) integer.
A relative time unit.
A relative time snap.

Lacework supports the following relative time units:

y - year
mon - month
w - week
d - day
h - hour
m - minute
s - second

A few more things to consider: To represent the current time, one can either specify now or +0s. When specifying an integer and relative time unit, snaps are optional. When specifying a snap, the integer and relative time unit are optional. For instance, @d is actually interpreted as +0s@d.

Usage: lacework query run --start -1d@d --end @d

Natural Time Ranges for LQL Queries

Natural time ranges allow a user to represent time range values using natural language. For instance, a natural time range of yesterday would represent a relative start time of -1d@d and a relative end time of @d.

A natural time has 3 components:

An adjective.
A positive number (only when using the last adjective).
The full text representation of a relative time unit (i.e. year/years).

We support the following adjectives (disambiguating previous and last by design):

this/current
previous
last

A few more things to consider:

last implies "in the last". So last week reads as "in the last week" and represents a start time of -1w and an end time of now.
previous will always snap. So previous week represents a start time of -1w@w and an end time of @w.
yesterday is a valid natural time and is equivalent to previous day.
today is a valid natural time and is equivalent to this day or current day.

Usage: lacework query run --range "this month"

Raw Lacework API

Use the api command to access raw Lacework's API. The command is useful to troubleshoot the behavior of commands, access both API v1 & v2, etc. This is considered an advanced command.

For APIv1

An example of an APIv1 endpoint you can access that is not abstracted by the CLI is the /v1/external/integrations/schema/{TYPE}, this API will return the integration schema for the passed integration type.

To see the schema of the AWS_CFG integration type run:

lacework api get /v1/external/integrations/schema/AWS_CFG

For a complete list of available APIv1 endpoints visit:

https://YOUR-ACCOUNT.lacework.net/api/v1/external/docs

For APIv2

You can also send APIv2 requests such as /v2/schemas, this API will return the list of all available Lacework schemas:

lacework api get /v2/schemas

For a complete list of available APIv2 endpoints visit:

https://YOUR-ACCOUNT.lacework.net/api/v2/docs

Telemetry

At Lacework, we develop and launch services thinking of our customers first. We thrive when we have customer feedback. Telemetry is additional information that helps us to better understand our customer's needs, diagnose issues, and deliver features that improve the customer experience.

The Lacework CLI collects telemetry, such as generic usage metrics, system and environment information, and errors. For more details about types of telemetry collected, see Types of Information Collected.

The Lacework CLI does not collect personal information, such as IP address. It also does not collect sensitive information passed through arguments or flags, such as usernames and passwords.

Opting Out of Telemetry

Users can opt-out of telemetry for the Lacework CLI by setting the environment variable LW_TELEMETRY_DISABLE to true.

NOTE: You must repeat the command for each new terminal or session.

Unix:

export LW_TELEMETRY_DISABLE=1

Windows:

setx LW_TELEMETRY_DISABLE 1

Types of Information Collected

Usage information – Commands and subcommands that are run.
Errors and diagnostic information – The status and duration of commands that are run, including exit codes, and failures when connecting to the Lacework API.
System and environment information – The version, operating system (Windows, Linux, or macOS), installation method, and the environment in which the Lacework CLI is executed (for example, inside a CI system, or a terminal).

We love and accept all sorts of contributions! 🙌🏽⭐

Provide feedback by opening new Github issues 💯
Do you see anything from this list you can help use code? Open a Pull Request 🥇
Would you like to reach out to our team directly? Send us an email to [email protected] 📩

🆕 Latest Release
🔧 Release Process
💻 CLI Documentation
🐳 CLI Docker Containers

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Documentation

Installation

Bash:

Powershell:

Homebrew:

Configuration

Multiple Profiles

Organizational Accounts

Output Formats

Environment Variables

Manage External Integrations

Agent Management

Agent Access Token Management

Lacework Event Insights

Manage Compliance Reports

Container Vulnerability Assessments

Generate Static HTML Vulnerability Assessment

Host Vulnerability Assessments

LQL Queries and Policies Overview

Query Sources

Relative Time Specifiers for LQL Queries

Natural Time Ranges for LQL Queries

Raw Lacework API

For APIv1

For APIv2

Telemetry

Opting Out of Telemetry

Unix:

Windows:

Types of Information Collected

Clone this wiki locally