This is the supporting documentation for Lynis and Lynis Enterprise, with focus on the Lynis client.
Part I: Lynis
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 the tests it provides a list of warnings and suggestions, on how to increase the security defenses of the system.
The software package consists of shell scripts, which are grouped and easy to understand. Being an open source tool, it is freely available and licensed as GPLv3 software. Lynis can be used as a standalone tool, or as component within the Lynis Enterprise suite.
This software helps with performing technical IT audits, discover vulnerabilities, detect possible intruders and do generic analysis of systems.
Since the tests are technical of nature, the primary audience for Lynis are system administrators, auditors and security professionals.
Requirements are low: a common shell to operate, root permissions are optional.
Lynis is a core component in the Lynis Enterprise solution. In this documentation both Lynis and Lynis Enterprise will be referenced. The Enterprise version consists of the following components:
- Central management interface
- Compliance checks
Features of Lynis Enterprise include:
- System and security audit checks
- Customized improvement plan
- File integrity assessment
- System and file forensics
- Extensive system audit report
- Usage of policies (reporting and monitoring)
- Extended debugging features
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
2.2. Using Lynis without installation
1. Create a directory
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
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 https://cisofy.com/files/lynis-version.tar.gz $ curl https://cisofy.com/files/lynis-version.tar.gz -o lynis-version.tar.gz3. Verification - Integrity
After downloading, test the file to confirm the integrity of the download. The related SHA1 and SHA256 hash are 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 $ sha256sum lynis-version.tar.gz $ sha1 lynis-version.tar.gz $ sha256 lynis-version.tar.gz $ openssl sha1 lynis-version.tar.gz $ openssl sha256 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.4. Verification - Signature
If you have GnuPG installed on your system, you can download our public key (https://cisofy.com/files/cisofy-software.pub) and the related signature of the download itself. The signature itself is a file with the extension .asc.$ wget https://cisofy.com/files/cisofy-software.pub $ gpg --import cisofy-software.pub $ gpg --list-keys --fingerprint /home/user/.gnupg/pubring.gpg ------------------------ pub 4096R/D5B79251 2014-11-04 [expires: 2030-10-31] Key fingerprint = 73AC 9FC5 5848 E977 024D 1A61 429A 566F D5B7 9251 uid CISOfy (Software Signing Key)
sub 4096R/6E8847E1 2014-11-04 [expires: 2030-10-31]
Verify that the results are the same as listed above. Next step is verifying the download:$ gpg --verify lynis-version.tar.gz.asc lynis-version.tar.gz gpg: Signature made Wed 05 Nov 2014 12:39:26 AM CET using RSA key ID D5B79251 gpg: Good signature from "CISOfy (Software Signing Key) <email@example.com>" gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 73AC 9FC5 5848 E977 024D 1A61 429A 566F D5B7 9251
Note: The warning is displayed as the system simply does not not know if it is trusted. As there is no central authority to validate, you can mark the key as trusted yourself. Before doing so, we have some tips to make sure you are using the right key:
- Compare the key output you get, with the results on this page
- Check DNS entry cisofy-software-key.cisofy.com, it should give the same fingerprint.$ host -t txt cisofy-software-key.cisofy.com cisofy-software-key.cisofy.com descriptive text "Key fingerprint = 73AC 9FC5 5848 E977 024D 1A61 429A 566F D5B7 9251"
$ gpg --edit-key firstname.lastname@example.org gpg (GnuPG) 1.4.16; Copyright (C) 2013 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. pub 4096R/D5B79251 created: 2014-11-04 expires: 2030-10-31 usage: SC trust: unknown validity: unknown sub 4096R/6E8847E1 created: 2014-11-04 expires: 2030-10-31 usage: E [ unknown] (1). CISOfy (Software Signing Key) <email@example.com> gpg> trust pub 4096R/D5B79251 created: 2014-11-04 expires: 2030-10-31 usage: SC trust: unknown validity: unknown sub 4096R/6E8847E1 created: 2014-11-04 expires: 2030-10-31 usage: E [ unknown] (1). CISOfy (Software Signing Key) <firstname.lastname@example.org> Please decide how far you trust this user to correctly verify other users' keys (by looking at passports, checking fingerprints from different sources, etc.) 1 = I don't know or won't say 2 = I do NOT trust 3 = I trust marginally 4 = I trust fully 5 = I trust ultimately m = back to the main menu Your decision? 5 Do you really want to set this key to ultimate trust? (y/N) y pub 4096R/D5B79251 created: 2014-11-04 expires: 2030-10-31 usage: SC trust: ultimate validity: unknown sub 4096R/6E8847E1 created: 2014-11-04 expires: 2030-10-31 usage: E [ unknown] (1). CISOfy (Software Signing Key) <email@example.com> Please note that the shown key validity is not necessarily correct unless you restart the program. gpg> quit
Now the key has be marked as being trusted and the related warning will be gone when verifying our downloads
5. Unpack the tarballtar xfvz lynis-version.tar.gz
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. BasicsIf 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)
- 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).
3.2. ParametersBelow the most commonly used parameter when running Lynis.
|--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)|
- If Lynis is not installed as package (with included man page), use --man or nroff -man ./lynis.8
- For systems where the shell background is light, use --nocolors or --reverse-colors
- Use --dump-options to see all available parameters of Lynis
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).
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).
- 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. ProfilesLynis 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.
- 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 outputWhile 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.
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 WarningsThe 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. PluginsLynis plugins are extensions to the Lynis core. Where normal Lynis controls perform individual tests and share the outcome, plugins will usually just gather information. This information is then collected and processed in bulk. The big benefit is that is quicker and more powerful. For example security intelligence can be applied by collecting data and correlating it on the central node.
Plugin phasesLynis has modular support to extend basic functionality by using plugins. Plugins are executed in several phases:
Plugins: Phase 1
Plugins which do use hooks into existing tests, or gather data for later processing, will use phase 1 to initialize. Some tests which are part of the plugin will then finish in phase 2.
Plugins: 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.
Plugins can be enabled by using the plugin option within the profile.
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.
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 just want an invidual test, you are advised to use the custom_test file instead, as plugins have a different goal.
If you consider writing a plugin, we ask you to contact us to determine the possibilities.
5. Reporting and LoggingLynis 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
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 usually the preferred option. This specific tool has more capabilities and features to deal with batches of data. Both the --upload parameter and Lynis Collector, are meant to upload data to the central node.
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.
For data uploads, the cURL utility is being used. For environments which require a proxy, the profile allows you to define any options given to cURL, like --proxy. In case a self-signed certificate is being used on the central node, you can disable full certificate checking with the --insecure option.
Upload via Lynis Collector
Lynis Collector can be downloaded by customers. 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. IntroductionThe Collector component within the Lynis suite, is a supporting tool. It collects reports from many systems and uploads it in one batch. It is available to users of the Enterprise solution. Only one Collector is usually needed within the network. 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. InstallationTo 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 useBefore running the collector, check if the following files and directories are present:
/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 dataDepending 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.
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 firstname.lastname@example.org "cd /usr/local/lynis; ./lynis -c -Q -q"
11. MonitoringProcessed 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 errorscurl: 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 codesResponse: Error 312 incorrect_data
- 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
To use Lynis Enterprise, you need a license key and an active user account. An account can be created during the ordering process or before. Management happens with a web based solution. No external plugins have to be installed to work with our solution.
For auditing purposes, Lynis needs to be configured on the systems who are to be audited. Optionally the Lynis Collector can be used to collect data and upload it from a central location.
Please refer to Section I and Section II to install and configure these components.
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 new system
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.
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 ( ).
16. Security hardeningOne 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 BaselinesBaselines 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 managementMore details will follow later
19. Event handlingEvents 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 upgradesSince 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.
Option 2. No install
Instead of installing Lynis at all, a cronjob could be used to fetch the latest Lynis package from an internal server (e.g. HTTP/FTP/SCP/NFS). The cronjob first extracts the tarball into a temporary directory. Then it runs Lynis from there, and before cleaning up, it 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-dateStaying 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:
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.
Freecode has also a RSS feed. Add https://freecode.com/projects/lynis/releases.atom to your favorite reader. No subscription to Freecode needed.
Follow founder Michael Boelen (@mboelen) or @cisofy_is
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 packagesFor 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:
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: SupportLynis 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.
ThanksThanks 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.