Registry / auth-security / pyclamd

pyclamd

JSON →
library0.4.0pypypi✓ verified 89d 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.9–3.13
musl
3.9–3.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.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.010s · 19.2MB
glibc
py 3.10–3.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
29 hits · last 30 days
node
22
Amazon
1
OpenAI (training)
1
Resources
pyclamd — pip install pyclamd · libregistry