Lynis

Documentation and installation guide

Author:	Michael Boelen (michael@rootkit.nl)
Description:	Security and system auditing tool
Web site:	http://www.rootkit.nl/projects/lynis.html
Support policy:	See section 'Support'

Introduction

Lynis is an auditing tool which tests and gathers (security) information from Unix based systems. The audience for this tool are security and system
auditors, network specialists and system maintainers.

Some of the (future) features and usage options:
- System and security audit checks
- File Integrity Assessment
- System and file forensics
- Usage of templates/baselines (reporting and monitoring)
- Extended debugging features

The name Lynis is fictive and does not have a special meaning. Everyone is free
to use Lynis under the conditions of the GPL v3 license (see LICENSE file).

Quick facts
Name:	Lynis
Type:	Audit, security, forensics tool
License:	GPL v3
Language:	Shell script
Required permissions:	root or equivalent
Other requirements:	write access to /var/log and /tmp

Installation

Before installing Lynis, confirm that you have downloaded the files from a trusted source. If you downloaded a tar ball, check if the SHA1
hash provided on the website (project page, bottom of the page), matches the SHA1 value of your local file. Depending on the OS you use,
this can be performed with the command sha1, sha1sum or if installed with openssl.

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

Lynis doesn't have to be installed, so it can be used directly from a (removable) disk.

Steps to run Lynis without installing:
- Create a custom directory (ie. /usr/local/lynis)
- unpack the tar ball (tar xfvz lynis-version.tar.gz) into this directory.

If you installed Lynis as a package from a software repository, make sure file checksum tests are enabled. Most package managers will use
this by default.

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>

Upgrade tip:
If you want to upgrade easily, make a shell script which removes an old installation, then unpacks and installs the new version. However, don't
forget to migrate your dynamic files (like report / profile files).

Supported systems

This tool is tested or confirmed to work with:
- Linux, FreeBSD, OpenBSD, PcBSD, Mac OS X, Solaris

For package management are the following tools supported:
- dpkg/apt, pkg_info, RPM

Using Lynis : Basics

To run Lynis you should meet a few requirements:
- You have to be root (log in as normal user, su to root)
or have equivalent rights (for example by using sudo).
- Have write access to /var/log (for using a log/debug and report file)
- Have write access to /tmp (temporary files)

Depending on the installation or the path you run Lynis from, you can start it with 'lynis' (if installed and the file is available in
your binary path) or 'sh lynis' or './lynis'.

Without parameters, Lynis will give you a valid list of parameters and return back to the shell prompt. At least the '-c' (--check-all) parameter
is needed, to start the scan process.

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

Using Lynis : Often used parameters

Parameter	Short version	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
--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)

If Lynis is not installed as package (with included man page), you also can use nroff -man ./lynis.8.

Using Lynis : Cronjobs

In case you want to create a daily report, you could create a cron job. By adding the option --cronjob all special chars will be stripped from
the output and the scan will be run completely automated (no user intervention is needed)

Example:
16    6     *       *       *       root    /path/to/lynis -c --auditor "automated" --cronjob

Though most options will be set correctly, you are still able to change other parameters where needed.

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. Of course this increases the amount of time
    to finish the tests, but decreases the load on the machine. If you set this option to 10 seconds and normally an amount of 60 tests is performed,
    this will add 600 seconds to the total amount of testing time.
- 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.

Using Lynis : 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)

Using Lynis : Scanning Results

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 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).

Using Lynis : Reports

Currently 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.

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

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

Using Lynis : Plugins

[UNDER DEVELOPMENT]

Lynis has modular support to include default and user customized plugins. When creating personal plugins, you are adviced to add a personal prefix, making the
file name unique (ie. custom_myplugin). This prevents the file being overwritten at a new release.

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

Using Lynis : Debugging and 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, you should schedule a log rotation
or make a backup before running Lynis again.

Stay up-to-date

Since releases add extra functionality and contain bug fixes, it is important to use one of the latest versions of Lynis.

Freshmeat
- Create an account on Freshmeat.net and subscribe to the project. When a new version is released, an e-mail will be send to all subscribers.
Internal check
- Lynis uses DNS to check for a TXT record, containing the latest version. When an audit is running, it will perform the check and display a message when a newer version is available.

Development

If you have input to improve Lynis, feel free to fill in the contact form.

Note: currently there is no need for additional developers, however patches will be considered.

Support

Lynis is tested on the most common operating systems. The documentation (README, FAQ) and the debugging information in the log file should cover
most questions and problems. Bugs can be reported by filling in the contact form at the web site.

NOTE: The contact form is not a place for common user questions. Questions (or the answer to it) which can be found in the docs, the web site or log
file will be discarded and bounced with a small line referring to the source which can help you. This is to avoid answering the same questions over and over,
encouraging the user to read the documentation and to make programming time more efficient.

Commercial support is available under strict conditions and depends on the request.

Project donations

Individuals and companies which use this software for more than 10 systems, should consider the value of this tool. To improve my tools, I rely on
internet sources, lots of books and a huge amount of time (spare time) investment. Book donations are highly appreciated and stimulate development.

Thanks

Thanks to the community for using and supporting open source software and my tools in particular. Many comments, bugs/patches and questions are the
key to success and motivation in developing tools like this.

A special thanks to anyone who donated a book or input in the past!

Lynis - Copyright 2007-2009, Michael Boelen - The Netherlands
http://www.rootkit.nl