Tissue Clamav Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require cleentfaar/tissue-clamav-adapter
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Cleentfaar\TissueClamavAdapter\TissueClamavAdapterServiceProvider"
   

2. Basic Configuration Ensure ClamAV is installed and running on your system. Configure the adapter in config/tissue-clamav-adapter.php:

   'clamav' => [
       'socket' => '/var/run/clamav/clamav.socket', // Default socket path
       'timeout' => 30, // Timeout in seconds
   ],
   

3. First Use Case: Scanning a File Integrate with Laravel Filesystem or Tissue:

   use Cleentfaar\TissueClamavAdapter\ClamavAdapter;
   use Tissue\File;
   
   $adapter = app(ClamavAdapter::class);
   $file = new File(storage_path('app/example.pdf'));
   
   $result = $adapter->scan($file);
   if ($result->isClean()) {
       // File is safe
   } else {
       // File contains malware
       foreach ($result->getErrors() as $error) {
           log::error("ClamAV scan error: " . $error);
       }
   }
   

Implementation Patterns

Workflow: File Upload Scanning

1. Pre-Processing Use Laravel’s HandleUploadedFile or a custom request handler to process uploads before storage:

   use Illuminate\Http\Request;
   use Cleentfaar\TissueClamavAdapter\ClamavAdapter;
   
   public function store(Request $request)
   {
       $request->validate(['file' => 'required|file']);
       $file = $request->file('file');
   
       $adapter = app(ClamavAdapter::class);
       $scanResult = $adapter->scan($file);
   
       if (!$scanResult->isClean()) {
           throw new \Exception("Malware detected!");
       }
   
       $path = $file->store('uploads');
       // Proceed with storage...
   }
   

2. Batch Scanning For bulk operations (e.g., migrating old files), use Laravel Queues:

   use Illuminate\Support\Facades\Bus;
   
   Bus::batch([
       new ScanFileJob($file1),
       new ScanFileJob($file2),
   ])->then(function (Batch $batch) {
       // Handle results
   })->dispatch();
   

3. Integration with Tissue Use Tissue’s File class for consistent handling:

   use Tissue\File;
   use Tissue\Storage\Filesystem;
   
   $storage = new Filesystem(storage_path('app'));
   $file = $storage->get('example.pdf');
   $adapter->scan($file);
   

Tips for Daily Use

• Cache Results: Store scan results in Redis/Memcached to avoid re-scanning identical files.
• Logging: Log scan results for auditing:

  \Log::info('ClamAV scan', ['file' => $file->path(), 'clean' => $result->isClean()]);
  

• Fallback Mechanism: Combine with another scanner (e.g., spatie/laravel-virus-scanner) if ClamAV fails.

Gotchas and Tips

Common Pitfalls

1. ClamAV Not Running

   • Symptom: Connection refused or timeouts.
   • Fix: Ensure ClamAV daemon (clamd) is running:

     sudo systemctl status clamav-daemon
     

   • Debug: Test ClamAV manually:

     clamscan --bell -r /path/to/files
     

2. Socket vs. TCP

   • The adapter defaults to a Unix socket. If using TCP, update the config:

     'clamav' => [
         'host' => '127.0.0.1',
         'port' => 3310,
     ],
     

3. Large Files

   • ClamAV may time out on large files (>100MB). Adjust the timeout in config or chunk the file:

     $adapter->setChunkSize(1024 * 1024); // 1MB chunks
     

4. False Positives

   • ClamAV may flag legitimate files. Whitelist known-safe files or directories in config/tissue-clamav-adapter.php:

     'exclusions' => [
         '*.jpg',
         '*.png',
         'vendor/**',
     ],
     

Debugging

• Enable Verbose Logging Add to config/tissue-clamav-adapter.php:

  'debug' => env('CLAMAV_DEBUG', false),
  

  Check Laravel logs for raw ClamAV output.

• Test with Known Malware Use EICAR test file (https://www.eicar.org/download-anti-malware-testfile/) to verify setup:

  file_put_contents('eicar.com', file_get_contents('https://www.eicar.org/download-anti-malware-testfile/'));
  $result = $adapter->scan(new File('eicar.com'));
  // Should return errors
  

Extension Points

1. Custom Error Handling Override the adapter’s handleScanResult method to customize responses:

   $adapter->setErrorHandler(function ($errors) {
       throw new \RuntimeException("Scan failed: " . implode(', ', $errors));
   });
   

2. Async Scanning Use Laravel’s dispatchSync for synchronous scans or dispatch for async:

   $adapter->scan($file)->dispatchSync();
   

3. Multi-Scanner Setup Combine with other Tissue adapters (e.g., spatie/laravel-virus-scanner) for redundancy:

   $results = [
       $adapter1->scan($file),
       $adapter2->scan($file),
   ];
   $allClean = collect($results)->every(fn ($r) => $r->isClean());