- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with os_hardening
- Usage - Configuration options and additional functionality
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
- Testing - Quality gates for your changes in the code
- Get in touch
- Contributors + Kudos
- License and Author
This Puppet module provides secure configuration of your base OS with hardening and is part of the DevSec Hardening Framework.
- Puppet OpenSource or Enterprise
- Module stdlib
- Module sysctl
After adding this module, you can use the class:
class { 'os_hardening': }
All parameters are contained within the main os_hardening
class, so you just have to pass them like this:
class { 'os_hardening':
enable_ipv4_forwarding => true,
}
If you are using this module in a PE environment, you have to set pe_environment = true
Otherwise puppet will drop an error (duplicate resource)!
system_environment = 'default'
define the context in which the system runs. Some options don't work fordocker
/lxc
pe_environment = false
set this to true if you are using Puppet Enterprise IMPORTANT - see aboveextra_user_paths = []
add additional paths to the user'sPATH
variable (default is empty).umask = undef
umask used for the creation of new home directories by useradd / newusers (e.g. '027')maildir = undef
path for maildir (e.g. '/var/mail')usergroups = true
true if you want separate groups for each user, false otherwisesys_uid_min = undef
andsys_gid_min = undef
override the default setting forlogin.defs
password_max_age = 60
maximum password agepassword_min_age = 7
minimum password age (before allowing any other password change)password_warn_age = 7
Days warning before password change is duelogin_retries = 5
the maximum number of login retries if password is bad (normally overridden by PAM / auth_retries)login_timeout = 60
authentication timeout in seconds, so login will exit if this time passeschfn_restrict = ''
which fields may be changed by regular users using chfnallow_login_without_home = false
true if to allow users without home to loginallow_change_user = false
if a user may usesu
to change his loginignore_users = []
array of system user accounts that should not be hardened (password disabled and shell set to/usr/sbin/nologin
)folders_to_restrict = ['/usr/local/games','/usr/local/sbin','/usr/local/bin','/usr/bin','/usr/sbin','/sbin','/bin']
folders to make sure of that group and world do not have write access to it or any of the contentsrecurselimit = 5
directory depth for recursive permission checkpasswdqc_enabled = true
true if you want to use strong password checking in PAM using passwdqcauth_retries = 5
the maximum number of authentication attempts, before the account is locked for some timeauth_lockout_time = 600
time in seconds that needs to pass, if the account was locked due to too many failed authentication attemptspasswdqc_options = 'min=disabled,disabled,16,12,8'
set to any option line (as a string) that you want to pass to passwdqcmanage_pam_unix = false
true if you want pam_unix managed by this moduleenable_pw_history = true
true if you want pam_unix to remember password history to prevent reuse of passwords (requiresmanage_pam_unix = true
)pw_remember_last = 5
the number of last passwords (e.g. 5 will prevent user to reuse any of her last 5 passwords)only_root_may_su = false
true when only root and member of the group wheel may use su, required to be true for CIS Benchmark complianceroot_ttys = ['console','tty1','tty2','tty3','tty4','tty5','tty6']
registered TTYs for rootwhitelist = []
all files which should keep their SUID/SGID bits if set (will be combined with pre-defined whiteliste of files)blacklist = []
all files which should have their SUID/SGID bits removed if set (will be combined with pre-defined blacklist of files)remove_from_unknown = false
true
if you want to remove SUID/SGID bits from any file, that is not explicitly configured in ablacklist
. This will make every Puppet run search through the mounted filesystems looking for SUID/SGID bits that are not configured in the default and user blacklist. If it finds an SUID/SGID bit, it will be removed, unless this file is in yourwhitelist
.dry_run_on_unknown = false
likeremove_from_unknown
above, only that SUID/SGID bits aren't removed. It will still search the filesystems to look for SUID/SGID bits but it will only print them in your log. This option is only ever recommended, when you first configureremove_from_unknown
for SUID/SGID bits, so that you can see the files that are being changed and make adjustments to yourwhitelist
andblacklist
.enable_module_loading = true
true if you want to allowed to change kernel modules once the system is running (egmodprobe
,rmmod
)load_modules = []
load this modules via initramfs if enable_module_loading is falsedisable_filesystems = ['cramfs','freevxfs','jffs2','hfs','hfsplus','squashfs','udf']
array of filesystems (kernel modules) that should be disabledcpu_vendor = 'intel'
only required ifenable_module_loading = false
: set the CPU vendor for modules to loadicmp_ratelimit = '100'
default value '100', allow overwriting, needs Stringdesktop_enabled = false
true if this is a desktop system, ie Xorg, KDE/GNOME/Unity/etcenable_ipv4_forwarding = false
true if this system requires packet forwarding in IPv4 (eg Router), false otherwisemanage_ipv6 = true
true to harden ipv6 setup, false to ignore ipv6 completelyenable_ipv6 = false
false to disable ipv6 on this system, true to enableenable_ipv6_forwarding = false
true if this system requires packet forwarding in IPv6 (eg Router), false otherwisearp_restricted = true
true if you want the behavior of announcing and replying to ARP to be restricted, false otherwiseenable_sysrq = false
true to enable the magic sysrq key, false otherwiseenable_core_dump = false
false to prevent the creation of core dumps, true otherwiseenable_stack_protection = true
for Address Space Layout Randomization. ASLR can help defeat certain types of buffer overflow attacks. ASLR can locate the base, libraries, heap, and stack at random positions in a process's address space, which makes it difficult for an attacking program to predict the memory address of the next instruction.enable_rpfilter = true
true to enable reverse path filtering (discard bogus packets), false otherwiserpfilter_loose = false
(only ifenable_rpfilter
is true) loose mode (rp_filter = 2) if true, strict mode otherwiseenable_log_martians = true
true to enable logging on suspicious / unroutable network packets, false otherwise WARNING - this might generate huge log files!unwanted_packages = []
packages that should be removed from the systemwanted_packages = []
packages that should be added to the systemdisabled_services = []
services that should not be enabledenable_grub_hardening = false
set to true to enable some grub hardening rulesgrub_user = 'root'
the grub username that needs to be provided when changing config on the grub promptgrub_password_hash = ''
a password hash created withgrub-mkpasswd-pbkdf2
that is associated with the grub_userboot_without_password = true
setup Grub so it only requires a password when changing an entry, not when booting an existing entrysystem_umask = undef
if this variable is set setup the umask for all user in the system (e.g. '027') *manage_home_permissions = false
set to true to manage local users file and directory permissions (g-w,o-rwx) *ignore_home_users = []
array for users that is not to be restricted by manage_home_permissions *manage_log_permissions = false
set to true to manage log file permissions (g-wx,o-rwx) *restrict_log_dir = ['/var/log/']
set main log dir *ignore_restrict_log_dir = []
array to exclude log dirs under the main log dir *manage_cron_permissions = false
set to true to manage cron file permissions (og-rwx)
As the CIS Distribution Independent Linux Benchmark is a good starting point regarding hardening of systems, it was deemed appropriate to implement an easy way to deal with one-offs for which one doesn't want to write an entire module.
For instance, to increase CIS DIL compliance on a Debian system, one should set the following:
wanted_packages => ['ntp'],
unwanted_packages => ['telnet'],
disabled_services => ['rsync'],
The default settings of NTP are actually pretty good for most situations, so it is not immediately necessary to implement a module. However, if you do use a module to control these services, that is of course preferred.
This module has been tested and should run on most Linux distributions. For an extensive list of supported operating systems, see metadata.json
If you want to contribute, please follow our contribution guide.
You should have Ruby interpreter installed on your system. It might be a good idea to use rvm for that purpose. Besides that you have to install the Puppet Development Kit
PDK and Docker Community Edition, as the integration tests run in Docker containers.
For all our integration tests we use test-kitchen
. If you are not familiar with test-kitchen
please have a look at their guide.
# Syntax & Lint tests
pdk validate
# Unit Tests
pdk test unit
Per default the integration tests will run in docker containers - unfortunately not all tests can run in container environments (e.g. sysctl settings).
# Install dependencies
gem install bundler
bundle install
# list all test instances
bundle exec kitchen list
# fast test on one machine
bundle exec kitchen test ubuntu-16-04-puppet5
# test on all machines
bundle exec kitchen test
For complete integration tests with DigitalOcean you have to get an account there and setup some environment variables:
KITCHEN_LOCAL_YAML=kitchen.do.yml
DIGITALOCEAN_ACCESS_TOKEN
- access token for DigitalOceanDIGITALOCEAN_SSH_KEY_IDS
- ID in DigitalOcean of your ssh key, see this for more information
The ssh key has to be named ~/.ssh/do_ci
and added to your profile at DigitalOcean.
After this you're ready to run the tests as described at Integration Tests (Docker).
If you want to run the full integration tests with Travis CI in your fork, you will have to add these environment variables in the settings of your fork:
KITCHEN_LOCAL_YAML=kitchen.do.yml
DIGITALOCEAN_ACCESS_TOKEN
- access token for DigitalOceanCI_SSH_KEY
- private part of a ssh key, available on DigitalOcean for your instances, in base64 encoded form (e.g.cat id_rsa | base64 -w0 ; echo
)DIGITALOCEAN_SSH_KEY_IDS
- ID in DigitalOcean ofCI_SSH_KEY
, see this for more information
Your patches will automatically get tested via Travis CI. The test summary is visible on Github in your PR, details can be found on the corresponding Travis puppet-os-hardening page.
You can reach us on several ways:
- @DevSecIO on Twitter
- Mailing list for questions and general discussion: devsec@freelists.org [subsribe]
- Mailing list with release announcements (no posts are possible here): devsec-announce@freelists.org [subscribe]
- Dominik Richter arlimus
- Edmund Haselwanter ehaselwanter
- Christoph Hartmann chris-rock
- Thomas Dütsch a-tom
- Patrick Meier atomic111
- Artem Sidorenko artem-sidorenko
- Kurt Huwig kurthuwig
- Matthew Haughton 3flex
- Reik Keutterling spielkind
- Daniel Dreier danieldreier
- Timo Goebel timogoebel
- Tristan Helmich fadenb
- Michael Geiger mcgege
For the original port of chef-os-hardening
to puppet:
- Artem Sidorenko artem-sidorenko
- Frank Kloeker eumel8
Thank you all!!
- Author:: Dominik Richter dominik.richter@gmail.com
- Author:: Deutsche Telekom AG
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.