Registry / auth-security / pyclamd

pyclamd

JSON →
library0.4.0pypypi✓ verified 87d ago

pyClamd provides a Pythonic interface to the ClamAV daemon (clamd), allowing applications to scan files and streams for viruses. Currently at version 0.4.0, it offers a robust way to integrate anti-malware scanning into Python projects, with releases occurring as needed for bug fixes or minor enhancements.

pip install pyclamd
INSTALL
IMPORT
SIG · PYCLAMD
P
pyclamd
auth-securitypythonv0.4.0
Install
2.4s avg
Import
10ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.0 · 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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.010s · 19.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.4s · import 0.011s · 20MB
17MB installed
● package 17MB
Code
Verified usage

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

ClamdAgnostic
from pyclamd import ClamdAgnostic
from pyclamd import Clamd
ClamdAgnostic is the recommended entry point as it attempts both Unix and network socket connections. 'Clamd' is not directly instantiable.
ClamdNetworkSocket
from pyclamd import ClamdNetworkSocket
ClamdUnixSocket
from pyclamd import ClamdUnixSocket

This quickstart demonstrates how to connect to the ClamAV daemon using `ClamdAgnostic`, ping it to verify connectivity, and then scan both a byte stream and a temporary file containing the EICAR test string. It includes basic error handling for common connection issues.

import pyclamd import os # Ensure Clamd daemon is running and accessible (e.g., via network or Unix socket) # For network socket: Host (default '127.0.0.1'), Port (default 3310) # For Unix socket: Socket path (default '/var/run/clamav/clamd.ctl') clamd_host = os.environ.get('CLAMD_HOST', '127.0.0.1') clamd_port = int(os.environ.get('CLAMD_PORT', '3310')) clamd_socket = os.environ.get('CLAMD_SOCKET', '/var/run/clamav/clamd.ctl') # Default for many Linux systems try: # Use ClamdAgnostic for automatic detection (Unix socket preferred if available) # This will try UnixSocket first, then NetworkSocket cd = pyclamd.ClamdAgnostic( unix_socket=clamd_socket, host=clamd_host, port=clamd_port ) # Ping the ClamAV daemon to check connectivity cd.ping() print("Successfully connected to ClamAV daemon.") # EICAR test string (standard antivirus test file) eicar_string = b"X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*" # Scan a stream of bytes result_stream = cd.scan_stream(eicar_string) print(f"Scan stream result for EICAR: {result_stream}") # Create a dummy file for file scan test_file_path = "eicar_test.txt" with open(test_file_path, "wb") as f: f.write(eicar_string) result_file = cd.scan_file(test_file_path) print(f"Scan file result for '{test_file_path}': {result_file}") if os.path.exists(test_file_path): os.remove(test_file_path) except pyclamd.ClamdError as e: print(f"ClamAV daemon error: {e}") print("Please ensure the ClamAV daemon (clamd) is running and accessible.") print(f" Network: {clamd_host}:{clamd_port}") print(f" Unix Socket: {clamd_socket}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaThe ClamAV daemon (clamd) must be running and accessible for `pyclamd` to function. `pyclamd` is just a client library and does not start the daemon.
fix
Ensure `clamd` is running as a service on your system. Verify its configuration (network address/port or Unix socket path) matches what `pyclamd` is configured to connect to.
affects: All
gotchaScan results are dictionaries mapping paths/streams to tuples like `('FOUND', 'Virus.Name')` or `('CLEAN', None)`. They are not simple booleans.
fix
Always parse the dictionary result. For example, `if result and result.get('path/to/file', ('CLEAN', ''))[0] == 'FOUND':` to check for an infection.
affects: All
gotcha`ClamdAgnostic` attempts to connect via Unix socket first, then falls back to a network socket. If both are configured but only one is desired, use `ClamdUnixSocket` or `ClamdNetworkSocket` explicitly.
fix
For explicit connection control, instantiate `pyclamd.ClamdUnixSocket(unix_socket='/path/to/clamd.sock')` or `pyclamd.ClamdNetworkSocket(host='localhost', port=3310)` directly.
affects: All
gotchaWhen using Unix sockets, the user running the Python script must have read and write permissions to the ClamAV daemon's socket file.
fix
Adjust the permissions of the `clamd.ctl` (or similar) socket file, or ensure the Python script is run by a user (e.g., `clamav` or `root`) with appropriate access.
affects: All
Errors
Common errors & fixes
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 111] Connection refused
The ClamAV daemon (clamd) is either not running or not listening on the specified network host and port.
fix
Start the `clamd` service. Verify the daemon's configuration (`clamd.conf`) for `LocalSocket` or `TCPSocket` settings, and ensure the `pyclamd` client uses matching `host` and `port`.
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 2] No such file or directory
The specified Unix socket path for `clamd` does not exist or is incorrect.
fix
Check the `clamd.conf` for the `LocalSocket` path. Ensure `pyclamd` is configured with the correct `unix_socket` argument (e.g., `ClamdUnixSocket(unix_socket='/var/run/clamav/clamd.ctl')`).
pyclamd.ClamdError: Could not connect to ClamAV daemon: [Errno 13] Permission denied
The user running the Python script does not have sufficient permissions to access the ClamAV daemon's Unix socket file.
fix
Grant read/write permissions for the socket file to the user running the script, or run the script as a user (e.g., `clamav`) that already has access. This often involves checking the permissions of `/var/run/clamav/clamd.ctl` and its parent directory.
Upgrade
Version history
0.4.0latest on PyPI · released Aug 27, 2017
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
18
Amazon
1
OpenAI (training)
1
Resources
pyclamd — pip install pyclamd · libregistry