The goal of this Ansible collection is to provide an easy ClamAV antivirus setup on macOS. It will configure clamd for scanning of files, automatically keep virus definitions up-to-date, can watch directories and scan changed/new files therein, and do a regular scan of recently modified files.

Background tasks are configured to have reduced CPU and IO priority. Furthermore, the regular scan of recently modified files will only be started if the Mac is connected to AC power to avoid draining your battery.

If infected files are found, they are moved to ~/quarantined and a notification is given.

The following software must be installed prior to using the Ansible roles from the collection:

• Python 3
• fswatch
• clamav (with clamd)

This software installation is not done by the collections's roles because there are different ways to install it and I do not want to force a particular way.

If you are a user of MacPorts, the requirements can be installed with these commands (feel free to use a different Python 3 version):

sudo port install python311 py311-pip fswatch clamav
sudo port select --set python3 python311

Pull requests with instructions for other installation methods are welcome.

If you mostly want to use the defaults, this is the fastest method to get this up and running.

# 1. Clone this repository
git clone https://github.com/jgosmann/macos_antivirus.git

# 2. Create a Python venv and install dependencies
cd macos_antivirus
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Create avwatch configuration
mkdir ~/.config
touch ~/.config/avwatch
# Add directories in which changed files should be scanned for viruses
# to ~/.config/avwatch (one per line).

# 4. Run Ansible quickstart playbook (you'll be asked for the sudo password)
ansible-playbook quickstart.yml

Note that by default it is assumed that prerequisites are installed in /opt/local (as MacPorts does). This path can be changed by setting the prefix variable. Furthermore, it is assumed that a _clamav user and group exist (MacPorts will create these).

Configuration can be adjusted by setting the respective variables on the command line with --extra-vars, e.g.:

ansible-playbook quickstart.yml --extra-vars prefix=/usr/local

I recommend to configure the "Script Editor" notifications as "alerts" in the system settings, such that notifications about infected files are not missed.

After setup of the Ansible roles, you will get notification that the following background items have been added:

• avwatch.sh
• clamd
• freshclam
• python3

When the first files are scanned, you may be asked to grant access to different folders (Desktop, Documents, Downloads, etc.) to python3.

Integrating the collection's roles into your own Ansible playbook gives you full flexibility. The steps are as follows:

1. Install collection:

   ansible-galaxy collection install jgosmann.macos_antivirus

2. Reference desired roles in your playbook and set variables according to desired configuration.
3. If using the avwatch roles (or the antivirus role including it), provide an ~/.config/avwatch file with a list of directories (one per line) in which changed files should be scanned for viruses.

Some variables are common to all roles:

Meta-role that includes avfullscan, avwatch, and freshclam.

Installs a regular scan of recently modified files. The scan will only start if your Mac is connected to AC power.

The "full" scan can also be invoked manually `` with the avfullscan.py <directory> [directory ...] command. Use `avfullscan.py --help` to see available options

• avscan

Installs the avscan.py script. It is a wrapper around clamdscan to submit files to clamd for scanning. Infected files will be moved to ~/quarantine and a GUI notification will be shown. See avscan.py --help for available options.

• clamd

Installs a launch agent to watch directories for changed files and scan them with avscan.py (clamd).

The directories to watch need to be configured with the file ~/.config/avwatch (one directory per line).

• avscan

Installs a launch daemon running clamd in the background.

Installs a launch daemon running freshclam (updating the virus signature database) on boot and each day thereafter.