Skip to content

Latest commit

 

History

History
358 lines (292 loc) · 16.7 KB

README.md

File metadata and controls

358 lines (292 loc) · 16.7 KB
Raw

Puppet OS hardening

Puppet Forge Version Puppet Forge Downloads Puppet Forge Endorsement Build Status

Table of Contents

  1. Module Description - What the module does and why it is useful
  2. Setup - The basics of getting started with os_hardening
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.
  5. Development - Guide for contributing to the module
  6. Testing - Quality gates for your changes in the code
  7. Get in touch
  8. Contributors + Kudos
  9. License and Author

Module Description

This Puppet module provides secure configuration of your base OS with hardening and is part of the DevSec Hardening Framework.

Setup

Setup Requirements

Beginning with os_hardening

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,
}

Usage

IMPORTANT for Puppet Enterprise

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

Parameters

  • system_environment = 'default' define the context in which the system runs. Some options don't work for docker/lxc
  • pe_environment = false set this to true if you are using Puppet Enterprise IMPORTANT - see above
  • extra_user_paths = [] add additional paths to the user's PATH 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 otherwise
  • sys_uid_min = undef and sys_gid_min = undef override the default setting for login.defs
  • password_max_age = 60 maximum password age
  • password_min_age = 7 minimum password age (before allowing any other password change)
  • password_warn_age = 7 Days warning before password change is due
  • login_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 passes
  • chfn_restrict = '' which fields may be changed by regular users using chfn
  • allow_login_without_home = false true if to allow users without home to login
  • allow_change_user = false if a user may use su to change his login
  • ignore_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 contents
  • ignore_max_files_warnings = false true if you do not want puppet to log max_files and performance warnings on the recursion of folders with > 1000 files eg /bin /usr/bin
  • recurselimit = 5 directory depth for recursive permission check
  • passwdqc_enabled = true true if you want to use strong password checking in PAM using passwdqc
  • auth_retries = 5 the maximum number of authentication attempts, before the account is locked for some time
  • auth_lockout_time = 600 time in seconds that needs to pass, if the account was locked due to too many failed authentication attempts
  • passwdqc_options = 'min=disabled,disabled,16,12,8' set to any option line (as a string) that you want to pass to passwdqc
  • manage_pam_unix = false true if you want pam_unix managed by this module
  • enable_pw_history = true true if you want pam_unix to remember password history to prevent reuse of passwords (requires manage_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 compliance
  • root_ttys = ['console','tty1','tty2','tty3','tty4','tty5','tty6'] registered TTYs for root
  • whitelist = [] 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 a blacklist. 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 your whitelist.
  • dry_run_on_unknown = false like remove_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 configure remove_from_unknown for SUID/SGID bits, so that you can see the files that are being changed and make adjustments to your whitelist and blacklist.
  • enable_module_loading = true true if you want to allowed to change kernel modules once the system is running (eg modprobe, rmmod)
  • load_modules = [] load this modules via initramfs if enable_module_loading is false
  • disable_filesystems = ['cramfs','freevxfs','jffs2','hfs','hfsplus','squashfs','udf'] array of filesystems (kernel modules) that should be disabled
  • cpu_vendor = 'intel' only required if enable_module_loading = false: set the CPU vendor for modules to load
  • icmp_ratelimit = '100' default value '100', allow overwriting, needs String
  • desktop_enabled = false true if this is a desktop system, ie Xorg, KDE/GNOME/Unity/etc
  • enable_ipv4_forwarding = false true if this system requires packet forwarding in IPv4 (eg Router), false otherwise
  • manage_ipv6 = true true to harden ipv6 setup, false to ignore ipv6 completely
  • enable_ipv6 = false false to disable ipv6 on this system, true to enable
  • enable_ipv6_forwarding = false true if this system requires packet forwarding in IPv6 (eg Router), false otherwise
  • arp_restricted = true true if you want the behavior of announcing and replying to ARP to be restricted, false otherwise
  • arp_ignore_samenet = false true will drop packets that are not from the same subnet (arp_ignore = 2), false will only check the target ip (arp_ignore = 1)
  • enable_sysrq = false true to enable the magic sysrq key, false otherwise
  • enable_core_dump = false false to prevent the creation of core dumps, true otherwise
  • enable_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 otherwise
  • rpfilter_loose = false (only if enable_rpfilter is true) loose mode (rp_filter = 2) if true, strict mode otherwise
  • enable_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 system
  • wanted_packages = [] packages that should be added to the system
  • disabled_services = [] services that should not be enabled
  • enable_grub_hardening = false set to true to enable some grub hardening rules
  • grub_user = 'root' the grub username that needs to be provided when changing config on the grub prompt
  • grub_password_hash = '' a password hash created with grub-mkpasswd-pbkdf2 that is associated with the grub_user
  • boot_without_password = true setup Grub so it only requires a password when changing an entry, not when booting an existing entry
  • system_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
  • ignore_files_in_folder_to_restrict = [] array to ignore files to hardened in dirs under the folder_to_restrict array
  • manage_cron_permissions = false set to true to manage cron file permissions (og-rwx)
  • enable_sysctl_config = true set to false to disable sysctl configuration
  • manage_system_users = true set to false to disable managing of system users (empty password and setting nologin shell)
  • shadow_group = undef override the group ownership of /etc/shadow
  • shadow_mode = undef override the file permissions of /etc/shadow

Hiera usage

It's also possible to set the parameters in Hiera like this:

os_hardening::password_max_age:  90
os_hardening::password_min_age:  0
os_hardening::password_warn_age: 14
os_hardening::unwanted_packages: ['telnet']
os_hardening::ignore_users:      ['git','githook','ansible','apache','puppetboard']

Note about wanted/unwanted packages and disabled services

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.

Limitations

This module has been tested and should run on most Linux distributions. For an extensive list of supported operating systems, see metadata.json

Development

If you want to contribute, please follow our contribution guide.

Testing

Local Testing

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.

PDK Tests

# Syntax & Lint tests
pdk validate

# Unit Tests
pdk test unit

Integration Tests (Docker)

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

Integration Tests (DigitalOcean)

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 DigitalOcean
  • DIGITALOCEAN_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 Github Actions 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 DigitalOcean
  • CI_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 of CI_SSH_KEY, see this for more information

CI testing of PRs & forks

Your patches will automatically get tested via Github Actions. The test summary is visible on Github in your PR, details can be found in the linked tests.

Get in touch

You can reach us on several ways:

Contributors + Kudos

For the original port of chef-os-hardening to puppet:

Thank you all!!

License and Author

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.