Clamd Python Interface

Warnings

• gotcha Clamd daemon must be running and accessible. The `clamd` library is merely a client; it does not start or manage the ClamAV daemon. Connection attempts will fail with `clamd.ClamdError` or `FileNotFoundError` if the daemon isn't running or the socket/network address is incorrect.
  Fix: Ensure the ClamAV daemon (`clamd`) is installed, started, and configured to listen on the specified Unix socket path or network address. Check system logs (e.g., `journalctl -u clamd.service`) for daemon status.
• gotcha Unix socket permissions can cause 'Permission denied' errors. When using `ClamdUnixSocket`, the user running the Python script needs appropriate read/write permissions for the socket file (e.g., `/var/run/clamav/clamd.ctl`).
  Fix: Adjust file permissions for the clamd socket or ensure the Python process is running as a user or group that has access (e.g., `clamav` group). Alternatively, consider using `ClamdNetworkSocket` if network access is configured and appropriate for your security model.
• gotcha The `scan()` and `multiscan()` methods return a dictionary where keys are stream names/file paths and values are tuples `(status, virus_name)`.
  Fix: Always check the dictionary structure. For stream scans, the key is typically 'stream'. The value is `('OK', None)` for clean files, or `('FOUND', 'VIRUS_NAME')` if a virus is detected. Example: `result = cd.scan(b'...')`; then access `result['stream'][0]` for status and `result['stream'][1]` for virus name.
• gotcha The library primarily uses bytes for scanning inputs, not strings. While Python 3 handles string-to-bytes implicitly in some I/O operations, explicitly encoding input strings to bytes (`my_string.encode()`) is best practice.
  Fix: Always provide byte strings (e.g., `b'my data'`) when scanning data directly. If you have a Python string, convert it using `.encode('utf-8')` or another appropriate encoding.

Install

• pip install clamd Install stable version

Imports

• clamd

  import clamd

• ClamdUnixSocket

  import clamd
  cd = clamd.ClamdUnixSocket()

  The primary way to connect using a Unix domain socket.
• ClamdNetworkSocket

  import clamd
  cd = clamd.ClamdNetworkSocket(host='127.0.0.1', port=3310)

  Used to connect to clamd over TCP/IP.

Quickstart

This quickstart demonstrates how to connect to the ClamAV daemon using a Unix domain socket, send a test string for scanning, and interpret the results. It includes basic error handling for common connection issues.

import clamd
import os

# Assuming clamd is running and accessible via its default Unix socket
# You might need to adjust the socket path or use ClamdNetworkSocket
# if clamd is running on a network port.

def scan_string(text_to_scan: str):
    try:
        # Common Unix socket paths for clamd:
        # /var/run/clamav/clamd.ctl (Ubuntu/Debian)
        # /run/clamd.ctl (Arch Linux)
        # /var/lib/clamav/clamd.sock
        
        # Use environment variable for socket path or default
        clamd_socket_path = os.environ.get('CLAMD_UNIX_SOCKET', '/var/run/clamav/clamd.ctl')
        cd = clamd.ClamdUnixSocket(path=clamd_socket_path)
        
        # Test connection
        cd.ping()
        print(f"Successfully connected to clamd at {clamd_socket_path}")
        
        # Scan the string. The 'stream' key is arbitrary for stream scans.
        # 'EICAR_Test_File' is a safe test virus string.
        result = cd.scan(b'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*')
        
        print(f"Scan result for string: {result}")
        
        # Interpret result
        if 'stream' in result and result['stream'][0] == 'FOUND':
            print(f"!!! VIRUS DETECTED: {result['stream'][1]} !!!")
        elif 'stream' in result and result['stream'][0] == 'OK':
            print("No virus detected.")
        else:
            print("Unexpected scan result format.")
            
    except clamd.ClamdError as e:
        print(f"Error connecting to or communicating with clamd: {e}")
        print("Please ensure the clamd daemon is running and accessible at the specified socket path/address, and that your user has permissions.")
    except FileNotFoundError:
        print(f"Error: Clamd Unix socket not found at {clamd_socket_path}. Please check the path and clamd status.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    # Example usage with the EICAR test string
    scan_string("This is a test file for antivirus scanning.")