README

Laravel Security Monitor is a lightweight Laravel package for file integrity monitoring and suspicious upload detection. It helps detect unexpected file changes, executable uploads, and common PHP malware signatures in writable paths.

Features

• Scans project files from base_path().
• Builds a SHA-256 baseline for accepted files.
• Detects added, deleted, and modified files compared with the baseline.
• Separately scans configured writable or suspicious directories.
• Flags .php, .phtml, .phar, image-like executable filenames such as image.jpg.php, and text files containing signatures like eval( or base64_decode(.
• Skips binary files when checking text-based PHP signatures, reducing false positives in images.
• Writes reports to the Laravel log with logger()->warning().
• Sends email alerts only when SECURITY_MONITOR_EMAIL is configured.
• Avoids duplicate email alerts for unchanged findings by storing an alert snapshot.
• Returns a successful exit code for reported findings so scheduled scans do not create false Sentry exceptions.

The baseline excludes these paths by default:

vendor
node_modules
.git
storage/logs
storage/framework
bootstrap/cache

Requirements

• PHP ^8.1
• Laravel 10, 11, 12, or 13
• A configured Laravel scheduler
• Mail configured in the application, if email alerts are enabled

Installation

Install the package with Composer:

composer require webgrade/laravel-security-monitor:^1.0

Publish the configuration file:

php artisan vendor:publish --tag=security-monitor-config

If the configuration file already exists and you intentionally want to replace it with the package version:

php artisan vendor:publish --tag=security-monitor-config --force

Environment Configuration

Add the package settings to .env:

SECURITY_MONITOR_ENABLED=true
SECURITY_MONITOR_EMAIL=security@example.com

Email alerts are disabled by default. Set SECURITY_MONITOR_EMAIL only when you want scan reports to be sent by email.

Email delivery uses the host application's mail configuration:

FROM: MAIL_FROM_ADDRESS / MAIL_FROM_NAME from the project
TO:   SECURITY_MONITOR_EMAIL

Example:

MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="${APP_NAME}"

SECURITY_MONITOR_ENABLED=true
SECURITY_MONITOR_EMAIL=security@example.com

After changing .env, clear or rebuild the Laravel config cache if the project uses cached configuration:

php artisan config:clear
php artisan config:cache

Scheduler

Run the scan every five minutes.

Laravel With app/Console/Kernel.php

Add the command in the schedule method:

use Illuminate\Console\Scheduling\Schedule;

protected function schedule(Schedule $schedule): void
{
    $schedule->command('security-monitor:scan')
        ->everyFiveMinutes()
        ->withoutOverlapping();
}

Laravel 11/12/13 With routes/console.php

use Illuminate\Support\Facades\Schedule;

Schedule::command('security-monitor:scan')
    ->everyFiveMinutes()
    ->withoutOverlapping();

Server Cron

The Laravel scheduler must be executed by cron:

* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1

Verify that the job is registered:

php artisan schedule:list | grep security-monitor

First Baseline

After a clean and verified deploy, create the initial baseline:

php artisan security-monitor:scan --reset

Do not run --reset automatically during deploys. Run it manually only after you know the project files are clean and expected.

Manual Scan

php artisan security-monitor:scan

When no issues are found, the command prints:

No suspicious changes found.

When added, deleted, modified, or suspicious files are found, the command:

• prints the report in the console
• writes the report to the Laravel log
• sends an email alert if SECURITY_MONITOR_EMAIL is configured
• returns a successful exit code so Laravel Scheduler does not report a false command failure

Invalid baseline files still return a failure exit code because that is a real configuration or storage problem.

Alert Snapshot

The package stores the last reported finding set in:

storage_path('app/security-monitor/alert-snapshot.json')

If the same findings are detected again, the report remains visible in the console and log, but the email alert is not sent again.

An email alert is sent again when:

• a new finding appears
• the list of added, deleted, modified, or suspicious files changes
• all findings are resolved, the snapshot is cleared, and findings later appear again
• php artisan security-monitor:scan --reset is run manually, which clears both the baseline and alert snapshot

Email Alert Test

Create a baseline from a clean state:

php artisan security-monitor:scan --reset

Create a suspicious test file:

mkdir -p storage/app/security-monitor-email-test
touch storage/app/security-monitor-email-test/probe.jpg.php
php artisan security-monitor:scan
rm storage/app/security-monitor-email-test/probe.jpg.php

If SECURITY_MONITOR_EMAIL is configured, the configured address should receive a report.

After the test, remove the test file. Run --reset again only if the project is clean and you intentionally want to rebuild the baseline.

Public Directory Scanning

File integrity is checked for the whole project, including public, public/css, public/js, and public/images, except for excluded paths.

Aggressive suspicious file scanning runs by default only in:

storage_path()
public_path('storage')
public_path('uploads')

If you want every suspicious file under public to be explicitly flagged, update config/security-monitor.php:

'scan_suspicious_paths' => [
    storage_path(),
    public_path(),
],

Updating

composer update webgrade/laravel-security-monitor
php artisan config:clear

To republish the package configuration:

php artisan vendor:publish --tag=security-monitor-config --force

--force overwrites local changes in config/security-monitor.php.

Temporarily Disable

SECURITY_MONITOR_ENABLED=false

Then clear cached configuration:

php artisan config:clear