README

Queopius Shield is a production-ready Laravel package for HTTP security hardening with great DX:

Security headers (HSTS, CSP, Referrer-Policy, and more)
HTTPS enforcement middleware
Optional dashboard UI for audit/inspection
Dashboard metrics with CSP-safe native charts and hardening plan
Optional CSP reports endpoint + storage
Security audit, endpoint scan, and report pruning commands
Publishable views for full UI customization

Why Queopius Shield

Safe-by-default with preset support
Progressive rollout path (CSP report-only first)
Works as reusable package and monorepo local package
Built for Laravel 12 and compatible with 11/12

Versioning and Laravel compatibility

Queopius Shield follows SemVer for package versions.

MAJOR: breaking changes
MINOR: new features, backward compatible
PATCH: fixes and internal improvements

Compatibility matrix

Shield version	Laravel	PHP	Status
`1.x`	`11.x`, `12.x`	`>=8.2`	Active

Composer constraints (current):

illuminate/*: ^11.0|^12.0
php: ^8.2

Support policy

Only actively maintained major versions receive fixes/features.
Security fixes are prioritized for the latest maintained major.
When a Laravel major reaches end-of-life, support can be dropped in the next Shield major.

Upgrade guidance

Use a stable constraint in host apps: composer require queopius/shield:^1.0
Read release notes before any major upgrade (1.x -> 2.x).
Run: php artisan shield:audit after upgrades to validate effective runtime security.

Quick start in 5 minutes

Install package:

composer require queopius/shield

Run installer:

php artisan shield:install --with-views

Migrate (for CSP reports table):

php artisan migrate

Add middleware aliases/global as needed (see below).
Run audit:

php artisan shield:audit

Installation and publish

php artisan vendor:publish --tag=shield-config
php artisan vendor:publish --tag=shield-views
php artisan vendor:publish --tag=shield-migrations

Middleware registration (Laravel 11/12)

Add aliases/global middleware in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'shield.headers' => \Queopius\Shield\Http\Middleware\AddSecurityHeaders::class,
        'shield.https' => \Queopius\Shield\Http\Middleware\EnforceHttps::class,
    ]);

    // Optional global
    $middleware->append(\Queopius\Shield\Http\Middleware\EnforceHttps::class);
    $middleware->append(\Queopius\Shield\Http\Middleware\AddSecurityHeaders::class);
})

Config basics

Config file: config/shield.php

Key areas:

preset: baseline config (web_compatible, api_strict)
headers.*: security headers setup
https.*: redirect + force scheme
ui.*: optional dashboard
csp_reports.*: endpoint + DB storage
audit.*: warnings and probe behavior
health_endpoint.*: optional JSON endpoint

Dashboard UI

Enable in config:

'ui' => [
  'enabled' => true,
  'path' => 'shield',
  'middleware' => ['web', 'auth'],
  'require_ability' => 'viewShieldDashboard',
  'theme' => 'light', // light|dark|auto
]

Then open /shield.

Dashboard access control (recommended)

Keep ui.middleware with auth (default in package).
Set ui.require_ability and define the Gate in your app:

Gate::define('viewShieldDashboard', fn ($user) => $user->hasRole('super_admin'));

With Spatie Permission you can map it to a permission:

Gate::define('viewShieldDashboard', fn ($user) => $user->can('shield.view'));

Dashboard endpoint scan extras:

Dynamic paths filter via scan_paths query/form
Export scan results:
- /shield?export=endpoints&format=json
- /shield?export=endpoints&format=csv

CSP reports

Enable:

'csp_reports' => [
  'enabled' => true,
  'route_path' => 'shield/csp-reports',
  'store_database' => true,
]

Use report-only initially, inspect reports, then enforce.

Commands

php artisan shield:install [--with-views] [--force]
php artisan shield:audit [--format=table|json|csv]
php artisan shield:scan [--json] [--paths=/,/login,/api]
php artisan shield:prune-reports [--days=30]

Recommended rollout path (safe adoption)

Start with preset web_compatible
Keep CSP in report_only
Observe dashboard + reports
Tighten CSP directives and remove unsafe-inline
Enable HTTPS redirect and HSTS in production

Reverse proxy notes

If app is behind Cloudflare / ALB / Nginx proxy, ensure Laravel trusted proxies are correctly configured so Request::isSecure() is reliable.

Local HTTPS test (production-like)

For monorepo host apps:

./scripts/generate-local-https-cert.sh
./vendor/bin/sail up -d --build

Set in host .env:

APP_URL=https://your-app.test:8443

Then run:

./vendor/bin/sail artisan optimize:clear

Open:

https://your-app.test:8443
https://your-app.test:8443/shield

Full trust instructions are in docs/guides/local-https.md.

Publishable views

Views namespace: shield.

You can override UI templates by publishing views:

php artisan vendor:publish --tag=shield-views

Output path: resources/views/vendor/shield

Local development in a Laravel app (monorepo)

Host app composer.json:

{
  "repositories": [
    {
      "type": "path",
      "url": "packages/queopius/shield",
      "options": {
        "symlink": true
      }
    }
  ],
  "require": {
    "queopius/shield": "*"
  }
}

Then:

composer require queopius/shield:*
php artisan shield:install --with-views
php artisan migrate
php artisan shield:audit
php artisan shield:scan

Package tests

Inside package directory:

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Docs

See docs/ for architecture, config reference, CSP reporting, dashboard and roadmap.

Release-hardening checklist: docs/production-readiness.md.

Community and governance

Contribution guide: CONTRIBUTING.md
Security policy: SECURITY.md
Release + Packagist automation: docs/guides/release-and-packagist.md

Licensing

Code: MIT (see LICENSE).
Documentation and guides: Creative Commons Attribution 4.0 International (CC BY 4.0).

Read the Docs

This package includes:

.readthedocs.yaml
mkdocs.yml
docs/requirements.txt

Local docs preview:

cd packages/queopius/shield
python3 -m venv .venv
source .venv/bin/activate
pip install -r docs/requirements.txt
mkdocs serve

Local strict build:

mkdocs build --strict

GitHub Actions docs workflow:

validates docs on PR/push via mkdocs build --strict
optional Read the Docs trigger on push to main

Required repository secrets for RTD trigger:

RTD_TOKEN: Read the Docs API token
RTD_PROJECT: Read the Docs project slug (example: queopius-shield)

Branding and badges notes

Logo placeholder path in this README:
- .github/assets/logo-queopius-shield.png
If repository owner/name changes, update badge URLs accordingly.
If Read the Docs project slug changes, update:
- https://readthedocs.org/projects/<slug>/badge/?version=latest

queopius / shield

Maintainers

Package info

Fund package maintenance!

Statistics

Security