Tissue Clamav Adapter Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The tissue-clamav-adapter package is a Tissue adapter, meaning it integrates with the Tissue library—a PHP file system abstraction layer—to enable ClamAV-based virus scanning for uploaded files. This is a niche but critical feature for applications handling user uploads (e.g., CMS, SaaS platforms, file-sharing services).
• Modularity: Since Tissue is designed for file system operations (e.g., FileSystem, File, Directory), this adapter extends its functionality without requiring a full rewrite. Ideal for monolithic or modular PHP apps already using Tissue.
• Alternatives: If the app doesn’t use Tissue, the adapter adds indirect complexity (requires Tissue dependency). Native PHP-ClamAV bindings (e.g., php-clamav) may be simpler for non-Tissue apps.

Integration Feasibility

• ClamAV Dependency: Requires a running ClamAV daemon (Linux/Unix) or Windows service. Dockerized ClamAV is an option but adds operational overhead.
• PHP Compatibility: Works with PHP 8.0+ (Tissue’s requirement). Older PHP versions may need polyfills or forks.
• Async Considerations: ClamAV scans are blocking by default. For high-throughput apps, consider:
  • Offloading scans to a queue worker (e.g., Laravel Queues, Symfony Messenger).
  • Using ClamAV’s streaming mode (if supported by the adapter).
• File Size Limits: ClamAV has memory constraints for large files. The adapter may need tuning (e.g., chunked scanning).

Technical Risk

Key Questions

1. Does the application already use Tissue?
   • If no, assess whether the indirect dependency (Tissue + ClamAV) justifies the abstraction.
2. What’s the expected file volume/size?
   • For high-volume uploads, async processing or a dedicated microservice may be needed.
3. Are there existing virus-scanning solutions?
   • Compare with alternatives like:
     • AWS S3 + Amazon VirusTotal (serverless).
     • Local PHP libraries (e.g., php-clamav).
4. Compliance Requirements
   • Does the app need audit logs for scans? The adapter may require custom logging.
5. CI/CD Impact
   • ClamAV updates may require dependency updates in CI pipelines.

Integration Approach

Stack Fit

• Best For:
  • PHP apps using Tissue (e.g., Laravel, Symfony, custom PHP).
  • Systems where file integrity is critical (e.g., media libraries, document management).
• Less Ideal For:
  • Non-PHP stacks (Node.js, Python, etc.).
  • Apps not using Tissue (unless Tissue’s abstraction is valuable for other reasons).
  • Serverless environments (ClamAV daemon is hard to spin up ephemerally).

Migration Path

1. Add Dependencies:

   composer require cleentfaar/tissue-clamav-adapter tissue/ti
   

2. Configure ClamAV:
   • Ensure the ClamAV daemon (clamd) is running and accessible.
   • Configure Tissue to use the adapter:

     use Cleentfaar\TissueClamavAdapter\ClamavAdapter;
     
     $filesystem = new \Tissue\FileSystem(
         new ClamavAdapter('/path/to/clamav/socket')
     );
     

3. Integrate with Upload Logic:
   • Scan files post-upload (e.g., in a FileUploaded event listener).
   • Example:

     $file = $filesystem->file('uploaded/file.pdf');
     if (!$file->scan()) {
         throw new \RuntimeException('Virus detected!');
     }
     

4. Error Handling:
   • Wrap scans in try-catch for ClamavException or socket timeouts.
   • Implement a fallback (e.g., skip scan if ClamAV is down).

Compatibility

• ClamAV Version: Test with the latest stable ClamAV (e.g., 1.0.x). Older versions may lack features.
• Tissue Version: The adapter may require Tissue 3.x+. Check composer.json for constraints.
• PHP Extensions: No additional PHP extensions are needed beyond Tissue’s requirements.

Sequencing

1. Phase 1: Proof of Concept
   • Test with a small set of files (known clean + known malicious).
   • Measure scan time and resource usage.
2. Phase 2: Integration
   • Plug into the upload pipeline (e.g., Laravel’s HandleUploadedFile).
   • Add logging for scan results.
3. Phase 3: Optimization
   • Implement caching for frequent scans of the same files.
   • Explore parallel scanning for batch uploads.
4. Phase 4: Monitoring
   • Track false positives/negatives and ClamAV daemon uptime.

Operational Impact

Maintenance

• ClamAV Updates:
  • Signature updates (daily/weekly) may require restarts or config changes.
  • Automate updates via cron or a config management tool (e.g., Ansible).
• Adapter Updates:
  • Monitor for Tissue/adapter breaking changes (MIT license allows forks if needed).
• Dependency Bloat:
  • Adding Tissue + ClamAV increases composer.lock size and build complexity.

Support

• Debugging Challenges:
  • ClamAV errors (e.g., socket timeout) may require server-level troubleshooting.
  • Logs should include:
    • Scan timestamps.
    • File hashes (for auditability).
    • ClamAV response codes.
• Vendor Lock-in:
  • Low risk (MIT license), but ClamAV-specific quirks may require custom workarounds.

Scaling

• Horizontal Scaling:
  • ClamAV daemon is not horizontally scalable by default. Solutions:
    • Shared socket: Multiple app instances connect to a single clamd.
    • Load-balanced scans: Route scans to multiple ClamAV instances (requires custom logic).
• Vertical Scaling:
  • Increase ClamAV’s MaxConnectionQueue for high concurrency.
  • Allocate more RAM for large file scans.
• Performance Trade-offs:
  • Scan speed vs. accuracy: Aggressive ClamAV settings may miss malware.
  • Caching: Store scan results in Redis to avoid rescanning identical files.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document ClamAV setup (daemon config, socket permissions).
  • Provide scan result codes (e.g., CLEAN, VIRUS, ERROR).
• Testing Strategy:
  • Unit tests: Mock ClamAV responses.
  • Integration tests: Scan real files in a staging environment.
  • Chaos testing: Simulate ClamAV failures (e.g., kill clamd during tests).
• Training:
  • Educate ops teams on ClamAV tuning (e.g., FreshClam updates).
  • Train devs on handling scan failures gracefully.