Relay Verity Connector Clamav Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require dbp/relay-verity-connector-clamav-bundle
   

   Ensure DbpRelayCoreBundle is already installed (this bundle depends on it).

2. Bundle Registration Add to config/bundles.php:

   Dbp\Relay\VerityConnectorClamavBundle\DbpRelayVerityConnectorClamavBundle::class => ['all' => true],
   

3. Configuration Create config/packages/dbp_relay_verity_connector_clamav.yaml:

   dbp_relay_verity_connector_clamav:
     url: '%env(CLAMAV_URI)%'  # e.g., 'http://clamav:3310'
     maxsize: 33554432         # 32MB max file size (adjust as needed)
   

4. First Use Case Inject the VerityConnectorClamavClient service into a controller or command:

   use Dbp\Relay\VerityConnectorClamavBundle\Client\VerityConnectorClamavClient;
   
   public function __construct(
       private VerityConnectorClamavClient $clamavClient
   ) {}
   

   Scan a file:

   $result = $this->clamavClient->scan($filePath);
   

Implementation Patterns

Core Workflows

1. File Scanning Use the scan() method to check files for malware:

   $scanResult = $this->clamavClient->scan('/path/to/file.pdf');
   // Returns bool|array (false on error, array with 'clean' => bool, 'virus' => string|null)
   

2. Streaming Large Files For files > maxsize, stream chunks via scanStream():

   $stream = fopen($filePath, 'r');
   $result = $this->clamavClient->scanStream($stream);
   

3. Integration with Relay API Extend Dbp\Relay\CoreBundle\Event\FileUploadEvent to trigger scans:

   use Dbp\Relay\CoreBundle\Event\FileUploadEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class ClamAVScannerSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [FileUploadEvent::NAME => 'onFileUpload'];
       }
   
       public function onFileUpload(FileUploadEvent $event)
       {
           $file = $event->getFile();
           $result = $this->clamavClient->scan($file->getPathname());
           if (!$result['clean']) {
               $event->markAsMalicious($result['virus']);
           }
       }
   }
   

4. Batch Processing Use Symfony’s Messenger component to queue scans:

   $this->messageBus->dispatch(
       new ScanFileMessage($filePath, $userId)
   );
   

Integration Tips

• Environment Variables: Always use %env(CLAMAV_URI)% for ClamAV service URLs.
• Caching: Cache scan results for repeated requests (e.g., via Symfony\Contracts\Cache\CacheInterface).
• Error Handling: Wrap calls in try-catch for ConnectionException (network issues) or RuntimeException (invalid responses).

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • If url or maxsize are missing in YAML, the bundle throws InvalidArgumentException. Validate config early:

     if (!array_key_exists('url', $config)) {
         throw new \InvalidArgumentException('ClamAV URI is required.');
     }
     

2. File Size Limits

   • ClamAV may reject files > maxsize even if your bundle allows it. Test with:

     dd if=/dev/zero of=testfile bs=34M count=1  # Exceeds default 32MB
     

3. Streaming Quirks

   • scanStream() fails silently if the stream is closed prematurely. Use fpassthru() or ensure streams are seekable:

     $stream = fopen($filePath, 'r+');  // 'r+' ensures seekability
     

4. Dependency Conflicts

   • This bundle requires dbp/relay-core-bundle. Install it first:

     composer require dbp/relay-core-bundle
     

Debugging

• Enable Debug Mode: Add to config/packages/dev/dbp_relay_verity_connector_clamav.yaml:

  debug: true
  

  Logs raw ClamAV responses to var/log/dev.log.

• Test Locally: Use Docker to spin up ClamAV:

  # docker-compose.yml
  services:
    clamav:
      image: clamav/clamav:latest
      ports:
        - "3310:3310"
  

Extension Points

1. Custom Responses Override the VerityConnectorClamavClient to modify scan results:

   class CustomClamAVClient extends VerityConnectorClamavClient
   {
       protected function processResponse(array $data): array
       {
           $data['custom_field'] = 'value';
           return parent::processResponse($data);
       }
   }
   

   Register as a service:

   services:
       Dbp\Relay\VerityConnectorClamavBundle\Client\VerityConnectorClamavClient:
           class: App\Service\CustomClamAVClient
   

2. Alternative Transports Extend Dbp\Relay\VerityConnectorClamavBundle\Http\ClamAVClient to support gRPC or WebSockets.

3. Event Dispatching Dispatch custom events after scans:

   $event = new FileScanEvent($filePath, $result);
   $this->eventDispatcher->dispatch($event);