HOWTO.md

This is about how to use the CVE-2021_44228-log4j plugin

This how to focuses on the RAW edition and on troubleshooting the plugin. For the Enterprise/Free edition you can do all the work via the bakery/automaic agent update.

If you have any issue with this plugin read this how to especally the If it doesn't work section. If this not help please have a look at the contribution guidelines this will make helping you a lot easier.

Linux and Windows

To use this plugin with the RAW edition of CMK you need to copy the following files from the directory ~/local/share/check_mk/agents/plugins of your CMK site to the client systems.

OS	What	File	To
Windows	scanner	log4j2-scan.windows	"C:\ProgramData\checkmk\agent\bin\log4j2-scan.exe"
	script	cve_2021_44228_log4j.windows	"C:\ProgramData\checkmk\agent\plugins\cve_2021_44228_log4j.ps1"
	config	cve_2021_44228_log4j.cfg.windows	"C:\ProgramData\checkmk\agent\config\cve_2021_44228_log4j.cfg"
Linux	scanner	log4j2-scan.linux	/usr/lib/check_mk_agent/bin/log4j2-scan
	script	cve_2021_44228_log4j.linux	/usr/lib/check_mk_agent/plugins/86400/cve_2021_44228_log4j.sh
	config	cve_2021_44228_log4j.cdg.linux	/etc/check_mk/cve_2021_44228_log4j.cfg

Don't forget to make the Linux files executable (chmod a+x log4j2-scan and chmod a+x CVE-2021-44228_log4j.sh).

For the RAW edition you need to configure the caching for the Windows plugin in the file C:\ProgramData\checkmk\agent\check_mk.user.yml (not tested).

plugins:
  enabled: true
  execution:
    - async: true
      cache_age: 86400
      pattern: $CUSTOM_PLUGINS_PATH$\cve_2021_44228_log4j.ps1
      run: true
      timeout: 600

Additional files created by the bakery

If you are using certion plugin configurations the bakery will create some additional files in the configuration directory of the agenet.

WATO option	Scanner option	file	content
Search path (bulk)	-f	cve_2021_44228_log4j_search.cfg	paths to search in seperated by newline
Exclude paths (bulk)	--exclude-config	cve_2021_44228_log4j_exclude.cfg	path to exclude from the sarch seperated by newline
Exclude files (bulk)	--exclude-file-config	cve_2021_44228_log4j_exclude_files.cfg	files exclude from the search seperated by newline

Using a specific version of the scanner

Included with this package are the scanner files for Linux and Windows in version 2.5.3 (2021-12-22). As the development of the scanner is still moving veriy fast forward, I will update the package from time to time. If you want to use a specific version of the scanner just put the files to ~/local/share/check_mk/agents/plugins of your CMK site and redeploy the agent (bakery).

OS	From	To
Windows	log4j2-scan.exe	log4j2-scan.windows
Linux	log4j2-scan	log4j2-scan.linux

At the time of writing this, I am testing with version 2.5.3 and 2.6.1 is already available.

Hints for other platforms (not Linux/Windows)

For other platforms you need

1. the scanner from logpresso logpresso CVE-2021-44228-Scanner Releases (Check that it run's on your destination platform)
2. you need a script as plugin for the check_mk_agent of your platform that executes the scanner and outputs the nessary information for CMK.

AIX/Solaris

For AIX and Solaris you can put the the files in the places like in the table above and use the bakery to greate the agent package and for the rollout.

BSD/UNIX/MacOS

On BSD/UNIX/MacOS the plugin for the check_mak_agent goes mostly in the /usr/lib/check_mk_agent/plugins/ ($PLUGINSDIR) directory. The scanner can be put under /usr/lib/check_mk_agent/bin/.

On this platforms is only a very basic check_mk_agent available, so you need to implement the caching for the agent plugin your self :-(. If you don't do this the scanner will run with every cycle of the check_mk_agent (once per minute in the default settings)

How can you do that?

• have a directory where the plugin can create a chache file. E.g. /var/lib/check_mk_agent/cache/ ($MK_MK_VARDIR)
• on the first run put the output from the plugin in this directory. E.g. cve_2021_44228_log4j.cache
• on every run check if this file exist and if so is it older than your intended scann intervall (E.g. one day - 86400 second)
• if the cache file doesn't exist or is to old rerun the scanner, else just output the cache file

The agent plugin script

The agent plugin is a basic shell script that reads the sanner options from the config file, runs the scanner and outputs the results for CMK. Here is the script for Linux as example.

#!/bin/bash
#
# Author: thl-cmk[at]outlook[dot]com
# URL   : https://thl-cmk.hopto.org
# Date  : 2021-12-18
#
# Wrapper around: https://github.com/logpresso/CVE-2021-44228-Scanner
#
# plugin for the check_mk linux agent
#
#

SCRIPT_VERSION="20220105.v0.0.2"
BAKERY_VERSION="N/A"
OPTIONS="/"
PLUGIN_TIMEOUT=300
PLUGIN_CONF_DIR="/etc/check_mk"
EXECUTABLE=/usr/lib/check_mk_agent/bin/log4j2-scan

if [ -f $MK_CONFDIR/cve_2021_44228_log4j.cfg ]; then
    . $MK_CONFDIR/cve_2021_44228_log4j.cfg 2>/dev/null
elif [ -f $PLUGIN_CONF_DIR/cve_2021_44228_log4j.cfg ]; then
    . $PLUGIN_CONF_DIR/cve_2021_44228_log4j.cfg 2>/dev/null
fi

PLUGIN_TIMEOUT=$PLUGIN_TIMEOUT"s"

printf "<<<cve_2021_44228_log4j:sep(0)>>>"
# 2021-12-19T22:08:52+01:00
date +%FT%T%:z
printf "SCAN OPTIONS: "
printf " %s " "${OPTIONS[@]}"
printf "\n"
printf "SCRIPT VERSION: %s\n" "$SCRIPT_VERSION"
printf "BAKERY VERSION: %s\n" "$BAKERY_VERSION"
printf "%s\n" "----------------------------------------------------"

if [ -f $EXECUTABLE ]; then
    timeout -s 9 $PLUGIN_TIMEOUT $EXECUTABLE "${OPTIONS[@]}"
    EXEC_STATUS=$?
    [ $EXEC_STATUS -eq 137 ] && printf "ERROR: scanner killed on timeout (%s).\n" "$PLUGIN_TIMEOUT"
else
  printf "ERROR: Executable not found: %s\n" "$EXECUTABLE"
fi

unset PLUGIN_TIMEOUT
unset PLUGIN_CONF_DIR
unset OPTIONS
unset EXECUTABLE
unset SCRIPT_VERSION
unset EXEC_STATUS
unset BAKERY_VERSION

exit 0

The important lines (for the check plugin to work) are:

• printf "<<<cve_2021_44228_log4j:sep(0)>>>" this connets the agent output with the check plugin
• date +%FT%T%:z the date/time when the scanner starts, the check plugin will expect this to be the first line of output
• printf " %s " "${OPTIONS[@]}" the options the scanner runs with, the check plugin expects this to start with SCAN OPTIONS:
• printf "SCRIPT VERSION: %s\n" "$SCRIPT_VERSION" the version of the script, the check plugin expects this to start with SCRIPT VERSION:
• printf "BAKERY VERSION: %s\n" "$BAKERY_VERSION" the version of the bakery, the check plugin expects this to start with BAKERY VERSION:
• timeout -s 9 $PLUGIN_TIMEOUT $EXECUTABLE "${OPTIONS[@]}" finaly this runs the scanner
• exit 0 reset the exit code from the scanner to 0, without this check_mk_agent might not accept the script output

Note: the format of the date output has to be in the form of 2021-12-19T22:08:52+01:00

The config file for cve_44228_log4j agent plugin

The bakery creates the config file cve_2021_44228_log4j.cfg for the agent plugin. At the moment this holds only the options for the scanner.

Example config file for the Linux agent plugin

# Created by Check_MK Agent Bakery.
# This file is managed via WATO, do not edit manually or you
# lose your changes next time when you update the agent.

BAKERY_VERSION=20220125.v0.1.0
OPTIONS=(--exclude-fs nfs,cifs --report-path /var/log/log4j_report.json --report-json --exclude "/mnt" --exclude-file-config /etc/check_mk/cve_2021_44228_log4j_exclude_files.cfg --scan-logback --scan-log4j1 --scan-zip --no-symlink --silent /);
PLUGIN_TIMEOUT=300
ATTACH_REPORT=/var/log/log4j_report.json

Example config file for the Windows agent plugin

# Created by Check_MK Agent Bakery.
# This file is managed via WATO, do not edit manually or you
# lose your changes next time when you update the agent.

BAKERY_VERSION=20220125.v0.1.0
OPTIONS=--all-drives --report-path c:\windows\temp\log4j_report.json --report-json --exclude "D:\Kannweg\backups-1" --exclude-file-config C:\ProgramData\checkmk\agent\config\cve_2021_44228_log4j_exclude_files.cfg --scan-logback --scan-log4j1 --scan-zip --silent 
PLUGIN_TIMEOUT=300
ATTACH_REPORT=c:\windows\temp\log4j_report.json

Note: as mentioned in the table on top there is a sample config for Linux and Windows available. In the sample you will find a short decription to all posible options (as with scanner version 2.5.3)

If it doesn't work

• check if the necessary files are there (see table on top)
• under *NIX check if the files are executable
• look for leftovers from older versions and remove them (see next toppic)
• run the scaner manually
• run the plugin manually
• run the agent manually, (look for the plugin output starting with <<<cve_2021_44228_log4j:sep(0)>>>)
• clear the cache sudo rm /var/lib/check_mk_agent/cache/*cve*
• use only Search Path / Drives to scan, try to exclude large volumes so the scan time comes down, if you are succesfull try aditional options step by step
• look at the Completed in xx.xx seconds and adjust the Scanner timeout setting (the scanner needs much more time in the background, so double the time)
• if there are only *.new files in the chache directory for the cve_2021_44228_log4j plugin, then the scanner has not finished to scan the system, maybe the timeout is still to low.

Manual run of the Windows version of the pluguin (use a admin shell)

Microsoft Windows [Version 10.0.19042.1083]
(c) Microsoft Corporation. All rights reserved.

C:\>powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File "C:\ProgramData\checkmk\agent\plugins\cve_2021_44228_log4j.ps1"
<<<cve_2021_44228_log4j:sep(0)>>>
2021-12-20T16:12:23+01:00
SCAN OPTIONS: --all-drives
Logpresso CVE-2021-44228 Vulnerability Scanner 2.3.1 (2021-12-19)
Scanning drives: C:\, D:\

Scanned 124575 directories and 472700 files
Found 0 vulnerable files
Found 0 potentially vulnerable files
Found 0 mitigated files
Completed in 36.59 seconds

C:\>

Manual run of the Linux version of the plugin

thl-cmk@checkmk:~$sudo  /usr/lib/check_mk_agent/plugins/86400/cve_2021_44228_log4j.sh
<<<cve_2021_44228_log4j:sep(0)>>>
2021-12-20T16:12:56+01:00
SCAN OPTIONS: /
Logpresso CVE-2021-44228 Vulnerability Scanner 2.3.1 (2021-12-19)
Scanning directory: / (without udev, tmpfs)

Scanned 5938 directories and 51489 files
Found 0 vulnerable files
Found 0 potentially vulnerable files
Found 0 mitigated files
Completed in 0.52 seconds
thl-cmk@checkmk:~$

Notes for updates from older versions/local check

Before you use the package please remove all older versions or the local checks related to this plugin.

Wehre to loock:

• the local checks directory /usr/lib/check_mk_agent/local and its subdirectories
• the plugin directory /usr/lib/check_mk_agent/plugins and its subdirectories
• the cache directory /var/lib/check_mk_agent/cache

Use with the enterprise/free edition of CMK

This is a step by step walk through on how to use this package. I assume you have already configured the automatic update for the CMK agent and have done the initial rollout/registering of the agent on your client systems.

1. configure the agent plugin Rule CVE-2021-44228-log4j
2. bake the agent
3. update tha agent
4. rediscover the services of your systems
5. configure the rule CVE-2021-44228-log4j for the check plugin (optional)

Agent plugin Rule CVE-2021-44228-log4j

First configure the agent plugin Rule CVE-2021-44228-log4j. Go to Setup > Agents > Windows, Linux, Solaris, AIX > Agent rules > CVE-2021-44228-log4j.

• Be shure to have one rule atached to your Linux clients and one to your Windows clinets, for example by a host tag matching on the operating system.
• in the Rule title you will find the version of the WATO plugin for this rule.

Bake the agent

If you have configured and activated the agent plugin rule, you ned to bake the agent. Go to Setup > Agents > Windows, Linux, Solaris, AIX klick Bake and sign agents, provide your signing key, klick Bake and sign.

After successfully finishing the agent bakery you should find an entry corresponding to your agent rule like this.

Update the agent on the client systems

Wait for the automatic agent update to finish (in the default settings the agent will check once an hour for an update).
Note: you can speed this up by issuing the cli command

thl-cmk@checkmk:~$ sudo cmk-update-agent -v

or on Windows in a Adminshell with

C:\> C:\Program Files (x86)\checkmk\service\check_mk_agent.exe"  updater

You can check the update status under Monitor > System > Agent update status. After an succesfull update it should look like this.

Rediscover the services

Now you can rediscover the services on your client system (or wait for the automatic service discovery if you have a rule for that). If everything is working as expected, you should get a new service like this.

Now you can activate the changes and you are done.

Configure the rule CVE-2021-44228-log4j for the check plugin (optional)

If you like you can configure most of the levels for the check plugin and the items on the short service output. By default there will be only Files vulnerable and Files potentially vulnerable show up, also all items that raise a warning or critical will show up on the short output. To do so go to Setup > Services > Service monitoring rules > CVE-2021-44228_log4j (under Operating System Resources) and configure the check plugin to your likings. For example to show the Last run and the version of the scanner

Then you get this output

Inventory plugins

There are two inventory plugins

• CVE Scanner for log4j summary
• CVE Scanner for log4j report

CVE Scanner for log4j summary

"CVE Scanner for log4j summary" is enabled by default. This inventory plugin/view gives you an overview of the versions (scanner/script/bakery) used by all your hosts. Additional you get the used scan options and the statistics from the scanner. This plugin uses the same data as the check plugin "cve_2021_44228_log4j". The "CVE Scanner for log4j summary" can be disabled in the "Hardware / Software Inventory" rule "log4j CVE scanner (CVE-2021-44228-log4j)".

CVE Scanner for log4j report

The second inventory plugin "CVE Scanner for log4j report" adds to all files reported by the logpresso scanner additional informations about several CVEs. This infromation is based solely on the log4j/logback version reported by the Logpresso scanner. To use this Inventory plugin you need to enable "Enable reporting" -> "Send report to checkmk" in the bakery rule. You can exclude scan errors from the inventory via the "Hardware / Software Inventory" rule "log4j CVE scanner (CVE-2021-44228-log4j)".

Check plugin cve_2021_44228_log4j_cves

There is an aditional check plugin cve_2021_44228_log4j_cves. This Plugin creates one service for each of the following CVEs:

• CVE-2021-44832
• CVE-2021-45105
• CVE-2021-45046
• CVE-2021-44228
• CVE-2021-42550
• CVE-2020-9488
• CVE-2017-5645
• CVE-2021-4104

It wil then add all files affected by this CVE to the service. The information if a file is affected by a certain CVE is based solely on the log4j/logback version reported by the Logpresso scanner. If a file is affected doesn't mean this can be exploited. To use this check plugin you must enable "Enable reporting" -> "Send report to checkmk" in the bakery rule. In the discovery rule for this check plugin ("Service discovery rules" -> "log4j CVEs") you can enable to create a service also for CVEs without affected files.

Scanner options implemented in the bakery

scanner option	bakery option	comment
target_path1 to n	Search method -> Search paths
-f [config_file_path]	Search method -> Search paths (bulk)	cve_2021_44228_log4j_search.cfg
--scan-log4j1	Scan for log4j 1 versions (CVE-2021-4104)
--scan-logback	Scan for logback (CVE-2021-42550)
--scan-zip	Scan zip files (increase timeout)
--force-fix	Fix files and backup -> Fix files. (Use at your own risk!)	Option was removed
--backup-path	Fix files and backup -> Backup directory (must exist)	Option was removed
--all-drives	Search method -> All drives	Windows only
--drives	Search method -> Drives to scan	Windows only
--no-symlink	Ignore symlinks	Linux only
--exclude [path_prefix]	Exclude paths -> Exclude paths -> Exclude paths
--exclude-config [config_file_path]	Exclude paths -> Exclude paths -> Exclude paths (bulk)	cve_2021_44228_log4j_exclude.cfg
--exclude-pattern [pattern]	Exclude paths -> Exclude paths by pattern
--exclude-file-config [config_file_path]	Exclude files (bulk)	cve_2021_44228_log4j_exclude_files.cfg
--exclude-fs	Exclude filesystems by type
--syslog-udp [host:port]	Enable syslog reporting -> Syslog server / Syslog server Port
--syslog-level [level]	Enable syslog reporting -> Loglevel
--syslog-facility [code]	Enable syslog reporting -> Facility
--rfc5424	Enable syslog reporting -> Use RFC5424 syslog format
--report-csv	Enable reporting -> Enable file reporting -> Report format -> CSV
--report-json	Enable reporting -> Enable file reporting -> Report format -> JSON
--report-path	Enable reporting -> Send report to checkmk	log4j_report.json
--report-dir	Enable reporting -> Enable file reporting -> Report output directory (must exist)
--no-empty-report	Enable reporting -> Enable file reporting -> Don't create empty reports
--csv-log-path	Append results to log file -> Log file format -> CSV
--json-log-path	Append results to log file -> Log file format -> JSON
--silent	Silent output
--debug	Debug scanner
--throttle	Throttle
-Xmx	Max memory
--trace	Trace scanner	Removed, produces to much data