Skip to main content

Configure Linux Agent Behavior in config.json File

If you run the install.sh script to install the Lacework Linux 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 and end with curly braces ({ }) with commas separating each property as shown by the following example config.json file:

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

The serverurl property is optional if your Lacework tenant is deployed in the US, but mandatory for non-US tenants.
https://api.lacework.net - US (default) https://api.fra.lacework.net - European Union (EU) https://auprodn1.agent.lacework.net - Australia and New Zealand (ANZ)

Example for a tenant in the EU:

{
"tokens": {"accesstoken": "63...ab1"},
"serverurl": "https://api.fra.lacework.net",
"proxyurl":"http://10.10.10.10:3128"
}

This section describes the general agent properties.

autoupgrade Property

If the autoupgrade property is set to enable, the agent automatically upgrades itself. This is the default setting.

To disable autoupgrade, enter the following in the config.json file:

"autoupgrade": "disable"
note

For improved security and to benefit from new and improved features, Lacework recommends that you do not disable automatic upgrade of the agent.

To enable automatic upgrade again, delete the "autoupgrade": "disable" property in the config.json file or change it to:

"autoupgrade": "enable"

cmdlinefilter Property

Edit the cmdlinefilter 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.

important

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, Lacework recommends disabling the smallest set of executables possible.

The cmdlinefilter property supports the sub-properties 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 excluded 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 recommended 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 regarding 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 therefore 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 of 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 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 system's container engine runtime.

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

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

You must restart the agent for this parameter to take effect. You do not need to restart the agent 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).

note

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"
note

You must restart the agent for this parameter to take effect. For more information, see Start, Stop, or Restart Lacework Agent.

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, go to eBPF Support.

By default, eBPF is enabled:

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

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

"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

Lite Mode

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 FIM scan, package scan, and process scan by default. If you want to re-enable FIM scan, package scan, or process 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.

  • To enable process scan, add the following to the config.json file. For more information, see procscan Property.

    "procscan": {
           "enable": "true"
      }

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

  • The Lacework Console does not indicate the perfmode as lite, it just appears 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

eBPF Lite Mode

The Lacework agent supports a special mode called eBPF lite mode that is similar to the Lite mode.

The eBPF lite mode provides the following benefits:

  • Uses less CPU and memory than the Lite mode.
  • Reduces agent CPU and memory consumption on hosts that have a large number of connections.
note

The Lacework agent supports the eBPF lite mode only on hosts running Linux kernel v4.16 and later. If you enable it on a host that has Linux kernel version older than v4.16, the agent will run in normal mode.

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

"perfmode": "ebpflite"

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

  • The Lacework Console does not indicate the perfmode as eBPF lite, it just appears normal.
  • The agent does not report outgoing UDP traffic.
  • 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:
    • 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

Scan Mode

The Lacework agent supports a special mode called scan mode, which reduces CPU consumption. When scan mode is enabled, the agent performs host vulnerability and FIM scans only. In scan mode, the agent does not perform other activities such as network monitoring or process attribution.

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

"perfmode": "scan"

procscan Property

Lacework agent v5.1 and later supports scanning processes to check if they reference any jar files and detect potential log4j vulnerability. The procscan config property controls the scanning of processes.

By default, process scanning is enabled and runs every 12 hours.

If you want to disable process scanning, set it to disabled as follows:

"procscan": {
      "enable": "false"
 }

If you want to change process scanning interval, change the following property:

"procscan": {
      "interval": "720"
}
note

The interval is in minutes.

proxyurl Property

You can configure the Lacework agent to use a network proxy by adding proxy information to the config.json file or by creating a 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.

If your proxy server requires a password:

{
"proxyurl": "http://username:password@Your_Proxy_Server:Your_Port"
}

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. This is mandatory for non-US users.

Lacework supports the following regions and endpoints:

RegionEndpoint
US (default)https://api.lacework.net (default)
European Union (EU)https://api.fra.lacework.net
Australia and New Zealand (ANZ)https://auprodn1.agent.lacework.net

The default endpoint is https://api.lacework.net and the default region is US. If you do not specify this property, the agent assumes that the default region is US and uses the default endpoint of https://api.lacework.net.

The following example shows you how to add the serverurl property 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:

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"]
}

By default, Lacework monitors a set of default paths and files and excludes monitoring a set of default paths and files. You can override the default settings using the filepath property (to include in monitoring) and fileignore property (to exclude from monitoring) in the config.json file.

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

"fim":{}

However, adding an empty set as shown in the following example 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 and files. The list of default paths and files has been omitted for security reasons. Contact Lacework Support for more information.

You can optionally override monitoring these default paths and files using the filepath property. For example, the following entry configures FIM to monitor only the /home/user/foo.txt file and all the files in the /home/user/.ssh and /opt/bin directories.

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

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

If you want to monitor an entire directory but exclude specific files in that directory, specify the directory to monitor with the filepath property and the files to exclude with the fileignore property.

The filepath property supports the * and ? wildcards.

Example for the * wildcard

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

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

Example for the ? wildcard

The following example runs FIM for all files starting with foo and have a character followed by file.txt under the /home/user/ folder. If the folder has: foo1file.txt, foo2file.txt, and foofile.txt, FIM runs only for foo1file.txt and foo2file.txt.

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

fileignore Property

By default, Lacework excludes monitoring a set of default paths and files. The list of default paths and files has been omitted for security reasons. Contact Lacework Support for more information.

You can optionally override these default non-monitored paths and files using the fileignore property. For example, the following entry configures FIM to ignore only the /home/user/foo2.txt file and all the files in the /etc/fstab folder.

"fileignore": ["/etc/fstab", "/home/user/foo2.txt"]

The fileignore property 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"

FIM will default to off in AWS Fargate, but you can enable it through the agent configuration file (config.json). FIM runs immediately in Fargate after a cooling period. The default cooling period is 60 minutes. However, if you want to run it immediately, set the cooling period to zero in the config.json file as follows:

{"fim":{"mode":"enable", "coolingperiod":"0"}

noatime Property

When the noatime property is set to true, it prevents the access timestamp (atime) from being used for metadata hash computation. The atime 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. The property is set to true by default. To disable noatime, add the following property.

"noatime": "false"