laravel-suspicious-files maintained by accentinteractive
Laravel Suspicious Files
Get notified when suspicious files (PHP or other) appear in your file system.
This package monitors your Laravel application for suspicious files that are created in monitored directories. It's designed to detect potential security threats like uploaded malware or backdoor scripts.
Requirements
- PHP 8.0 or higher
- Laravel 11.x, 12.x, or 13.x
Installation
Install the package via Composer:
composer require accentinteractive/laravel-suspicious-files
The package will automatically register itself via Laravel's auto-discovery.
Configuration
Publish the configuration file:
php artisan vendor:publish --provider="Accentinteractive\LaravelSuspiciousFiles\LaravelSuspiciousFilesServiceProvider" --tag="config"
This will create a config/suspicious-files.php file where you can customize:
- Monitored directories - Directories to scan for suspicious files
- Excluded directories - Directories to skip (e.g., vendor, storage)
- Allowed files - Files that are permitted (e.g., index.php)
- File extensions - Extensions to monitor (default: php)
- Email notifications - Configure email alerts
Environment Variables
Add these to your .env file:
# Email address to receive security alerts
SUSPICIOUS_FILES_EMAIL=security@example.com
# Whether to send email notifications (true/false)
SUSPICIOUS_FILES_SEND_EMAIL=true
Usage
Manual Scan
Run a manual scan to check for suspicious files created in the last 5 minutes:
php artisan suspicious-files:find
Custom Time Window
Check for files created in the last 30 minutes:
php artisan suspicious-files:find --minutes=30
Send Email Notification
Send an email alert if suspicious files are found:
php artisan suspicious-files:find --notify
Scheduled Monitoring
Add to your app/Console/Kernel.php to run automatic scans:
protected function schedule(Schedule $schedule)
{
// Check every 5 minutes for files created in the last 10 minutes
$schedule->command('suspicious-files:find --minutes=10 --notify')
->everyFiveMinutes();
}
How It Works
- The command scans configured directories for PHP files
- Checks if files were created within the specified time window
- Excludes configured directories (vendor, storage, etc.)
- Skips allowed files (like index.php)
- Reports findings via CLI output
- Logs security events to Laravel logs
- Optionally sends email notifications
Security Alerts
When suspicious files are detected:
- CLI Output: Table showing file path, size, creation time, and age
- Log Entry: Critical log entry with file details
- Email Alert: Optional email with file information
- Cache: Results stored for 7 days for review
Configuration Example
return [
'monitored_directories' => [
'public/uploads',
'storage/app/public',
],
'excluded_directories' => [
'vendor',
'node_modules',
'storage/framework',
// ... more exclusions
],
'allowed_files' => [
'index.php',
],
'suspicious_file_extensions' => [
'php',
'phtml',
'php3',
'php4',
'php5',
],
'email' => [
'notification_email_address' => env('SUSPICIOUS_FILES_EMAIL', ''),
'subject' => '⚠ SECURITY ALERT: suspicious files detected',
'view' => 'suspicious::email.security-alert',
],
];
Use Cases
- Upload Directory Monitoring: Detect malicious files uploaded through file upload forms
- Web Shell Detection: Identify backdoor scripts placed by attackers
- Security Auditing: Regular scans for unauthorized PHP files
- Incident Response: Quick detection of file-based attacks
Testing
Run the test suite:
composer test
Contributing
Please see CONTRIBUTING.md for details.
Security
If you discover any security-related issues, please email joost@accentinteractive.nl instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.