Security Checker Laravel Package

Getting Started

Minimal Steps

1. Install the Package Add to composer.json in your Laravel project:

   composer require --dev enlightn/security-checker
   

   This installs the scanner as a dev dependency.

2. Run the Scanner Execute the CLI command in your project root:

   vendor/bin/security-checker security:check composer.lock
   

   This scans your composer.lock file for vulnerable dependencies and displays results in the terminal.

3. Quick Check in Laravel For Laravel projects, create an Artisan command to wrap the scanner:

   php artisan make:command SecurityCheckCommand
   

   Update the generated command (app/Console/Commands/SecurityCheckCommand.php):

   use Enlightn\SecurityChecker\SecurityChecker;
   protected $signature = 'security:scan';
   public function handle(SecurityChecker $scanner) {
       $result = $scanner->checkComposerLock();
       if ($result->hasVulnerabilities()) {
           $this->error("Vulnerabilities found!");
           exit(1);
       }
   }
   

   Run it with:

   php artisan security:scan
   

Implementation Patterns

Workflow: Local Development

1. Pre-Commit Hook Add a script to composer.json to run the scanner before committing:

   "scripts": {
       "pre-commit": "php artisan security:scan",
       "security-check": "vendor/bin/security-checker security:check composer.lock"
   }
   

   Use it with:

   composer run security-check
   

2. Severity Filtering Configure the scanner to ignore low-severity issues in config/security-checker.php:

   'severity' => ['high', 'critical'],
   

Workflow: CI/CD Pipeline

1. GitHub Actions Example Add a step to your workflow (.github/workflows/security.yml):

   - name: Security Check
     run: vendor/bin/security-checker security:check composer.lock --severity=critical
   

   Fail the build if critical vulnerabilities are found.

2. GitLab CI Example Integrate into your .gitlab-ci.yml:

   security_check:
     script:
       - composer require --dev enlightn/security-checker
       - vendor/bin/security-checker security:check composer.lock --format=json > security-report.json
     artifacts:
       paths:
         - security-report.json
   

Integration Tips

1. Laravel Artisan Integration Extend the scanner to work with Laravel’s event system:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       if ($this->app->environment('production')) {
           $scanner = app(SecurityChecker::class);
           $result = $scanner->checkComposerLock();
           if ($result->hasVulnerabilities()) {
               Log::error('Security vulnerabilities detected in production!');
           }
       }
   }
   

2. Custom Output Formats Use the --format flag to generate JSON or GitHub-compatible output:

   vendor/bin/security-checker security:check composer.lock --format=json
   

   Parse the JSON output in your CI/CD pipeline for custom alerts.

3. Whitelisting Known Issues Exclude specific packages or versions from scans by configuring config/security-checker.php:

   'ignore' => [
       'vendor/package' => '1.0.0', // Ignore a specific version
       'vendor/another-package',    // Ignore an entire package
   ],
   

Gotchas and Tips

Pitfalls

1. False Positives

   • The scanner may flag dependencies as vulnerable even if your project isn’t affected (e.g., due to transitive dependencies).
   • Fix: Cross-reference with Snyk or GitHub Advisories for confirmation.

2. Slow Scans in Monorepos

   • Scanning large vendor/ directories can be time-consuming.
   • Fix: Use the --exclude-dir flag to skip irrelevant directories:

     vendor/bin/security-checker security:check composer.lock --exclude-dir=node_modules
     

3. Permission Issues

   • Running the scanner in CI may fail if composer.lock isn’t readable.
   • Fix: Ensure the CI user has access to the file or run the scanner in a pre-build step.

4. Outdated Advisories

   • The scanner relies on the Security Advisories Database, which may lag behind new CVEs.
   • Fix: Regularly update the package (composer update enlightn/security-checker).

Debugging

1. Verbose Output Enable debug mode for detailed logs:

   vendor/bin/security-checker security:check composer.lock --verbose
   

2. Check Cache The scanner caches results to avoid re-scanning. Clear the cache if results seem stale:

   vendor/bin/security-checker security:clear-cache
   

3. Manual Advisory Lookup If a vulnerability is incorrectly flagged, manually verify it on:

   • CVE Details
   • NVD Database

Extension Points

1. Custom Severity Thresholds Override default severity levels in config/security-checker.php:

   'severity' => ['low', 'medium', 'high', 'critical'],
   

2. Slack/Email Alerts Parse the JSON output and trigger alerts:

   $result = $scanner->checkComposerLock();
   if ($result->hasVulnerabilities()) {
       $vulnerabilities = $result->getVulnerabilities();
       // Send Slack/email notification with $vulnerabilities
   }
   

3. Laravel Notifications Integrate with Laravel’s notification system:

   use Illuminate\Notifications\Messages\MailMessage;
   use Illuminate\Support\Facades\Notification;
   
   Notification::route('mail', 'admin@example.com')
               ->notify(new SecurityVulnerability($vulnerabilities));
   

4. Custom Composer Plugin Extend the scanner as a Composer plugin for automatic checks:

   // composer.json
   "extra": {
       "security-checker": {
           "enabled": true,
           "severity": ["critical"]
       }
   }
   

Configuration Quirks

1. Default Output Format The scanner defaults to console output. To change it globally, set:

   'output' => 'json', // or 'github'
   

2. CI-Specific Flags Use --fail-on to control build failures:

   vendor/bin/security-checker security:check composer.lock --fail-on=critical
   

3. Excluding Directories Skip scanning specific directories (e.g., node_modules):

   vendor/bin/security-checker security:check composer.lock --exclude-dir=node_modules,tests