Configure Agent Behavior in config.json File – Lacework

This topic contains the following sections.

General Agent Properties
File Integrity Monitoring (FIM) Properties

If you run the install.sh script to install a Lacework agent on a machine, the script creates a config.json file in the /var/lib/lacework/config directory. You can add properties to the config.json file to alter the agent behavior as described below.

General Agent Properties

The config.json file must start with a { parentheses and end with a } parentheses with commas separating each property as shown by the contents of this example config.json file:

{
"tokens": {"accesstoken": "Your_Access_Token"},
"proxyurl":"http://Your_Proxy_Server:Your_Port"
}

This first section describes the general agent properties.

autoupgrade Property

If this property is set to enable, the agent automatically upgrades itself. This is the default setting. Before changing this setting, contact Lacework Customer Success.

For example, to disable autoupgrade, enter this in the config.json file:

"autoupgrade": "disable"

cmdlinefilter Property

Specify to selectively disable command-line argument collection when Lacework is collecting process metadata. By default, the agent collects all the command-line arguments for all executables unless limited by the cmdlinefilter property.

Lacework protects your data as it is collected and persisted in Lacework. For more information, see Lacework Security. However, you may choose to selectively disable sensitive data collection by the Lacework agent by specifying the cmdlinefilter property in the agent JSON configuration file. Limiting the data collected by the agent reduces Lacework’s process-aware threat and intrusion detection in your cloud environment and limits the events that Lacework generates. If you must disable sensitive data collection in your environment, limit disabling to the smallest set of executables possible.

The cmdlinefilter property supports the sub-properties called allow and disallow and these sub-properties support lists of comma-separated strings and the * wildcard.

The agent matches an executable only if the string in the sub-property matches the name of the executable, including the pathname.

For example, if the filter string is:

allow=java,bin/bash

Then this would match /bin/java, /usr/bin/java, /bin/bash, /usr/bin/bash. But it would not match /bin/java_2 (not a suffix match), /bin/myjava (needs to match full command), or /mybin/bash (needs to match full path component).

disallow Sub-Property

If a list of comma-separated strings is specified for the disallow sub-property and an executable path contains one of the specified strings, the Lacework agent does not collect data for that executable. In the following example, any java executable found in the operating system is excluded from collection.

"cmdlinefilter": {"allow": "", "disallow": "java"}

If you specified /bin/java both the /usr/bin/java and /usr/mypath/bin/java match and therefore both would be executed from collection.

"cmdlinefilter": {"allow": "", "disallow": "/bin/java"}

allow Sub-Property

If a list of comma-separated strings is specified for the allow sub-property the Lacework agent collects data only for those executables that match one of the strings. In the following example, only the perl and bash executables found in the operating system are included in collection.

 "cmdlinefilter": {"allow": "perl,bash", "disallow": ""}

WARNING: Limiting the data collected by the agent reduces Lacework’s process-aware threat and intrusion detection in your cloud environment and limits the events that Lacework generates. Lacework recommends using extreme caution when specifying these properties. Limiting collection to a small set of executables as shown in the previous example is not recommended.

The following invocation sections are listed in the order of most recommended to least recommended.

All Executables

When the “*” wildcard is specified for the allow property, and nothing is specified for the disallow property, the agent collects data for all executables.

"cmdlinefilter": {"allow": "*", "disallow": ""}

This is the default and the recommended setting. If you do not specify the cmdlinefilter property, this is the default setting.

Disable Specified Executables

To exclude the collection for a specified list of executables, set the allow property to “” and list the executables to exclude in the ‘disallow’ property.

"cmdlinefilter": {"allow": "", "disallow": "/usr/bin/mysql,java"}

If any of the strings specified in the list match an executable path, data about that executable is not collected. In this example, all java executables found in the operating system are excluded from collection but only mysql executable paths that contain the string /usr/bin/mysql are excluded, for example, the /usr/me/bin/mysql path does not contain the /usr/bin/mysql’ string so it is not excluded and data is collected for it. This setting stops the collection of data for the listed executables. If you must limit collection for some executables, this is the recommended setting.

Only Allow Specified Executables

To limit the collected data to a specified list of executables, list the allowed executables in the allow property and specify “” for the disallow property.

"cmdlinefilter": {"allow": "perl,/bin/bash", "disallow": ""}

In this example, all perl executables found in the operating system are included in the collection but only the bash executable paths that contain the string /bin/bash are included in the collection, for example, both /usr/bin/bash and /bin/bash match /bin/bash so data for both these executables are collected. This setting limits the collection of data to a set of executables and is not recommended.

No Collection for Any Executables

When nothing is specified for the allow property, and the “*” wildcard is specified for the disallow property, the agent collects no data for any executables.

"cmdlinefilter": {"allow": "", "disallow": "*"}

This setting stops all executable collection and is not recommended.

cpulimit Property

Specify the maximum number of CPU units that the Lacework agent can use on the host where the agent is installed. If the agent measures sustained CPU usage over the specified limit during a 4-minute window, the agent restarts. Note that if the CPU usage spikes quickly up and down, the agent does not restart.

"cpulimit": "500m"

In this example, the suffix m stands for one hundred millicpu.

Note: Configuring the local agent cpulimit property is for non-container-based agent deployments only. To change the CPU limits for K8s container-based agent deployments, see Change Agent Resource Installation Limits on K8s Environments.

ContainerEngineEndpoint Property

If you set this property in the agent configuration file (config.json), the agent uses the new parameter (which can be any valid URL, TCP endpoint, or a Unix socket) as the endpoint.

If you don’t configure this property, the agent uses the default endpoint depending on the container engine runtime on the system.

Here are a few examples of how to set the ContainerEngineEndpoint:

"ContainerEngineEndpoint": "tcp://0.0.0.0:2375"
"ContainerEngineEndpoint": "unix:///run/docker.sock"

You must restart the agent for this parameter to take effect. You do not need to restart if you are running agent v4.0 or higher.

Although the agent can now communicate with a container runtime such as Docker listening on a TCP endpoint, setting up the Docker daemon this way is not recommended for security reasons.

Note: If either the ContainerRunTime or the ContainerEngineEndpoint setting is wrong, the agent will not detect the container.

ContainerRunTime Property

If you set this property in the agent configuration file (config.json), the agent uses the container run time that you specify. You can specify ContainerRunTime as containerd or docker.

If you don't configure this property, the agent automatically discovers the run time (containerd or docker).

If you are using agent v3.9.5 or higher, you do not need to specify this property because it automatically discovers the docker or containerd run time.

You must configure both ContainerRunTime and its corresponding ContainerEngineEndpoint together as shown in the following examples:

"ContainerRunTime": "docker"

"ContainerEngineEndpoint": "unix:///var/run/docker.sock"

"ContainerRunTime": "containerd"

"ContainerEngineEndpoint": "unix:///run/containerd/containerd.sock"

You must restart the agent for this parameter to take effect.

eBPF

Lacework agent v4.3 and later supports eBPF (Extended Berkeley Packet Filter) technology, which allows you to effectively monitor short-lived connections and processes, resulting in better visibility of your workloads. For details, see eBPF Support.

By default, eBPF is enabled:

"ebpf": {
    "attribution": "enabled",
  }

If you want to turn if off, set it to disabled as follows:

"ebpf": {
    "attribution": "disabled",
  }

memlimit Property

Specify the maximum amount of memory that the Lacework agent can use on the host where the agent is installed. If the agent measures sustained memory usage over the specified limit during a 4-minute window, the agent restarts. Note that if the memory usage spikes quickly up and down, the agent does not restart.

Specify the unit of size as a suffix, as shown in the following example.

"memlimit": "750M"

In this example, the suffix M stands for Megabytes.

Specify one of the following size units as a suffix.

m or M is Megabytes.
g or G is Gigabytes.

Note: Configuring the local agent memlimit property is for non-container-based agent deployments only. To change the memory limits for K8s container-based agent deployments, see Change Agent Resource Installation Limits on K8s Environments.

perfmode Property

The Lacework agent supports a special mode called lite mode, which reduces CPU consumption. If your workload has a large number of connections, it would benefit from the lite mode. In lite mode, for the same load (number of connections) the agent CPU/Memory usage is 10% less than normal.

To enable lite mode, add the following line to the config.json file:

"perfmode": "lite"

Lite mode does not change the effectiveness of Lacework intrusion detection.

Lite mode disables features such as package scan or FIM scan by default. If you want to re-enable package scan or FIM scan, enable it explicitly in the config.json file. To enable FIM scan, see mode Property. To enable package scan, add the following to the config.json file:

“packagescan”: {
      “enable”: “true”,
      “interval”: “60”
  }

Note: The interval is in minutes.

The following are the limitations of running the agent in the lite mode:

The Lacework Console does not indicate the perfmode as lite (it just shows normal).
The agent does not report UDP traffic in lite mode.
The agent might not detect process attribution for certain local traffic (which originates and is consumed on the same machine). For example, in normal mode, if connections are terminated on an nginx server running on the host, the agent is expected to report all connections that are terminated by nginx with connection details showing dst_pid_hash as pid_hash of nginx.
The agent does not collect the following connection metrics in lite mode:
- SESS_COUNT_IN
- SESS_COUNT_OUT
- PKT_PER_SESS_COUNT_IN
- PKT_PER_SESS_COUNT_OUT
- BYTES_PER_PKT_COUNT_IN
- BYTES_PER_PKT_COUNT_OUT
- SESSTIME_PER_SESS_IN
- SESSTIME_PER_SESS_OUT
- RESPTIME_PER_SESS_IN
- RESPTIME_PER_SESS_OUT
- OUTGOING histogram
- INCOMING histogram

proxyurl Property

You can configure the Lacework agent to use a network proxy by adding proxy information to the configuration file or by creating an https_proxy environment variable. For more information, see Required Connectivity, Proxies & Certificates.

"proxyurl":"http://Your_Proxy_Server:Your_Port"

Where Your_Proxy_Server is the URL for your HTTP or Socks proxy server and Your_Port is the port number of your proxy server.

When you configure the Lacework agent in environments with http/s proxy, the agent attempts a connection through the configured proxy. In agent v4.3 and later, if there is a failure or timeout for the connection, the agent will not be able to connect to Lacework. In releases prior to agent v4.3, if there is a failure or timeout for the connection, the agent bypasses the proxy and uses a direct outbound connection.

serverurl Property

In Lacework agent v3.8 and higher, you can use the serverurl property to specify the endpoint that the agent communicates with.

The following example shows you how to add the serverurl option in the config.json file:

{"serverurl" : "Your_API_Endpoint"}

Where Your_API_Endpoint is the endpoint for your region.

tags Property

Specify name/value tags to categorize your agents, for example, identifying critical assets. For more information, see Adding Agent Tags.

"tags":
{
  "test_01": "Value_01",
  "test_02": "Value_02"
}

tokens Property

To connect to the Lacework Application, Lacework agents require an access token. For more information, see Agent Access Tokens.

"tokens": {"accesstoken": "Your_Access_Token"}

Where Your_Access_Token is an access token generated by Lacework.

File Integrity Monitoring (FIM) Properties

This section describes the File Integrity Monitoring (FIM) agent properties. For more information about File Integrity Monitoring, see the following topics:

For more information about the Files (FIM) Dossier, see Files (FIM) Dossier.
For frequently asked questions about File Integrity Monitoring, see Lacework File Integrity Monitoring [FIM] - FAQs.

These properties must be specified within a single fim property as shown in the following example:

"fim":   
{
  "filepath": ["/home/user/.ssh", "/opt/bin"], 
  "fileignore": ["/etc/fstab"]
}

All directories and files that you want to monitor or ignore must be explicitly added to the configuration file. You can list either directories or files. For example, if you want to monitor an entire directory, but exclude specific files, you would list the directory to monitor in filepath and the specific files to exclude in fileignore.

Adding a blank "fim" entry as shown below has no effect on the default parameters.

"fim":{}

However, adding an empty set as shown below overrides the default parameters and results in no files being monitored.

"fim":  
{  
  "filepath":[],"fileignore":[]  
}

filepath Property

By default, Lacework monitors a set of default paths. (The list of default paths has been omitted for security reasons. Contact Support for the list of default paths.) You can optionally override these default paths using this property as shown in the following example.

NOTE: Specifying more filepaths may temporarily increase scan time, CPU, memory, and network resource usage.

"filepath": ["/home/user/.ssh", "/opt/bin"]

The filepath property also supports the * and ? wildcards.

Example for the * wildcard

The following example runs fim for all files under /home/user/ folder starting with foo. If the folder has: foofile1.txt, foofile2.log, and nofoofile1.txt, fim runs for foofile1.txt and foofile2.log.

"filepath": ["/home/user/foo*"]

Example for the ? wildcard

The following example runs fim for all files under /home/user/ folder starting with foo. If the folder has: foo1file.txt, foo2file.txt, and foofile.txt, fim runs for foo1file.txt and foo2file.txt.

"filepath": ["/home/user/foo?file.txt"]

fileignore Property

By default, Lacework excludes monitoring a set of default paths. You can optionally override these non-monitored default paths using this property as shown in the following example.

"fileignore": ["/etc/fstab"]

The fileignore property also supports the * and ? wildcards.

runat Property

By default, Lacework runs the FIM scan at an undetermined time once per day. To control the start time of the daily FIM scan, enter the start time as HH:MM as shown in the following example.

"runat": "23:50"

mode Property

The mode property enables the --enable-fim/--disable-fim option in the Lacework CLI. To enable the CLI option, add the following property.

"mode": "enable"

noatime Property

The noatime property prevents atime from being used for metadata hash computation. The atime (access timestamp) is the last time a file was read. This means someone used a program to display the contents of the file or read some values from it. Nothing was edited or added to the file. The data was referenced but unchanged. Metadata is one of the dimensions of hash, hash is used by the agent to determine if the file was changed. To enable noatime, add the following property.

"noatime": "true"

Articles in this section