LATEST VERSION: 1.3 - CHANGELOG
ClamAV Add-on for PCF v1.3

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 is 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).

Prerequisites

To install ClamAV Add-on, you need the following things:

  • A PCF operator with admin rights. For more information, see Understanding Pivotal Cloud Foundry User Types.

  • Operations Manager (Ops Manager) v1.7 or later.

  • At least 1 GB of memory free on each VM before deploying ClamAV Add-on. ClamAV Add-on uses 610 MB of memory.

  • A local mirror to get ClamAV virus updates. For instructions on how to set up a local mirror, see Private Local Mirrors in the ClamAV documentation.

Create the ClamAV Manifest

The ClamAV manifest is a YML file that contains runtime config information for ClamAV Add-on. To create the ClamAV manifest for your deployment, follow the instructions below.

clamav.yml Template for Linux

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

      releases:
      - name: clamav
        version: x.x.x
      addons:
      - name: clamav
        jobs:
        - name: clamav
          release: clamav
          properties:
            clamav:
              database_mirror: 192.0.2.1
        include:
          stemcell:
          - os: ubuntu-trusty
    

clamav.yml Template for Windows

Create a file named clamav.yml using the following code as a template.
      releases:
      - name: clamav
        version: x.x.x
      addons:
      - name: clamav-windows
        jobs:
        - name: clamav-windows
          release: clamav
          properties:
            clamav:
              database_mirror: 192.0.2.1
        include:
          stemcell:
          - os: windows2012R2
    

General clamav.yml Template Configuration

  1. In the database_mirror field of the template, provide the hostname or IP address of a private ClamAV update mirror. Environments that cannot connect to the internet should use an update mirror. If you do not specify a value, ClamAV defaults to an S3-based mirror for updates. For compliance reasons, only use the S3-based mirror in non-production environments.
    For instructions on how to set up a local mirror, see Private Local Mirrors in the ClamAV documentation.
  2. (Optional) If you have to use a proxy server to connect to the internet, 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, indicated below in bold:
      releases:
      - name: clamav
          version: x.x.x
      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 the ClamAV Add-on software binary from the Pivotal Network.
  2. Copy the software binary to your Ops Manager 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 the Ops Manager VM.
    scp -i PATH-TO-PRIVATE-KEY clamav.yml ubuntu@YOUR-OPS-MANAGER-VM-IP:
  4. SSH into the Ops Manager VM.
    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 config as described in Update the Runtime Config for ClamAV.

Update the Runtime Config for ClamAV

  1. Update your runtime config to include configuration changes for the ClamAV Add-on for PCF.

    Note: If you have installed other BOSH add-ons, you must merge the ClamAV manifest clamav.yml into your existing runtime config manifest and use the merged manifest.

    bosh update runtime-config PATH/clamav.yml
  2. Verify the runtime config changes match what you specified in the ClamAV manifest. These changes appear differently on Linux and Windows hosts.
    bosh runtime-config
  3. Navigate to your Installation Dashboard in Ops Manager.
  4. 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.

Note: When you configure syslog forwarding, ensure there is 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 clamd and freshclamd, do the following:
    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 in /var/vcap 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.

  5. After clamdscan completes, a notification should appear in /var/log/messages. This scan can take up to an hour.

ClamAV Log Format

ClamAV log format is unstructured. If a virus is detected, the following text is sent to syslog:

Jul 11 17:36:35 k2lam76scmb clamd[3022]: SelfCheck: Database status OK
Jul 11 17:42:34 k2lam76scmb clamd[3022]: /bin/infected-file: Eicar-Test-Signature FOUND

A generalized format for the logline is:

clamd[PID]: INFECTED-FILE-PATH: VIRUS-NAME FOUND

Enable On-Access Scan

Note: On-Access Scan is not supported on Windows.

ClamAV offers immediate file scanning upon file modification. This feature may reduce the time it takes to detect and report malware.

Enable the feature with the on_access runtime config property:

  1. In the clamav.yml file, add the on_access property under the clamav property, set on_access to yes, shown in bold:
      releases:
      - name: clamav
          version: x.x.x
      
    addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: on_access: yes scheduled: yes ...
  2. Apply changes by updating your runtime config as described in Update the Runtime Config for ClamAV.

Disable Scheduled Scan

By default, ClamAV runs a virus scan every hour. The scan frequency is not configurable, but you can disable the scan completely if necessary.

To disable the scheduled scan, do the following:

  1. In the clamav.yml file, set the property scheduled to no.
  2. Apply changes by updating your runtime config as described in Update the Runtime Config for ClamAV.

Choose the Action on Infected Files

You can configure ClamAV to take action when infected files are found. By default, a notification is sent to the syslog when an infected file is found. However, you can specify other actions, as described in step 2 below.

  1. In the clamav.yml file, add the action property under the clamav property and, optionally, the action_destination property, shown in bold:
      releases:
      - name: clamav
          version: x.x.x

    addons: name: clamav jobs: - name: clamav release: clamav properties: clamav: action: ACTION action_destination: PATH ...

  2. Replace ACTION with one of the following values:
    • 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
    If you don’t supply an action, the function fails.
  3. Replace PATH with the directory location where you want the infected files moved or copied to. The system does not scan the moved-to or copied-to location. If the directory path is not valid, the function fails.

    Example configuration:

      releases:
      -name: clamav
          version: x.x.x

    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