README

Laravel package implementing PITB Application Security Procedure controls.

Installation

composer require pitbphp/security-starter

Composer will prompt you to choose an auditing library during install:

If you skipped the prompt or used --no-interaction, run:

php artisan security:install

This publishes config, optional views, sets SECURITY_AUDIT_DRIVER, installs the chosen package, and runs migrations.

Publish customizable views

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

Views are copied to resources/views/vendor/security/ where you can edit them freely.

User model

use Pitbphp\Security\Traits\HasPitbSecurity;

class User extends Authenticatable
{
    use HasPitbSecurity;
}

Optional password history for other models (e.g. Client)

Password history is always enabled for authenticated users with HasPitbSecurity.

For other models like clients, add the model to config and use the trait:

// config/security.php
'history_models' => [
    \App\Models\Client::class,
],

use Pitbphp\Security\Traits\HasPasswordHistory;

class Client extends Model
{
    use HasPasswordHistory;
}

use Pitbphp\Security\Rules\PitbPassword;

$request->validate([
    'password' => ['required', 'confirmed', new PitbPassword($client)],
]);

app(PasswordHistoryService::class)->record($client, Hash::make($request->password));

Package routes (no conflicts)

All routes are prefixed under /security with the security. route name prefix:

Override prefix in .env:

SECURITY_ROUTE_PREFIX=security
SECURITY_ROUTE_NAME_PREFIX=security.

API / Sanctum mode (optional)

By default the package runs in web mode (sessions). For API-first apps, enable Sanctum support:

composer require laravel/sanctum

SECURITY_MODE=hybrid   # web | api | hybrid
SECURITY_API_GUARD=sanctum
SECURITY_API_TOKEN_IDLE_MINUTES=20

API routes

API security violations return JSON with an error_code (e.g. password_expired, mfa_required, account_locked). Tokens are revoked on account violations when SECURITY_API_REVOKE_ON_VIOLATION=true.

Example API flow

# 1. Login and receive Sanctum token (your app login route)
# 2. If MFA enabled, verify OTP:
curl -X POST /api/security/mfa/verify \
  -H "Authorization: Bearer {token}" \
  -d "otp=123456"

# 3. If password expired:
curl -X POST /api/security/password/update \
  -H "Authorization: Bearer {token}" \
  -d "password=NewPass123!&password_confirmation=NewPass123!"

Environment

SECURITY_MODE=web
SECURITY_MAIL_TO=security@example.com,admin@example.com
SECURITY_AUDIT_DRIVER=activitylog
SECURITY_PASSWORD_EXPIRY_DAYS=90
SECURITY_SESSION_IDLE_MINUTES=20
SECURITY_MFA_ENABLED=false

Manual reviews

php artisan security:record-access-review --user=1 --notes="Reviewed admin roles"
php artisan security:record-log-review --user=1 --notes="No anomalies"
php artisan security:disable-inactive-users --dry-run
php artisan security:prune-logs

Auditing drivers

Auth events are always stored in security_events regardless of driver.

For Owen-It, add Auditable to sensitive models. For Activity Log, key events are logged automatically via the package listeners.