Lynis Enterprise - Self-Hosted Guide

Documentation for the Lynis Enterprise version running on-premises

Supporting documentation for Lynis Enterprise, with focus on the self-hosted version and its installation. For the installation of Lynis (client), please refer to the Lynis Installation Guide.





Overview of self-hosted version of Lynis Enterprise

Part I: Lynis Enterprise (Self-Hosted)


1. Introduction

The self-hosted version of Lynis Enterprise runs within your IT environment. It is similar to the SaaS solution, yet hosted in your own network.


2. Software Components

Lynis Enterprise consists of open source components, including its open source scanning client Lynis. To run the self-hosted version of Lynis Enterprise, the following components are used:

  • Control Panel (web interface)
    • Framework
    • Interface
    • Data definitions
  • Lynis (client)
  • Updater (installation/updates)

3. System requirements

To run Lynis Enterprise self-hosted, ensure that your system meets at least these requirements:

  • 64-bit installation of Linux
  • CentOS, Debian, openSUSE or Ubuntu
  • 1 GB of memory, preferably more
  • 10 GB partition /data

We suggest to use a new virtual machine, for maximum flexibility.

Note: These requirements do not apply to the clients to be audited.




Part II: Installation

Lynis Updater

The installation of Lynis Enterprise begins with downloading the Lynis Updater. Customers will receive a license key, together with a link to download the latest Updater.

This tool is both an install and update tool. It will perform installation and snesures you always have the latest software updates. Besides software updates, it will also download and import data definitions. It performs system maintenance and activates the modules you are entitled to use.

The Updater has two common methods to run: automatic or interactive.


Using the Lynis Updater

After downloading the Updater, extract it into a temporary directory:

tar xfvz lynis-updater-sometext.tar.gz

and run it
sh lynis-updater -i

The Updater can be deleted from the temporary directory, after the installation process has been completed. The latest version will then be available from /data/lynis-enterprise/updater.

The first time you run the tool, provide the -i (or --interactive) option. This tells the updater that someone is behind the keyboard. It will then let you provide all required input, like an e-mail address, license key, and passwords.


Automatic Mode

During the installation, the Updater will prepare itself for later scheduled runs. In this case it will run in the automatic mode. This means it can perform most checks and actions, unless they require direct input. This mode is used therefore ideal for daily update checking and maintenance.


Master License Key

During the first run, the master license key is asked. If you don't have a valid key, cancel the installation and request one via our support. The license key is needed to receive software updates.


Database Configuration

Lynis Enterprise uses open source components. For storing data, the well-known database engine PostgreSQL is used. In this section we cover the related configuration bits.

Database Connection

To enable a connection, the pg_hba.conf file need to be modified. The location of this file depends on your operating system and version of PostgreSQL. First step is to determine where your pg_hba.conf is.

find / -name pg_hba.conf -print

Add the following line to the beginning of your pg_hba.conf file
local  lynis_enterprise  lynis_enterprise  md5

This ensures that the user lynis_enterprise can connect locally to the database, with a hashed password.


Database tables

The database structure is automatically created after all software components are installed. Normally no action is required regarding the set-up of this part.


Using a Proxy

When using a proxy in your environment, the easiest option is to define the proxy in the cURL configuration file.

Create the file /root/.curlrc with contents:

proxy = <host>:<proxy_port>

Users

Lynis Enterprise has different types of users:
  • Super Users
  • Normal Users
  • Functional Users

Super Users

After installation of Lynis Enterprise, the Updater will provide the option to create a super user. This account type has a high level of privileges. This includes activities like creating company entities, license, and user accounts. Also activities for maintenance and status checking, are exclusively available to this user type. Even though it has high privileges, it can't view system data.

Additional super users can be created via the console.

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py createsuperuser


Normal Users

Users can reset their password, by using an e-mail based password reset link. An alternative is that the administrator performs this reset on the central system:

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py changepassword user_name


Functional Users

For some actions, like automation and integration, functional accounts are being used. These are similar to normal users, with the exception that they have a specific set of permissions.


Part III: Security


Firewall Configuration

It is suggested to limit the amount of systems to connect to the central server. For the working of the system only HTTPS on TCP port 443 is required. Port 80 for HTTP is optional. The other services you might want to allow is those for monitoring and SSH access.

  • HTTP (80) - To redirect users who didn't specify protocol
  • HTTPS (443) - To receive data, download updates, provide web interface and API

Part IV: Monitoring and Maintenance


Monitoring

For the best experience and security, your self-hosted installation should be properly managed. This includes monitoring for performance and security, and doing the right maintenance. The Updater helps partially with this, but there are also things you can do.

System Usage

Relevant metrics regarding the hardware are disk usage, memory usage and processor utilization. Increase the capacity of these factors, if the system encounters high utilization on a regular basis. To prevent spikes, the system already spreads imports and other maintenance work as much as possible.


Lynis Enterprise Interface

To ensure the application runs properly, it is advised to monitor the machine. Add the system to your monitoring and monitor on port 443. We suggest to monitor https://your-address/status/ and let it check for a 200 response code. The page will output its status in JSON and return warnings or errors if something is wrong.


Database

Since the database is one of the heavy users regarding system utilization, we suggest to monitor it.


Maintenance

Data directory

All data, configuration files and software components are stored on the /data partition (or directory).

If you want to clean out older downloads, you can easily find all files which are older than 90 days, with the following snippet:

find /data/lynis-enterprise/downloads -mtime +90

noteDon't reduce this amount to lower than 30 days, as it might result in downloading the same files every time the Updater runs.


Backup and Restores

The ability to restore your data is important. Therefore the Updater will create a backup script, to facilitate the creation of backups.


What to Backup?

Install your backup utility and at least include /data and /etc in your backup. If you want to take the safe route, it is advised to also make a separate database backup of your PostgreSQL instance. The Updater utility does include another method to storage database dumps, but better safe than sorry.


Database Dumps

Backups are made daily and stored in /data/lynis-enterprise/backups. For every first day of the month, a "month backup" will be created. To save space, a maximum of 42 (30 daily, 12 monthly) database dumps will be stored.

The dumps created with the dump script, can be stored via the manage utility.



Part V: Frequently Asked Questions

Hardware

What kind of hardware should I use to run Lynis Enterprise?

Just a virtual machine, 64 bits. Provide it at least with 1 GB of memory and a /data partition of 10 GB.

Processes

How can I restart the Lynis Enterprise interface?

CentOS/openSUSE:
systemctl restart lynis-interface

Debian/Ubuntu:
/etc/init.d/lynis-interface restart

What processes should be running?

At least: python processes, lynis-parser, nginx, postgres

Status

What is the best URL to monitor the application?

Monitor port 443 (HTTPS) and query https://your-hostname/status/ for a 200 code.

How can I test my monitoring is working?

Shutdown the Lynis Enterprise interface


Part VI: Troubleshooting

We test out software extensively. If you still ever run into an issue, here are some tips to do the first line of troubleshooting.


Internal error

When you get an internal server error message, the page lacks details on purpose, to prevent information leakage. As a manager of the interface, you can still get more details. There are two common options for that:

  • Option 1: send debug information by e-mail
  • Option 2: send debug information to screen

Option 1: e-mail

A safe option is to configure an administrator to receive the debug data by e-mail. For that the mail configuration on the local system should be working correctly. Ensure that this is the case first. Next step is adding an administrator e-mail address to the local_settings.py file. When an error occurs, this address will be used.

echo "ADMINS = (('Name', 'your.name@example.com'),)" >> /data/lynis-enterprise/interface/bin/lynis_interface/lynis_interface/local_settings.py

After changing the configuration, restart the Lynis Enterprise interface

Option 2: screen

To activate this, change the local_settings.py file and set the DEBUG value to True.

echo "DEBUG = True" >> /data/lynis-enterprise/interface/bin/lynis_interface/lynis_interface/local_settings.py

Note: this option is useful for quick debugging, but not suited for running in production. It disables several tests, including overriding security controls. So after discovering the internal error message, remove the DEBUG line and restart the interface.

To test if the debug function is working correctly, use the internal Debug test. Log in as a superuser to the interface, and go to Internals section.


Reinstall interface

If the interface is really not working as expected, one option is to do a fresh install. Delete everything in the /data directory, or simply rename the lynis-enterprise directory to another name.

# Step 1: Delete interface files

rm -rf /data/lynis-enterprise/interface/*

# Step 2: Remove downloads

rm /data/lynis-enterprise/downloads/*

# Step 3: Run updater

/data/lynis-enterprise/updater/lynis-updater --debug

1) Rename /data/lynis-enterprise to /data/lynis-enterprise2 2) Run updater (/data/lynis-enterprise2/updater) 3) Cancel when it asks for details, then copy configuration file: cp /data/lynis-enterprise2/updater/config /data/lynis-enterprise/updater/config 4) Run updater again, to perform all actions
/data/lynis-enterprise/interface/bin/lynis_interface/manage.py makemigrations lynis_interface
/data/lynis-enterprise/interface/bin/lynis_interface/manage.py makemigrations
/data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate

If it shows: Applying lynis_interface.0001_initial... FAKED
Then force the migration.

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate --fake lynis_interface zero

Clear migrations

When the database is not properly in sync (e.g. after reinstall the interface, or restoring the database), it might be needed to reapply some migration steps. The database model describes how the database tables and field should look like. We can apply these by running a migration.

# su - postgres
postgres@host:~> psql
postgres=# \c lynis_enterprise;
lynis_enterprise=# delete from django_migrations where app='lynis_interface';
lynis_enterprise=# \q

(most of the output is ommitted in this example)

Remove the migration files on disk:

rm /data/lynis-enterprise/interface/bin/lynis_interface/lynis_interface/migrations/[0-9]*

Create migrations:

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py makemigrations

Output should look like this:

# /data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate --l lynis_interface
lynis_interface
 [X] 0001_initial
Next step is ensure that
# /data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate lynis_interface zero
Operations to perform:
  Unapply all migrations: lynis_interface
Running migrations:
  Unapplying lynis_interface.0001_initial... OK

After the initial migration is unapplied, we can reapply it again:

# /data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate lynis_interface 0001
Operations to perform:
  Target specific migration: 0001_initial, from lynis_interface
Running migrations:
  Applying lynis_interface.0001_initial... OK

Synchronize the database again:

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py syncdb

Still issues?

In case the solution on this page did not help you solving the issue, please provide the following information:

  • Output of: ls -l /data/lynis-enterprise/downloads/
  • Output of: /data/lynis-enterprise/interface/bin/lynis_interface/manage.py inspectdb
  • Output of: /data/lynis-enterprise/interface/bin/lynis_interface/manage.py migrate --l lynis_interface

Advanced Settings


Configuration

For our solution we use the popular Django framework. This framework can be configured independently of our software. This is useful for defining settings like the time zone, email relay configuration, etc.

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py print_settings

Email settings

By default the sender address is webmaster@localhost. To change this, edit the local_settings.py file.

DEFAULT_FROM_EMAIL="my-alias@example.com"

The reset link for emails is configured by the installer. In case it needs to be changed, use the 'set_default_site' command, followed by the domain (or --fqdn to set it to the full hostname including domain name)

/data/lynis-enterprise/interface/bin/lynis_interface/manage.py set_default_site --domain example.com --name "my domain"