
================================================================================

  Lynis - README

================================================================================

  Author:                   Michael Boelen (michael@rootkit.nl)
  Description:              Security and system auditing tool
  Web site:                 http://www.rootkit.nl/projects/lynis.html
  Development start:        May 2007
  Support policy:           See section 'Support'
  Documentation:            See web site, README, FAQ and CHANGELOG file

================================================================================


[+] 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
   - Author:   Michael Boelen
   - Web site: http://www.rootkit.nl
   - Required permissions: root or equivalent
   - Other requirements: write access to /var/log and /tmp
   


[+] Installation
-------------------------------

  Lynis doesn't have to be installed, so it can be used directly from a
  (removable) disk. If you want the program to be installed, use one of the
  following methods:

  - Create a custom directory (ie. /usr/local/lynis) and unpack the tarball
    (tar xfvz lynis-version.tar.gz) into this directory.
  - Create a RPM package by using the lynis.spec file (see web site)
    run 'rpmbuild -ta lynis-version.tar.gz' (= build RPM package)
    run 'rpm -ivh <filename>' (= install RPM package)

  ========================
   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).
  Or better: split these files up and make sure that you always use the right ones
  (especially with automated scanning).



[+] Supported systems
-------------------------------

  Since the complexity of auditing different systems and platforms, Lynis is
  developed on BSD and Linux.
  
  This tool is tested or confirmed to work with:
  - Linux     : CentOS 5.x, Debian 4.x, RHEL 5.x, Ubuntu 7.xx, 8.xx
  - FreeBSD   : 6.x, 7.x
  - Mac OS X  : 10.4.x, 10.5.x
  - OpenBSD   : 4.x

  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 (lynis-lv.rootkit.nl).
  - Lynis needs write access to /var/log/lynis.log (unless logging is disabled,
    which disables debugging information as well and is not recommended).

  

[+] Using Lynis : Often used parameters
-------------------------------

  --auditor "Given name Surname"  : Assign a name to the audit (report)
  --checkall (-c)                 : Start the check
  --cronjob                       : Run Lynis as cronjob (includes -c -Q)
  --quick                         : Don't wait for user input, except on errors
  --quiet                         : Only show warnings (includes --quick)
  --version                       : Check program version (and quit)
  
  To view the man page: nroff -man ./lynis.8 or use the --manpage option

  ========================
   Tip:
  ========================
  To see all valid options, run Lynis without parameters (or with --help)



[+] Using Lynis : Cronjobs
-------------------------------

  When using the cronjob option (--cronjob), several options will be set
  automaticly (ie --checkall and --quick), to avoid long lines. Colors will
  be disabled, to avoid special chars showing up in the output.
  
  Though most options will be set correctly, you are still able to change
  other parameters where needed.
  
  ========================
   Tip:
  ========================
  If you only want to see the warnings while running Lynis as a cronjob, use
  the options --cronjob and --quiet together.
  



[+] Using Lynis : Profiles
-------------------------------

  [UNDER DEVELOPMENT]
  
  == You are adviced to avoid customizing your profiles currently since they
     will most likely change every few versions ==

  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.
  
  For example, 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. Even unconfigured options can result a warning, since the program
  simply checks just for ie. the presence of files, a configured option or a visible
  presence (process list, network socket). While auditing, keep in mind you (as
  auditor) will have to think about every step and related step(s) and configure the
  profile where needed.
  
  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
-------------------------------

  [UNDER DEVELOPMENT]

  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.



[+] Development
-------------------------------

  If you have input to improve Lynis, feel free to drop a note. However, for the
  time being no project group will be formed. 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 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.
  For more information fill in the contact form, regarding this.



[+] 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-2008, Michael Boelen - The Netherlands
 http://www.rootkit.nl
