A file hash only means something if you trust the moment it was recorded. That sounds obvious, but it is the part of integrity checking that people most often skip. Here are the design decisions behind the baseline feature in Laravel Scalpel, an open-source intrusion evidence scanner for Laravel. Scalpel is now at v1.11.0, and the trade-offs below came up repeatedly in issues and in an independent review by Laravel News.
What a baseline records
scalpel:baseline stores three things for each included file: its SHA-256 hash, its size, and its modification time. Later, scalpel:diff compares the live files against that record and reports files that were added, modified, or deleted.
php artisan scalpel:baseline
php artisan scalpel:diff
The idea is simple. Content scanners tell you whether a file looks suspicious. A baseline tells you whether a file changed, even if it looks perfectly normal. A backdoor hidden in a legitimate file will not match any pattern, but it will not match the old hash either.
Decision 1: what to leave out
A baseline that reports every log rotation is a baseline you will stop reading. By default, frequently changing paths such as logs, sessions, compiled views, and storage/app are excluded.
vendor/ gets different treatment. It is skipped by the content scanners, because scanning thousands of third-party files produces noise. But it stays in the baseline comparison. If someone drops a file into an installed package, you still see it in the diff.
Decision 2: strict or fast hashing
By default, Scalpel runs in strict mode and re-hashes every file on each comparison. That is the most reliable option and also the slowest.
The --fast option first compares size and modification time, and reuses the old hash when both match. It saves work, but it has a known blind spot: an attacker who edits a file and restores its original size and modification time can slip past the baseline comparison. Other scanners may still catch the file by its content or location, but the baseline alone will not.
A practical rule: use strict mode where the result matters, such as scheduled integrity checks, and --fast only where speed matters more, such as frequent local runs.
Decision 3: sign the baseline
If an attacker can rewrite the baseline, the diff becomes meaningless. Scalpel can HMAC-sign baselines and JSON reports when SCALPEL_SIGNING_ENABLED is true. The key goes in SCALPEL_SIGNING_KEY, and it should be a dedicated key, not your APP_KEY.
When signing is on, scalpel:diff verifies the baseline before using it. A missing or invalid signature is reported as CRITICAL. For saved JSON reports, scalpel:verify checks the signature.
Two details matter in practice. First, turn on signing before you create the first baseline, otherwise you have an unsigned record to start from. Second, signing has a clear limit: it detects a baseline regenerated without the key, but it cannot help if the attacker can read the key or modify the scanner itself.
Decision 4: when to refresh
A baseline is a record of a state you trust, so it has to be refreshed deliberately. The suggested flow after each deployment is to run php artisan optimize, then scalpel:baseline --force to replace the old record. Until a baseline exists, both scan and diff report a MEDIUM finding telling you to create one.
Never create a baseline on a server you suspect is already compromised. You would be recording the attacker's files as normal.
The trust boundary
All of this runs in the same process, with the same permissions, as your application. Anyone who can change your code can also change the scanner. So the strongest setup moves the trust boundary outside the app:
- Trigger scans from outside the server, for example from CI or a scheduler on another machine.
- Keep code directories read-only where possible.
- Send reports and baselines to storage the server cannot write to.
A scanner like this detects evidence of an intrusion. It does not block or contain one.
Try it
composer require hryagstn/laravel-scalpel
php artisan vendor:publish --tag=scalpel-config
Requires PHP 8.2 or later and supports Laravel 10 to 13.
If you have a case where the baseline gives noisy or misleading results, please open an issue. I covered what the individual scanners look for in a separate post on DEV: https://dev.to/harryagustiana/what-a-filesystem-scan-can-and-cannot-tell-you-after-a-laravel-intrusion-1hn5
Source: https://github.com/hryagstn/laravel-scalpel