How to create custom tests in Lynis

Custom tests in Lynis

Although Lynis has many tests built-in, there are enough reasons to create your own custom tests. Instead of patching up existing files, there is a better way to run them and make use of existing functions.

In this article we will have a look on how to create your own tests and what functions can be used. With the software being open source and licensed under GPL, you have the flexibility to see existing tests and adjust them to your needs.

Creating tests

No custom tests enabled in Lynis

Creating custom tests is easy, as the toolkit of Lynis is written in shell script. So there is a lot of examples available in the already existing tests. To make it even easier, there is a small template available, which is named tests_custom.template and located in the include directory.

Prerequisites

This test start with checking if the OPENSSLBINARY variable has been set (“! -z” means is it not zero or empty). If it is set, then the prerequisites of this particular test have been set and checking when using the Register function.

When no prerequisites apply, remove the parameter from the Register function.

Register the test

The Register function actually registers the related test and determines if there are any reasons to skip the test. If not, the variable SKIPTEST will be set to 0.

This function needs at least the test-no, weight, network and description.

With the –test-no we define an unique identifier for your test. Use always “CUST-” followed by a four-digit number.

The –weight defines how important the test is, using L (low), M (medium) or H (high). When unsure, use M. By using the –network parameter, you can define if it needs network access, or not. Most tests won’t use any network function, so it is safe to use “NO” as a default value.

Tips for tests

From here on your test can do everything which is allowed in shell scripting. Run commands and test configuration files.

We suggest to avoid “exotic” commands and use as much bourne scripting (not bourne again, or bash). The reason is portability and it avoids that you have to add additional checks. When using commands which are not on the system, it may result in unexpected outcomes or errors on screen.

Make sure to initialize any variables which you will reuse at a later stage. For example, we use COUNT and FOUND a lot. We initialize those values to zero at the beginning of each test where it is used. The reason is to avoid a false positive in a test running at a later stage.

Testing your custom tests

When you are done with adding your tests, you can easily test them by only running the custom category.

./lynis audit systems --tests-category "custom"

After running Lynis again, it should show your custom test(s) and the related result. For example after enabling the test in the template:

Output of custom test in Lynis

Common functions

During the creation of your own tests, you can reuse existing functions. These will simplify the way data is logged to a log file, or displayed on screen.

Display

The Display function shows text on screen.

It uses at least the indent and text parameters. Optionally are the result and related color of the result.

The status usually is something like OK, Found, BAD, NONE, where color is one of the colors defined in the include/consts file.

logtext

This function will log a string to the defined log file.

Usage: logtext “This is a test”

ReportException

Use this function to trigger the exception message at the end of the scan, when an unexpected result occurred and you did not catch it with a normal “if” statement. For example: if you expect a test to exit with exit code 0 or 1 and it actually gave back “2”, then trigger the exception. This helps in debugging and monitoring for unexpected results.

Other functions

There are more functions available. They are stored in include/functions, with a description. By searching for the related function in the existing tests, they provide many examples on how to use the function.

Linux and UNIX security automation

Lynis is a free and open source security scanner. It helps with testing the defenses of your Linux, macOS, and Unix systems. Typical use-cases for this software include system hardening, vulnerability scanning, and checking compliance with security standards (PCI-DSS, ISO27001, etc).