Laravel Security Check Laravel Package

Getting Started

leonardolima/laravel-security-check is a configuration linter, not a vulnerability scanner. It inspects your Laravel app's runtime config (debug flags, session/cookie settings, env values, headers, etc.) and reports settings that are unsafe for production. Treat it as a pre-flight checklist for APP_ENV=production, not as a substitute for composer audit or a full scanner like Enlightn.

Minimal steps:

1. Install as a dev dependency so it never ships to production, pinned exactly (the package is young and its API is still moving — see the 1.0.1 note below):

   composer require --dev leonardolima/laravel-security-check:1.0.1
   

2. Discover the registered command rather than guessing its name (packages of this type vary):

   php artisan list | grep -i security
   

   It is almost always a security:*-prefixed command that accepts an --env option.
3. Publish the config if a publishable tag exists:

   php artisan vendor:publish --tag=security-check-config
   

   Inspect the published file before trusting defaults — the list of checks and their severity thresholds is what you will actually tune.
4. Run it against a real environment, not your local .env:

   php artisan security:check --env=production
   

First use case: run it once on an existing/legacy project before a release. The highest-value catches are usually APP_DEBUG=true leaking stack traces, SESSION_SECURE_COOKIE unset, APP_KEY missing/blank, and permissive CORS/session settings. Read the output like a diff against a hardened baseline, not a pass/fail grade.

Release 1.0.1 at a glance: the only change is a class-rename cleanup ("Melhoria no nome das class"). There are no new checks, options, or config keys — the CLI surface is unchanged, so nothing in the commands above moves. The one thing that can move is PHP-level references: if you extended a check class, type-hinted against one, or registered a custom check by FQCN, re-verify those names after upgrading. Renames landing in a patch release is a signal to pin exact versions rather than using ^1.0.

Implementation Patterns

CI gate on deploy. Run the check as a build step after the environment is configured but before traffic is shifted, and fail on a non-zero exit code:

- run: composer install --no-interaction
- run: php artisan config:clear && php artisan security:check --env=production

Keep it in a job that installs dev dependencies; if you use composer install --no-dev in production images, copy the package in a separate build stage or run the check on a staging target instead.

Validate prod config from the safety of your machine. Because the command reads config for a given env, you can audit the production config locally by exporting the same variables (or by --env=production with a committed, non-secret config) — useful for reviewing a teammate's infra PR without deploying.

Composer script for consistency:

"scripts": {
  "security:check": "php artisan config:clear && php artisan security:check --env=production"
}

Everyone runs the same entry point and gets the same exit code, which is what CI consumes.

Regression baseline. Capture the current (clean) output and diff subsequent runs. Any new finding becomes a review item; this turns the tool into a config regression test rather than a one-off audit. Run it on a schedule (e.g. nightly via the scheduler or a cron CI job) so drifting config is caught between releases.

Pair with complementary checks in the same CI job: composer audit for dependency advisories, php artisan about to snapshot the resolved config, and if it exposes a check registry, register a custom check for org-specific rules (required security headers, enforced cookie domain, disallowed drivers).

Custom checks need an upgrade pass. If you implement the package's check interface, keep those classes in your own namespace with your own names and don't subclass the package's concrete checks — then a rename inside the package can't break your registration. After any bump (including 1.0.1), run the full suite once and confirm your custom checks still execute; a silent registration miss looks identical to a pass.

Report, don't just fail. Pipe the output into a PR comment or build artifact. A human-readable list of findings with the offending config key is more actionable than a red X, and it documents why the gate exists for future contributors.

Gotchas and Tips

• config:clear before running. If you changed .env or run with --env, a cached config (config:cache) will serve stale values and the check will validate the wrong thing. This is the single most common source of confusing results.
• Env value parsing. APP_DEBUG=false is a string until Laravel casts it; checks that compare against real booleans can behave differently depending on how the value is read. Verify a known-bad setting actually fails before trusting a passing run.
• Local false positives. HTTPS, secure cookies, and HSTS are meaningless with APP_ENV=local/testing. Scope the command to production environments in CI and document that local failures are expected — otherwise developers start ignoring the output.
• It is not a vulnerability scanner. It cannot see outdated packages, known CVEs, or logic flaws. Do not let a green run stand in for composer audit, dependency pinning, or code review.
• Dev-dependency placement. A --dev install means the command does not exist in a --no-dev prod image. If your deploy runs the check on the production host, either install it there deliberately or run the check in a pre-deploy stage that has dev dependencies.
• Exit codes matter for CI. Confirm the command returns non-zero when findings exceed your severity threshold; some setups only print warnings. Set the failure threshold in the published config rather than via CLI flags so it is version-controlled.
• Class renames in patch releases (1.0.1). "Melhoria no nome das class" changes class names but ships as 1.0.1. Composer's autoloader hides this at runtime, so the failure mode is a fatal class not found or a silently skipped custom check — not a Composer conflict. Pin an exact version ("leonardolima/laravel-security-check": "1.0.1"), read the diff before bumping, and treat ^1.0 as unsafe until the API settles.
• Low adoption — pin and review. With ~0 dependents and a changelog measured in single lines, skim the source before relying on it in a gate. The check list is small enough to audit in minutes, which also tells you exactly which config keys it covers and which it silently ignores.
• Extension point. If the package exposes a check interface/registry, implement org-specific checks there behind your own stable class names rather than forking or subclassing internals. If it does not, keep custom rules as a thin wrapper script that runs the package plus your own assertions.