README

HK2 Sanitize Search — Magento 2 Search Query Sanitizer

HK2 SanitizeSearch is a lightweight Magento 2 module that sanitizes user-submitted search queries by stripping harmful SQL keywords and characters. It hooks into Magento\Search\Model\QueryFactory via a beforeCreate plugin, applies a regex filter, and logs sanitization events to a dedicated log file for auditing.

📄 Overview

The module acts as a defense-in-depth layer against SQL injection attempts entering through the storefront search box. It removes SQL control keywords (SELECT, INSERT, UPDATE, DELETE, DROP, UNION), statement terminators (;), and comment markers (--, #) from user input before it reaches the search pipeline. Clean queries pass through with zero overhead.

🧠 Problem Statement

Magento's native search accepts arbitrary user input and feeds it into the search query pipeline. While Magento uses prepared statements and proper ORM practices, an unsanitized search box represents an unnecessary attack surface. Malicious actors can probe the system by submitting search strings containing SQL control characters and keywords (e.g., SELECT, UNION, ;, --).

Security best practices dictate that user input should be sanitized at every trust boundary. The search input field — accessible to any visitor — is a clear trust boundary that benefits from proactive sanitization.

💡 Solution Approach

A plugin intercepts the beforeCreate method of Magento\Search\Model\QueryFactory and applies a preg_replace to remove dangerous patterns from the raw query string:

SQL keywords: SELECT, INSERT, UPDATE, DELETE, DROP, UNION (case-insensitive)
Statement terminator: ;
SQL comment markers: -- and #

If any content is stripped, the event is logged to var/log/sanitizer.log at WARNING level. The sanitizer can be toggled on/off via admin configuration at Stores > Configuration > HK2 > Search Sanitizer.

🆚 Alternatives Considered

Approach	Why not chosen
Prepared statement reliance only	Places full trust in the ORM layer; no defense-in-depth at the input boundary
Full input validation/whitelisting	Too restrictive; would break legitimate search queries with special characters
WAF-level filtering	Requires external infrastructure; adds latency; harder to audit
Escaping instead of stripping	Escaped SQL keywords may still appear suspicious in logs or trigger false alarms
Third-party security module	Heavy dependency; most include far more than search sanitization

Stripping is chosen as a minimal, predictable operation — it removes known dangerous patterns without altering the shape of legitimate queries.

👥 Who is this for?

Magento 2 store owners hardening their storefront against SQL injection probes
Security-conscious developers needing a zero-dependency, auditable sanitization layer
Agencies and system integrators deploying sites that must pass security compliance reviews
Merchants in regulated industries (finance, healthcare, e-commerce) with customer data behind the search interface

🎯 Use Cases

E-commerce stores — prevent SQL injection attempts through the product search box
Multi-tenant Magento installations — a vulnerability in one tenant's code could be probed via search
Compliance-driven environments — satisfying audit requirements for input sanitization at all user entry points
Staging/demo sites — quickly add a security layer without modifying core or installing a full security suite
Custom search implementations — where Magento\Search\Model\QueryFactory is still part of the pipeline

✨ Key Features

SQL keyword stripping — removes SELECT, INSERT, UPDATE, DELETE, DROP, UNION, ;, --, and # from search queries (case-insensitive)
Dedicated logging — every sanitization event is recorded to var/log/sanitizer.log at WARNING level with original and sanitized values
Configurable enable/disable — toggle via Stores > Configuration > HK2 > Search Sanitizer
Defense-in-depth — complements Magento's ORM and prepared statements with input-level sanitization
Zero impact on clean queries — queries without harmful patterns pass through unmodified
Lightweight — single plugin, no database schemas, no API endpoints, no console commands

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│  Storefront search form                                                │
│  User submits:  "product; DROP TABLE customers; --"                    │
└──────────────────────────┬──────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Magento\Search\Model\QueryFactory::beforeCreate                       │
│  (Plugin: HK2\SanitizeSearch\Plugin\SearchSanitizer)                   │
│                                                                         │
│  1. Check config flag (hk2_sanitizesearch/general/enabled)             │
│  2. If disabled → return original query unchanged                       │
│  3. If enabled:                                                         │
│     a. preg_replace(/(select|insert|update|delete|drop|union|;|--|#)/i) │
│     b. trim()                                                           │
│     c. If changed → log original + sanitized to Monolog (WARNING)      │
│     d. Return sanitized query                                           │
└─────────────────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  Normal Magento search pipeline                                        │
│  (Query, search results, etc.)                                          │
└─────────────────────────────────────────────────────────────────────────┘

Logging (when change detected):
    HK2\SanitizeSearch\Logger\Logger (custom Monolog channel)
        └── HK2\SanitizeSearch\Logger\Handler (writes to var/log/sanitizer.log, WARNING level)

Key files

File	Role
`Plugin/SearchSanitizer.php`	Plugin intercepting `QueryFactory::beforeCreate`
`Logger/Logger.php`	Custom Monolog logger class
`Logger/Handler.php`	Log handler writing to `var/log/sanitizer.log`
`etc/di.xml`	Plugin registration and logger wiring
`etc/module.xml`	Module declaration sequencing on `HK2_Core`
`etc/adminhtml/system.xml`	Admin system configuration under HK2 tab
`etc/adminhtml/menu.xml`	Admin menu entry under Content

📋 System Requirements

Magento: 2.4.x (Open Source / Adobe Commerce)
PHP: ^8.1 || ^8.2 || ^8.3 || ^8.4
Composer: 2.x
Dependencies: hk2/core ^1.0, magento/framework ^103.0.0
No database modifications — operates entirely at the PHP plugin layer

🚀 Installation

composer require hk2/sanitize-search

bin/magento module:enable HK2_SanitizeSearch
bin/magento setup:upgrade
bin/magento cache:clean

Verify:

bin/magento module:status HK2_SanitizeSearch

⚙️ Configuration

Navigate to Stores > Configuration > HK2 > Search Sanitizer (or Content > Search Sanitizer from the admin menu).

Setting	Description
Enable Search Sanitization	Set to Yes to enable SQL keyword stripping. Set to No to pass all queries through unchanged.

Default: No (disabled). Ships disabled so operators can enable after testing.

Configuration path: hk2_sanitizesearch/general/enabled

🔒 Content Security Policy (CSP)

This module does not modify Magento's CSP headers or csp_whitelist.xml. It operates exclusively at the server-side PHP layer before the search query enters the ORM pipeline.

HK2 SanitizeSearch complements CSP in a holistic security strategy: CSP prevents malicious scripts from executing in the browser, while search sanitization prevents malicious SQL patterns from entering the database pipeline.

🚀 Production Readiness

This module is production-ready and has been designed with the following considerations:

Zero database schema changes — no setup patch, no SQL install/upgrade scripts, no data patches
Zero API surface — no REST, GraphQL, or SOAP endpoints to secure
Minimal performance impact — a single preg_replace on the search query string; disabled by default
Configurable at runtime — toggle via admin configuration without code deployment
Defense-in-depth — complements existing Magento security layers rather than replacing them
Auditable — all sanitization events are logged with original and sanitized values for forensic review

Enable on staging first, test with your store's typical search patterns, then enable in production.

🔐 Privacy & GDPR

No personal data collection — the module does not track, store, or transmit user identities, IP addresses, or session data
Log contents — the only persisted data is the original and sanitized query string (written to var/log/sanitizer.log at WARNING level)
Log retention — standard Magento log rotation applies; configure per your data protection obligations
No third-party services — the module makes no external network calls and sends no data off-server
Recommended actions: review log retention for var/log/sanitizer.log, consider disabling query logging if searches may contain PII, include sanitization logging in your data processing register

🧪 Testing Strategy

Test case	Input	Expected output
Clean query	`laptop`	`laptop` (unchanged, no log)
SQL keyword	`SELECT * FROM users`	`* FROM users` (logged)
Statement terminator	`admin'; DELETE`	`admin''` (logged)
Comment marker	`password-- comment`	`password comment` (logged)
Hash comment	`admin#foo`	`adminfoo` (logged)
Mixed case	`UnIoN Select 1`	`1` (logged)
Multiple keywords	`DROP;SELECT;UPDATE`	`` (empty, logged)
Disabled module	any input with config disabled	unchanged, no log
Empty input	``	`` (no error)

Recommended approach: enable on a staging environment first, submit various test queries, and inspect var/log/sanitizer.log before enabling in production.

No automated test suite ships with the module.

📚 Documentation

Additional documentation is available in the docs/ directory:

⚠️ Known Limitations

Pattern-based, not context-aware — the regex match removes substrings. "selective" becomes "ive". This is by design: the filter errs on the side of removing potential threats.
Defense-in-depth, not primary SQL protection — not a substitute for prepared statements, parameterized queries, or proper ORM usage.
No Unicode / multibyte awareness — non-ASCII homoglyph attacks are not detected.
Log growth — in high-traffic stores with aggressive probing, the log file may grow quickly.

🤝 Contributing

Contributions are welcome. Please open an issue or pull request on the GitHub repository.

All contributions must adhere to the Conventional Commits specification for automated semantic release.

📄 License

Licensed under the Open Software License 3.0 (OSL-3.0).

The OSL-3.0 is an OSI-approved open source license. It allows you to use, modify, and distribute this software, provided that distributed modifications are made available in source code form.

⚖️ Disclaimer

This module provides defense-in-depth sanitization and is not a replacement for secure coding practices. The author and Basant Mandal are not responsible for any damages or security breaches resulting from the use or misuse of this software. Always follow Magento security best practices, keep your installation up to date, and perform regular security audits.

hk2 / sanitize-search

Maintainers

Package info

Statistics

Security