Tissue Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require cleentfaar/tissue-bundle
   

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Cleentfaar\TissueBundle\CLTissueBundle::class => ['all' => true],
   ];
   

3. Configure ClamAV in config/packages/cl_tissue.yaml:

   cl_tissue:
       adapter: cl_tissue.adapter.clamav
       clamav:
           binary: '/usr/bin/clamscan'  # Adjust path to your ClamAV binary
   

First Use Case: File Upload Validation

1. Add the CleanFile constraint to your entity:

   use Cleentfaar\TissueBundle\Validator\Constraints as TissueAssert;
   
   /**
    * @TissueAssert\CleanFile()
    */
   private $file;
   

2. Test with a malicious file to see the validation reject it.

Implementation Patterns

Workflow: Real-Time Upload Scanning

1. Form Handling:
   • Use Symfony’s File type in forms to trigger validation.
   • Example form type:

     use Symfony\Component\Form\Extension\Core\Type\FileType;
     
     $builder->add('file', FileType::class, [
         'constraints' => [new \Cleentfaar\TissueBundle\Validator\Constraints\CleanFile()]
     ]);
     

2. Error Handling:
   • Catch TissueException in your controller to customize error messages:

     try {
         $form->handleRequest($request);
         if ($form->isSubmitted() && $form->isValid()) {
             // Process file
         }
     } catch (\Cleentfaar\TissueBundle\Exception\TissueException $e) {
         $this->addFlash('error', 'File contains malware: ' . $e->getMessage());
         return $this->redirectToRoute('upload');
     }
     

Workflow: Batch Processing

1. Scan Files Programmatically:
   • Inject the scanner service (cl_tissue.scanner) and scan files in bulk:

     use Cleentfaar\TissueBundle\Scanner\ScannerInterface;
     
     public function __construct(private ScannerInterface $scanner) {}
     
     public function processFiles(array $filePaths): void {
         foreach ($filePaths as $path) {
             if (!$this->scanner->scan($path)) {
                 throw new \RuntimeException("Malware detected in $path");
             }
         }
     }
     

2. Queue Long-Running Scans:
   • Use Symfony Messenger or a queue system (e.g., Symfony Messenger + Doctrine) to avoid blocking requests.

Integration Tips

• Custom Adapters:
  • Implement Cleentfaar\TissueBundle\Adapter\AdapterInterface for non-ClamAV engines (e.g., Sophos).
  • Tag your adapter service:

    services:
        app.tissue.adapter.sophos:
            class: App\Adapter\SophosAdapter
            tags: ['cl_tissue.adapter']
    

• Symfony Validator Integration:
  • Extend CleanFile constraint for custom logic (e.g., whitelist file types):

    use Cleentfaar\TissueBundle\Validator\Constraints\CleanFile as BaseCleanFile;
    
    class CustomCleanFile extends BaseCleanFile {
        public function validatedBy() { return static::class; }
        public function getTargets() { return [self::PROPERTY_CONSTRAINT]; }
    }
    

Gotchas and Tips

Pitfalls

1. ClamAV Binary Path:

   • The bundle defaults to /usr/bin/clamscan. On Windows or custom installations, update config/packages/cl_tissue.yaml:

     cl_tissue:
         clamav:
             binary: 'C:\Program Files\ClamAV\bin\clamscan.exe'
     

   • Debug Tip: Verify the path with shell_exec('which clamscan') (Linux/macOS) or check the Windows PATH.

2. Permission Issues:

   • ClamAV requires read access to scanned files. Ensure your web server user (e.g., www-data) has permissions:

     chmod -R 755 /path/to/uploaded/files
     

   • Workaround: Run the scanner as a dedicated user with proper permissions.

3. Outdated Dependencies:

   • The bundle was last updated in 2017. Test thoroughly with modern Symfony (5.4+) and PHP (8.0+).
   • Mitigation: Fork the repo and update dependencies (e.g., symfony/validator, symfony/dependency-injection).

4. False Positives:

   • ClamAV may flag harmless files (e.g., legitimate archives). Configure exclusions in clamav.conf or pre-filter files:

     // Whitelist specific extensions
     $scanner->setAllowedExtensions(['pdf', 'jpg']);
     

Debugging

1. Enable Verbose Logging: Add to config/packages/monolog.yaml:

   handlers:
       cl_tissue:
           type: stream
           path: "%kernel.logs_dir%/tissue.log"
           level: debug
           channels: ["cl_tissue"]
   

   Then log scanner events in your adapter:

   $this->logger->debug('Scanning file: ' . $filePath);
   

2. Manual ClamAV Test: Validate your setup with:

   clamscan -r /path/to/test/files
   

Extension Points

1. Custom Scanner Configuration: Override the scanner service to add pre/post-scan hooks:

   services:
       app.tissue.scanner:
           class: App\Scanner\CustomScanner
           decorates: cl_tissue.scanner
           arguments: ['@app.tissue.scanner.inner']
   

   class CustomScanner implements ScannerInterface {
       public function scan($filePath) {
           // Pre-scan logic (e.g., size check)
           $result = $this->scanner->scan($filePath);
           // Post-scan logic (e.g., quarantine)
           return $result;
       }
   }
   

2. Async Scanning: Use Symfony Messenger to offload scans:

   use Cleentfaar\TissueBundle\Message\ScanFileMessage;
   
   $bus->dispatch(new ScanFileMessage($filePath));
   

   Configure the transport in config/packages/messenger.yaml.

3. GUI Feedback: Extend the bundle’s Twig templates (Resources/views/) to show scan progress or results to users.