Skip to content

CLI Documentation

Jump to bottom
Salim Afiune edited this page Feb 18, 2021 · 75 revisions

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/master/cli/install.sh | bash

Powershell:

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

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

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)

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

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_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

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> 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.

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

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

  1. Specify a start time with the flag --start
  2. Specify both, start and end times with the flags --start and --end
  3. 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.

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 fixes.

Additionally, the CLI makes it easy to request on-demand scans of new images designed for continuous integration (CI) pipelines. You can find more information on Integrating the Lacework CLI with Continuous Integration (CI) Pipelines.

There is also a blog post on Integrating Lacework with Jenkins CI.

NOTE: Periodic vulnerability scans run approximately every hour.

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 run <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 run <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

Raw Lacework API

Use the api command to access raw Lacework's RestfulAPI, useful when there are no available CLI commands that match an API endpoint or to troubleshoot the behavior of the CLI sub-commands. This is considered an advanced command.

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

To see the schema for the AWS_CFG integration type run:

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

For a complete list of available API endpoints visit:

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 details of the 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:

PS C:\> 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! 🙌🏽⭐

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

Clone this wiki locally