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',
        ];
    }
}

'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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

mohamedhekal / laravel-vulnerability-audit

Maintainers

Details