README

Laravel Shield Scanner is a security-first Laravel package designed to proactively scan your application for malware, web shells, and suspicious PHP code. It leverages heuristic analysis and offers seamless antivirus integration for enhanced protection. This package is built for a range of hosting environments—shared hosting, VPS, Windows, Linux—and prioritizes safe, reversible actions.

No silent deletes. No unsafe installs. No fake “PHP antivirus” claims.

🔥 Why Laravel Shield Scanner?

Most Laravel security tools are limited to:

• Dependency scanning
• Configuration validation
• File name blacklists
• Blind file deletion

Laravel Shield Scanner sets itself apart by:

• Scanning actual file contents
• Detecting suspicious behaviors, not just names
• Safely quarantining instead of deleting
• Functioning even without antivirus installed

✨ Features

Laravel Shield Scanner offers a robust suite of security features tailored for real-world use.

🔍 Heuristic Malware Detection

• Identifies both common and advanced PHP web shells:
  • Adminer
  • Tiny File Manager
  • WSO
  • c99 / r57
• Flags code obfuscation techniques:
  • Chains of base64, gzinflate
  • Abuse of rot13, URL decoding
• Detects dangerous behaviors:
  • Use of eval, assert, system, shell_exec
  • Dynamic execution from user input
• Ignores file names—focuses on content and behavior

🦠 Optional Antivirus Integration

• Automatic detection and integration with:
  • ClamAV (Linux)
  • Maldet (Linux)
  • Windows Defender (Windows)
• Antivirus is optional; heuristic scanning is always active
• No auto-install, no root access required
• Safe for shared hosting

🧺 Safe Quarantine System (Recycle-Bin Style)

• Suspicious files are moved, not deleted
• Original path is preserved for restoration
• PHP execution is blocked (via .htaccess)
• Files are restorable—no permanent loss

♻️ Restore Support

• Restore all quarantined files
• Files return to exact original locations
• Same filename, same content

📄 Daily Isolated Logs

• Logs are written per day
• Logs are outside Laravel’s default log
• Structured JSON format for auditability

⚙️ Smart Installer

• Creates config if missing
• Merges only missing keys (preserves user settings)
• Prepares required directories
• Never overwrites user settings

📦 Installation

Install the package using Composer:

composer require laravel-shield/scanner

Laravel will auto-discover the service provider.

🚀 Quick Start (Recommended)

1️⃣ Run the Smart Installer

php artisan shield:install

This will:

• Create config/shield.php if missing
• Merge missing config keys if outdated
• Create required directories:
  • storage/laravel-shield-quarantine
  • storage/logs/laravel-shield

2️⃣ Run a Full Security Scan

php artisan shield:scan

🧪 Available Commands

• 🔍 Full Security Scan

  • php artisan shield:scan
    • Performs heuristic malware scan
    • Runs antivirus scan (if available)
    • Optionally quarantines suspicious files
    • Writes a daily log file

• 🦠 Antivirus Status

  • php artisan shield:av:status
    • Lists available antivirus engines
    • Provides installation guidance
    • Does not install anything automatically

• 🔄 Update Antivirus Definitions

  • php artisan shield:av:update
    • Safely updates virus definitions
    • Skips if antivirus is not installed

• ♻️ Restore Quarantined Files

  • php artisan shield:quarantine:restore
    • Restores all quarantined files to their original paths

• 🛠️ Smart Installer

  • php artisan shield:install
    • One-time setup command
    • Safe to re-run—never overwrites user config

⚙️ Configuration

The configuration file is located at: config/shield.php

Default configuration:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | File extensions to scan
    |--------------------------------------------------------------------------
    */
    'scan_extensions' => [
        'php', 'phtml', 'php5', 'php7', 'phar'
    ],

    /*
    |--------------------------------------------------------------------------
    | Enable or disable quarantine
    |--------------------------------------------------------------------------
    */
    'quarantine_enabled' => true,

    /*
    |--------------------------------------------------------------------------
    | Quarantine directory
    |--------------------------------------------------------------------------
    */
    'quarantine_path' => storage_path('laravel-shield-quarantine'),

    /*
    |--------------------------------------------------------------------------
    | Paths to ignore during scanning
    |--------------------------------------------------------------------------
    */
    'ignore_paths' => [
        'vendor', 'node_modules',
    ],

    /*
    |--------------------------------------------------------------------------
    | Daily log file path
    |--------------------------------------------------------------------------
    */
    'log_path' => storage_path('logs/laravel-shield/laravel-shield-' . date('Y-m-d') . '.log'),
];

Important: Adjust ignore_paths in config/shield.php to exclude folders you do not want scanned, and remove folder names from this list if you later want them scanned. If your vendor packages legitimately use functions like eval, consider setting 'quarantine_enabled' => false. This helps avoid quarantining those files by mistake.

🧺 Quarantine System (Details)

• Files are moved, not deleted
• PHP execution is blocked using a universal .htaccess
• Directory listing is disabled
• Restore metadata is stored in a manifest

Example structure:

storage/laravel-shield-quarantine/
├── .htaccess
├── index.html
└── 2026-01-24/
    ├── files/
    │   └── public_evil.php
    └── manifest.json

📄 Logs

Logs are written daily to:

storage/logs/laravel-shield/
└── laravel-shield-YYYY-MM-DD.log

Each log entry includes:

• Scan timestamp
• Severity level
• Detection reasons
• File hash (SHA256)
• Detection engine used

🖥️ Platform Support

⚠️ Security Disclaimer

No scanner can guarantee 100% detection. Laravel Shield Scanner:

• Detects common and advanced PHP malware
• Uses behavior-based heuristics
• Integrates real antivirus engines

It does NOT replace:

• Firewalls
• WAFs
• OS-level security
• Secure development practices

Always follow security best practices.

🤝 Contributing

Contributions are welcome! You can:

• Suggest detection improvements
• Help reduce false positives
• Add new antivirus integrations
• Improve documentation

Open an issue or submit a pull request.

📜 License

MIT License
Free for personal and commercial use.

⭐ Philosophy

Laravel Shield Scanner follows one rule:

Security should protect — not surprise.

No destructive actions. No hidden behavior. Full control for developers.

🏗️ Process Overview

Below is a simplified flowchart of the scanning and quarantine process:

flowchart TD
    A[User Runs Scan Command] --> B[Heuristic Malware Scan]
    B --> C{Suspicious File Found}
    C -- Yes --> D[Quarantine File]
    C -- No --> E[Continue Scanning]
    D --> F[Log Detection]
    E --> F
    F --> G{Antivirus Integration Available}
    G -- Yes --> H[Run Antivirus Scan]
    G -- No --> I[Finish]
    H --> I

🗃️ Quarantine and Restore Process

flowchart TD
    Q[File Flagged as Suspicious] --> R[Move to Quarantine Directory]
    R --> S[Block PHP Execution via .htaccess]
    S --> T[Store Restore Metadata]
    T --> U[User Runs Restore Command]
    U --> V[Return File to Original Path]
    V --> W[Remove Quarantine Metadata]

📝 Key Takeaways

{
    "title": "Non-Destructive Scanning",
    "content": "All actions are reversible. No files are deleted without your explicit approval."
}

{
    "title": "Real-World Hosting Ready",
    "content": "Safe for use on shared hosting, Linux, Windows, and macOS (with limitations)."
}

{
    "title": "No Hidden Behavior",
    "content": "No silent deletes or destructive actions. Full logs and quarantine support."
}

Enjoy peace of mind with Laravel Shield Scanner: security that protects, not surprises.