Registry / auth-security / clamd
library1.0.2pypypi✓ verified 89d ago

Clamd is a Python interface library for communicating with the ClamAV daemon (`clamd`). It allows Python applications to send files or streams to `clamd` for virus scanning. The current stable version is 1.0.2, with a low release cadence indicating maturity and stability, focusing on Python 3.7+.

pip install clamd
INSTALL
IMPORT
SIG · CLAMD
C
clamd
auth-securitypythonv1.0.2
Install
1.5s avg
Import
309ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.340s · 18.4MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.279s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")
Debug
Known issues
gotchaClamd 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.
affects: All versions
gotchaUnix 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.
affects: All versions
gotchaThe `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.
affects: All versions
gotchaThe 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.
affects: All versions
Errors
Common errors & fixes
clamd.ClamdError: Error 111 connecting 127.0.0.1:3310. Connection refused.
The `clamd` daemon is not running, is configured to listen on a different address/port, or a firewall is blocking the connection.
fix
Ensure the `clamd` service is running (`sudo systemctl start clamav-daemon` or `sudo service clamav-daemon start`). Verify `clamd.conf` for correct `LocalSocket` or `TCPAddr`/`TCPSocket` settings and check firewall rules to allow connections to the daemon's port (default 3310) or socket.
ModuleNotFoundError: No module named 'clamd'
The `clamd` Python library has not been installed in your current Python environment.
fix
Install the `clamd` library using pip: `pip install clamd`
{'file_path': ('ERROR', "Can't open file or directory")}
The `clamd` daemon, running as a specific user (e.g., 'clamav'), lacks the necessary read permissions for the file or directory attempting to be scanned, or a security module like AppArmor/SELinux is preventing access.
fix
Grant read permissions to the user under which `clamd` runs for the target files/directories. If AppArmor or SELinux is active, review and adjust their profiles to allow `clamd` access to the relevant paths.
clamd.ClamdError: BufferTooLongError: Buffer length (X) is greater than StreamMaxLength (Y) in /etc/clamav/clamd.conf
The data stream sent to `clamd` for scanning exceeds the maximum size allowed by the `StreamMaxLength` directive in the `clamd` configuration file.
fix
Edit the `clamd.conf` file (typically `/etc/clamav/clamd.conf`) to increase the `StreamMaxLength` value to accommodate larger streams, then restart the `clamd` service. Alternatively, ensure the data stream being sent is within the configured limit.
Upgrade
Version history
1.0.2latest on PyPI · released Aug 21, 2014
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
28
OpenAI (training)
1
Resources
clamd — pip install clamd · libregistry