PHPackages hryagstn/laravel-scalpel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. hryagstn/laravel-scalpel ActiveLibrary[File & Storage](/categories/file-storage) hryagstn/laravel-scalpel ======================== Filesystem intrusion evidence scanner for Laravel applications v1.4.0(1mo ago)2459MITPHPPHP ^8.1CI passing Since May 23Pushed 1mo ago1 watchersCompare [ Source](https://github.com/hryagstn/laravel-scalpel)[ Packagist](https://packagist.org/packages/hryagstn/laravel-scalpel)[ RSS](/packages/hryagstn-laravel-scalpel/feed)WikiDiscussions main Synced 3w ago READMEChangelog (4)Dependencies (14)Versions (10)Used By (0) [![Laravel Scalpel Logo](docs/logo.png)](docs/logo.png) Laravel Scalpel =============== [](#laravel-scalpel) **Intrusion Evidence Scanner for Laravel** [![Build Status](https://camo.githubusercontent.com/93e21d51c8338097fb286a57e7a55ff1c74009a9d8e59e22f79321f390e9af2a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f687279616773746e2f6c61726176656c2d7363616c70656c2f74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265)](https://github.com/hryagstn/laravel-scalpel/actions) [![Latest Version on Packagist](https://camo.githubusercontent.com/5200f0598f2919a88737cd41e243299f49419156bf257ad40b15773df551e4c4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f687279616773746e2f6c61726176656c2d7363616c70656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hryagstn/laravel-scalpel) [![PHP Version](https://camo.githubusercontent.com/80352c675dfff188f9954871e05ee0780f857d0f269c19f8a9aa9062bfd5ee69/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f687279616773746e2f6c61726176656c2d7363616c70656c3f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hryagstn/laravel-scalpel) [![Laravel Version](https://camo.githubusercontent.com/760c4bbf0fffd6578154aa9f4500ae7a765b8a4eaaf52b1beaa72bebdd917ce6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e782532307c25323031312e782532307c25323031322e782532307c25323031332e782d626c75653f7374796c653d666c61742d737175617265)](https://packagist.org/packages/hryagstn/laravel-scalpel) [![Website](https://camo.githubusercontent.com/a72fbbe22c5687a544e946ff67ff7633423cd548bdf515922a1e93238cfa985b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f776562736974652d687279616773746e2e6769746875622e696f2532466c61726176656c2d2d7363616c70656c2d636f72616c3f7374796c653d666c61742d737175617265)](https://hryagstn.github.io/laravel-scalpel/) [![License](https://camo.githubusercontent.com/7a34c44bfe7efd9b73713b9144bdddd0d67e018a65165474e6611c42af502671/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f687279616773746e2f6c61726176656c2d7363616c70656c3f7374796c653d666c61742d737175617265)](LICENSE) A zero-dependency, filesystem-level forensic scanner that detects signs of compromise in your Laravel application โ€” obfuscated backdoors, rogue PHP files, tampered `.htaccess` directives, missing `.env` files, and unexpected filesystem changes. Interactive landing page and simulator: **[hryagstn.github.io/laravel-scalpel](https://hryagstn.github.io/laravel-scalpel/)** --- ๐Ÿšจ The Problem ------------- [](#-the-problem) It often starts the same way: a production Laravel app is quietly compromised. Obfuscated PHP backdoors appear in directories like `public/icons/` or `storage/`. An `.htaccess` file is modified to allow Python script execution. The `.env` file is deleted or tampered with to disable error reporting and cover tracks. These attacks don't trigger your WAF. They don't show up in your application logs. The malicious files sit silently on disk, waiting. **Laravel Scalpel is not a WAF, firewall, or runtime protection layer.** It is a *forensic filesystem scanner* โ€” a post-incident or preventive tool that examines your project's file structure and contents for evidence of intrusion. Think of it as a security audit you can run on-demand or in CI/CD. Unlike configuration auditors that check for *potential* vulnerabilities, Laravel Scalpel looks for *evidence that a compromise has already occurred* โ€” making it the tool you reach for when something feels wrong, not just as a preventive checklist. --- ๐Ÿ“ฆ Installation -------------- [](#-installation) ``` composer require hryagstn/laravel-scalpel ``` Publish the configuration file: ``` php artisan vendor:publish --tag=scalpel-config ``` This creates `config/scalpel.php` where you can customize scan behavior, exclusion lists, and severity thresholds. > **Requirements:** PHP 8.1+ ยท Laravel 10.x, 11.x, 12.x, or 13.x --- โšก Quick Start ------------- [](#-quick-start) Run all scanners at once: ``` php artisan scalpel:scan ``` Create a filesystem baseline snapshot: ``` php artisan scalpel:baseline ``` Compare current state against the baseline: ``` php artisan scalpel:diff ``` That's it. Three commands to audit your entire project for intrusion evidence. > **Important:** Always run `vendor:publish` and complete your initial setup **before** running `scalpel:baseline`. The baseline should capture your application's known-good state after all configuration is in place. --- ๐Ÿ“– Command Reference ------------------- [](#-command-reference) ### `scalpel:scan` [](#scalpelscan) Run one or more scanners against your project. ``` # Run all scanners php artisan scalpel:scan # Run specific scanners only php artisan scalpel:scan --only=structural,obfuscated # Output results as JSON (for machine consumption) php artisan scalpel:scan --format=json ``` **Options:** OptionDescription`--only`Comma-separated list of scanners to run: `structural`, `obfuscated`, `htaccess`, `env``--format`Output format: `table` (default) or `json`**Exit codes:** CodeMeaning`0`No findings (clean)`1`Findings detected (CRITICAL or HIGH)`2`Findings detected (MEDIUM or LOW only)--- ### `scalpel:baseline` [](#scalpelbaseline) Create a snapshot of your project's current filesystem state. This snapshot is stored at the path configured in `scalpel.baseline_path` (default: `storage/app/private/scalpel/baseline.json`). ``` # Create a baseline (fails if one already exists) php artisan scalpel:baseline # Overwrite an existing baseline php artisan scalpel:baseline --force ``` **Options:** OptionDescription`--force`Overwrite an existing baseline file--- ### `scalpel:diff` [](#scalpeldiff) Compare the current filesystem state against a previously created baseline snapshot. Reports added, removed, and modified files. ``` # Compare against baseline php artisan scalpel:diff # Output diff as JSON php artisan scalpel:diff --format=json ``` **Options:** OptionDescription`--format`Output format: `table` (default) or `json`**Exit codes:** Same as `scalpel:scan`. --- ๐Ÿ” How It Works -------------- [](#-how-it-works) Laravel Scalpel ships with five independent scanners. Each focuses on a specific class of intrusion evidence. ### Structural Anomaly Scanner [](#structural-anomaly-scanner) Detects PHP files in directories where they should never exist โ€” `public/`, `storage/`, `bootstrap/cache/`, and any other paths you define as "non-PHP zones." Attackers commonly drop webshells into public-facing directories disguised as image folders (e.g., `public/icons/shell.php`). This scanner catches them. - Scans all configured `non_php_zones` for `.php` files - Automatically excludes known legitimate files (`public/index.php`) and directories (`public/vendor/`) - Configurable allow-lists for both files and directories ### Obfuscated Code Scanner [](#obfuscated-code-scanner) Detects common PHP obfuscation patterns used in backdoors and webshells. Scans all `.php` files in the project for: PatternDescriptionSeverity`eval(base64_decode)`Classic obfuscation โ€” decode and executeCRITICAL`eval(gzinflate)`Compressed payload executionCRITICAL`eval(str_rot13)`ROT13 obfuscation with evalCRITICAL`eval(gzuncompress)`Compressed payload execution (variant)CRITICAL`eval(gzdecode)`Compressed payload execution (variant)CRITICAL`assert()` with varsDynamic code execution via assertHIGHVariable functions`$var()` style dynamic function callsMEDIUM`preg_replace` `/e`Code execution via deprecated regex modifierHIGHLong encoded stringsSuspiciously long base64/hex strings (โ‰ฅ500 chars)MEDIUMEach pattern can be individually toggled in the configuration. ### Htaccess Scanner [](#htaccess-scanner) Scans all `.htaccess` files in your project for dangerous directives that could allow execution of non-PHP scripts. Attackers often modify `.htaccess` to register Python, Perl, or CGI handlers, enabling them to run arbitrary scripts through the web server. Detects: - `AddHandler` directives mapping to dangerous script types - `AddType` directives mapping to dangerous MIME types - Custom handler registrations for `cgi-script`, `python-program`, `perl-script`, etc. ### Baseline Diff Scanner [](#baseline-diff-scanner) Creates a cryptographic snapshot of your entire project filesystem and detects changes over time. This is your "known good state" mechanism. **Workflow:** 1. Run `php artisan scalpel:baseline` after a clean deployment 2. Run `php artisan scalpel:diff` periodically or in CI to detect unauthorized changes 3. Added, removed, or modified files are reported with severity ratings Baseline snapshots exclude volatile directories like `storage/logs/`, `storage/framework/cache/`, and other paths configured in `baseline_excluded_paths`. ### Env Integrity Scanner [](#env-integrity-scanner) Verifies the existence and basic integrity of your `.env` file. Attackers sometimes delete or truncate the `.env` file to disable error reporting, remove debug information, or reset application keys. Checks: - `.env` file exists - `.env` file is not empty - `.env` file is readable --- โš™๏ธ Configuration Reference -------------------------- [](#๏ธ-configuration-reference) After publishing, the configuration file lives at `config/scalpel.php`. Below is a reference for every key. ### `non_php_zones` [](#non_php_zones) Directories where PHP files should not exist. Relative to the project root. ``` 'non_php_zones' => [ 'public', 'storage', 'bootstrap/cache', ], ``` ### `structural_allowed_files` [](#structural_allowed_files) Individual files within non-PHP zones that are known to be legitimate. Relative to the project root. ``` 'structural_allowed_files' => [ 'public/index.php', ], ``` ### `structural_allowed_directories` [](#structural_allowed_directories) Subdirectories within non-PHP zones where PHP files are expected (e.g., published assets). ``` 'structural_allowed_directories' => [ 'public/vendor', ], ``` ### `excluded_paths` [](#excluded_paths) Paths to exclude from **all** scanners. Relative to the project root. ``` 'excluded_paths' => [ 'vendor', 'node_modules', '.git', ], ``` ### `obfuscation_patterns` [](#obfuscation_patterns) Toggle individual obfuscation detection patterns on or off. ``` 'obfuscation_patterns' => [ 'eval_base64_decode' => true, 'eval_gzinflate' => true, 'eval_str_rot13' => true, 'eval_gzuncompress' => true, 'eval_gzdecode' => true, 'assert_dynamic' => true, 'variable_functions' => true, 'preg_replace_e' => true, 'long_encoded_string' => true, ], ``` ### `long_string_threshold` [](#long_string_threshold) Minimum character length for a string to be flagged as a suspiciously long encoded payload. ``` 'long_string_threshold' => 500, ``` ### `htaccess_dangerous_handlers` [](#htaccess_dangerous_handlers) Script handlers and MIME types that are flagged when found in `.htaccess` directives. ``` 'htaccess_dangerous_handlers' => [ 'cgi-script', 'python-program', 'perl-script', 'ruby-script', 'application/x-httpd-python', 'application/x-httpd-perl', 'application/x-httpd-ruby', 'application/x-httpd-cgi', ], ``` ### `baseline_excluded_paths` [](#baseline_excluded_paths) Additional paths excluded from baseline snapshots and diff comparisons (on top of `excluded_paths`). ``` 'baseline_excluded_paths' => [ 'storage/logs', 'storage/framework/cache', 'storage/framework/sessions', 'storage/framework/views', 'storage/app/private/scalpel', ], ``` ### `baseline_path` [](#baseline_path) Where the baseline snapshot JSON file is stored, relative to `storage/app/private/` (or `storage/app/` depending on your local disk configuration). ``` 'baseline_path' => 'scalpel/baseline.json', ``` ### `severity_threshold` [](#severity_threshold) Minimum severity level to include in results. Findings below this level are silently filtered out. Options: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`. ``` 'severity_threshold' => 'LOW', ``` --- ๐Ÿ”„ CI/CD Integration ------------------- [](#-cicd-integration) Laravel Scalpel uses exit codes to signal results, making it straightforward to integrate into CI/CD pipelines. ### GitHub Actions Example [](#github-actions-example) ``` name: Security Scan on: push: branches: [main] pull_request: branches: [main] schedule: - cron: '0 6 * * *' # Daily at 6 AM UTC jobs: scalpel-scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.2' - name: Install Dependencies run: composer install --no-interaction --prefer-dist - name: Run Scalpel Scan run: php artisan scalpel:scan --format=json - name: Run Baseline Diff run: php artisan scalpel:diff --format=json ``` > **Tip:** Store a baseline snapshot in your repository (or generate it during deployment) so `scalpel:diff` can detect unauthorized post-deployment changes. Known False Positives --------------------- [](#known-false-positives) **`bootstrap/cache/` files modified or deleted**These files are regenerated by Laravel when running `php artisan optimize`or `php artisan optimize:clear`. If you see changes here after running these commands, it is expected. If you see changes without having run these commands, investigate immediately. Recommended Workflow -------------------- [](#recommended-workflow) 1. Deploy new code 2. Run `php artisan optimize` 3. Run `php artisan scalpel:baseline --force` This ensures the baseline always reflects the post-deployment known-good state. Automation & Monitoring --------------------------- [](#automation--monitoring) Pair Laravel Scalpel with [n8n-bastion](https://github.com/hryagstn/n8n-bastion)for automated scheduled scanning and real-time Telegram alerts when CRITICAL or HIGH findings are detected on your VPS. --- ๐Ÿ›ก๏ธ Security Model & Limitations ----------------------------------- [](#๏ธ-security-model--limitations) ### Trust Boundary & Process Space [](#trust-boundary--process-space) Laravel Scalpel is designed as a **detection layer**, not a **containment layer**. Because it runs as a PHP Artisan command within your application's environment: - It runs with the same operating system user and permissions as your web server/PHP process. - It shares the same memory space and filesystem access. - It operates within the same trust boundary as the application code it is inspecting. ### What This Means in Practice [](#what-this-means-in-practice) If an attacker achieves arbitrary code execution with the ability to write to the filesystem: - They could theoretically modify the Laravel Scalpel source files or configuration to suppress scan results. - They could intercept or delete logs before they are reported. - They could tamper with the generated JSON reports to hide signs of intrusion. This is an inherent limitation of *any* in-process security scanner and is not unique to Laravel Scalpel. ### Recommended Production Mitigations [](#recommended-production-mitigations) To run Laravel Scalpel securely in production environments, pair it with standard infrastructure-level hardening: 1. **External Scan Triggers:** Instead of relying on web-accessible triggers, trigger scans externally via a secure task runner (e.g., system `cron` or the [n8n-bastion](https://github.com/hryagstn/n8n-bastion) `sentinel.sh` pattern) running under a different user namespace. 2. **Infrastructure Isolation:** Use read-only filesystems (e.g., in Docker containers) for code zones (`app/`, `bootstrap/`, `config/`, `public/`) so attackers cannot write new files or tamper with existing code, making Laravel Scalpel scans highly predictable and robust. 3. **Decoupled Output Channels:** Save outputs to write-once/read-many logs or stream findings immediately to an external log ingestion endpoint. 4. **"Smoke Alarm" Mindset:** Treat Laravel Scalpel as a lightweight, early-warning "smoke alarm" to trigger quick alerts rather than a replacement for network firewalls, OS-level file integrity monitoring (FIM), or WAF policies. ### Output Integrity via HMAC Signing [](#output-integrity-via-hmac-signing) To prevent tampering with scan reports in transit between execution and delivery to log consumers (such as an external webhook or monitoring agent), Laravel Scalpel includes built-in HMAC signing for JSON outputs. #### How It Works [](#how-it-works) When enabled, Laravel Scalpel generates an `HMAC-SHA256` signature of the canonical JSON output payload and appends it as a top-level `"signature"` field. - **What it protects against:** Tampering with the report payload *after* generation (e.g., intercepting and modifying the report on disk or in transit). - **What it does NOT protect against:** An attacker with root/write privileges disabling the scan entirely, or extracting the signing key from the environment if the key is stored inside the compromised server. #### Configuration & Usage [](#configuration--usage) Enable signing in your `config/scalpel.php` or `.env` file: ``` SCALPEL_SIGNING_ENABLED=true SCALPEL_SIGNING_KEY=your-secure-signing-secret-key-change-me ``` > **Warning:** The `SCALPEL_SIGNING_KEY` should **never** default to or share the same value as your `APP_KEY`. Keep it isolated. Ideally, inject this key into the runtime environment via a secrets manager or deployment pipeline rather than committing it to a local `.env` file. When you run a scan, the JSON output will include a signature: ``` php artisan scalpel:scan --format=json ``` Output: ``` { "total": 0, "findings": [], "signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ``` #### Verifying Signatures [](#verifying-signatures) You can verify the integrity of a scan output file using the `scalpel:verify` Artisan command: ``` # Verify a file php artisan scalpel:verify storage/scalpel-output.json # Verify via stdin cat storage/scalpel-output.json | php artisan scalpel:verify - ``` If the payload is authentic and untampered, the command will output a success message and exit with status code `0`. If the signature is invalid, missing, or the payload was tampered with, it will output an error and exit with status code `1`. #### Pairs Well with n8n-bastion [](#pairs-well-with-n8n-bastion) If you are using [n8n-bastion](https://github.com/hryagstn/n8n-bastion), you can extend the `sentinel.sh` runner script to verify output integrity before sending findings to your webhooks. For example, modify your cron execution script: ``` # Run scan and save output php artisan scalpel:scan --format=json > /tmp/scalpel-output.json # Verify signature before dispatching if php artisan scalpel:verify /tmp/scalpel-output.json; then # Send verified payload to n8n webhook curl -X POST https://your-n8n-bastion-domain.com/webhook/scalpel-alert \ -H "Content-Type: application/json" \ -d @/tmp/scalpel-output.json else # Signature failed - report tamper alert immediately! curl -X POST https://your-n8n-bastion-domain.com/webhook/scalpel-alert \ -H "Content-Type: application/json" \ -d '{"status": "tampered", "error": "Signature verification failed!"}' fi ``` --- ๐Ÿค Contributing -------------- [](#-contributing) Contributions are welcome! Please read our [contributing guide](CONTRIBUTING.md) to learn how to get started, set up the development environment, and run tests. Please make sure your code follows the existing style and includes appropriate tests. --- ๐Ÿ“„ License --------- [](#-license) Laravel Scalpel is open-sourced software licensed under the [MIT License](LICENSE). ### Health Score 45 โ€” FairBetter than 91% of packages Maintenance93 Actively maintained with recent releases Popularity21 Limited adoption so far Community7 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~4 days Total 8 Last Release 35d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/af56733738c9a9dd43633fbfd1ee9dab4c09ea41182bf5d18701af52b1e2fb0a?d=identicon)[hryagstn](/maintainers/hryagstn) --- Top Contributors [![hryagstn](https://avatars.githubusercontent.com/u/204626097?v=4)](https://github.com/hryagstn "hryagstn (28 commits)") --- Tags filesystemlaravelsecurityscannerobfuscationbackdoorintrusion-detection ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/hryagstn-laravel-scalpel/health.svg) ``` [![Health](https://phpackages.com/badges/hryagstn-laravel-scalpel/health.svg)](https://phpackages.com/packages/hryagstn-laravel-scalpel) ``` ### Alternatives [laravel/ai The official AI SDK for Laravel. 1.0k3.2M246](/packages/laravel-ai)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9762.4M133](/packages/roots-acorn)[unisharp/laravel-filemanager A file upload/editor intended for use with Laravel 5 to 10 and CKEditor / TinyMCE 2.2k3.5M86](/packages/unisharp-laravel-filemanager)[propaganistas/laravel-disposable-email Disposable email validator 6023.0M7](/packages/propaganistas-laravel-disposable-email)[psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)