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` |
|AIX| scanner | `log4j2-scan.aix` | `/usr/lib/check_mk_agent/plugins/86400/log4j2-scan` |
|| script | `your_cmk_agent_plugin.aix` | `/usr/lib/check_mk_agent/plugins/86400/your_cmk_agent_plugin` |
|Solaris| scanner | `log4j2-scan.solaris` | `/usr/lib/check_mk_agent/plugins/86400/log4j2-scan` |
|| script | `your_cmk_agent_plugin.solaris` | `/usr/lib/check_mk_agent/plugins/86400/your_cmk_agent_plugin` |

**Note**: AIX and Solaris are not included yet included in this package.

Don't forget to make the Linux (AIX/Solaris) 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>

<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>
This is a basic shell script that 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
#

SCRIPTVERSION="2021-12-18-0.0.1"
OPTIONS="/"
EXECUTABLE=/usr/lib/check_mk_agent/bin/log4j2-scan
PLUGIN_CONF_DIR="/etc/check_mk/"


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

if [ -f $EXECUTABLE ]; then
    echo "<<<cve_2021_44228_log4j:sep(0)>>>"
    # 2021-12-19T22:08:52+01:00
    date +%FT%T%:z
    echo "SCAN OPTIONS: $OPTIONS"
    echo "SCRIPT VERSION: $SCRIPTVERSION"
    $EXECUTABLE $OPTIONS
    exit 0
fi
```

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

- `echo "<<<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
- `echo "SCAN OPTIONS: $OPTIONS"` the options the scanner runs with, the check plugin expects this to start with `SCAN OPTIONS: `
- `echo "SCRIPT VERSION: $SCRIPTVERSION"` the version of the script, the check plugin expects this to start with `SCRIPT VERSION: `
- `$EXECUTABLE $OPTIONS` finaly this runs the scanner
- `exit 0` reset the exit code from the scanner to 0, without this check_mk_agent my 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.

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

OPTIONS="--scan-logback --scan-log4j1 --no-symlink --scan-zip --silent /"
```

**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 agent manually, (look for the plugin output starting with `<<<cve_2021_44228_log4j:sep(0)>>>`)
- try the plugin manually
- 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
- try to increase the "Scanner timeout" setting
- 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.

Windows cmd
```
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:\>
```

Linux shell
```
thl-cmk@checkmk:~$  /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>