README

Laravel AI Security Guardian is a defensive security package for Laravel applications. It scans for dependency issues, insecure code patterns, misconfiguration, risky uploads, unsafe routes, and common business logic weaknesses. It also provides a review-first UI, safe report generation, and optional AI-assisted analysis with token-aware safeguards.

Highlights

Local security scanners for dependency, configuration, Blade, route, upload, and code risk checks.
Optional AI-assisted deep scan for higher-level triage and remediation guidance.
Review-first dashboard for scans, findings, reports, patch suggestions, provider settings, notifications, and health checks.
Safe auto-fix workflow with explicit review gates.
Multi-language UI support with RTL output.
JSON and Markdown report generation.
Designed to minimize unnecessary AI token usage.

Requirements

PHP 8.2 or newer
Laravel 10, 11, or 12
A supported AI provider if deep analysis is enabled

Installation

Install the package with Composer:

composer require abdalmolood/laravel-ai-security-guardian

Publish the package configuration:

php artisan vendor:publish --tag=ai-security-guardian-config

Publish the migrations and run them:

php artisan vendor:publish --tag=ai-security-guardian-migrations
php artisan migrate

Optional: publish the package views and translations if you want to customize them.

php artisan vendor:publish --tag=ai-security-guardian-views
php artisan vendor:publish --tag=ai-security-guardian-lang

Quick Start

Add the required environment variables:

AI_SECURITY_ENABLED=true
AI_SECURITY_UI_ENABLED=true
AI_SECURITY_UI_PREFIX=ai-security
AI_SECURITY_UI_THEME=auto
AI_SECURITY_UI_LOCALE=en
AI_SECURITY_UI_AVAILABLE_LOCALES=en,ar
AI_SECURITY_UI_RTL_LOCALES=ar

AI_SECURITY_PROVIDER=openai
AI_SECURITY_OPENAI_API_KEY=your_api_key
AI_SECURITY_OPENAI_MODEL=gpt-4.1

AI_SECURITY_AI_ENABLED=true
AI_SECURITY_DEEP_SCAN_ENABLED=true
AI_SECURITY_AI_MAX_FINDINGS=12
AI_SECURITY_AI_MAX_TEXT_LENGTH=360
AI_SECURITY_AI_MAX_REFERENCES=3
AI_SECURITY_AI_MAX_COMPLETION_TOKENS=1200

Run a standard scan:

php artisan ai-security:scan

Run an in-depth scan with AI assistance:

php artisan ai-security:scan --deep

The deep scan command also has an alias:

php artisan ai-security:scan:deep

Generate the latest report:

php artisan ai-security:report
php artisan ai-security:report --format=json

Open the dashboard in your browser:

/ai-security

Features

Security Scanners

The package includes scanners for:

Composer dependency vulnerabilities
Dangerous environment and config values
Unsafe Blade output
Route and middleware access gaps
Unsafe file upload flows
Sensitive PHP patterns and raw SQL usage
Optional AST-based heuristics for larger application patterns

Review-First UI

The dashboard is intentionally read-focused:

Scan history
Finding triage
Report generation
Patch suggestions
Provider settings
Scanner settings
Notification settings
Health checks
Help and usage guidance

Token-Aware AI Usage

The AI pipeline is designed to avoid waste:

Context is redacted before being sent to a provider
Findings are compacted and deduplicated
Request size is capped
Completion size is capped
Identical requests can be cached
Deep analysis runs only when it is explicitly enabled and needed

AI Providers

The package supports:

OpenAI
Gemini
DeepSeek
Custom OpenAI-compatible endpoints

Example provider configuration:

OpenAI example:

AI_SECURITY_PROVIDER=openai
AI_SECURITY_OPENAI_API_KEY=your_api_key
AI_SECURITY_OPENAI_MODEL=gpt-4.1

Custom provider example:

AI_SECURITY_PROVIDER=custom
AI_SECURITY_CUSTOM_BASE_URL=http://localhost:11434/v1
AI_SECURITY_CUSTOM_API_KEY=local-key
AI_SECURITY_CUSTOM_MODEL=your-model

Scheduler

Daily scans can be enabled through configuration. Laravel's scheduler must still be active in production:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Default scan time:

AI_SECURITY_SCAN_TIME=03:00

Localization and RTL

The package ships with English and Arabic translations.

Locale and RTL behavior can be configured with:

AI_SECURITY_UI_LOCALE=en
AI_SECURITY_UI_AVAILABLE_LOCALES=en,ar
AI_SECURITY_UI_RTL_LOCALES=ar

You can switch languages from the UI, and pages will render with the correct direction automatically. RTL is based on the active locale.

Notifications

Supported notification channels:

Email
Telegram
Slack

Example configuration:

AI_SECURITY_MAIL_ENABLED=true
AI_SECURITY_MAIL_TO=security@yourdomain.com

AI_SECURITY_TELEGRAM_ENABLED=false
AI_SECURITY_TELEGRAM_BOT_TOKEN=
AI_SECURITY_TELEGRAM_CHAT_ID=

AI_SECURITY_SLACK_ENABLED=false
AI_SECURITY_SLACK_WEBHOOK_URL=

Safe Auto-Fix

The package can produce safe fixes for eligible findings, but direct file modification remains gated.

Enable direct fixes only when you have a clear review process:

Edit the published config file:

// config/ai-security-guardian.php
'auto_fix' => [
    'enabled' => true,
    'production_direct_fix' => false,
],

Set production_direct_fix to true only when you want to permit direct file changes for eligible findings.

Run the fixer explicitly when you are ready:

php artisan ai-security:fix --direct

Rollback support is also available:

php artisan ai-security:rollback {patch_id}

Extending the Package

Add a Custom Scanner

Implement ScannerInterface and register it in your application:

use Abdalmolood\AiSecurityGuardian\Contracts\ScannerInterface;
use Illuminate\Support\Collection;

class MyCustomScanner implements ScannerInterface
{
    public function getName(): string
    {
        return 'My Custom Scanner';
    }

    public function scan(): Collection
    {
        return collect();
    }
}

app(Abdalmolood\AiSecurityGuardian\Scanners\ScannerManager::class)
    ->registerScanner(new MyCustomScanner());

Add a Custom AI Provider

Implement AiProviderInterface to plug in another provider:

use Abdalmolood\AiSecurityGuardian\Contracts\AiProviderInterface;
use Abdalmolood\AiSecurityGuardian\DTO\AiResponse;

class MyCustomAiProvider implements AiProviderInterface
{
    public function analyze(string $prompt, array $context = []): AiResponse
    {
        return new AiResponse([]);
    }
}

Example Outputs

Example finding payload:

{
  "title": "APP_DEBUG is enabled in production",
  "severity": "critical",
  "category": "configuration",
  "affected_file": ".env",
  "description": "The APP_DEBUG environment variable is set to true in production.",
  "recommendation": "Set APP_DEBUG=false in the .env file."
}

Example report summary:

# Security Scan Report

## Summary
- Started At: 2024-01-01 10:00:00
- Total Findings: 1
- Risk Score: 10

## Findings
### APP_DEBUG is enabled in production
- Severity: Critical
- Category: configuration
- Affected File: .env

Testing

Run the test suite:

vendor/bin/pest

Support and Customization

The package is built to be published and customized. You can override:

Config
Views
Translations
Migrations

License

MIT

abdalmolood / laravel-ai-security-guardian

Maintainers

Package info

Statistics

Security