README

Queopius Sentinel 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 Sentinel

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

Versioning and Laravel compatibility

Queopius Sentinel follows SemVer for package versions.

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

Compatibility matrix

Composer constraints (current):

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

Laravel 13 requires PHP ^8.3, so PHP 8.2 support applies to Laravel 11 and 12 only.

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 Sentinel major.

Upgrade guidance

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

Quick start in 5 minutes

1. Install package:

composer require queopius/sentinel

1. Run installer:

php artisan sentinel:install --with-views

1. Migrate (for CSP reports table):

php artisan migrate

1. Add middleware aliases/global as needed (see below).

2. Run audit:

php artisan sentinel:audit

Installation and publish

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

Middleware registration (Laravel 11/12/13)

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

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

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

Config basics

Config file: config/sentinel.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' => 'sentinel',
  'middleware' => ['web', 'auth'],
  'require_ability' => 'viewSentinelDashboard',
  'theme' => 'light', // light|dark|auto
]

Then open /sentinel.

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('viewSentinelDashboard', fn ($user) => $user->hasRole('super_admin'));

With Spatie Permission you can map it to a permission:

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

Dashboard endpoint scan extras:

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

CSP reports

Enable:

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

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

Commands

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

Recommended rollout path (safe adoption)

1. Start with preset web_compatible
2. Keep CSP in report_only
3. Observe dashboard + reports
4. Tighten CSP directives and remove unsafe-inline
5. 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/sentinel

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

Publishable views

Views namespace: sentinel.

You can override UI templates by publishing views:

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

Output path: resources/views/vendor/sentinel

Local development in a Laravel app (monorepo)

Host app composer.json:

{
  "repositories": [
    {
      "type": "path",
      "url": "packages/queopius/sentinel",
      "options": {
        "symlink": true
      }
    }
  ],
  "require": {
    "queopius/sentinel": "^2.0"
  }
}

Then:

composer require queopius/sentinel:^2.0
php artisan sentinel:install --with-views
php artisan migrate
php artisan sentinel:audit
php artisan sentinel: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/sentinel
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: queopiussentinel)

Branding and badges notes

• Logo placeholder path in this README:
  • .github/assets/logo-queopius-sentinel.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