Vigil scans your application for common vulnerabilities and misconfigurations. 15 built-in checks, a 0–100 security score, and an optional Filament v5 dashboard.
Automate the tedious task of securing Laravel applications. Stop doing manual security reviews and let Vigil do the heavy lifting.
Comprehensive checks grouped into 5 categories: filesystem, configuration, HTTP headers, dependencies, and extended checks.
Scans your codebase for hardcoded API keys, passwords, and tokens. Smart env() filtering reduces false positives.
Get a security score from 0 to 100 based on your check results. Track your progress over time and identify areas for improvement.
Generate SHA-256 baselines of your public files and detect unauthorized modifications on subsequent scans.
An optional, beautiful Filament v5 dashboard with scan history, score widgets, and one-click scanning for teams.
Create custom security checks by implementing the SecurityCheck interface. Register them in a service provider.
Use --fail-on=critical,high to exit with code 1 when vulnerabilities are found. Works with GitHub Actions, GitLab CI, Jenkins.
Output results as a human-readable table or machine-readable JSON. Write reports to files for archiving or compliance.
Store scan results in your database with configurable retention periods. Track security trends over time automatically.
After installing the package, a single Artisan command gives you a complete security overview. Use --detailed to see exact file paths, line numbers, and actionable fix suggestions.
Each check is tuned to avoid false positives. The secret scanner understands env() calls.
Failed checks include the exact file, line number, and a concrete fix suggestion.
File scanning respects size limits so it won't choke on large codebases.
Every check ships enabled by default (except file integrity, which requires a baseline). Enable or disable individual checks in config/vigil.php.
For teams using Filament v5, Vigil ships with a complete dashboard panel. Monitor your security posture visually, track trends over time, and trigger scans directly from the browser.
Laravel Vigil requires a modern PHP and Laravel environment. The Filament dashboard integration is entirely optional.
| Dependency | Version | Required |
|---|---|---|
| PHP | 8.2+ | Yes |
| Laravel | 11.x or 12.x | Yes |
| Filament | 5.x | Optional |
Install the package via Composer. The service provider registers automatically via Laravel's package auto-discovery.
composer require filastudio/laravel-vigilPublish the configuration file to customize which checks are enabled and adjust behavior:
php artisan vendor:publish --tag=vigil-configIf you want to store scan history in the database, publish and run the migrations:
php artisan vendor:publish --tag=vigil-migrations
php artisan migrateThis creates vigil_scans and vigil_check_results tables. Old records are cleaned up automatically based on the retention setting in config.
The published config/vigil.php file allows you to enable or disable individual checks and customize scanning behavior:
return [
// Enable or disable individual checks
'checks' => [
'fs.public_folder' => true,
'fs.malicious_js' => true,
'fs.storage_dangerous' => true,
'fs.permissions' => true,
'fs.sensitive_exposure' => true,
'cfg.php_ini' => true,
'cfg.env' => true,
'cfg.session' => true,
'cfg.cors' => true,
'http.headers' => true,
'dep.composer_audit' => true,
'ext.hardcoded_secrets' => true,
'ext.debug_routes' => true,
'ext.telescope_debugbar' => true,
'ext.file_integrity' => false, // Requires baseline
],
// Allowed file extensions in public directory
'public_allowed_extensions' => [
'css', 'js', 'jpg', 'jpeg', 'png', 'gif', 'svg', 'webp',
'ico', 'woff', 'woff2', 'ttf', 'eot', 'pdf', 'map', 'txt',
],
// Store scan results in database
'store_results' => true,
// Retention period for scan results (days)
'results_retention_days' => 90,
// Notification settings (future feature)
'notifications' => [
'enabled' => false,
'channels' => ['mail'],
'notify_on_severity' => ['critical', 'high'],
'mail_to' => env('VIGIL_MAIL_TO', null),
],
];The primary command. Runs all enabled checks and prints results as a formatted table. Returns exit code 0 on success and 1 when the --fail-on threshold is triggered.
php artisan vigil:audit| Option | Description |
|---|---|
| --category | Filter by category (e.g. filesystem,configuration) |
| --check | Run specific checks (e.g. fs.public_folder,cfg.env) |
| --fail-on | Exit with code 1 if issues of given severity are found (e.g. critical,high) |
| --format | Output format: table (default) or json |
| --output | Write output to a file path |
| --detailed | Show full context: file paths, line numbers, and fix suggestions |
# Run only filesystem checks
php artisan vigil:audit --category=filesystem
# Run specific checks with detailed output
php artisan vigil:audit --check=fs.public_folder,cfg.env --detailed
# Generate a JSON report file
php artisan vigil:audit --format=json --output=storage/security-report.json
# CI/CD: fail the build on critical or high severity issues
php artisan vigil:audit --fail-on=critical,highGenerates SHA-256 hashes of all files in public/ and storage/app/public/ and saves them to storage/app/vigil_baseline.json. Once a baseline exists, enable the ext.file_integrity check in your config to compare against it on subsequent scans.
php artisan vigil:baselineDisplays all 15 checks with their category, severity, and current enabled/disabled status as configured in config/vigil.php.
php artisan vigil:listYou can run scans directly from your application code by resolving the VigilScanner from the service container:
use FilaStudio\Vigil\VigilScanner;
$scanner = app(VigilScanner::class);
$results = $scanner->run();
foreach ($results as $result) {
echo $result->check . ': ' . $result->status->value . PHP_EOL;
}
// Access the security score
$score = $scanner->score($results); // 0–100You can also filter by category or specific checks:
// Run only filesystem checks
$results = $scanner->run(categories: ['filesystem']);
// Run specific checks
$results = $scanner->run(checks: ['fs.public_folder', 'cfg.env']);Vigil ships with an optional Filament v5 plugin. To enable it, install Filament v5 and register the plugin in your panel provider:
use FilaStudio\Vigil\Filament\VigilPlugin;
public function panel(Panel $panel): Panel
{
return $panel
// ...
->plugin(VigilPlugin::make());
}Publish the Filament views if you want to customize them:
php artisan vendor:publish --tag=vigil-viewsThe plugin adds a Vigil navigation item to your panel with the following pages and widgets:
Create your own security checks by implementing the SecurityCheck interface:
use FilaStudio\Vigil\Contracts\SecurityCheck;
use FilaStudio\Vigil\Data\CheckResult;
use FilaStudio\Vigil\Enums\Severity;
use FilaStudio\Vigil\Enums\CheckStatus;
class MyCustomCheck implements SecurityCheck
{
public function id(): string
{
return 'custom.my_check';
}
public function title(): string
{
return 'My Custom Check';
}
public function category(): string
{
return 'custom';
}
public function severity(): Severity
{
return Severity::High;
}
public function run(): CheckResult
{
// Your check logic here
$passed = true; // replace with actual logic
return new CheckResult(
check: $this->id(),
title: $this->title(),
status: $passed ? CheckStatus::Passed : CheckStatus::Failed,
message: $passed ? 'All good.' : 'Issue found.',
);
}
}Register your custom check in a service provider:
use FilaStudio\Vigil\VigilScanner;
public function boot(): void
{
$this->app->resolving(VigilScanner::class, function (VigilScanner $scanner) {
$scanner->addCheck(new MyCustomCheck());
});
}Vigil uses PHP 8.1+ backed enums for type-safe values throughout the package:
// Severity levels
FilaStudio\Vigil\Enums\Severity::Critical
FilaStudio\Vigil\Enums\Severity::High
FilaStudio\Vigil\Enums\Severity::Medium
FilaStudio\Vigil\Enums\Severity::Low
// Check status
FilaStudio\Vigil\Enums\CheckStatus::Passed
FilaStudio\Vigil\Enums\CheckStatus::Failed
FilaStudio\Vigil\Enums\CheckStatus::Warning
FilaStudio\Vigil\Enums\CheckStatus::SkippedOld scan records are automatically pruned based on the results_retention_days setting in your config. You can also run cleanup manually:
php artisan vigil:cleanupTo schedule automatic cleanup, add it to your routes/console.php (Laravel 11+):
use Illuminate\Support\Facades\Schedule;
Schedule::command('vigil:cleanup')->daily();Use Vigil in your pipeline to automatically fail builds when security vulnerabilities are detected. The --fail-on flag controls which severity levels trigger a non-zero exit code.
Tip: Combine with --format=json --output=report.json to archive security reports as build artifacts.
name: Security Audit
on: [push, pull_request]
jobs:
vigil:
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 Vigil security audit
run: php artisan vigil:audit --fail-on=critical,highsecurity-audit:
image: php:8.2
stage: test
before_script:
- apt-get update && apt-get install -y git unzip
- curl -sS https://getcomposer.org/installer | php
- php composer.phar install --no-interaction
script:
- php artisan vigil:audit --fail-on=critical,high
artifacts:
when: always
paths:
- storage/security-report.jsonpipeline {
agent any
stages {
stage('Install') {
steps {
sh 'composer install --no-interaction'
}
}
stage('Security Audit') {
steps {
sh 'php artisan vigil:audit --fail-on=critical,high'
}
}
}
post {
always {
archiveArtifacts artifacts: 'storage/security-report.json',
allowEmptyArchive: true
}
}
}Install Vigil in seconds and get a complete security overview. Free and open source.