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](CONTRIBUTING.md "Contributing") this will make helping you a lot easier.

<details><summary>Linux and Windows</summary>

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
```

<details><summary>Additional files created by the bakery</summary>

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 | 

</details>


</details>


<details><summary>Using a specific version of the scanner</summary>

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.
</details>



<details><summary>Hints for other platforms (not Linux/Windows)</summary>

For other platforms you need
1. the scanner from logpresso [logpresso CVE-2021-44228-Scanner Releases](https://github.com/logpresso/CVE-2021-44228-Scanner/releases) (Check that it run's on your destination platform)
1. 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
</details>

<details><summary>The agent plugin script</summary>
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**_

</details>

<details><summary>The config file for cve_44228_log4j agent plugin</summary>

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)

</details>

<details><summary>If it doesn't work</summary>

- 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:~$
```
</details>

<details><summary>Notes for updates from older versions/local check</summary>

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` 
</details>


<details><summary>Use with the enterprise/free edition of CMK</summary>

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) 
<details><summary>Agent plugin Rule CVE-2021-44228-log4j</summary>

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.

![Agent rule CVE-2021-44228-log4j sample](doc/agent-rule-sample.png "Agent rule CVE-2021-44228-log4j sample")

</details>

<details><summary>Bake the agent</summary>

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`.

![Bake agent sample](doc/agent-bake-and-sign-sample.png "bake agent sample")

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

![Bake agent success](doc/agent-backery-success.png "bake agent success")

</details>
<details><summary>Update the agent on the client systems</summary>

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.

![Agent update successfull](doc/agent-update-ok.png "Agent update successfull")

</details>

<details><summary>Rediscover the services</summary>

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.

![successfull service discovery](doc/service-discovery.png "successfull service discovery")

Now you can activate the changes and you are done.

</details>

<details><summary>Configure the rule CVE-2021-44228-log4j for the check plugin (optional)</summary>

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

![check rule sample](doc/check-rule-sample.png "check rule sample")

Then you get this output

![service sample](doc/service-sample.png "service-sample")

</details>

<details><summary>Inventory plugins</summary>

There are two inventory plugins
- CVE Scanner for log4j summary
- CVE Scanner for log4j report

<details><summary>CVE Scanner for log4j summary</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 summary](doc/sample-inventory.png)

</details>

<details><summary>CVE Scanner for log4j report</summary>

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)".

![CVE Scanner for log4j report](doc/sample-inventory-report.png)

</details>

</details>

<details><summary>Check plugin cve_2021_44228_log4j_cves</summary>

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.

![Sample log4j CVEs srvices](doc/sample-log4j-services.png)

</details>

<details><summary>Scanner options implemented in the bakery</summary>


| scanner option | bakery  option | comment |
| ------ | ------ | ------ |
| target_path1 to n | Search method -> Search paths |
| --all-drives | Search method -> All drives | Windows only |
| --api-key | Use Logpresso watch -> Logpresso watch API key |  |
| --backup-path | Fix files and backup -> Backup directory (must exist) | Option was removed |
| --csv-log-path | Append results to log file ->  Log file format -> CSV |
| --debug | Debug scanner |
| --drives | Search method -> Drives to scan | Windows 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-file-config [config_file_path] | Exclude files (bulk) | cve_2021_44228_log4j_exclude_files.cfg | 
| --exclude-fs | Exclude filesystems by type |
| --exclude-pattern [pattern] | Exclude paths -> Exclude paths by pattern |
| -f [config_file_path] | Search method -> Search paths (bulk) | cve_2021_44228_log4j_search.cfg |
| --force-fix | Fix files and backup -> Fix files. (Use at your own risk!) | Option was removed |
| --http-proxy | Use Logpresso watch-> Use a http proxy server |  |
| --json-log-path | Append results to log file ->  Log file format -> JSON |
| --no-empty-report | Enable reporting -> Enable file reporting -> Don't create empty reports |
| --no-symlink | Ignore symlinks | Linux only |
| --report-csv | Enable reporting -> Enable file reporting -> Report format -> CSV |
| --report-dir |  Enable reporting -> Enable file reporting -> Report output directory (must exist) |
| --report-json | Enable reporting -> Enable file reporting -> Report format -> JSON |
| --report-patch | Report safe files |  |
| --report-path | Enable reporting -> Send report to checkmk | log4j_report.json |
| --rfc5424 | Enable syslog reporting -> Use RFC5424 syslog format |
| --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) |
| --silent | Silent output |
| --syslog-facility [code] | Enable syslog reporting -> Facility |
| --syslog-level [level] | Enable syslog reporting -> Loglevel |
| --syslog-udp [host:port] | Enable syslog reporting -> Syslog server / Syslog server Port |
| --throttle | Throttle |
| --trace | Trace scanner | Removed, produces to much data |
| -Xmx | Max memory |


</details>




</details>