Laravel Vigil

Laravel Vigil is a static security analysis tool for Laravel applications, written in Go. It scans your project for misconfigurations, vulnerabilities, exposed secrets, and insecure coding patterns — in seconds, with zero dependencies.

---

Features

• Fast: Written in Go — scans a typical Laravel project in under 2 seconds.
• Comprehensive: Checks .env, config files, Composer dependencies, and PHP source code.
• Extensible: Add custom rules in plain YAML — no code required.
• CI/CD-ready: Outputs JSON, SARIF, Markdown, and HTML reports. Integrates with GitHub Actions, GitLab CI, and more.
• Baseline support: Suppress known/accepted findings so only new issues are reported.
• Docker-first: Ships as a minimal (~4 MB) Docker image built on scratch.

---

What Does It Check?

Laravel Vigil runs 30+ checks across the following categories:

Category	Examples
Environment (.env)	APP_DEBUG=true, empty APP_KEY, empty DB_PASSWORD, insecure SESSION_DRIVER
Config (config/*.php)	Hardcoded debug, insecure cookie flags, CORS wildcard, hardcoded passwords
Dependencies	Known CVEs in composer.lock via OSV.dev (Packagist ecosystem)
Injections	SQL injection (DB::raw, whereRaw), command injection (shell_exec), code execution (eval)
XSS	Unescaped Blade output {!! !!} with user-controlled variables
CSRF	Forms missing @csrf directive
Secrets	Hardcoded API keys, passwords, tokens in source code
Cryptography	Use of weak algorithms: MD5, SHA1
Debug artifacts	dd(), dump(), phpinfo() left in production code
Mass assignment	Dangerous use of $request->all() with create()/update()

---

Installation

Docker (Recommended)

docker pull filastudio/laravel-vigil-scanner:latest

Go

If you have Go 1.21+ installed:

go install github.com/filastudio/laravel-vigil-scanner@latest

Build from Source

git clone https://github.com/filastudio/laravel-vigil-scanner.git
cd laravel-vigil-scanner
make build

---

Usage

Quick Start (Docker)

Mount your Laravel project directory into the container and run:

docker run --rm -v $(pwd):/app:ro filastudio/laravel-vigil-scanner:latest

Save Reports

mkdir reports
docker run --rm \
  -v $(pwd):/app:ro \
  -v $(pwd)/reports:/reports \
  filastudio/laravel-vigil-scanner:latest \
  scan . --output json,sarif,markdown,html --output-dir /reports

CLI Reference

vigil scan [path] [flags]

Flags:
  -o, --output string        Output formats, comma-separated: console,json,sarif,markdown,html
      --output-dir string    Directory to write report files (default ".")
      --min-severity string  Minimum severity to report: info,low,medium,high,critical (default "info")
      --fail-on string       Exit with code 1 if findings at this severity or above exist
      --disable string       Comma-separated list of scanners to disable
      --rules-dir string     Path to custom YAML rules directory
      --baseline string      Path to baseline file to suppress known findings
      --update-baseline      Add all current findings to the baseline
      --branch string        Git branch to scan (for remote repositories only)

Scan a Remote Repository

vigil scan https://github.com/user/laravel-app
vigil scan https://github.com/user/laravel-app --branch develop

Initialize Configuration

vigil init

This creates .vigil/config.yaml and .vigil/rules/custom.yaml in your project.

Baseline — Suppress Known Findings

# Step 1: Run scan and save all current findings to a baseline
vigil scan . --update-baseline --baseline .vigil-baseline.json

# Step 2: Future scans will suppress those findings
vigil scan . --baseline .vigil-baseline.json

# View all suppressed findings
vigil baseline show --baseline .vigil-baseline.json

---

Custom Rules

Extend Vigil with your own YAML rules. Create a directory (e.g., .vigil/rules) and pass it via --rules-dir.

Example rule (.vigil/rules/custom.yaml):

rules:
  - id: TEAM-001
    title: "Usage of deprecated facade"
    description: "MyLegacyFacade is deprecated and should not be used."
    severity: "low"
    category: "Best Practice"
    enabled: true
    patterns:
      - type: "contains"
        target: "php-files"
        pattern: "MyLegacyFacade::"
    remediation: "Replace MyLegacyFacade with NewFacade."

Run with custom rules:

vigil scan . --rules-dir .vigil/rules

---

CI/CD Integration

GitHub Actions

Add the following workflow to your Laravel project at .github/workflows/security-scan.yml:

name: Laravel Security Scan

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  security-scan:
    name: Laravel Vigil
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Laravel Vigil
        run: |
          docker run --rm \
            -v "${{ github.workspace }}:/app:ro" \
            -v "${{ github.workspace }}/reports:/reports" \
            filastudio/laravel-vigil-scanner:latest \
            scan . \
            --output json,sarif,markdown \
            --output-dir /reports \
            --fail-on high

      - name: Upload SARIF to GitHub Security tab
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: reports/vigil-report.sarif

      - name: Upload report artifact
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: vigil-security-report
          path: reports/

Findings will appear in the Security → Code scanning alerts tab of your repository.

GitLab CI

vigil-security-scan:
  image: docker:latest
  services:
    - docker:dind
  script:
    - mkdir -p reports
    - docker run --rm
        -v "$CI_PROJECT_DIR:/app:ro"
        -v "$CI_PROJECT_DIR/reports:/reports"
        filastudio/laravel-vigil-scanner:latest
        scan . --output json,sarif --output-dir /reports --fail-on high
  artifacts:
    paths:
      - reports/
    when: always

---

Available Scanners

Scanner	Description
env-scanner	Checks .env file for dangerous settings
config-scanner	Checks config/*.php for insecure configuration
dependency-scanner	Checks composer.lock against OSV.dev CVE database
rules-scanner	Applies built-in and custom YAML rules to PHP source files

Disable specific scanners:

vigil scan . --disable dependency-scanner,config-scanner

---

Output Formats

Format	Description
console	Colored terminal output (default)
json	Machine-readable JSON (vigil-report.json)
sarif	SARIF 2.1.0 for GitHub/GitLab Security tabs (vigil-report.sarif)
markdown	Markdown report (vigil-report.md)
html	Self-contained HTML report with dark theme (vigil-report.html)

---

Docker Compose

services:
  vigil:
    image: filastudio/laravel-vigil-scanner:latest
    volumes:
      - ./:/app:ro
      - ./reports:/reports
    command: scan . --output json,html --output-dir /reports

---

License

Laravel Vigil is released under the MIT License.