# sansec/magento2-module-shield

`composer require sansec/magento2-module-shield`

Canonical URL: https://packagento.com/sansec/magento2-module-shield

## At a glance

- **Vendor**: sansec (https://packagento.com/sansec.md)
- **Latest version**: 1.0.25 — released 2026-05-21
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/sansec/magento2-module-shield and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require sansec/magento2-module-shield:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## README

Requires Magento 2.3+, PHP 7.2+ and an [eComscan account](https://sansec.io/pricing) (Advanced or up).

### Installation

```bash
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`](https://nginx.org/en/docs/http/ngx_http_realip_module.html) on nginx, [`mod_remoteip`](https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html) 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](https://dashboard.sansec.io/d/account/shield). If you do not want reports, you can disable it with:

```bash
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](https://sansec.io/shield).

### 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:

```bash
composer show sansec/magento2-module-shield
```

To upgrade to the latest version:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

#### 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](./LICENSE).

## Recent Versions

| Version | Released |
|---|---|
| 1.0.25 | 2026-05-21 |
| 1.0.24 | 2026-04-23 |
| 1.0.23 | 2026-04-11 |
| 1.0.22 | 2026-03-29 |
| 1.0.21 | 2026-02-12 |
| 1.0.20 | 2025-11-14 |
| 1.0.19 | 2025-10-27 |
| 1.0.18 | 2025-09-16 |
| 1.0.17 | 2025-09-16 |
| 1.0.16 | 2025-08-22 |

Showing 10 of 46 versions. Full release history on https://packagento.com/sansec/magento2-module-shield.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-openssl | * |
| magento/framework | * |
| php | >=7.2 |

### Require (dev)

| Package | Constraint |
|---|---|
| phpunit/phpunit | ^8 |

## Quality

Latest release (1.0.25) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | Pass |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 93 | 14 errors, 79 warnings (ruleset: Magento2) — 7 auto-fixable with phpcbf |
| PHPMD | Warning | 25 | 25 rule violations (MissingImport:18, UnusedFormalParameter:6, CyclomaticComplexity:1) |
| Cpd | Warning | 2 | 2 duplicated chunks spanning 52 total lines (min-lines=5, min-tokens=70) |
| Composer validate | Info | 3 | valid; 3 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 18 | 18 | – | – |
| 2.4.8 | – | 18 | 18 | – |
| 2.4.9 | – | – | 18 | 18 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["sansec/magento2-module-shield"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

sansec is a Magento 2 vendor on Packagento. See https://packagento.com/sansec.md for their full catalogue.