README

Requires Magento 2.3+, PHP 7.2+ and a Sansec account (Advanced or up).

Installation

composer require sansec/magento2-module-shield
bin/magento setup:upgrade
bin/magento config:set sansec_shield/general/license_key <your license key>
bin/magento sansec:shield:sync-rules

Configuration

You can configure your license key and other settings via System → Configuration → Security → Sansec Shield.

Whitelisted IP addresses

IPs listed under Whitelisted IP Addresses bypass all Shield checks. Matching is performed against the connecting peer (REMOTE_ADDR) only; proxy-forwarded headers such as X-Forwarded-For and CF-Connecting-IP are intentionally ignored because they are client-controlled and can be spoofed.

If your store sits behind a reverse proxy or CDN, configure your webserver to rewrite the trusted proxy header into REMOTE_ADDR (ngx_http_realip_module on nginx, mod_remoteip on Apache). Once REMOTE_ADDR reflects the real client IP, the whitelist will match it correctly.

Testing & live reports

Test it by visiting your store and add ?SANSEC-SHIELD-TEST to your URL, it should give you "permission denied". You'll see your first blocked attack appear instantly on your Shield Dashboard. If you do not want reports, you can disable it with:

bin/magento config:set sansec_shield/general/report_enabled 0

You can always view detailed logs in var/log/sansec_shield.log.

See for FAQs our Shield guide.

Cron

Shield rules update automatically through the standard Magento cron mechanism. If you are running a standard cron setup (bin/magento cron:run), no further action is required.

If you only run specific cron groups (bin/magento cron:run --group <group name>), make sure to include a cron for the sansec group as well.

You can verify Shield rules sync every 5 minutes in var/log/sansec_shield.log.

Upgrading

The Sansec Shield module is deliberately kept stable and there is no need to monitor for updates. If an essential new version is released, we will notify you via email.

To check your current version:

composer show sansec/magento2-module-shield

To upgrade to the latest version:

composer require sansec/magento2-module-shield:^1.0
bin/magento setup:upgrade

Troubleshooting

"Please enable the module and configure the license key"

If you get this error when running bin/magento sansec:shield:sync-rules, even though the license key is already configured, flush the Magento cache:

bin/magento cache:flush

Then retry the sync command.

"There are no commands defined in the sansec:shield namespace"

Run the Magento dependency injection compiler:

bin/magento setup:di:compile

Composer upgrades unrelated packages during installation

Shield's only dependency is magento/framework, so it will not pull in or force any additional upgrades. If you see many packages being upgraded, your vendor/ directory was out of sync with composer.lock. Running composer require synced your vendor directory to match.

To avoid this, revert composer.lock to a version that matches your current vendor directory before installing Shield:

git checkout composer.lock
composer require sansec/magento2-module-shield

If installing via Composer is not an option, you can copy the source files directly into app/code/Sansec/Shield, though you will need to handle updates manually from that point on.

Rules stopped updating, but Shield still blocks

Symptom: the dashboard shows a signature date that stops advancing, while Shield keeps blocking attacks and keeps reporting them. The last-seen rule set is frozen at the moment the cron last ran.

Shield schedules sansec_shield_sync_rules in its own cron group, sansec. A crontab that dispatches groups individually runs only the groups it names, so a setup like this never syncs rules:

*/5 * * * * bin/magento cron:run --group=default
*/5 * * * * bin/magento cron:run --group=index
*/5 * * * * bin/magento cron:run --group=consumers

Confirm it by checking that the log has no recent sync entries:

grep 'Finished synchronization' var/log/sansec_shield.log | tail -5

If the last entry is old, run the group by hand. It should log a sync within seconds:

bin/magento cron:run --group=sansec

Fix it by adding a sansec line to the crontab alongside the others, or by replacing the per-group lines with a plain bin/magento cron:run, which covers every group. See Cron above.

Cron job not running on symlink-based deployments

Magento's cron:install resolves symlinks to their real path, so after a new deployment the crontab still points to the old release directory. Ensure that the crontab uses your stable symlink (e.g. /data/web/current/bin/magento) instead.

License

Sansec Shield is published under the liberal MIT license.

sansec / magento2-module-shield

Package info

Security

Statistics