Secrets Laravel Package

Getting Started

Start by installing the package via Composer:

composer require --dev captainhook/secrets

The primary entry point is the Detector class. Its detectIn() method scans a string for secrets using pre-defined regex suppliers (e.g., Aws, Google, GitHub, Gitlab) or custom patterns. After installation, the first practical use case is integrating it into a local pre-commit hook (e.g., with CaptainHook) to block commits containing credentials — but even without the full hook runner, you can use the detector standalone in CI scripts or artisan commands.

Implementation Patterns

• Pre-commit Hook Integration: Use Detector in your commit-msg or prepare-commit-msg hook to scan staged files for secrets before allowing the commit. Example: scan diff hunks or full file contents.
• CI/CD Security Gate: Add a lightweight job (e.g., in GitHub Actions) that runs Detector over changed files or the whole codebase, failing the build if any secrets are found.
• Custom Supplier Classes: Extend Regex\Supplier to define domain-specific patterns (e.g., internal API keys like MYAPP_SECRET_KEY\s*=), then pass them to useSuppliers().
• White-listing Legitimate Matches: Use allow() with exact match strings or regexes (e.g., test fixtures like #root#) to avoid false positives.
• Static Analysis Integration: Wrap detector in a simple LARAVEL Artisan command to scan source trees (php artisan secrets:scan), outputting matches or generating reports.

Gotchas and Tips

• Case sensitivity & multiline files: All regex patterns are applied per line unless you preprocess multi-line content manually. The default suppliers use mb_detect_encoding() for safety, but ensure ext-mbstring is enabled (as required in composer.json).
• False positives in config files: Test files (e.g., .env.testing, database.php) often contain placeholder secrets. Use allow() for known safe patterns or skip scanning non-production paths.
• Performance: Avoid passing huge strings (e.g., full binary files) to detectIn(). Use file-by-file scanning in loops or integrate with tools that isolate changes (e.g., git diff output).
• Extending suppliers: When submitting a new supplier PR, ensure it follows naming conventions (Aws, Google, Gitlab) and includes comprehensive regex covering common formats (e.g., AKIA..., AIzaSy..., glpat-...).
• Debugging false negatives: Use var_dump($result->matches()) — sometimes the detected string may be empty if the pattern group is misconfigured (e.g., non-capturing groups without match() extraction). Also verify the input encoding — UTF-8-only patterns may miss non-ASCII chars.