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

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

1. E-commerce stores — prevent SQL injection attempts through the product search box
2. Multi-tenant Magento installations — a vulnerability in one tenant's code could be probed via search
3. Compliance-driven environments — satisfying audit requirements for input sanitization at all user entry points
4. Staging/demo sites — quickly add a security layer without modifying core or installing a full security suite
5. 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

📋 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).

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

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:

• Installation Guide
• Usage Guide
• Compatibility Matrix

⚠️ Known Limitations

1. 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.
2. Defense-in-depth, not primary SQL protection — not a substitute for prepared statements, parameterized queries, or proper ORM usage.
3. No Unicode / multibyte awareness — non-ASCII homoglyph attacks are not detected.
4. 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.