Tissue Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require cleentfaar/tissue-bundle
   

   Ensure symfony/flex is configured to auto-load bundles (default in Laravel/Symfony 5.1+).

2. Enable the Bundle Add to config/bundles.php (Symfony) or config/app.php (Laravel via extra.bundles):

   Cleentfaar\TissueBundle\CLTissueBundle::class => ['all' => true],
   

3. Configure Tissue Publish the default config:

   php artisan vendor:publish --tag=tissue-config
   

   Edit config/tissue.php to specify:

   • scanner (e.g., clamav, fprot)
   • scan_paths (directories/files to monitor)
   • excluded_paths (ignored files/dirs)
   • threshold (max allowed infections before blocking)

4. First Scan Trigger a manual scan via CLI:

   php artisan tissue:scan
   

   Or integrate into a Laravel job/queue for async processing.

First Use Case: File Upload Validation

1. Hook into Upload Logic Use middleware or a service to scan files before saving:

   use Cleentfaar\TissueBundle\Scanner;
   
   class UploadController extends Controller {
       public function store(Request $request) {
           $scanner = app(Scanner::class);
           $file = $request->file('document');
   
           if ($scanner->scan($file->getPathname())) {
               throw new \Exception("Malware detected!");
           }
   
           // Save file...
       }
   }
   

2. Log Results Enable logging in tissue.php:

   'log_results' => true,
   

   Check storage/logs/tissue.log for scan reports.

Implementation Patterns

Workflow: Scheduled Scans

1. Cron Job Integration Add to app/Console/Kernel.php:

   protected function schedule(Schedule $schedule) {
       $schedule->command('tissue:scan')->dailyAt('2:00');
   }
   

   Or use Laravel’s task scheduler:

   php artisan schedule:run
   

2. Batch Processing For large directories, chunk scans:

   $scanner->scanDirectory('/path/to/files', 100); // Scan 100 files at a time
   

Integration Tips

1. Laravel Filesystem Scan files stored in storage/app:

   use Illuminate\Support\Facades\Storage;
   
   $path = Storage::path('uploads/document.pdf');
   $scanner->scan($path);
   

2. Event-Driven Scans Trigger scans on file uploads via events:

   // In EventServiceProvider
   protected $listen = [
       'file.uploaded' => [Scanner::class, 'scanFile'],
   ];
   

3. Custom Actions on Infection Extend the ScanResult object to add logic:

   $result = $scanner->scan($file);
   if ($result->isInfected()) {
       $this->quarantine($file); // Custom method
   }
   

Symfony/Laravel Hybrid Patterns

• Dependency Injection Bind the scanner in config/services.php (Laravel) or services.yaml (Symfony):

  'scanner' => Cleentfaar\TissueBundle\Scanner::class,
  

  Inject via constructor:

  public function __construct(private Scanner $scanner) {}
  

• Twig Integration (Symfony) Pass scan results to templates:

  {% if scanResult.isInfected %}
      <div class="alert">⚠️ Malware detected!</div>
  {% endif %}
  

Gotchas and Tips

Pitfalls

1. Scanner Dependencies

   • ClamAV/F-Prot: Ensure the underlying scanner (e.g., clamav-daemon) is installed and running.
     • Fix: Install via package manager (e.g., sudo apt-get install clamav).
   • Debug: Check tissue.php for scanner config and verify the binary path.

2. Performance Overhead

   • Scanning large directories (e.g., storage/app/public) can be slow.
     • Fix: Use scanDirectory() with batch sizes or offload to a queue.

3. False Positives

   • Some legitimate files (e.g., PDFs with embedded fonts) may trigger false alarms.
     • Fix: Adjust threshold or whitelist paths in excluded_paths.

4. File Locking

   • Scanning open files (e.g., during upload) may fail.
     • Fix: Use temporary paths or defer scanning until files are closed.

Debugging

1. Verbose Logging Enable debug mode in tissue.php:

   'debug' => true,
   

   Logs will include scanner commands and file paths.

2. Manual Scanner Test Run the scanner directly to verify:

   clamscan /path/to/file  # Replace with your scanner command
   

3. Artisan Commands

   • php artisan tissue:scan --path=/custom/path (scan specific dir)
   • php artisan tissue:update (update scanner definitions)

Extension Points

1. Custom Scanners Implement Cleentfaar\TissueBundle\ScannerInterface:

   class MyScanner implements ScannerInterface {
       public function scan(string $file): ScanResult {
           // Custom logic (e.g., API call to a cloud scanner)
       }
   }
   

   Register in tissue.php:

   'scanner' => MyScanner::class,
   

2. Post-Scan Actions Extend ScanResult to add metadata:

   $result->setCustomData(['user_id' => auth()->id(), 'action' => 'quarantine']);
   

3. Database Integration Store results in a table:

   $scanner->scan($file)->saveToDatabase(); // Hypothetical method
   

   Tip: Use Laravel’s observers or events to sync with a scan_results table.

Config Quirks

1. Case-Sensitive Paths Ensure scan_paths and excluded_paths use consistent slashes (/ or \) based on your OS.

2. Symlinks Scanning symlinked directories may cause infinite loops.

   • Fix: Add follow_symlinks: false to tissue.php.

3. Environment-Specific Config Use Laravel’s .env or Symfony’s %kernel.environment% to switch scanners:

   'scanner' => env('TISSUE_SCANNER', 'clamav'),