This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Please read our Contribution Guide.

Table of Contents

• Description
• This is a SIMP module
• Using clamav
  • Enabling updates
    • freshclam
    • rsync
      • Client side
      • Server side
• Limitations
• Development
  • Acceptance tests

Description

This module provides an interface to the installation and management of ClamAV.

See REFERENCE.md for API documentation.

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Please read our Contribution Guide

This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:

• When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.

• If used independently, all SIMP-managed security subsystems are disabled by default and must be explicitly opted into by administrators. Please review the simp-simp_options module for details. These catalysts are used by SIMP to allow users to override default behavior of classes that are included by default.

NOTE:

• SIMP's clamav class was removed from the default class list in all SIMP scenarios in SIMP 6.5. Users of SIMP 6.5 or later must manually add clamav to the class list or include it via a manifest.

• Because of the SIMP 6.5 clamav change, SIMP's simp_options::clamav catalyst has been deprecated and will be removed in a future release. In the interim, the catalyst is still used as a wrapper for this module for backwards compatibility. Therefore, you must have simp_options::clamav undefined or set to true for this module to do anything.

• Setting the SIMP catalyst, simp_options::clamav, to false does not uninstall ClamAV, it simply prevents this module from doing anything. See the Using clamav section below for how to remove ClamAV from the system.

Using clamav

This module can be used to add or remove clamav from a system.

To manage ClamAV with this module:

include clamav

By default this module will install ClamAV and set up a cron to do a scan.

To remove ClamAV from the system set the following via Hiera:

---
clamav::enable: false

Enabling updates

Generally, your updates will be provided by an upstream package repository, such as EPEL. However, there are two optional methods for enabling DAT file updates.

freshclam

To enable the freshclam update system, set the following via Hiera:

---
clamav::enable_freshclam: true

NOTE: No additional configuration of freshclam is currently supported. To update the configuration file, you will need to create your own File resource.

rsync

You may choose to enable rsync downloads of the DAT files from a SIMP rsync server. The module defaults are already set to support this configuration.

Client side

Add the following to Hiera to enable rsync downloads:

---
clamav::enable_data_rsync: true

Server side

To add DAT files to the server, you should place them in /var/simp/environments/<environment>/rsync/Global/clamav and ensure that the permissions are set to 409:409.

Limitations

SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux and compatible distributions, such as CentOS. Please see the metadata.json file for the most up-to-date list of supported operating systems, Puppet versions, and module dependencies.

Development

Please see the SIMP Contribution Guidelines.

Acceptance tests

This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:

bundle install
bundle exec rake beaker:suites

Please refer to the SIMP Beaker Helpers documentation for more information.

Some environment variables may be useful:

BEAKER_debug=true
BEAKER_provision=no
BEAKER_destroy=no
BEAKER_use_fixtures_dir_for_modules=yes

• BEAKER_debug: show the commands being run on the STU and their output.
• BEAKER_destroy=no: prevent the machine destruction after the tests finish so you can inspect the state.
• BEAKER_provision=no: prevent the machine from being recreated. This can save a lot of time while you're writing the tests.
• BEAKER_use_fixtures_dir_for_modules=yes: cause all module dependencies to be loaded from the spec/fixtures/modules directory, based on the contents of .fixtures.yml. The contents of this directory are usually populated by bundle exec rake spec_prep. This can be used to run acceptance tests to run on isolated networks.

Reference

Table of Contents

Classes

• clamav: Installs the command line ClamAV anti-virus scanner.
• clamav::set_schedule: Allows you to set a schedule for ClamAV to run a check on your system via cron

Classes

clamav

If you wish to schedule a virus scan, you will need to create a cron job that is appropriate, or drop a script into the cron.* directory that is appropriate.

Parameters

The following parameters are available in the clamav class:

• enable
• manage_group_and_user
• clamav_user
• clamav_group
• package_name
• enable_freshclam
• enable_data_rsync
• schedule_scan
• rsync_source
• rsync_server
• rsync_timeout
• package_ensure

enable

Data type: Boolean

Disables/Enables clamav

• Toggles freshclam/clamscan cronjobs, selbooleans, rsync, and package installation.

Default value: true

manage_group_and_user

Data type: Boolean

Optionally manage the clamav user and group.

Default value: true

clamav_user

Data type: String

The clamav user.

Default value: 'clam'

clamav_group

Data type: String

The clamav group.

Default value: 'clam'

package_name

Data type: String

The name of clamav rpm package.

Default value: 'clamav'

enable_freshclam

Data type: Boolean

If true, will enable the freshclam cron job.

Default value: false

enable_data_rsync

Data type: Boolean

If true, will use the SIMP rsync subsystem to pull down clamav DAT files.

• NOTE: $enable_freshclam takes precedence

Default value: false

schedule_scan

Data type: Boolean

If true, will enable the scheduled system scan.

• The default targets are extremely conservative so you will probably want to adjust this.

Default value: true

rsync_source

Data type: String

The rsync server source path for the clamav definitions.

• Setting this parameter to an empty String will disable the clamav rsync.

Default value: "clamav_${facts['environment']}/"

rsync_server

Data type: Simplib::Host

The hostname or IP of the rsync server providing clamav definitions.

Default value: simplib::lookup('simp_options::rsync::server', { 'default_value' => '127.0.0.1' })

rsync_timeout

Data type: Integer

The amount of time, in seconds, to wait for rsync to respond.

Default value: simplib::lookup('simp_options::rsync::timeout', { 'default_value' => 2 })

package_ensure

Data type: String[1]

The value used for package ensure attribute.

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })

clamav::set_schedule

• All 'yes/no' variables have been translated to 'true/false' for consistency.

• Defaults to weekly.

• See also

  • clamscan(1)
    • for any undefined variables.

Parameters

The following parameters are available in the clamav::set_schedule class:

• enable
• minute
• hour
• monthday
• month
• weekday
• nice_level
• scan_targets
• official_db_only
• logfile
• recursive
• cross_fs
• summary
• infected_only
• bytecode
• bytecode_unsigned
• bytecode_timeout
• detect_pua
• exclude_pua
• include_pua
• max_files
• max_filesize
• max_scansize
• max_recursion
• max_dir_recursion
• logrotate

enable

Data type: Boolean

Enables/Disables the clamscan cronjob. Defaults to true.

Default value: simplib::lookup('clamav::enable', { 'default_value' => true})

minute

Data type: Simplib::Cron::Minute

Default value: '32'

hour

Data type: Simplib::Cron::Hour

Default value: '5'

monthday

Data type: Simplib::Cron::MonthDay

Default value: '*'

month

Data type: Simplib::Cron::Month

Default value: '*'

weekday

Data type: Simplib::Cron::Weekday

Default value: '0'

nice_level

Data type: Integer

The system 'nice' level at which to run the virus scan.

Default value: 19

scan_targets

Data type: Array[Stdlib::Absolutepath]

An array of directories upon which to perform this scan.

Default value: ['/tmp','/var/tmp','/dev/shm']

official_db_only

Data type: Boolean

Default value: true

logfile

Data type: Stdlib::Absolutepath

Default value: '/var/log/clamscan.log'

recursive

Data type: Boolean

Default value: true

cross_fs

Data type: Boolean

Default value: true

summary

Data type: Boolean

Default value: false

infected_only

Data type: Boolean

Default value: true

bytecode

Data type: Boolean

Default value: true

bytecode_unsigned

Data type: Boolean

Default value: false

bytecode_timeout

Data type: Integer

Default value: 60000

detect_pua

Data type: Boolean

Default value: false

exclude_pua

Data type: Array[String]

Default value: []

include_pua

Data type: Array[String]

Default value: []

max_files

Data type: Integer

Default value: 10000

max_filesize

Data type: Integer

The maximum archive size to scan, in megabytes.

Default value: 25

max_scansize

Data type: Integer

The maximum scanned file size to scan, in megabytes.

Default value: 100

max_recursion

Data type: Integer

Default value: 16

max_dir_recursion

Data type: Integer

Default value: 15

logrotate

Data type: Boolean

Enable the use of the SIMP logrotate capabilities.

Default value: simplib::lookup('simp_options::logrotate', { 'default_value' => false })

• Mon Oct 23 2023 Steven Pritchard steve@sicura.us - 6.9.0

• [puppetsync] Add EL9 support

• Wed Oct 11 2023 Steven Pritchard steve@sicura.us - 6.8.0

• [puppetsync] Updates for Puppet 8
  • These updates may include the following:
    • Update Gemfile
    • Add support for Puppet 8
    • Drop support for Puppet 6
    • Update module dependencies

• Wed Aug 23 2023 Steven Pritchard steve@sicura.us - 6.7.0

• Add AlmaLinux 8 support

• Mon Jun 12 2023 Chris Tessmer chris.tessmer@onyxpoint.com - 6.6.0

• Add RockyLinux 8 support

• Tue Jun 15 2021 Chris Tessmer chris.tessmer@onyxpoint.com - 6.5.0

• Removed support for Puppet 5
• Ensured support for Puppet 7 in requirements and stdlib

• Thu Dec 17 2020 Chris Tessmer chris.tessmer@onyxpoint.com - 6.4.1

• Removed EL6 support

• Tue Oct 29 2019 Jeanne Greulich jeannegreulich@onyxpoint.com - 6.4.0-0

• Updated the README to clarify what simp_options::clamav actually does and to note that clamav was removed from the SIMP's default class list in SIMP 6.5.
• Set the default for clamav::set_schedule::enable to lookup clamav::enable, so that class will remove the clamav schedule if clamav is disabled.

• Tue Sep 24 2019 Trevor Vaughan tvaughan@onyxpoint.com - 6.4.0-0

• Disable rsync pulls by default
• Update README.md
• Add REFERENCE.md

• Thu Jun 06 2019 Steven Pritchard steven.pritchard@onyxpoint.com - 6.3.0-0

• Add v2 compliance_markup data

• Mon Mar 25 2019 Joseph Sharkey shark.bruhaha@gmail.com - 6.2.0-0

• Standardized cron datatypes to use the Simplib::Cron::### types. This allows more flexibility in cron scheduling.

• Thu Mar 07 2019 Liz Nemsick lnemsick.simp@gmail.com - 6.1.1-0

• Update the upper bound of stdlib to < 6.0.0
• Update URLs in the README.md

• Wed Oct 03 2018 Jeanne Greulich jeanne.greulich@onyxpoint.com - 6.1.0-0

• Add package_ensure parameter to use simp_options package_ensure value for managing the installation of packages. If simp_options is not being used it will default to install ( previously set to latest) If not using simp_options the value can be changed by setting clamav::package_ensure to latest in hiera.
• update Gemfile to use puppet ~> 5.0
• update .rubyversion to 2.4.4

• Fri Sep 07 2018 Liz Nemsick lnemsick.simp@gmail.com - 6.1.0-0

• Drop Hiera 4 support

• Mon Mar 19 2018 Trevor Vaughan tvaughan@onxypoint.com - 6.1.0-0

• Add support for Puppet 5 and OEL

• Mon Sep 11 2017 Chris Tessmer chris.tessmeri@onyxpoint.com - 6.0.2-0

• Permit clamav to disable both freshclam AND rsync updates

• Wed Apr 19 2017 Nick Markowski nmarkowski@keywcorp.com - 6.0.1-0

• Updated logrotate to use new lastaction API
• Update puppet dependency and remove OBE pe dependency in metadata.json

• Thu Dec 13 2016 Nick Markowski nmarkowski@keywcorp.com - 6.0.0-0

• Updated global catalysts
• Strong typed

• Thu Dec 01 2016 Trevor Vaughan tvaughan@onyxpoint.com - 6.0.0-0

• Updated to use the environment-aware rsync in SIMP 6

• Fri Nov 18 2016 Chris Tessmer chris.tessmer@onyxpoint.com - 5.0.0-0

• Updated to compliance_markup version 2

• Tue Aug 02 2016 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.1-0

• Update to new naming scheme

• Wed Feb 10 2016 Ralph Wright ralph.wright@onypoint.com - 4.1.0-8

• Added compliance function support

• Tue Nov 10 2015 Chris Tessmer chris.tessmer@onypoint.com - 4.1.0-7

• migration to simplib and simpcat (lib/ only)

• Fri Aug 28 2015 Nick Markowski nmarkowski@keywcorp.com - 4.1.0-6

• Added enable_clamav parameter to toggle: package install, freshclam/clamscan cron jobs, clamav rsync, antivirus selboolean.
• The clamav user, group now manageable and package name mutable.
• Added validation to init.pp

• Fri Feb 27 2015 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-5

• Updated to use the new 'simp' environment.
• Changed calls directly to /etc/init.d/rsyslog to '/sbin/service rsyslog' so that both RHEL6 and RHEL7 are properly supported.

• Fri Jan 16 2015 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-4

• Changed puppet-server requirement to puppet

• Mon Jun 23 2014 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-3

• Fixed SELinux check for when selinux_current_mode is not found.

• Mon May 05 2014 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-2

• Removed management of /var/lib/clamav to avoid SELinux labeling fights with Rsync. This directory is managed by the RPM.
• Fixed a template bug in the directory specifications.
• Changed scan_directory to scan_targets in set_schedule
• Set up the schedule by default via a boolean in the clamav class
• Removed /home from the default scan list and added /dev/shm

• Wed Apr 16 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-2

• Added spec tests.
• Fixed incorrect validation in manifests.

• Fri Apr 04 2014 Nick Markowski nmarkowski@keywcorp.com - 4.1.0-2

• Selinux booleans now set if mode != disabled

• Thu Feb 13 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-1

• Converted all string booleans into native booleans.

• Tue Dec 10 2013 Kendall Moore kmoore@keywcorp.com - 4.1.0-0

• Changed singleton clamav::set_schedule define to paramterized class and updated code documentation for compatibility with puppet 3 and hiera.

• Tue Dec 10 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-11

• Removed the 'clamav' user and group since they are no longer used by the default clamav packages.
• Updated the configuration to allow for the removal of the freshclam cron job by default. If enabled, freshclam will be used instead of rsync.

• Sat Dec 07 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-10

• Modified the selinux boolean from clamscan_can_scan_system to antivirus_can_scan_system which is present in the newest versions of ClamAV

• Thu Oct 03 2013 Kendall Moore kmoore@keywcorp.com - 4.0.0-9

• Updated all erb templates to properly scope variables.

• Mon Jun 10 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-8

• Added support for more clamscan options in the clamav::set_schedule define and reduced the default noise level in the output so that user's cron logs aren't spammed.

• Thu May 02 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-7

• Set the clamscan_can_scan_system boolean for ClamAV

• Mon Feb 25 2013 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-6

• Added a call to $::rsync_timeout to the rsync call since it is now required.
• Created a Cucumber test to ensure the clamav module installs correctly.
• We may have finally gotten rsync and the clamav module in sync!
  • The clamav user/group is 410
  • The clam user/group is 409

• Fri Nov 16 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-5

• Changed the group of /var/lib/clamav to 'clam' and the mode to 664 for freshclam support.

• Fri Sep 21 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-4

• Reversed the order of removal for clamav.i686 and clamav_lib.i686 since they did not match the proper depencency order in the RPMs.

• Wed Apr 11 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-3

• Moved mit-tests to /usr/share/simp...
• Updated pp files to better meet Puppet's recommended style guide.

• Fri Mar 02 2012 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-2

• Improved test stubs.

• Mon Dec 26 2011 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-1

• Updated the spec file to not require a separate file list.

• Mon Nov 07 2011 Trevor Vaughan tvaughan@onyxpoint.com - 4.0.0-0

• Fixed call to rsyslog restart for RHEL6.

• Thu Jan 27 2011 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-1

• Updated to use rsync native type

• Tue Jan 11 2011 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-0

• Refactored for SIMP-2.0.0-alpha release

• Wed Oct 27 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1.0-2

• Added set_schedule define

• Tue Oct 26 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1.0-1

• Converting all spec files to check for directories prior to copy.

• Wed May 19 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1.0-0

• Code and Doc refactor

• Fri Nov 06 2009 Trevor Vaughan tvaughan@onyxpoint.com - 0.1-0

• Initial Release