Twitter icon for CISOfy handle Facebook icon for CISOfy page Google+ icon for CISOfy plus page

Lynis Documentation

Documentation and installation guide


As part of our open source vision, we like to openly share our knowledge. Please refer to the information below for additional guidance. If you are looking for downloads, visit our downloads section.

Abstract

Part I: Lynis
Part II: Lynis collector
Part III: Lynis Enterprise
Part IV: Tips and Suggestions
Part V: Support
Part VI: Frequently Asked Questions

Part I: Lynis

1. Introduction

Lynis is an open source security tool to audit and harden Unix/Linux based systems. It performs an extensive set of tests and collects information about the system. After finishing the tests, it provides the user with suggestions to increase the security of the system. With the addition of plugins and the Lynis Enterprise solution, companies can get much more out of Lynis like central management, reporting and in-depth system scans.

Lynis is written in shell script and licensed under the conditions of GPLv3. It can be used as a standalone tool or as component within the Lynis Enterprise suite.

Audience
Since the tests are technical of nature, the primary audience for Lynis are system administrators, auditors and security professionals. Also individuals who are experienced on the terminal, are a good candidate to use Lynis for improving the security of their system. For less technical oriented people, the Lynis Enterprise solution will provide better insight in the scan results, like compliance benchmarks and reporting.

Requirements
Requirements are low: a common shell to operate, root permissions are optional.

Some of the (future) features include:
- System and security audit checks
- Customized improvement plan
- File integrity assessment
- System and file forensics
- Extensive system audit report
- Usage of templates/baselines (reporting and monitoring)
- Extended debugging features

2. Installation

Package
Although no installation is needed, a common method to use Lynis is installing it via a package. This could be with the repositories provided by the operating system, or a manually created package. Please note that some repositories go for stability and don't update software after the release, with exception of security updates. This might result in using a very old version of Lynis and is usually not preferred. So before using a package, confirm that updates are provided.

Red Hat based: $ yum install lynis
Debian based: $ apt-get install lynis

Lynis without installation

1. Create a directory (ie. /usr/local/lynis)
Lynis can be started from each directory (or from removable media). While this step is therefore optional, it does apply if Lynis is to be run on a scheduled basis (see section Cronjobs).

$ mkdir /usr/local/lynis
$ cd /usr/local/lynis

2. Download
Go to the Downloads section and copy the link to the Lynis tarball (ends with lynis-version.tar.gz). Use this link together with wget (usually installed by default). Mac OS users can use curl tool, where BSD users could use fetch.

$ wget http://cisofy.com/files/lynis-version.tar.gz
$ curl http://cisofy.com/files/lynis-version.tar.gz -o lynis-version.tar.gz

After downloading, test the file to confirm the integrity of the download. The related SHA1 hash is provided on the website as well. Depending on your OS, this can be performed with the command sha1, sha1sum or with openssl.

$ sha1sum lynis-version.tar.gz
$ sha1 lynis-version.tar.gz
$ openssl sha1 lynis-version.tar.gz

The resulting hash displayed should be the same as on the website. If not, try downloading it on another machine or via a browser, to confirm the download was not corrupted. If the hash still shows a different value, please contact us.

3. Unpack the tar ball
$ tar xfvz lynis-version.tar.gz

Upgrade tip:
If you want to upgrade easily, use a shell script which removes an old installation, then unpacks and installs the new version. Note: migrate your dynamic files (eg report and profile files).

3. Using Lynis

3.1. Basics

If Lynis is installed as a package, just typing in 'lynis' will start the program and provide the available parameters. When using a manually installed instance of Lynis, or running it from a temporary directory, use ./lynis (or sh lynis) from the local directory.

At least the '-c' (--check-all) or another scan parameter is needed to start the scan process.

To run Lynis you should meet a few requirements:
- Have write access to /var/log (for using a log/debug and report file)
- Have write access to /tmp (temporary files)

Notes:
- For the update check, outgoing DNS requests should be allowed (query of TXT record).
- Lynis needs write access to /var/log/lynis.log (unless logging is disabled, which disables debugging information as well).

3.2. Parameters

Below the most commonly used parameter when running Lynis.

Parameter Abbreviated Description
--auditor "Given name Surname"   Assign an auditor name to the audit (report)
--checkall -c Start the check
--check-update   Check if Lynis is up-to-date
--cronjob   Run Lynis as cronjob (includes -c -Q)
--help -h Shows valid parameters
--manpage   View man page
--nocolors   Do not use any colors
--pentest   Perform a penetration test scan (non-privileged)
--quick -Q Don't wait for user input, except on errors
--quiet   Only show warnings (includes --quick, but doesn't wait)
--reverse-colors Use a different color scheme for lighter backgrounds
--version -V Check program version (and quit)

Tips
- If Lynis is not installed as package (with included man page), use nroff -man ./lynis.8.
- For systems where the shell background is not dark, use --nocolors or --reverse-colors.

3.3. Cronjobs

Running Lynis as a cronjob is also possible. For that purpose the --cronjob parameter exists. By adding this option all special chars will be stripped from the output and the scan will be run completely automated (no user intervention needed).

Example:
#!/bin/sh

AUDITOR="automated"
DATE=$(date +%Y%m%d)
HOST=$(hostname)
LOG_DIR="/var/log/lynis"
REPORT="$LOG_DIR/report-${HOST}.${DATE}"
DATA="$LOG_DIR/report-data-${HOST}.${DATE}.txt"

cd /usr/local/lynis
./lynis -c --auditor "${AUDITOR}" --cronjob > ${REPORT}

mv /var/log/lynis-report.dat ${DATA}

# The End
Add the contents of this script to /etc/cron.daily/lynis and create the related paths in the script (/usr/local/lynis and /var/log/lynis).

Tips:
  • If you only want to see the warnings while running Lynis as a cronjob, use the options --cronjob and --quiet together.
  • The profile option 'pause_between_tests' can be used to increase the wait time between tests. This might be used to decrease the load on the machine slightly. Please note that a small delay between the tests will result in taking the scan (much) longer to finish.
  • If you want to sync the report file to a central host, you could write a small script to run Lynis and sync/copy the report file afterwards.

3.4. Profiles

Lynis uses profiles to have a set of predefined options for your operating system and personal wishes. If you don't provide a profile (--profile <name>), the default profile (default.prf) will be used. You are adviced to copy the default.prf and adjust it to your needs.

With the usage of profiles, you can make a template/baseline for different types of systems.

Examples:
- Profile per operating system (Debian Linux, RedHat Linux, OpenBSD)
- Profile per system roles (mail server, web server)
- Profile per security level (low, medium, high level)

3.5. Screen output

While Lynis scans a system it will perform single target tests and output the result of every (performed) test to the screen. Every scan result has to be interpreted by the auditor and (re)checked what it means.

Behind most tests, it will output [OK] or [WARNING], where the first one is considered an expected (good) result, the second one unexpected. However, keep in mind that a result saying "[OK]" does NOT always mean the scanned target is correctly configured, safe (security wise) or a best practice.

On the opposite, every "[WARNING]" doesn't have to be 'bad', since systems (and their requirements) are different. However, as auditor you are adviced to pay attention to them and check what influence the test has on your system or policy.
Actions you can take after getting a warning:

- Fix the problem
Read the log file about the technical background (often it contains a suggestion at the test), consult internet sources and documentation about what the impact of the change can be.

- Disable the test (whitelisting)
Within the scan profile, tests can be completely disabled (option test_skip_always). When you have a test which gives a warning and you are not interested in the result of that particular test, you can ingore it.

For example:
You have only one DNS server configured on your workstation. A test shows a warning and reveals that it expects at least two working name servers. In such case you can choose not to get informed about it and disable the test. Extend the option test_skip_always in your scanning profile with the test number (which can be found in the log file or at the end of the Lynis screen output).

After every scan, the auditor should consult the log file (/var/log/lynis.log) and interpreter the results. If tests are displayed as a "[WARNING]", the log file will give the reason why a warning was displayed. In most cases a "Suggestion:" line will be present, to assist in resolving the issue or give more information what was tested (or expected).

3.6. Suggestions and Warnings

The screen output, as outlined in previous section, will provide the status of most tests on screen. During the audit proces, Lynis will gather any possible suggestion or warning. These results will be grouped and displayed at the bottom of screen output. Usually warnings are events which really need an action. Suggestions on the other hand could indicate room for improvement. It's common to find much more suggestions than warnings. This does not imply that because there are many suggestions (and no warnings) that a system is properly secured!

To determine what has been checked together with the related suggestion/warning, the test identifier is displayed on the same line (between brackets). Open the lynis log file (/var/log/lynis.log) and search for this identifier.


4. Plugins

Plugin phases

Lynis has modular support to extend basic functionality by using plugins. Plugins are executed in several phases:

Phase 1
Plugins which do use hooks into existing tests, or gather data for later processing, will use phase 1 to initialize and finish execution in phase 2.

Phase 2
After running all tests, plugins get a last chance to do their job. For example parse discovered elements on the system, like a virtual host within Apache.
Plugins which can be used standalone (e.g. no hooks, no input from existing tests), can be executed in phase 1. No need for a phase 2 component.

Enabling plugins:
Plugins can be enabled by using the plugin_enable option within the profile.
Example: plugin_enable=<custom_myplugin>

Plugin directory
The directory in which plugins can be stored is determined by Lynis. By default it tries a few paths (/usr/local/lynis/plugins /usr/local/share/lynis/plugins /usr/share/lynis/plugins and /etc/lynis/plugins). If these directories are not found, then the local work directory is being used. To use a different directory, use the --plugin-dir parameter, followed by the directory name.

Custom plugins
When creating personal plugins, you are adviced to add a personal prefix and making the file name unique (ie. custom_myplugin). This prevents the file being overwritten at a new release. If you consider writing a plugin, we ask you to contact us to determine the possibilities.


5. Reporting and Logging

Lynis supports one report format, which can be used to gather results and display them in a custom or (more) friendly presentation. The report file can also be used to compare scan results from the past with a current scan. Lynis Enterprise on the other hand has much more possibilities to display data, including extended reports in several formats.

Contents of report file:
- Remarks: #<remark>
- Section: [<section name>]
- Option/value: <option name>=<value of option>

When an option may have multiple values (like installed packages for example), brackets ([]) are added. Example: installed_package[]=Package-1.0.0

Logging
When a system is scanned and results are displayed, additional debugging information will be added to the log file (default: /var/log/lynis.log). For advanced testers this information will be useful to see what the program did in the background or where anomalies showed up (and often why).

Information in the log file:
- Time of an action/event
- Reason(s) why a test failed or will be skipped
- Output of (internal) tests and sub tests
- Suggestions about configuration options or how to fix/improve things
- Threat/impact score

Remark: the log file will be purged every scan. If you need debugging or logging information for previous scans, schedule log rotation or make a backup before running Lynis again.


6. Integration with Lynis Enterprise

Lynis data can be uploaded via the --upload option. For companies using multiple systems, the Lynis Collector is the preferred option though. This specific tool has more capabilities and features to deal with batches of data. Both the upload parameter and Lynis Collector are meant to collect Lynis data and save it in a central repository.

Upload via Lynis

Add the license key in in the scan profile (default.prf or your customized profile). After adjusting, use the --upload parameter to upload the data after scanning.

Upload via Lynis Collector

Lynis Collector can be downloaded by registered members. See part II for more details about this component. Data from systems will be collected by this collector, checked for consistency and then uploaded to the central management node.


Part II: Lynis Collector

7. Introduction

The collector component within the Lynis suite is meant as a supporting tool to collect reports from Lynis. It's available to Enterprise users who would like to collect the report file generated by Lynis and upload it to the central management. Besides collecting the report files, the collector has the following goals:

- Confirm a valid license is used
- Check consistency of report files
- Mask or remove sensitive information

8. Installation

To use the collector, download the tarball from the Downloads section. Create a local directory (e.g. /usr/local/lynis-collector) and limit the permissions to this directory. The tool does not need root permissions, so a restricted user is sufficient.

The only requirement for the Collector is the availability of a recent version of the curl binary, which is used to upload the files to the management node. In case curl is not installed yet, please install it and make sure that the appointed user account can run the command. Next step would be unpacking the archive into the created directory and adjust the settings.conf file. Add a valid license key and adjust the local path to the location created in the previous step.

After this the collector can be tested by running it. When using it from an alternative path, specificy the settings file with the -s parameter, followed by the full path and name of the settings file. The collector will then perform a license key check and display the status. If it's working as expected, turn off screen output by adjusting the DEBUG option to zero (0).

9. Configuring for first use

Before running the collector, check if the following files and directories are present:
/your/location/new (directory)
/your/location/processed (directory)
/your/location/collector.sh (main script)
/your/location/settings.conf (configuration file)

When using the collector for the first time, consider collecting only a few machines. Use the DEBUG option and check if the data is properly uploaded. After sending the data with the collector, login in the Enterprise interface and check if the systems are listed in the overview. First time they might be displayed slightly different, as not all data is directly processed.

10. Collecting data

Depending on your Lynis schedule (e.g. daily/weekly), the related report file should be forwarded to the collector node. As it's depending on the environment what options can be used, we list here the common available options and tips.

Upload to webserver
Similiar to the Collector itself, curl can be used to upload a file to an internal webserver. Before the file is being uploaded, it should be renamed to avoid overwriting data. An unique field would be the hostid, which is also present in the report file. Another option could be using the IP address or the hostname, although duplicates can exist. Additional measures should be taken to limit access to the directory on disk, but also via HTTP requests. Strict permissions and deny accessing via your webserver should be implemented.

FTP, NFS, rsync, SCP
Existing file copy protocols can be used to copy the file. These protocols often have limited protection against overwriting of files. Especially since systems need write permission so they can copy the data, there is a risk in deletion or overwriting file contents.

Pull data
Instead of having the clients push the data, the data could also be pulled from the collector. For example with SCP and allowing only a particular copy command in the authorized_keys file.
Example: ssh -t -i /root/.ssh/id_rsa_automated root@yourhost.com "cd /usr/local/lynis; ./lynis -c -Q -q"

11. Monitoring

Processed files
After processing the data, by default a file will be moved from new to processed. In some cases this could result in the directory consuming too much space. Monitor this directory and additionally apply a find command against this directory, with autodeletion of old files.


12. Collector support and errors

curl: open --data-urlencode: is unknown
curl: try 'curl --help' for more information

The version of curl used is too old and not supporting the --data-urlencode option. Download a newer version of curl to fix this particular issue.

Warning: no hostid found in job. Skipping this file.
Lynis was not able to find an unique host identifier for the related operating system. Please check the logfile (/var/log/lynis.log) and search for "hostid" to gather additional hints. Please contact us for further assistance.

Error codes

Response: Error 312 incorrect_data
Possible causes:
- Log file is used instead of report file (/var/log/lynis-report.dat). Check if the report file is used.
- The hostid is incorrect, double or having invalid characters. Check if the hostid is present in the report, is unique and does not have additional characters (like a Windows "enter", or CRLF).

Response: Error 320 no_credits
Possible cause: No more credits available in your license, or too much data uploads for that day.


Part III: Lynis Enterprise

13. Introduction

To use Lynis Enterprise, every company needs a license key combined with one or more user accounts. These can be created during the ordering process or before. Secondly Lynis needs to be configured on the systems who are to be audited, together with the Lynis Collector software. Please refer to Section I and Section II to install and configure these components. If Lynis and the Collector have been configured then the remaining configuration can be done within the Enterprise interface.

14. Account Management

An account on the Lynis Enterprise service provides access to the systems and configuration of a company. Each account can be linked only to one company.

15. Management of systems

Adding

During the life cycle of a system, it can be easily added by uploading the data to Lynis Enterprise. If the unique ID of the system is not known yet, the system will be added to the pool of machines, to which the license belongs. No manual actions are needed.

Removing

When a system is being decommissioned, the absence of new scan data will be noticed and a related event will be raised. If the system is to be removed altogether, select the system and use the delete icon ( Delete system ).

16. Security hardening

One of the main components of Lynis and Lynis Enterprise is to provide guidance in security hardening of systems. Per system the related security controls are listed. The Enterprise edition includes an implementation plan, customized to your environment. This way help is provided to select which controls.

17. Compliance and Baselines

Baselines provide a means to check for a defined policy and report about the compliance with the policy. Each system can be linked to a baseline of choice.

18. Change management

More details will follow later

19. Event handling

Events within the Lynis Enterprise solution are used to inform the administrator(s) about a specific activity. This includes exceeding a warning threshold or for example missing data. Usually an event is a call to action and check the related component.

20. Software upgrades

Since Lynis will be often updated to support new tests and software, performing regular updates is advised. Depending on the installation method there are two options to stay up-to-date:
Option 1. Using software packages
If the platform(s) used provides an up-to-date Lynis package, it could be used as part of your software upgrade strategy. In case the vendor maintains only "stable" releases, they will usually not release newer versions of Lynis, until the next OS release. Then you might consider creating a Lynis package yourself. See the Tips section on how to create a package. While one must try to avoid doing too much manual work in this world of automation, building a Lynis package usually takes only a few minutes. After that all other servers can make use of this fresh package.

Option 2. No install
Instead of installing Lynis at all, a cronjob could be written to fetch the latest Lynis package from an internal server (e.g. HTTP/FTP/SCP/NFS). The cronjob extracts the tarball into a temporary directory, runs Lynis from there and before cleaning up, sends the data to the Lynis Collector. Updating to a new release would mean the administrator will test the new version first on a few systems and then upload it to the central location. From that very moment all systems will be using the latest version.


Part IV: Tips and Suggestions

Staying up-to-date

Staying up-to-date with software is important to have access to the latest functionality and make sure that known bugs have been solved. Since Lynis is an auditing tool, it's possibly even more important to keep up with the latest version. Right now we don't provie auto-updating yet. We believe strongly that people should test software releases before applying them into production.

To get notified when new releases are available, the following options are available:

Notification list
At our Downloads page you can subscribe to the notification list. When a new release is available, you get an e-mail with the changes.
RSS
Freecode has also a RSS feed. Add https://freecode.com/projects/lynis/releases.atom to your favorite reader. No subscription to Freecode needed.

Twitter
Follow founder Michael Boelen (@mboelen) or @cisofy_is

Lynis --check-update
For monitoring purposes or to notify yourself, it's possible to parse the output of Lynis while it checks for the latest version. If the output is "Outdated", a new version is available. Background information: Lynis uses DNS to check for the latest version by using a TXT record query.

Building your own packages

For companies or individuals who prefer their own packages, there is a lynis.spec file available. Building a RPM is very easy due to the low amount of dependencies of Lynis and consists of the following steps:

Package creation:
To create a custom package for installation on your machine(s):
- Download lynis.spec file (see project page)
- Adjust version number and if needed, paths
- Run 'rpmbuild -ta lynis-version.tar.gz' to build the RPM package
- Install package by running: rpm -ivh <filename>

Error: You have to be root (or equivalent) to perform an audit. Please su(do) and try again.

Lynis needs to be executed as root for a full audit. Change to the root and execute Lynis again. Sudo might work as well. If you don't have root permissions, use the --pentest option.

Error: Change ownership of ./include/const and ./include/functions to 'root'

To protect alteration of the files, Lynis perform a few security checks. If the related files are not owned by root, or their permissions are not strict enough, Lynis will show this on screen, including the commands to fix it. Usually it is caused because files were untarred by a user other than root.


Part V: Support

Lynis is tested on the most common operating systems. The documentation (README, FAQ) and the debugging information in the log file usually provides the answer to most questions (or problems). Bugs can be reported by contacting us. Commercial support is available.

Part VI: Frequently Asked Questions

Is Lynis really free?

Yes, Lynis is open source and free to use. By default it comes without warranties or support, as described in the Lynis package. If you prefer support, then integration with Lynis Enterprise is better suitable for your needs.

Is Lynis restricted in funtionality compared with the Enterprise version?

There are no limitations regarding functionality. Lynis is also part of the Enterprise version, therefore it has full functionality. The only part missing are (some) plugins, as they are not intended to be used stand-alone.

What systems are supported?

All common systems based on Unix/Linux are supported. Examples include Linux itself, *BSD, Mac OS X, Solaris. HP-UX and AIX are known to be working.
For package management are the following tools supported:
- dpkg/apt, pkg_info, RPM

What is the difference between Lynis and Lynis Enterprise?

Both are two different products, yet related. Lynis is the open source auditing tool and used a component within the Lynis Enterprise solution. Companies which are using Lynis Enterprise, will therefore also be using Lynis. Lynis Enterprise itself is a central management environment, which leverages the data collected by Lynis.

Can I create my own tests?

Sure you can! Lynis has a test category named "custom" (filename tests_custom). If this file exists, it will execute your own defined tests.
While creating your own tests is totally fine, please consider if others could benefit from them as well by sharing them with us. We accept most tests and give you the appropriate credit (or keep it anonymous if preferred).

The colors used are hard to read with my white background, how can I solve this?

Disable color usage or use the --reverse-colors option

What is the difference between a normal test and a plugin?

While both are similiar in what they can do, a test has the main goal of performing a check and directly form a conclusion (something is present or not, the outcome is good or bad etc). The purpose of plugins is to collect data for later use. In particular the Lynis Enterprise solution will use plugins to collect extra data which will be later analyzed. One example would be to determine exceptions or outliers. It would not make sense to have everyone build up databases of data, while all information is already centrally stored.

Is it possible to become reseller of Lynis?

Yes. Please contact us for the possibilites.


Thanks

Thanks to the community for using and supporting open source software and our tools in particular. Many comments, bugs/patches and questions are the key to success and motivation in developing tools like Lynis. A special thanks to donators, supporters and partners!


Lynis is copyrighted by Michael Boelen and licensed under the GPLv3 license. rootkit.nl was the previous home of Lynis. cisofy.com is the official location for the Lynis projects.