ClamAV Add-on for PCF

Page last updated:

This topic describes how to add ClamAV to your Pivotal Cloud Foundry (PCF) deployment.

About ClamAV Add-on for PCF

This add-on may be necessary for regulatory purposes if your compliance auditor requires antivirus protection within the PCF environment. For example, auditors sometimes expect that antivirus protection be present in an environment that must comply with standards such as Payment Card Industry Data Security Standard (PCI DSS) or Health Insurance Portability and Accountability Act (HIPAA).

ClamAV can be configured to scan on-access, on schedule, or both.

Prerequisites

Note: ClamAV Add-on for PCF does not work on Windows.

To complete the ClamAV Add-on installation:

  • You must be a PCF operator with admin rights. See the Understanding Pivotal Cloud Foundry User Types topic for more information.

  • You must have Pivotal Operations Manager (Ops Manager) v1.7 or later.

  • ClamAV Add-on uses 610 MB of memory. Ensure you have at least 1 GB of memory free on each VM before deploying ClamAV Add-on.

Create the ClamAV Manifest

The ClamAV manifest is a YML file that contains runtime configuration information for ClamAV Add-on. Follow the steps below to create the ClamAV manifest for your deployment:

  1. Create a file named clamav.yml, using the following code as a template.

    releases:
    - name: clamav 
      version: 1.0.0
    addons:
    - name: clamav
      jobs:
      - name: clamav
        release: clamav
      properties:
        clamav:
          database_mirror:
            192.0.2.1

  2. (Optional) Provide the hostname or IP address of a private ClamAV update mirror. Environments that cannot connect to the Internet normally use an update mirror. If you do not specify a value, ClamAV defaults to db.local.clamav.net for updates. Mirror servers behind this address might be unreachable which may lead to a failed ClamAV Add-on deployment. See the Private Local Mirrors topic of the ClamAV documentation for instructions on how to set up a local mirror.

  3. (Optional) If you want to download the virus definitions database through a proxy server, do the following:

    • Add the proxy_host and proxy_port properties.
    • If the proxy server needs authentication, add proxy_user and proxy_password properties.

    Replace the example text shown in bold:

    releases:
    - name: clamav
      version: 1.1.1
    addons:
    name: clamav
      jobs:
        - name: clamav
          release: clamav
      properties:
        clamav:
          on_access: no
          scheduled: yes
          proxy_host: proxy.localdomain
          proxy_port: 3128
          proxy_user: clamav
          proxy_password: secret
    ...
    

Download and Deploy ClamAV Add-on

  1. Download ClamAV Add-on software binary from the Pivotal Network to your local machine.

  2. Copy the software binary to your Ops Manager virtual machine (VM).

    $ scp -i PATH/TO/PRIVATE/KEY clamav-release.tar.gz ubuntu@YOUR-OPS-MANAGER-VM-IP:

  3. Copy the ClamAV manifest, clamav.yml file, to your Ops Manager instance.

    $ scp -i PATH/TO/PRIVATE/KEY clamav.yml ubuntu@YOUR-OPS-MANAGER-VM-IP:

  4. SSH into Ops Manager.

    $ ssh -i PATH-TO-PRIVATE-KEY ubuntu@YOUR-OPS-MANAGER-VM-IP

  5. On the Ops Manager VM, navigate to the software binary location.

    $ cd PATH-TO-BINARY

  6. On the Ops Manager VM, target your BOSH director instance.

    $ bosh target YOUR-OPS-MANAGER-DIRECTOR-IP
    Target set to 'Ops Manager'
    Your username: director
    Enter password: ******************
    Logged in as 'director'
    

  7. Upload your release.

    $ bosh upload release PATH-TO-BINARY/BINARY-NAME.tar

  8. From the command line, confirm that the upload of the ClamAV software binary completed. You should see the ClamAV release.

    $ bosh releases

  9. Update your runtime configuration to include ClamAV.

    Note: If you installed other BOSH add-ons, you must merge the ClamAV manifest into your existing add-on manifest. Append the contents of clamav.yml to your existing add-on YML file.

    $ bosh update runtime-config PATH/YOUR-ADD-ON-YML.yml
  10. Verify your runtime configuration changes match what you specified in the ClamAV manifest.

    $ bosh runtime-config
    Acting as user 'admin' on 'micro'
    releases:
    - name: clamav
      version: 1.0.0
    
    addons: name: clamav jobs: - name: clamav release: clamav ...

  11. Navigate to your Installation Dashboard in Ops Manager.

  12. Click Apply Changes.

Configure Forwarding for ClamAV Alerts

The ClamAV BOSH release writes all alerts to the syslogs of the VMs in your deployment. You can use syslog forwarding to forward the alerts to a syslog aggregator.

  • Using the Elastic Runtime tile: Follow the steps to Configure System Logging in the Elastic Runtime tile. The syslog aggregator that you specify receives all alerts generated on Elastic Runtime VMs, including the ClamAV alerts.
  • Using the BOSH syslog release: You can use the syslog BOSH release to forward system logs. See the syslog-release for instructions.

Note: When you configure syslog forwarding, ensure enough disk space for the logs. Make sure that log rotation is frequent enough. If in doubt, rotate the logs hourly or when they reach a certain size. Pivotal recommends forwarding logs to a remote syslog aggregation system.

Verify Your ClamAV Add-on Installation

  1. BOSH ssh into one of the VMs in your deployment.

  2. Run monit summary. Look for the following processes in the output:

    The Monit daemon 5.2.4 uptime: 3d 0h 56m
    Process 'clamd'                     running
    Process 'freshclam'                 running
  3. If monit summary does not list freshclamd and clamd, perform the following steps:

    1. Try to start the ClamAV processes by running the following commands:
      $ monit start clamd
      $ monit start freshclam
      
    2. Run monit summary again. If you do not see the processes mentioned above, check /var/vcap/sys/log/clamav logs for errors.
  4. If monit summary does list freshclamd and clamd, create a file on the VM with the following contents:

    X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*
    

    This is a virus signature used to test anti-virus software. It may take up to an hour for ClamAV to locate the signature. Check your syslog aggregator for the notification. If the notification does not appear, check /var/log/messages on the VM. If virus notifications appear in the VM syslog but not in the aggregator, verify your syslog forwarding settings.

Enable On-Access Scan

ClamAV offers immediate file scanning upon file modification. This feature might reduce the time it takes to detect and report malware. Enable the feature through the on_access runtime config property, as follows.

  1. In the clamav.yml file, add the on_access property under the clamav property:

    releases:
    - name: clamav
      version: 1.1.1
    
    addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: on_access: yes scheduled: yes ...

  2. Apply this configuration change by following the instructions from step 9, Update your…, in the Download and Deploy ClamAV Add-on section above.

Note: The scheduled property is responsible for running ClamAV from cron and is set to yes by default. Setting it to no and applying the changes disables cron runs.

Isolate Infected Files

You can configure ClamAV to remove or isolate files identified as infected.

Allowed values for the clamav.action configuration property are:

  • notify — The default, only send a notification to syslog
  • remove — Delete the infected file from the filesystem
  • move — Move the infected file to the directory location specified by action_destination
  • copy — Copy the infected file to the directory location specified by action_destination

Example configuration:

  releases:
  - name: clamav
      version: 1.1.7
  
addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: action: move action_destination: /var/vcap/data/clamav/found ...

Create a pull request or raise an issue on the source for this page in GitHub