Forge Home

log4jscanner

Module utilizing Google's log4jscanner to scan infrastructure for vulnerable log4j JARs

7,094 downloads

3,386 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 0.4.0 (latest)
  • 0.3.0
  • 0.2.0
released Jan 14th 2022
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 8.0.0
  • , , , , , , , , , , ,
Tasks:
  • run_scan
  • run_scan_osx

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-log4jscanner', '0.4.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-log4jscanner
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-log4jscanner --version 0.4.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppetlabs/log4jscanner — version 0.4.0 Jan 14th 2022

log4jscanner

This module utilizes Google's log4jscanner tool to monitor your infrastructure for vulnerable jar files.

Description

This module can be used in two ways:

  1. Run the log4jscanner::run_scan task on a node. A list of vulernable jars is printed in the task output.
  2. Apply the log4jscanner class to any Linux or Windows nodes with a Puppet Agent. This will set up a scheduled task to scan for vulnerable jars once per day, and keeps a custom fact called 'log4jscanner' updated with the results.

Log4jscanner binaries

The binaries were compiled using Go version 1.17.5 and running go build from the google/log4jscanner repo at SHA edf4af1a38a2930c86fdd955da1719e3d649441c. log4jscanner_nix was compiled on Centos 7, log4jscanner.exe on Windows 2019, and log4jscanner_osx on 10.15.

Compiling your own binaries

If you'd like to compile your own binaries or add support for another platform, this is the rough workflow to follow. Feel free to contribute new platform support with a pull request to this repository.

  1. Compile binaries and add them to the /files directory. Use the existing naming convention of log4jscanner_<platform>.
    • If you're replacing a binary, ensure it's named exactly the same as the original.
  2. Calculate the sha256 checksum for each binary with a command like sha256sum log4jscanner_nix.
  3. Add the checksums to the appropriate places in the log4jscanner class in /manifests/init.pp.
    • Add the appropriate conditional logic if you're adding new platform support.
  4. If you're adding support for another platform, then create a platform specific task following the example of the log4jscanner::run_scan_osx task.

Setup

What log4jscanner affects

When the class is applied, the module provides an additional fact (log4jscanner). This also adds a cron job (Linux) or scheduled task (Windows) that defaults to running once per day.

On Linux systems, files are saved to /opt/puppetlabs/log4jscanner. On Windows, they are saved to C:\ProgramData\PuppetLabs\log4jscanner.

Usage

Manifest

Include the module:

include log4jscanner

Advanced usage:

class { 'log4jscanner':
  linux_directories => ['/opt', '/usr'],
  linux_skip_directories => ['/opt/puppetlabs'],
  cron_hour = 12,
  cron_minute = 30,
  windows_directories => ["C:"],
  windows_skip_directories => ["C:\\Windows\\Temp"],
  scheduled_task_every = 2,
}

In this example, all Linux nodes will scan the /opt and /usr directories, while skipping /opt/puppetlabs, and all Windows nodes will scan C: and skip the Windows temp directory. It will scan Linux nodes every day at 12:30 PM, and Windows nodes every other day.

Note that when using the class with OSX, you'll want to use the osx_directories and osx_skip parameters, and you'll likely need to change the scan_data_group to admin rather than root.

Task

Run a basic scan from the command line:

puppet task run log4jscanner::run_scan --nodes <nodes> directories=/opt,/var skip=/opt/puppetlabs

Note that for OSX, you'll want to run the log4jscanner::run_scan_osx task.

Reference

Manifest Parameters

  • ensure: Set to 'absent' to remove artifacts (cron/scheduled tasks, files) from nodes. (default 'present')
  • linux_directories: Array of directories to scan on Linux nodes. (default ['/'])
  • linux_skip: Array of glob patterns to skip scanning on Linux nodes. (default ['/proc','/sys','/tmp'])
  • scan_data_owner: User to own log4jscanner files. (default 'root')
  • scan_data_group: Group to own log4jscanner files. (default 'root')
  • cron_user: User to run the cron job for scanning. (default 'root')
  • cron_hour: Hour for cron job run. (default 'absent')
  • cron_month: Month for cron job run. (default 'absent')
  • cron_monthday: Day of the month for cron job run. (default 'absent')
  • cron_weekday: Day of the week for cron job run. (default 'absent')
  • cron_minutes: Minute for cron job run. (default is a random int between 0 and 59)
  • windows_directories: Array of directories to scan on Windows nodes. (default ['C:'])
  • windows_skip: Array of glob patterns to skip scanning on Windows nodes. (default ["C:\Windows\Temp"])
  • scheduled_task_every: Run the scheduled task every X days. (default 1)
  • osx_directories: Array of directories to scan on OSX nodes (default ['/'])
  • osx_skip: Array of glob patterns to skip scanning on OSX nodes (default ['/tmp', '/Users/osx', '/dev', '/private/var/db', '/private/var/folders', '/System/Volumes/Data/private/var/db', '/System/Volumes/Data/private/var/folders'])

Task Parameters

  • directories: Comma-separated list of directories to search for vulnerable log4j jars
  • skip: Comma-separated list of glob patterns to skip when scanning
  • rewrite: When true, rewrite vulnerable jars as they are detected. NOT RECOMMENDED.

Limitations

Tested on a limited number of OS flavors. Please submit fixes if you find bugs!

Development

Fork, develop, submit pull request.

Contributors

Class/fact code heavily cribbed from os_patching by Tony Green