README

A comprehensive security audit package for Laravel applications that scans for vulnerabilities, weak configurations, and security best practices. This package helps developers and teams ensure their Laravel projects follow security best practices before deployment.

🎯 Features

🔑 Password Strength Scanner

• Scans user passwords against known weak password lists
• Supports both hashed and plain text password checking
• Configurable password strength requirements

⚙️ Environment Configuration Checker

• Detects if APP_DEBUG is enabled in production
• Validates APP_ENV settings
• Checks session driver security
• Verifies HTTPS enforcement

🧑‍💻 User Role & Permissions Analyzer

• Identifies admin roles with excessive permissions
• Warns about unrestricted access patterns
• Analyzes role hierarchy and privilege escalation risks

🗃️ Database Schema Analyzer

• Scans for missing timestamps (created_at, updated_at)
• Checks for soft delete support (deleted_at)
• Validates primary key presence
• Analyzes table indexing and security layers

📦 Composer Package Version Checker

• Detects outdated packages from composer.lock
• Compares versions with Packagist API
• Alerts for critical security updates

🧾 File Permissions Scanner

• Checks .env, storage, and logs folder permissions
• Validates file accessibility and writability
• Identifies potential security vulnerabilities

🔍 Additional Security Checks

• CSRF and CORS configuration validation
• Laravel Sanctum/Passport token policies
• Hardcoded secrets detection
• Debug route exposure scanning

📦 Installation

Via Composer

composer require mohamedhekal/laravel-vulnerability-audit

Publish Configuration

php artisan vendor:publish --provider="MohamedHekal\LaravelVulnerabilityAudit\LaravelVulnerabilityAuditServiceProvider"

🚀 Quick Start

Basic Security Scan

php artisan security:scan

Generate Detailed Report

php artisan security:report --format=html
php artisan security:report --format=pdf

Scheduled Security Audits

php artisan security:schedule

📋 Configuration

The configuration file config/vulnerability-audit.php allows you to customize:

return [
    'scanners' => [
        'password' => [
            'enabled' => true,
            'min_strength' => 8,
            'check_common_passwords' => true,
        ],
        'environment' => [
            'enabled' => true,
            'strict_mode' => false,
        ],
        'database' => [
            'enabled' => true,
            'check_timestamps' => true,
            'check_soft_deletes' => true,
        ],
        'packages' => [
            'enabled' => true,
            'check_updates' => true,
            'critical_packages' => ['laravel/framework', 'symfony/console'],
        ],
        'permissions' => [
            'enabled' => true,
            'sensitive_files' => ['.env', 'storage', 'logs'],
        ],
    ],
    
    'notifications' => [
        'enabled' => true,
        'channels' => ['mail', 'slack'],
        'recipients' => ['admin@example.com'],
    ],
    
    'reporting' => [
        'save_reports' => true,
        'report_path' => storage_path('security-reports'),
        'retention_days' => 30,
    ],
];

🛠️ Usage Examples

Command Line Interface

# Basic security scan
php artisan security:scan

# Scan with specific scanners
php artisan security:scan --scanners=password,environment

# Generate HTML report
php artisan security:report --format=html --output=security-report.html

# Generate PDF report
php artisan security:report --format=pdf --output=security-report.pdf

# Schedule regular audits
php artisan security:schedule --frequency=daily

Programmatic Usage

use MohamedHekal\LaravelVulnerabilityAudit\Services\SecurityAuditService;

$auditService = app(SecurityAuditService::class);

// Run all scanners
$results = $auditService->runFullAudit();

// Run specific scanner
$passwordResults = $auditService->runScanner('password');

// Get audit summary
$summary = $auditService->getAuditSummary();

Web Dashboard

Access the security dashboard at /security-audit (if enabled):

// In your routes/web.php
Route::middleware(['auth', 'admin'])->group(function () {
    Route::get('/security-audit', [SecurityAuditController::class, 'dashboard']);
    Route::get('/security-audit/reports', [SecurityAuditController::class, 'reports']);
});

📊 Report Formats

Console Output

🔐 Laravel Security Audit Report
================================

✅ Environment Configuration
   - APP_DEBUG: Disabled ✓
   - APP_ENV: Production ✓
   - HTTPS: Enforced ✓

⚠️  Password Security
   - 3 users with weak passwords detected
   - Recommendation: Enforce password policy

❌ Database Schema
   - Table 'temp_data' missing timestamps
   - Table 'logs' missing primary key

📦 Package Updates
   - Laravel Framework: 10.35.0 (Latest: 10.40.0)
   - Symfony Console: 6.3.0 (Latest: 6.4.0)

🔒 File Permissions
   - storage/logs: 755 ✓
   - .env: 644 ✓

Overall Security Score: 85/100

HTML Report

Generates a beautiful, interactive HTML report with:

• Color-coded severity levels
• Detailed recommendations
• Actionable security fixes
• Historical audit comparison

PDF Report

Professional PDF reports suitable for:

• Security compliance documentation
• Client security audits
• Team security reviews

🔧 Custom Scanners

Create custom security scanners:

namespace App\Security\Scanners;

use MohamedHekal\LaravelVulnerabilityAudit\Contracts\SecurityScanner;

class CustomSecurityScanner implements SecurityScanner
{
    public function scan(): array
    {
        return [
            'name' => 'Custom Security Check',
            'status' => 'warning',
            'message' => 'Custom security issue detected',
            'recommendation' => 'Implement custom security measure',
            'severity' => 'medium',
        ];
    }
}

Register in configuration:

'custom_scanners' => [
    \App\Security\Scanners\CustomSecurityScanner::class,
],

🚨 Notifications

Configure notifications for security issues:

// In your notification class
use MohamedHekal\LaravelVulnerabilityAudit\Notifications\SecurityAuditNotification;

class SecurityAlert extends SecurityAuditNotification
{
    public function toSlack($notifiable)
    {
        return (new SlackMessage)
            ->error()
            ->content('Security audit completed with issues detected!')
            ->attachment(function ($attachment) {
                $attachment->title('Security Issues')
                    ->content($this->auditResults);
            });
    }
}

🧪 Testing

# Run all tests
composer test

# Run specific test suite
./vendor/bin/phpunit --filter=PasswordScannerTest

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage

📈 Security Score Calculation

The package calculates an overall security score based on:

• Critical Issues (40%): Immediate security threats
• High Issues (30%): Significant security risks
• Medium Issues (20%): Moderate security concerns
• Low Issues (10%): Minor security improvements

🔄 Scheduled Audits

Add to your Laravel scheduler:

// In app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('security:scan')
        ->daily()
        ->at('02:00')
        ->withoutOverlapping();
        
    $schedule->command('security:report --format=html')
        ->weekly()
        ->sundays()
        ->at('09:00');
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🔒 Security

If you discover any security-related issues, please email mohamedhekal@gmail.com instead of using the issue tracker.

📄 License

The MIT License (MIT). Please see License File for more information.

🙏 Acknowledgments

• Laravel community for the amazing framework
• Security researchers and contributors
• All package users and feedback providers

📞 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: mohamedhekal@gmail.com

Made with ❤️ by Mohamed Hamad