Download the PHP package yorcreative/laravel-scrubber without Composer

Laravel Scrubber

A Laravel package to scrub sensitive information that breaks operational security policies from being leaked on accident or not by developers.

Requirements

• PHP 8.2, 8.3, 8.4, or 8.5
• Laravel 10.x, 11.x, 12.x, or 13.x

Installation

install the package via composer:

Publish the packages assets.

Configuration

Adjust the configuration file to suite your application, located in /config/scrubber.php.

Usage

The scrubber can be utilized in two ways, the first one being a Log scrubber. A tap is added to detect and sanitize any sensitive information from hitting a log file. The second way is to integrate into your application and utilize the Scrubber directly. This way is particular useful if you, for example, would like to detect and sanitize any messages on a messaging platform.

Logging Detection & Sanitization

Direct Usage for Detection & Sanitization

Detection Statistics API

Track what patterns are matching and how often:

Events

The scrubber can dispatch a SensitiveDataDetected event each time a pattern matches during scrubbing. This is useful for alerting, metrics, or audit logging.

Enable events in your config:

The event carries three public properties:

Register a listener in your EventServiceProvider or with the Event facade:

Log Channel Opt-in

This package provides you the ability to define through the configuration file what channels you want to scrub specifically. By default, this package ships with a wildcard value and opts in to scrub all the log channels in your application.

Defining Log Channel Opt-in

To opt in to one or more channels, list the channel(s) name into the tap_channels array in the config.

To disable tap logging functionality and use the package independently and not tap your Laravel application logging, modify the config file by setting the tap_channels field as follows:

Regex Class Opt-in

You have the ability through the configuration file to define what regex classes you want loaded into the application when it is bootstrapped. By default, this package ships with a wildcard value.

Regex Collection & Defining Opt-in

To opt in, utilize the static properties on the RegexCollection class.

Note: The package includes 31 built-in patterns. See all available patterns in RegexCollection.php.

PII Detection with Partial Masking

The following patterns use contextual replacement values for improved readability instead of the generic **redacted**:

Opting Into Custom Extended Classes

To create custom scrubbers, see the Extending the Scrubber section.

The regex_loader array takes strings, not objects. To opt in to specific custom extended regex classes, define the class name as a string.

For example if I have a custom extended class as such:

The regex_loader array should be defined as such:

RegexCollection & Defining Opt-out

When using wildcard loading ('regex_loader' => ['*']), you can exclude specific regex patterns using the exclude_regex configuration. This allows you to load all patterns except those explicitly excluded.

The exclude_regex configuration supports multiple formats for excluding patterns:

• Base class names (e.g., 'GoogleApi')
• Fully qualified class names
• RegexCollection constants
• Custom namespace classes

This is particularly useful when you want to use most patterns but need to exclude a few specific ones from your scrubbing process.

Config Loader Filtering

The config_loader scrubs config values matching key patterns (e.g., *password, *token). Two additional options give you control over which values get scrubbed.

Minimum Length

By default, config values shorter than 4 characters are ignored. This prevents overly aggressive scrubbing when packages use short default values (e.g., Livewire's release_token defaults to 'a', which would cause every letter "a" in your logs to be redacted).

Non-string config values (booleans, integers, etc.) are always excluded regardless of this setting.

Key Exclusions

Certain config keys may match broad loader patterns but should not be treated as sensitive values. The config_loader_exclusions option allows you to bypass scrubbing for specific keys or key prefixes using wildcard patterns:

About the Scrubber

This package provides the ability to pull in secrets from external sources. Providing the ability to detect information leakage, and sanitize secrets without needing an exact regex pattern to detect it.

Encryption

For enhanced application security, all secrets pulled, from any provider, are encrypted and only decrypted to run the detection. You can see this in action here.

Secret Manager Providers

Laravel Scrubber supports pulling secrets from multiple external secret management services. This allows you to detect and sanitize secrets without needing exact regex patterns - if a value matches a secret from your vault, it gets scrubbed.

To enable secret managers, set secret_manager.enabled to true in your config and enable one or more providers.

GitLab CI/CD Variables

Pull secrets from GitLab project variables.

See GitLab's documentation on adding project variables.

AWS Secrets Manager

Pull secrets from AWS Secrets Manager. Requires the AWS SDK.

The AWS SDK automatically uses the default credential chain (environment variables, IAM roles, ECS task roles, etc.) when credentials are not explicitly provided.

HashiCorp Vault

Pull secrets from HashiCorp Vault using REST API. No additional dependencies required.

Azure Key Vault

Pull secrets from Azure Key Vault using REST API. No additional dependencies required.

Authentication methods (in order of precedence):

1. Direct access token - For testing or short-lived tokens
2. Managed Identity - Auto-detected when running in Azure (App Service, Functions, VMs)
3. Client credentials - Service principal with tenant_id, client_id, client_secret

Google Cloud Secret Manager

Pull secrets from Google Cloud Secret Manager using REST API. No additional dependencies required.

Authentication methods (in order of precedence):

1. Direct access token - For testing or when running outside GCP
2. Application Default Credentials - Auto-detected when running in GCP (Compute Engine, Cloud Run, GKE, Cloud Functions)

When running on GCP, leave access_token empty to use ADC automatically.

JSON Secret Values

All providers support JSON-formatted secret values. Nested values are automatically flattened:

This creates three scrubber patterns:

• database-config.host → db.example.com
• database-config.credentials.username → admin
• database-config.credentials.password → secret123

Extending the Scrubber

Creating new Scrubber Detection Classes

This command will create a stubbed out class in App\Scrubber\RegexCollection. The Scrubber package will autoload everything from the App\Scrubber\RegexCollection folder with the wildcard value on the regex_loader array in the scrubber config file. You will need to provide a Regex Pattern and a Testable String for the class and you may also provide a Replacement Value if you want to replace the detected value with something other than the default value in the config file.

Validating Regex Patterns

After creating or modifying regex classes, you can verify that every loaded pattern correctly matches its own testable string:

The command tests each pattern against the string returned by getTestableString() and prints a results table:

The command exits with a non-zero status when any pattern fails, making it suitable for CI pipelines.

Testing

Credits

• Yorda
• Magentron
• Whizboy-Arnold
• majchrosoft
• Lucaxue
• AlexGodbehere
• JorgeAnzola
• Haddowg
• LorenzoSapora
• All Contributors