ClamAV Anti-Virus
Integrates with the open-source ClamAV anti-virus scanner to scan uploaded files for viruses.
clamav
Install
composer require 'drupal/clamav:^2.1'
composer require 'drupal/clamav:^2.0'
Overview
The ClamAV module provides integration between Drupal and the ClamAV open-source anti-virus scanner. When users upload files to the site, the module automatically scans them for viruses and malware before allowing them to be saved. Infected files are blocked during the validation routine, preventing them from being stored on the system.
The module supports three scanning modes: direct executable, TCP/IP daemon, and Unix socket daemon. Daemon modes offer significantly better performance (approximately 10,000 times faster than executable mode) because virus definitions remain loaded in memory rather than being reloaded for each scan.
Site administrators can configure which file stream wrappers are scanned, control behavior when ClamAV is unavailable, and enable verbose logging. The module also provides a hook that allows other modules to conditionally include or exclude specific files from scanning based on custom criteria.
Features
- Automatic virus scanning of all uploaded files during the file validation process
- Three scanning modes: Executable (direct clamscan), Daemon TCP/IP, and Daemon Unix Socket for flexible deployment options
- High performance daemon modes that are approximately 10,000 times faster than executable mode
- Configurable behavior when ClamAV is unavailable: block unchecked files or allow them to be uploaded
- Stream wrapper scheme filtering to control which file systems are scanned (local vs remote)
- Extensible hook system allowing other modules to control which files are scanned
- Drush command for batch scanning all existing managed files in the system
- Comprehensive logging with verbose and debug modes for troubleshooting
- System status report integration showing ClamAV version and connection status
- Seamless integration with Drupal's file validation event system
Use Cases
Protecting user uploads on a community site
On websites where users can upload files (such as forums, social networks, or document sharing platforms), enable ClamAV to automatically scan all uploaded files before they are saved. This prevents malicious users from uploading infected files that could harm other users who download them.
Securing private document management
For intranets or document management systems handling sensitive files, configure ClamAV with Unix socket daemon mode for optimal performance. Set outage behavior to 'Block unchecked files' to ensure no unscanned files can be uploaded even if ClamAV is temporarily unavailable.
E-commerce file attachments
On e-commerce sites where customers upload files for custom orders (print shops, design services), use ClamAV to scan all attachments. Enable verbose logging to maintain an audit trail of all scanned files.
Retroactive scanning of existing files
After installing ClamAV on an existing site, use the 'drush clamav:scan-files' command to batch scan all previously uploaded files and identify any infected content that may already exist in the system.
Excluding specific file types from scanning
Implement hook_clamav_file_is_scannable() to skip scanning of trusted file types (like images from verified sources) or files uploaded by administrators, while maintaining full scanning for user-uploaded content.
Multi-server deployment with centralized scanning
In a web cluster environment, configure all web servers to use Daemon TCP/IP mode pointing to a central ClamAV server, ensuring consistent scanning across all nodes without requiring ClamAV installation on each web server.
Tips
- Use Daemon mode (Unix socket or TCP/IP) instead of Executable mode for significantly better performance - daemon modes are approximately 10,000 times faster.
- The Unix socket daemon mode is slightly faster than TCP/IP mode because it avoids network overhead, but TCP/IP mode is more flexible for distributed deployments.
- Enable verbose logging temporarily when troubleshooting to see logs for all scanned files, not just infected ones.
- Keep ClamAV virus definitions updated regularly using freshclam to ensure detection of the latest threats.
- Consider the security implications of 'Allow unchecked files' setting - only use this if you have other security measures in place to handle potential ClamAV outages.
- Use the Drush command periodically to scan existing files, especially after updating virus definitions.
Technical Details
Admin Pages 1
/admin/config/media/clamav
Configure ClamAV anti-virus integration settings including scanning mode, connection parameters, outage behavior, and logging options.
Permissions 1
Hooks 1
hook_clamav_file_is_scannable
Allows modules to control whether a specific file should be scanned by ClamAV. Modules can force scanning, prevent scanning, or not affect the decision.
Drush Commands 1
drush clamav:scan-files
Scans all existing managed permanent files in the system for viruses using ClamAV. Processes files in batches to avoid timeout issues.
Troubleshooting 5
Verify the ClamAV daemon is running and accessible. For TCP/IP mode, check that the hostname and port are correct. For Unix socket mode, ensure the socket file exists and has proper permissions. For executable mode, verify the path to clamscan is correct.
This typically indicates ClamAV is unavailable and 'Block unchecked files' is enabled. Check the Drupal logs for connection errors and verify ClamAV service status.
Switch from Executable mode to Daemon mode (TCP/IP or Unix socket). Daemon modes are approximately 10,000 times faster because virus definitions remain loaded in memory.
Ensure the web server user has permission to access the ClamAV socket file (for Unix socket mode) or execute the clamscan binary (for executable mode). Check file permissions and SELinux/AppArmor policies.
Increase PHP max_execution_time and post_max_size. Consider using daemon mode for faster scanning. For very large files, implement hook_clamav_file_is_scannable() to skip scanning based on file size.
Security Notes 5
- Always keep ClamAV virus definitions updated using freshclam or clamav-freshclam service to protect against the latest threats.
- Consider setting outage_action to 'Block unchecked files' in production environments to prevent potentially infected files from being uploaded when ClamAV is unavailable.
- The module only scans files during upload - it does not continuously monitor files after they are saved. Run periodic batch scans using the Drush command.
- Files stored in remote stream wrappers (like S3 or CDN storage) are not scanned by default. Enable specific remote schemes only if necessary and if they support the scanning mechanism.
- Virus scanning adds latency to file uploads. For high-traffic sites, ensure your ClamAV infrastructure can handle the load by using daemon mode and potentially scaling horizontally.