Laravel Leakproof Laravel Package

Getting Started

• Install as a dev dependency so it never ships to production: composer require --dev mykholy/laravel-leakproof.
• Publish the config first — this is the file you'll actually live in: php artisan vendor:publish --tag=leakproof-config. Start by reading config/leakproof.php to understand which scanners/patterns are enabled.
• Run the scanner once against a clean branch to see the baseline report before you start tuning anything: php artisan leakproof:scan (check php artisan list for the exact command name in your version, since the quick-start docs were corrected in v1.1.0).
• First real use case: run it against the repo you're most worried about — a legacy app with a long-lived .env, committed config files, and a few years of git history — and treat the initial output as a triage list, not a pass/fail gate.
• Look at the scanner's pattern definitions before changing config. Knowing what it matches (and what it deliberately ignores) is the difference between trusting the tool and disabling it after the third false positive.

Implementation Patterns

Local pre-commit gate. Wire the scanner into a git pre-commit hook (or a Husky/CaptainHook task) so a stray sk-... key never reaches the remote. Keep the local run scoped to staged files if the full scan is slow — full scans belong in CI.

CI quality gate. The headline feature of v1.1.0 is release quality gates: run the scan as a dedicated pipeline step and let the non-zero exit code block the build. A typical GitHub Actions shape:

- run: composer install --no-interaction --prefer-dist
- run: php artisan leakproof:scan --ci

Treat this as a separate job from your test suite so a leak failure is obviously a security failure, not a flaky test.

Release/deploy gate. Run the scanner in the deploy pipeline just before artisan config:cache or the release step, so a bad merge can't be promoted. This is where "quality gate" earns its name — it catches secrets that arrived via a merge commit rather than a direct push.

AI credential detection (new in 1.1.0). The new patterns cover AI provider keys (OpenAI/Anthropic-style sk-, sk-ant-, and similar). If your app calls an LLM, this is your highest-value scanner category — those keys are expensive to leak and often pasted into config/, notebooks, seeders, and test fixtures. Add the relevant directories to the scan scope explicitly.

Extension points. Register project-specific patterns (internal API tokens, tenant keys, custom headers) in the config's pattern list rather than writing a bespoke grep script. Keeping everything in one config means one place to audit when your credential formats change.

Baseline + allowlist flow. On adoption in a mature repo: run the scan, review findings, fix the real ones, and allowlist the confirmed-safe placeholders (example, changeme, <your-key-here>). Re-baseline only deliberately — a silently growing allowlist is how scanners die.

Gotchas and Tips

• .env.example and docs are the #1 false-positive source. Placeholder values and tutorial snippets trip pattern matching. Allowlist these paths rather than weakening the patterns globally.
• Exclude vendor/, node_modules/, and build artifacts. Scanning dependencies bloats runtime and buries your own findings in third-party noise.
• Entropy-based detection is noisy by nature. Long hashes, base64 fixtures, and minified assets look like secrets. Prefer explicit patterns for gating, and treat entropy findings as advisory until tuned.
• A clean scan is not proof of no leak. These tools match known formats; a hand-rolled token or a secret split across lines will slip through. Pair the scanner with git-history scanning and actual key rotation when something is found.
• Exit codes matter in CI. Confirm the scanner returns non-zero on findings in your pinned version before you make it a blocking gate — otherwise you have a very reassuring no-op.
• Rotate first, refactor second. If the scanner finds a live key, rotating it is the fix. Removing the string from the file is cleanup; the credential is already compromised if it was ever pushed.
• Pin the version in CI. Pattern sets change between releases (1.1.0 added AI credential coverage), so an unpinned dependency can turn a green build red overnight or, worse, stop failing on something it used to catch.
• Keep the config in version control and review changes to it the same way you review a phpunit.xml change — loosening a pattern is a security decision, not a formatting one.