Quahog Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Quahog provides a PHP interface for interacting with ClamAV’s clamd daemon, enabling virus scanning in applications. This is a strong fit for:
  • File upload systems (e.g., media libraries, document processing).
  • Email gateways (malware scanning before delivery).
  • Security-sensitive workflows (e.g., financial document validation).
• Layered Integration: Works as a service layer (e.g., middleware, background job, or API endpoint) rather than a core framework component, minimizing architectural disruption.
• Stateless Design: Since ClamAV is external, Quahog’s stateless nature aligns with microservices or decoupled architectures.

Integration Feasibility

• PHP/Composer Compatibility: Leverages PSR-4 autoloading and modern PHP (5.6+), with minimal dependencies (only phpseclib for SSH support).
• ClamAV Dependency: Requires a running clamd instance (Linux/Unix preferred). Dockerized ClamAV or cloud-based scanning (e.g., AWS ClamAV) can mitigate this.
• Async Potential: Can be integrated with Laravel’s queues (e.g., scan-file job) to avoid blocking I/O.
• Error Handling: Basic exceptions (QuahogException), but may need custom wrappers for Laravel’s Illuminate\Support\Facades\Log.

Technical Risk

Key Questions

1. ClamAV Infrastructure:
   • Is clamd available in production? If not, what’s the deployment plan (e.g., self-hosted, SaaS)?
   • What’s the SLA for ClamAV updates (e.g., virus definition refreshes)?
2. Performance:
   • What’s the expected throughput (scans/sec) for the target workload?
   • Are there file size limits (e.g., 50MB+ files) that could trigger timeouts?
3. Security:
   • How will scan results be logged/audited (e.g., GDPR compliance for flagged files)?
   • Is there a need to sanitize file paths to prevent ClamAV command injection?
4. Fallbacks:
   • What’s the backup plan if clamd is unavailable (e.g., queue dead-lettering)?
5. Maintenance:
   • Who will handle Quahog updates if the package stagnates?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Middleware: Scan files on upload (e.g., HandleUploadedFile middleware).
  • Jobs/Queues: Offload scans to scan-file job (e.g., ScanFileJob extends Job).
  • Artisan Commands: Periodic virus definition updates (clamav:update).
  • API Gateways: Pre-scan incoming requests (e.g., POST /upload).
• Compatibility:
  • PHP 8.x: No breaking changes expected (test with phpunit/phpunit@^9).
  • Laravel 9/10: Works with PSR-15 middleware or custom service providers.
  • Alternatives: If Quahog is too limited, consider:
    • rubix/ml (for ML-based scanning).
    • Direct exec() calls to clamd (less portable but flexible).

Migration Path

1. Proof of Concept (PoC):
   • Install Quahog in a sandbox (composer require xenolope/quahog).
   • Test basic scans:

     use Xenolope\Quahog\Client;
     $client = new Client('unix:///var/run/clamav/clamd.ctl');
     $result = $client->scanFile('/path/to/file.pdf');
     

   • Validate against known malware samples.
2. Laravel Integration:
   • Option A (Middleware):

     // app/Http/Middleware/ScanUpload.php
     public function handle(Request $request, Closure $next) {
         if ($request->hasFile('document')) {
             $client = app(Client::class);
             $scan = $client->scanFile($request->file('document')->path());
             if ($scan->isInfected()) { throw new \Exception('Malware detected!'); }
         }
         return $next($request);
     }
     

   • Option B (Job):

     // app/Jobs/ScanFileJob.php
     public function handle() {
         $client = new Client(config('clamav.socket'));
         $result = $client->scanFile($this->filePath);
         // Store result in DB or dispatch notification.
     }
     

3. Infrastructure Setup:
   • Deploy clamd (e.g., Docker: docker run --name clamav -p 3310:3310 -v clamav-db:/var/lib/clamav clamav/clamav).
   • Configure Laravel to point to the socket (e.g., .env):

     CLAMAV_SOCKET=unix:///var/run/clamav/clamd.ctl
     

Compatibility

• ClamAV Config:
  • Ensure clamd.conf allows local scans and has sufficient resources:

    MaxConnectionQueueLength 128
    MaxThreadStackSize 8MB
    ScanMail true
    ScanArchive true
    

• Firewall/Network:
  • If using TCP/IP, open port 3310 and whitelist Laravel servers.
• PHP Extensions:
  • No hard dependencies, but phpseclib (for SSH) may need openssl enabled.

Sequencing

1. Phase 1 (Core Integration):
   • Implement basic scanning in a non-critical endpoint (e.g., admin uploads).
   • Monitor clamd logs (/var/log/clamav/freshclam.log) for errors.
2. Phase 2 (Scaling):
   • Add queueing for high-volume scans (e.g., user uploads).
   • Implement caching for frequent scans of the same file (e.g., Redis).
3. Phase 3 (Resilience):
   • Add health checks for clamd (e.g., ping endpoint).
   • Implement fallback to a secondary scanner if Quahog fails.

Operational Impact

Maintenance

• Package Updates:
  • Monitor for Quahog forks or forks of this repo (e.g., this one).
  • Pin version in composer.json until maintenance is assured.
• ClamAV Updates:
  • Schedule weekly freshclam updates (e.g., Laravel scheduler):

    // app/Console/Commands/UpdateClamAV.php
    public function handle() {
        exec('freshclam --quiet');
    }
    

  • Test updates in staging for false positives.
• Logging:
  • Log scan results (e.g., scan_attempts table) for auditing:

    \Log::info('ClamAV scan', [
        'file' => $filePath,
        'infected' => $result->isInfected(),
        'virus' => $result->getVirusName(),
    ]);
    

Support

• Troubleshooting:
  • Common issues:
    • Connection refused: Check clamd is running (systemctl status clamav).
    • Timeouts: Increase clamd timeouts in config or chunk files.
    • Permission denied: Ensure PHP user (e.g., www-data) has access to clamd socket.
  • Debugging commands:

    clamd --version
    clamdscan --bell -r /path/to/file  # Manual test
    

• Support Matrix:

  Component	Support Owner	Escalation Path
  Quahog Package	TPM (fork if needed)	PHP community forums
  ClamAV	SysOps	ClamAV mailing list
  Laravel	Dev Team	Laravel Slack/GitHub Issues

Scaling

• Horizontal Scaling:
  • ClamAV: Load-balance clamd instances (e