README

AI-powered threat detection for Laravel applications. Monitors logs for suspicious activity and uses a Claude AI agent (via tool use) to classify threats, block IPs, and alert administrators.

Requirements

PHP 8.1+
Laravel 8, 9, 10, 11, or 12
Guzzle 7+
An Anthropic API key

Installation

1. Require the package

composer require timmonaghan/laravel-security-agent

2. Publish the config

php artisan vendor:publish --tag=security-agent-config

3. Publish and run the migrations

php artisan vendor:publish --tag=security-agent-migrations
php artisan migrate

4. (Optional) Publish the email view

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

5. Add environment variables to .env

LSA_ANTHROPIC_API_KEY=sk-ant-...
LSA_MODEL=claude-sonnet-4-6               # optional, this is the default

SECURITY_ADMIN_EMAILS=admin@example.com,ops@example.com
SECURITY_CONFIDENCE_THRESHOLD=0.85        # 0.0–1.0, default 0.85
SECURITY_BLOCK_TTL_MINUTES=60             # default 60
SECURITY_LOG_PATH=/path/to/storage/logs/laravel.log  # default: storage/logs/laravel.log
SECURITY_SCHEDULE_FREQUENCY=everyMinute  # everyMinute (default), everyFiveMinutes, everyTenMinutes, everyFifteenMinutes, everyThirtyMinutes, hourly

# Admin panel
LSA_ADMIN_ENABLED=true
LSA_ADMIN_PASSWORD=your-secret-password
LSA_ADMIN_PATH=lsa-admin                  # URL path, default: lsa-admin

6. Ensure the Laravel scheduler is running

# In cron (recommended for production)
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

The package auto-registers the security-agent:monitor command in the Laravel scheduler.

Admin Web Panel

Laravel Security Agent ships with a built-in web panel for monitoring and configuration.

Access it at: https://your-app.com/lsa-admin (or your configured LSA_ADMIN_PATH)

The panel provides:

Dashboard — live counts of security events and blocked IPs, plus a table of the 10 most recent events with IP, pattern type, confidence score, and outcome.
Settings — change the active Claude model and update the Anthropic API key without touching the server. Changes are written directly to your .env file.
Password protection — set LSA_ADMIN_PASSWORD in .env to secure the panel. The panel is disabled (403) if no password is configured.

To use a custom URL path:

LSA_ADMIN_PATH=security-dashboard

How It Works

Log polling — security-agent:monitor runs on the configured schedule and reads new log lines using a byte-offset (stored in cache), so it only processes new entries.
Pattern detection — Lines are scanned for sqli, auth_brute_force, and 404_flood patterns. Matching batches are dispatched as AnalyzeThreat jobs.
AI analysis — ThreatAgent sends the suspicious batch to Claude with four tools: get_ip_history, get_recent_events, block_ip, send_alert. Claude reasons over the evidence and calls tools as needed (max 10 turns).
Auto-block or alert — High-confidence threats (≥ threshold) are written to lsa_ip_blocklist with an expiry. Lower-confidence threats trigger an admin email.
Audit trail — Every event and agent decision is stored in lsa_security_events with a human-readable summary.
API rate limiting — Built-in rate limiter prevents runaway Claude API calls under heavy log volume.

Blocklist Middleware (Optional)

The package ships a ready-made middleware. To enforce the IP blocklist on incoming requests, register it in app/Http/Kernel.php:

use Timmonaghan\SecurityAgent\Http\Middleware\BlocklistMiddleware;

// Add to the $middleware array for global enforcement:
protected $middleware = [
    // ...
    BlocklistMiddleware::class,
];

// Or add to $middlewareGroups['web'] to apply only to web routes:
protected $middlewareGroups = [
    'web' => [
        // ...
        BlocklistMiddleware::class,
    ],
];

Rollback

composer remove timmonaghan/laravel-security-agent
php artisan migrate:rollback  # or drop tables manually

Notes

Queue driver sync is supported (MVP default) but an async driver (Redis, database) is recommended for production to avoid blocking the scheduler process during Claude API calls.
IPv4 only in this release.
Database tables are prefixed with lsa_ (lsa_security_events, lsa_ip_blocklist) to avoid collisions with host app tables.

timmonaghan / laravel-security-agent

Maintainers

Package info

Statistics

Security