Security Advisories Health Check Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/security-advisories-health-check
   

   Ensure spatie/laravel-health is also installed (required dependency).

2. Register the Check: Add to your AppServiceProvider or a dedicated health check service provider:

   use Spatie\Health\Facades\Health;
   use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;
   
   public function boot()
   {
       Health::checks([
           SecurityAdvisoriesCheck::new()->retryTimes(3),
       ]);
   }
   

3. First Use Case: Trigger the health check via CLI or HTTP endpoint (e.g., /health). The check will:

   • Scan composer.json for installed packages.
   • Query Packagist for security advisories.
   • Return a false status if vulnerabilities are found.

Key Files to Review

• Config: config/health.php (if customizing health check routes).
• Logs: Check Laravel logs for API errors during advisories fetch.

Implementation Patterns

Workflows

1. Integration with CI/CD: Fail builds if advisories are detected:

   SecurityAdvisoriesCheck::new()
       ->failWhenAdvisoriesFound() // Explicitly mark as critical
       ->cacheResultsForMinutes(30);
   

   Add to .github/workflows/laravel.yml:

   - name: Run Health Checks
     run: php artisan health:check --fail-on=security-advisories
   

2. Customizing Output: Extend the check to log advisories to a database or Slack:

   SecurityAdvisoriesCheck::new()
       ->onAdvisoriesFound(function (array $advisories) {
           // Send alert or log
           Log::warning('Security advisories found', ['advisories' => $advisories]);
       });
   

3. Partial Scans: Exclude specific packages (e.g., dev dependencies):

   SecurityAdvisoriesCheck::new()
       ->ignorePackages(['monolog/monolog', 'phpunit/phpunit']);
   

Integration Tips

• Laravel Health Dashboard: Use with spatie/laravel-health to expose advisories via /health endpoint. Customize the dashboard template to highlight critical advisories.

• Scheduling: Run daily via Laravel scheduler:

  $schedule->command('health:check --only=security-advisories')->daily();
  

• Composer Scripts: Hook into post-update-cmd to auto-check advisories:

  {
    "scripts": {
      "post-update-cmd": "php artisan health:check --only=security-advisories --fail-on=security-advisories"
    }
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • Packagist may throttle requests. Use cacheResultsForMinutes() (default: 0 = no cache).
   • For high-frequency checks, cache for at least 30 minutes to avoid hitting limits.

2. False Positives:

   • Some advisories may be patched in newer versions of the same package. Verify with:

     composer why-not <package> <version>
     

3. Network Issues:

   • The check fails silently if Packagist is unreachable. Add retry logic:

     SecurityAdvisoriesCheck::new()->retryTimes(5)->withRetryDelay(2);
     

4. Composer Lock Mismatches:

   • The check uses composer.json, not composer.lock. For accurate results, ensure composer install runs before checks.

Debugging

• Enable Verbose Logging:

  php artisan health:check --verbose --only=security-advisories
  

  Look for Guzzle HTTP client logs to diagnose API failures.

• Manual API Test: Test Packagist API access:

  curl https://packagist.org/p/laravel/framework.json
  

Extension Points

1. Custom Advisory Sources: Override the default Packagist source by binding a custom AdvisoryFetcher:

   $this->app->bind(SecurityAdvisoriesCheck::class, function () {
       return new SecurityAdvisoriesCheck(new CustomAdvisoryFetcher());
   });
   

2. Severity Filtering: Filter advisories by severity (e.g., ignore "low" severity):

   SecurityAdvisoriesCheck::new()
       ->ignoreSeverities(['low']);
   

3. Mocking for Tests: Use a mock AdvisoryFetcher in tests:

   $fetcher = Mockery::mock(AdvisoryFetcher::class);
   $fetcher->shouldReceive('fetchAdvisories')
       ->andReturn(['laravel/framework' => ['CVE-2023-1234']]);
   
   $check = new SecurityAdvisoriesCheck($fetcher);
   

Config Quirks

• Cache Driver: The cache uses Laravel’s default cache driver. Ensure config/cache.php is configured for your environment.

• Environment-Specific Checks: Disable checks in local environments:

  if (app()->environment('local')) {
      Health::checks([]); // Skip all checks
  }