Install Agent with the Lacework CLI

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

The Lacework CLI runs on macOS, Linux, and Windows. If you are new to the Lacework CLI, see Getting Started with the Lacework CLI..

You can use the Lacework CLI to create agent access tokens and install the Lacework agent on supported Linux distributions.

Manage Agent Access Token Using Lacework CLI

You can use the Lacework CLI to create, edit, and enable or disable agent access tokens from the command-line, without the need to login to the Lacework Console.

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 and update the new token on all machines using the old token. When complete, the old token can be safely disabled without interrupting Lacework services.

• To list all agent access tokens:

  lacework agent token list

  For more information, see lacework agent token list.

• To create a new agent access token:

  lacework agent token create MyTokenName [description]

  Note: [description] is an optional argument.

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

  For more information, see lacework agent token create.

• To view agent access token details:

  lacework agent token show MyAgentToken

  For more information, see lacework agent token show.

• To disable an agent access token:

  lacework agent token update MyAgentToken --disable

  For more information, see lacework agent token update.

  Note: By design, agent tokens cannot be deleted. You can only disable tokens.

• To enable an agent access token:

  lacework agent token update MyAgentToken --enable

• To update the name and description of an agent access token:

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

Install Agent on Hosts with the Lacework CLI

You can use the lacework agent install command to install the agent on a remote host over SSH if you have root privileges on the remote host. When you run this command without any options, an interactive prompt appears to collect the authentication information required to access the remote host.

note

This method for deployment is suitable for one off installations, but does not take into account the configuration of the Lacework agent. For custom configuration of the agent with the /var/lib/lacework/datacollector/config.json file, Lacework recommends using a configuration management tool such as Ansible or Chef.

• To authenticate the remote host with a username and password:

  lacework agent install MyHost --ssh_username MyUsername --ssh_password MyPassword

• To authenticate the remote host with an identity file:

  lacework agent install MyUsername@MyHost -i /path/to/your/key

• To use an agent access token of your choice, do the following:

  1. Run the lacework agent token list command to view the list of agent access tokens.
  2. Copy the token you want to use and specify it using the --token option for the lacework agent install command.

After you install the agent, it takes 10 to 15 minutes for agent data to appear in the Lacework Console under Resources > Agents.

Install Agent on AWS EC2 Instances

You can use the following commands to install the Lacework agent on all the EC2 instances in your AWS account:

Command	Description
lacework agent aws-install ec2ic	Uses EC2 Instance Connect to securely connect to EC2 instances and install the agent.
lacework agent aws-install ec2ssh	Uses SSH to securely connect to EC2 instances and install the agent.

note

These commands are supported only for EC2 instances with public IP addresses that are open to the Internet on port 22.

1. Ensure that your AWS account credentials have the AmazonEC2FullAccess or equivalent policy attached.

2. Ensure that your EC2 instances have public IP addresses that are open to the Internet on port 22.

3. Open a terminal window.

4. Add your AWS account credentials as environment variables.

   export AWS_ACCESS_KEY_ID=YOUR-AWS-ACCESS-KEY-ID
   export AWS_SECRET_ACCESS_KEY=YOUR-AWS-SECRET-ACCESS-KEY

5. Run the lacework agent aws-install ec2ic or lacework agent aws-install ec2ssh command. You can use the following options to install the agent only on specific EC2 instances:

   Option	Description
   --include_regions	Installs the agent only on EC2 instances in a specified region. For example, use the following command to install the agent only on EC2 instances in the us-west-2 and us-east-2 regions: lacework agent aws-install ec2ic --include_regions us-west-2,us-east-2
   --tag TagName,TagValue	Installs the agent only on EC2 instances that have a tag with a specific value. For example, use the following command to install the agent only on EC2 instances that have a tag named sales with the value EMEA: lacework agent aws-install ec2ic --tag sales,EMEA Note: This option is supported only for EC2 instances for which you have permissions to retrieve tags. For more information, see Configure Access to Tags in AWS.
   --tag_key TagName	Installs the agent only on EC2 instances that have a specific tag. For example, use the following command to install the agent only on EC2 instances that have a tag named sales: lacework agent aws-install ec2ic --tag_key sales Note: This option is supported only for EC2 instances for which you have permissions to retrieve tags. For more information, see Configure Access to Tags in AWS.

4. The list of agent access tokens defined in your Lacework account are displayed. Select an agent access token using the up or down arrow key and press Enter.

   The agent is installed on all the EC2 instances on which it is not already installed.

Install Agent on Google Compute Engine Instances

You can use the lacework agent gcp-install osl command to install the Lacework agent on all the Google Compute Engine (GCE) instances in your Google Cloud organization.

note

This command is supported only for GCE instances with OS Login enabled and with public IP addresses that are open to the Internet on port 22. For more information about enabling OS Login, see Set up OS Login.

1. Ensure that your GCP account credentials have privileges equivalent to the Compute Instance Admin role.

2. Ensure that your GCE instances have OS Login enabled and have public IP addresses that are open to the Internet on port 22.

3. Open a terminal window.

4. Add your Google Cloud credentials as an environment variable.

   export GOOGLE_APPLICATION_CREDENTIALS=PATH-TO-YOUR-CREDENTIAL-JSON-FILE

   For more information, see GOOGLE_APPLICATION_CREDENTIALS.

5. Run the command:

   lacework agent gcp-install osl GCPUserName

   Where GCPUserName is your GCP username.

   You can use the following options to install the agent only on specific GCE instances:

   Option	Description
   --project_id	Installs the agent only on GCE instances in a specified project. For example, use the following command to install the agent only on GCE instances in the my-lacework project: lacework agent gcp-install osl GCPUserName --project_id my-lacework Note: If you run the command on a GCE instance, the project ID for the instance is read from the GCP metadata server and the agent is installed only on the GCE instances in that project. If you do not run the command on a GCE instance, you must specify the project ID to install the agent only on GCE instances in that project.
   --include_regions	Installs the agent only on GCE instances in a specified region. For example, use the following command to install the agent only on GCE instances in the us-west1 and us-east1 regions: lacework agent gcp-install osl GCPUserName --include_regions us-west1,us-east1
   --metadata MetadataKey,MetadataValue	Installs the agent only on GCE instances that have a metadata key with a specific value. For example, use the following command to install the agent only on GCE instances that have the metadata key named sales with the value EMEA: lacework agent gcp-install osl GCPUserName --metadata sales,EMEA Note: This option is supported only for GCE instances for which you have permissions to retrieve user-defined labels. For more information, see Configure Access to Labels in Google Cloud.
   --metadata_key MetadataKey	Installs the agent only on EC2 instances that have a specific metadata key. For example, use the following command to install the agent only on GCE instances that have the metadata key named sales: lacework agent gcp-install osl GCPUserName --metadata_key sales Note: This option is supported only for GCE instances for which you have permissions to retrieve user-defined labels. For more information, see Configure Access to Labels in Google Cloud.

6. The list of agent access tokens defined in your Lacework account are displayed. Select an agent access token using the up or down arrow key and press Enter.

   The agent is installed on all the GCE instances in your Google Cloud organization on which it is not already installed.