Quahog Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require xenolope/quahog
   

   Register the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       Xenolope\Quahog\QuahogServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Xenolope\Quahog\QuahogServiceProvider" --tag="config"
   

   Update config/quahog.php with your clamd daemon details (default: unix:///var/run/clamav/clamd.ctl).

3. First Scan Inject the Quahog facade or service into a controller/service:

   use Xenolope\Quahog\Facades\Quahog;
   
   public function scanFile(Request $request) {
       $filePath = $request->file('file')->getRealPath();
       $result = Quahog::scan($filePath);
       return response()->json($result);
   }
   

Implementation Patterns

Core Workflows

1. File Scanning

   • Basic Scan: Use Quahog::scan($filePath) to check a file.
   • Streaming: For large files, stream chunks via Quahog::scanStream($stream).
   • Recursive Scanning: Use Quahog::scanDirectory($path) to scan all files in a directory.

2. Command Execution

   • Run raw clamd commands (e.g., reload, stats):

     Quahog::command('reload');
     $stats = Quahog::command('stats');
     

3. Integration with Laravel

   • Middleware: Scan uploads before processing:

     public function handle($request, Closure $next) {
         if ($request->hasFile('file')) {
             $scan = Quahog::scan($request->file('file')->getRealPath());
             if ($scan['infected']) {
                 abort(403, 'Malware detected!');
             }
         }
         return $next($request);
     }
     

   • Events: Trigger actions post-scan (e.g., quarantine infected files):

     event(new FileScanned($filePath, $result));
     

4. Batch Processing

   • Queue scans for async processing (e.g., Laravel Queues):

     ScanFileJob::dispatch($filePath)->onQueue('scans');
     

Advanced Patterns

1. Custom Responses Extend the default response format:

   $result = Quahog::scan($filePath, [
       'format' => 'json',
       'verbose' => true,
   ]);
   

2. Logging Log scan results to a custom table or external service:

   \Log::info('Scan result', ['file' => $filePath, 'result' => $result]);
   

3. Fallback Mechanisms Handle clamd unavailability gracefully:

   try {
       $result = Quahog::scan($filePath);
   } catch (\Exception $e) {
       // Fallback to another AV or log the error
   }
   

Gotchas and Tips

Common Pitfalls

1. Connection Issues

   • Ensure clamd is running and the socket path/port in config/quahog.php is correct.
   • Test connectivity manually:

     clamdscan --socket=/var/run/clamav/clamd.ctl /tmp/testfile
     

2. Permission Errors

   • The PHP process (e.g., www-data) must have read access to scanned files and write access to clamd socket.
   • Set permissions:

     chmod 666 /var/run/clamav/clamd.ctl
     chmod -R 755 /path/to/files
     

3. Large File Handling

   • Avoid memory issues with streams:

     $stream = fopen($filePath, 'r');
     $result = Quahog::scanStream($stream);
     fclose($stream);
     

4. Signature Updates

   • Quahog::command('reload') must be called after manual clamav-freshclam updates.

Debugging Tips

1. Enable Verbose Output Configure config/quahog.php:

   'verbose' => env('QUAHOG_VERBOSE', false),
   

   Check Laravel logs for raw clamd output.

2. Check clamd Logs Monitor /var/log/clamav/freshclam.log or /var/log/clamav/clamd.log for errors.

3. Test with Known Files Use EICAR test file:

   echo "X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*" > /tmp/eicar.com
   

   Scan via:

   Quahog::scan('/tmp/eicar.com'); // Should return 'infected'.
   

Extension Points

1. Custom Commands Extend the Quahog class to add domain-specific commands:

   Quahog::extend(function ($quahog) {
       $quahog->customCommand = function ($arg) {
           return $quahog->run('custom ' . $arg);
       };
   });
   

2. Response Parsing Override response handling in app/Providers/QuahogServiceProvider.php:

   public function boot() {
       Quahog::macro('parseResponse', function ($raw) {
           // Custom parsing logic
           return ['custom' => 'data'];
       });
   }
   

3. Mocking for Tests Use Laravel’s service container to mock Quahog:

   $this->app->instance(\Xenolope\Quahog\Quahog::class, Mockery::mock());