DEV Community

Cover image for Automate Your Laravel Security Audits with Vigil
FilaStudio
FilaStudio

Posted on

Automate Your Laravel Security Audits with Vigil

#laravel #vigil #security #laravelvigil

Keeping a Laravel application secure is a continuous process. From forgetting to turn off debug mode in production to accidentally committing API keys, common misconfigurations can leave your application vulnerable. While manual checks are helpful, they are often time-consuming and prone to human error. This is where automation becomes a developer's best friend.

Introducing Laravel Vigil, an open-source security audit tool designed specifically for Laravel. It scans your application's filesystem, PHP configuration, HTTP headers, and Composer dependencies to identify common vulnerabilities and misconfigurations, helping you proactively secure your projects.

Laravel Vigil

In this article, we'll explore how Laravel Vigil can streamline your security workflow, from local development to CI/CD pipelines.

Why Another Security Scanner?

The Laravel ecosystem has several great security tools. However, Vigil was born from the practical need to automate a recurring checklist of issues frequently encountered across multiple projects. The development philosophy focused on three key areas:

  • Low Noise: Checks are carefully tuned to avoid false positives. For instance, the hardcoded secret scanner is smart enough to recognize and ignore env() helper calls, reducing unnecessary alerts.
  • Actionable Feedback: When a check fails, Vigil provides a clear, detailed report including the exact file and line number, along with a concrete recommendation for fixing the issue.
  • Performance: The tool is designed to be fast and efficient, with features like file size limits during scanning to prevent it from getting bogged down in large codebases.

Core Features at a Glance

Vigil comes packed with 15 built-in checks, a security scoring system, and an optional, elegant Filament v5 dashboard.

Here’s a breakdown of its main capabilities:

Category Description
Filesystem Scanning Scans for malicious JavaScript, dangerous file uploads in storage, incorrect file permissions, and sensitive files (.env, .git) exposed in the public directory.
Configuration Audits Audits php.ini settings, .env configurations (like APP_DEBUG and APP_KEY), session security, and Cross-Origin Resource Sharing (CORS) policies.
HTTP Header Validation Verifies that essential security headers like HSTS, CSP, and X-Frame-Options are correctly implemented.
Dependency Checking Integrates with composer audit to flag any known vulnerable packages in your project.
Advanced Scanning Includes detection for hardcoded secrets, file integrity monitoring against a baseline, and checks for debug routes or tools like Telescope left enabled in production.

Getting Started in Minutes

You can add Vigil to your project using Composer.

composer require filastudio/laravel-vigil
Enter fullscreen mode Exit fullscreen mode

The package’s service provider is registered automatically. To customize the default settings, you can publish the configuration file:

php artisan vendor:publish --tag=vigil-config
Enter fullscreen mode Exit fullscreen mode

If you wish to store scan history in your database, publish the migrations and run them:

php artisan vendor:publish --tag=vigil-migrations
php artisan migrate
Enter fullscreen mode Exit fullscreen mode

Now, you're ready to run your first audit directly from the command line:

php artisan vigil:audit
Enter fullscreen mode Exit fullscreen mode

This command executes all enabled checks and presents the results in a clean, readable table format. For more detailed output, including file paths and fix suggestions, just add the --detailed flag.

php artisan vigil:audit --detailed
Enter fullscreen mode Exit fullscreen mode

Detailed Output

Seamless CI/CD Integration

Vigil is designed to be a part of your automated workflow. You can use the --fail-on flag to set a severity threshold (critical, high, medium). If any check fails at or above the specified level, the command will exit with a non-zero status code, failing your CI/CD pipeline.

Here is an example for GitHub Actions:

- name: Security Audit
  run: php artisan vigil:audit --fail-on=critical,high
Enter fullscreen mode Exit fullscreen mode

This simple addition to your workflow ensures that security regressions are caught before they ever reach production.

The Filament Dashboard

For those who use the excellent Filament admin panel builder, Vigil offers an optional plugin that provides a beautiful dashboard to view and run security audits.

To install it, simply register the plugin in your AdminPanelProvider:

use FilaStudio\Vigil\Filament\VigilPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            VigilPlugin::make(),
        ]);
}
Enter fullscreen mode Exit fullscreen mode

The dashboard provides:

  • A security score widget (0-100).
  • A counter for critical issues.
  • A history of recent scans.
  • A button to trigger new scans directly from the browser.

This makes security monitoring accessible not just to developers, but to the entire team.

Extensible by Design

While Vigil ships with a comprehensive set of checks, every application has unique security requirements. You can easily create your own custom checks by implementing the SecurityCheck interface and registering it within a service provider. This allows you to tailor the audit process to your specific needs, such as ensuring all database connections use SSL in production.

Conclusion

Laravel Vigil offers a powerful, flexible, and developer-friendly way to automate security auditing in your Laravel projects. By integrating it into your daily workflow, you can catch common vulnerabilities early, enforce security best practices, and deploy your applications with greater confidence. Give it a try on your next project!

Check out the project on GitHub to learn more.

Top comments (0)