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.

note

If you modify the config.json file, the agent automatically applies the changes within 60 seconds.

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://aprodus2.agent.lacework.net - US-02 (US) 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.

anonymizeincoming Property​

IP addresses are considered as personally identifiable information (PII) by privacy laws such as GDPR (General Data Protection Regulation). If applicable in your region or country, you can use the anonymizeincoming property to enable the Lacework agent to anonymize inbound IP addresses to comply with privacy laws that may be relevant to your business. This feature is customer-controlled, and it is the customer's responsibility to determine what is applicable to their region or country.

Note the following:

  • Only source public IPv4 addresses for incoming network connections (IPv4 addresses of external hosts connecting to a server) will be anonymized. Public IPv4 addresses for outgoing networking connections (IPv4 address of a server connecting to external hosts) will not be anonymized.
  • The anonymized IPv4 addresses will be displayed in the Lacework Console. You cannot identify the real IP address from an anonymized IP address.
  • IPv6 addresses will not be anonymized.
  • Private and internal IPv4 addresses will not be anonymized. This includes the following subnets:
    • 127.0.0.0/8: Loopback IP range
    • 10.0.0.0/8: Private IP range (see RFC1918)
    • 172.16.0.0/12: Private IP range (see RFC1918)
    • 192.168.0.0/16: Private IP range (see RFC1918)
    • 169.254.0.0/16: Link-Local IP range (see RFC3927)

To anonymize public IPv4 addresses, enter the following in the config.json file:

"anonymizeincoming": {"netmask": "IPv4 netmask value"}

IPv4 netmask value can be any valid IPv4 netmask, except for the following that should not be used for the reasons given below.

Invalid NetmaskReason
0.0.0.0This netmask will result in IPv4 addresses anonymized as 0.0.0.0.
127.0.0.0This netmask will result in IPv4 addresses anonymized as 127.0.0.0 (loopback IP range) or 0.0.0.0.
224.0.0.0This netmask will result in IPv4 addresses anonymized as multicast addresses.
255.255.255.255With this netmask, the anonymized IPv4 addresses will be the same as the original IPv4 addresses.

Example​

The following examples show how the netmask you specify anonymizes IPv4 addresses. Note how multiple IP addresses are anonymized to the same IP address 54.213.202.0 and 54.213.0.0.

Public IP AddressNetmaskAnonymized IP Address
54.213.202.1255.255.255.054.213.202.0
54.213.202.65255.255.255.054.213.202.0
54.213.202.78255.255.255.054.213.202.0
54.213.202.1255.255.0.054.213.0.0
54.213.202.65255.255.0.054.213.0.0
54.213.202.78255.255.0.054.213.0.0

Limitations of Anonymizing Public IPv4 Addresses​

  • You cannot identify the real IP address from an anonymized IP addresses. This can impact your ability to identify the source of a threat or unusual activity that is reported in an alert.
  • Only the source IP addresses in incoming network connections are anonymized, and multiple IP addresses may be anonymized to the same IP address. This will result in inaccurate polygraphs in the Lacework Console because the source and target IP address of an incoming connection cannot be matched.
  • Depending on the netmask, the geographical location of an anonymized IP address may not be correct.

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 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 alerts 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 it will match /bin/java, /usr/bin/java, /bin/bash, /usr/bin/bash. But it will 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 /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.

codeaware Property​

info

This feature is in Preview as of Linux Agent v6.4.

Enables the agent to detect active and inactive dpkg and RPM packages on hosts. Package status detection enables you to know whether a vulnerable package is being used by an application on your host and prioritize fixing active vulnerable packages first.

note

Package status detection is also supported for golang, Java, and npm packages if you do the following:

  1. Install Linux agent v6.5 or later on hosts.
  2. Enable package status detection for the agent using the codeaware property.
  3. Enable Agentless Workload Scanning on the hosts.

Use the Package Status filter in the Host Vulnerability page to view active or inactive vulnerable packages on hosts. See Host Vulnerability - Package Status for details.

By default, package status detection is disabled.

  • To enable package status detection, add the following to the config.json file:

    "codeaware":{"enable":"all"}

  • To disable package status detection, delete the "codeaware":{"enable":"all"} property in the config.json file or change it to the following.

    "codeaware":{"enable":"false"}
note

Package status detection uses very low CPU, memory, and network resources. If the agent has sustained CPU or memory usage over the CPU or memory limits (specified using the cpulimit and memlimit properties) during a 4-minute window, the agent restarts. Note that if the CPU or memory usage spikes quickly up and down, the agent does not restart.

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"

Although the agent can 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, cri-o, or docker.

If you don't configure this property, the agent automatically discovers the run time (containerd, cri-o, 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"

discover_dns_over_tcp Property​

info

This feature is in Preview as of Linux Agent v6.5.

By default, the agent discovers DNS requests over TCP and sends them to the Lacework platform to enable it to identify DNS-over-TCP connections.

To disable the agent from discovering DNS requests over TCP, specify the following in the config.json file:

“discover_dns_over_tcp” : “false”
note

The agent does not discover the following over TCP:

  • Fragmented DNS packets
  • DNS packets greater than 512 bytes
  • Encrypted DNS packets
  • DNSSEC records

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.

metadata_request_interval Property​

The agent retrieves metadata tags from AWS to enable you to quickly identify where you need to take actions to fix alerts displayed in the Lacework Console. To ensure that the latest metadata is displayed in the Lacework Console, the agent periodically makes describe-tags API calls to retrieve tags from AWS.

  • To limit the number of API calls, use the metadata_request_interval property in the config.json file to specify the interval during which the agent retrieves the tags.

    The interval can be specified in ns (nanoseconds), us (microseconds), ms (milliseconds), s (seconds), m (minutes), or h (hours). For example, to retrieve the tags once every 15 minutes, specify the following in the config.json file.

    “metadata_request_interval”: “15m”

  • To disable the agent from retrieving tags from AWS, specify the following in the config.json file:

    “metadata_request_interval”: “0”

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)
US-02 (US)https://aprodus2.agent.lacework.net
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, no files will be monitored if you add an empty filepath property as shown below, and no files will be excluded from monitoring if you add an empty fileignore property as shown below. 

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

FIM is enabled by default on your host machine.

To disable FIM, specify the following in your config.json file:

"mode": "disable"

If FIM is disabled, you can enable it by doing one of the following:

  • Delete the following in your config.json file:

    "mode": "disable"

  • Change "mode": "disable" in your config.json file to "mode": "enable".

FIM is disabled by default in AWS Fargate, but you can enable it through the config.json file. 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"