Ansible Role clamav¶
This role installs and configures ClamAV, „an open-source antivirus engine for detecting trojans, viruses, malware & other malicious threats.“ It also configures freshclam to regularly update the official ClamAV signatures (12 times a day). It runs on Red Hat-family systems as well as Debian and Ubuntu. This role exposes options for enabling on-access scanning and / or periodic full-scans and configures mail notifications for found viruses.
When using on-access scanning, one might need to increase the inotify/max_user_watches. Have a look at the official documentation. This can be done using the linuxfabrik.lfops.kernel_settings role.
Available since LFOps 3.0.0.
How the Role Behaves¶
On a fresh host the role downloads the signature database once (a synchronous freshclam run) before starting clamd, because clamd refuses to start without a database. The freshclam service then keeps the database updated. The database directory /var/lib/clamav is given to the freshclam database owner so freshclam can write to it.
On every run (and on demand via --tags clamav:test) the role runs a self-test that confirms ClamAV detects the EICAR test signature. It feeds the EICAR string to the standalone clamscan over stdin, so the test triggers neither the VirusEvent mail notification nor an on-access detection, and writes nothing to disk.
Dependent Roles¶
Any LFOps playbook that installs this role runs these for you. Optional ones can be disabled via the playbook’s skip variables.
On RHEL-compatible systems, the
antivirus_can_scan_systemandantivirus_use_jitSELinux booleans must be enabled (role: linuxfabrik.lfops.selinux) so ClamAV can scan the whole system.Optional: Fangfrisch must be installed to download unofficial ClamAV signatures (role: linuxfabrik.lfops.fangfrisch).
Optional Role Variables¶
clamav__clamd_service_enabled
Enables or disables the clamd background service, analogous to
systemctl enable/disable. The clamd service is required for on-access scanning and full-scans.Type: Bool.
Default:
true
clamav__clamdscan_on_calendar
When the full-scan should be run. Have a look at systemd.time(7) for the format.
Type: String.
Default:
'*-*-* 21:{{ 59 | random(seed=inventory_hostname) }}'
clamav__clamdscan_paths
Which paths should be scanned during the full-scan.
Type: String.
Default:
'{{ clamav__scan_on_access_include_paths }}'
clamav__clamdscan_timer_enabled
Enables or disables the clamdscan timer for the periodic full-scan, analogous to
systemctl enable/disable.Type: Bool.
Default:
false
clamav__clamonacc_service_enabled
Enables or disables the on-access scanning service, analogous to
systemctl enable/disable.Type: Bool.
Default:
false
clamav__freshclam_private_mirror
„This option allows you to easily point freshclam to private mirrors“ (see
man freshclam.conf).Type: List.
Default:
[]
clamav__freshclam_service_enabled
Enables or disables the freshclam service, analogous to
systemctl enable/disable. Freshclam is responsible for updating the official ClamAV signatures.Type: Bool.
Default:
true
clamav__mail_from
Username with access to the mail server. Required to send mail notifications for found viruses.
Type: String.
Default:
'{{ mailto_root__from }}'
clamav__mail_recipients
List recipient addresses to which the mail notifications should be sent.
Type: String.
Default:
'{{ mailto_root__to }}'
clamav__mail_subject_prefix
This will set a prefix that will be showed in front of the hostname. Can be used to separate servers by environment or customer.
Type: String.
Default:
''
clamav__scan_alert_broken_executables
„With this option clamav will try to detect broken executables (both PE and ELF) and alert on them with the Broken.Executable heuristic signature.“
Type: Bool.
Default:
true
clamav__scan_detect_pua
On-access & full-scans: „Detect Possibly Unwanted Applications.“
Type: Bool.
Default:
true
clamav__scan_max_directory_recursion
„Maximum depth directories are scanned at.“
Type: Number.
Default:
20
clamav__scan_max_file_size
Full-scan: „Files larger than this limit won’t be scanned.“
Type: String.
Default:
'450M'
clamav__scan_max_recursion
Specifies how deeply nested archives should be scanned recursively.
Type: Number.
Default:
30
clamav__scan_max_scan_size
„Sets the maximum amount of data to be scanned for each input file.“
Type: String.
Default:
'450M'
clamav__scan_on_access_exclude_paths
On-access: „Set the exclude paths. All subdirectories are also excluded.“
Type: List.
Default:
[]
clamav__scan_on_access_include_paths
On-access: „Set the include paths (all files inside them will be scanned).“
Type: List.
Default:
[]
clamav__scan_on_access_max_file_size
On-access: „Don’t scan files larger than this.“
Type: String.
Default:
'500M'
clamav__scan_on_access_prevention
On-access: Prevents access to the file if a virus is found. Note that this also blocks the full-scan from accessing the files.
Type: Bool.
Default:
false
clamav__whitelist_files
Whitelist specific files. Use
sigtool --md5 my-false-positive-fileto generate the entry. Have a look at the official documentation for details.Type: List.
Default:
[]
clamav__whitelist_signatures
Whitelist specific signatures. Note that it is possible that one needs to whitelist multiple signatures for the same finding, as it can come from different databases with different names. Have a look at the example below and the official documentation for details.
Type: List.
Default:
[]
Example:
# optional
clamav__clamd_service_enabled: true
clamav__clamdscan_on_calendar: '*-*-* 21:{{ 59 | random(seed=inventory_hostname) }}'
clamav__clamdscan_paths: '{{ clamav__scan_on_access_include_paths }}'
clamav__clamdscan_timer_enabled: false
clamav__clamonacc_service_enabled: false
clamav__freshclam_private_mirror: []
clamav__freshclam_service_enabled: true
clamav__mail_from: '{{ mailto_root__from }}'
clamav__mail_recipients: '{{ mailto_root__to }}'
clamav__mail_subject_prefix: '000-my-customer-'
clamav__scan_alert_broken_executables: true
clamav__scan_detect_pua: true
clamav__scan_max_directory_recursion: 20
clamav__scan_max_file_size: '450M'
clamav__scan_max_recursion: 30
clamav__scan_max_scan_size: '450M'
clamav__scan_on_access_exclude_paths:
- '/root/private-files'
clamav__scan_on_access_include_paths:
- '/root'
clamav__scan_on_access_max_file_size: '500M'
clamav__scan_on_access_prevention: false
clamav__whitelist_files:
- '44d88612fea8a8f36de82e1278abb02f:68:eicar.com'
clamav__whitelist_signatures:
- 'Eicar-Signature'
- 'Eicar-Test-Signature'
- 'Win.Test.EICAR_HDB-1'
- 'Win.Test.EICAR_HSB-1'