How to: Using Lynis plugins

Within this “how to” we explain when and how to use Lynis plugins.

What are plugins?

Plugins are small extensions to an existing program. Also Lynis supports the use of external plugins to extend functionality. Lynis plugins are written in shell script and might use system binaries or external binaries to perform additional checks.

The big difference between custom tests and plugins in Lynis, are the goal of the tests. If some logic function checks a value and can inform the user to take an action, it’s better to use a normal test. For tests which primarily gather information, to be processed later, then a plugin is better suited.

Usually test data from a plugin will be reported in the log file (/var/log/lynis.log) and the report. Of course it depends on the plugin itself on how much data will be stored.

Creating a plugin

Create a file by using the plugin template file. Give it a filename plugin__phase1 and limit the permissions (e.g. chmod 600). If you create a custom plugin, we suggest to add custom to it (e.g. plugin_mycompany-custom_phase1), to prevent filename clashes.

Now alter the file and set the author, plugin name (short name) and version number. The category is especially useful for bundled plugins. If there is only one plugin, give it a name you prefer (e.g. custom).

Next thing is to activate the plugin in the scan profile. Add a line “plugin=pluginname”, so Lynis knows it should actually use the plugin.

When creating tests, don’t use existing test IDs or categories. Use the CUST category with a followup number (CUST-001, CUST-002 etc), so it’s clear that the tests are custom build to your needs.

Custom plugins

Depending on your needs, you might want to create a custom plugin. While we support that, please note that often it’s not needed. Many tests can be integrated in the main Lynis code. For users of the Enterprise Suite we can even help you creating the plugin, to avoid having to maintain your custom snippets.

Common solutions

My plugin does not get activated

Check the profile and see if the plugin is enabled. Check the file permissions of the plugin file itself. Additionally check the /var/log/lynis.log file for additional hints.

I can’t program, can you help?

Sure we can. Users of Lynis Enterprise Suite will get additional help, depending on your needs.