PHPackages                             flarex/flareshield - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. flarex/flareshield

ActiveLibrary[Security](/categories/security)

flarex/flareshield
==================

Laravel-native AI security framework — protects chatbots, agents, RAG pipelines and tool-calling workflows against prompt injection, jailbreaks, system prompt leakage, RAG injection and unsafe AI output.

v1.0.0(1mo ago)03MITPHPPHP ^8.2

Since May 7Pushed 1mo agoCompare

[ Source](https://github.com/flarexsolutions/flareshield)[ Packagist](https://packagist.org/packages/flarex/flareshield)[ Docs](https://github.com/flarex/flareshield)[ RSS](/packages/flarex-flareshield/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (8)Versions (2)Used By (0)

FlareShield
===========

[](#flareshield)

[![Latest Version on Packagist](https://camo.githubusercontent.com/98285f1892ba73309cd08d6e05d59cba52b30b66a423fcc3578bf694e490a9b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f666c617265782f666c617265736869656c642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/flarex/flareshield)[![License](https://camo.githubusercontent.com/a5ac6f73901f988cbcb7cc3708853b5b0349efc37191c37a400e2e35ffd24ddc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f666c617265782f666c617265736869656c642e7376673f7374796c653d666c61742d737175617265)](LICENSE)

> **Laravel-native AI security framework for the LLM era.**Defend chatbots, agents, RAG pipelines and tool-calling workflows against prompt injection, jailbreaks, system prompt leakage, RAG poisoning, malicious tool usage and unsafe AI output — with a single Composer install.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Why FlareShield](#why-flareshield)
- [Threat Model](#threat-model)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Middleware](#middleware)
- [Guarding RAG Documents](#guarding-rag-documents)
- [Guarding Tool Calls](#guarding-tool-calls)
- [Output Validation](#output-validation)
- [Per-Agent Configuration](#per-agent-configuration)
- [Security Levels](#security-levels)
- [Events](#events)
- [Extending FlareShield](#extending-flareshield)
- [Testing](#testing)
- [Architecture](#architecture)
- [License](#license)

---

Why FlareShield
---------------

[](#why-flareshield)

LLM-powered features ship in days, but the threat surface of an AI system is fundamentally different from a traditional web app. FlareShield gives Laravel developers a **defense-in-depth toolkit** designed specifically for that gap:

- **Layered detection** — heuristic, encoded-payload, HTML/Markdown, hidden-instruction, multilingual and indirect-injection scanners.
- **Risk-scored verdicts** — every prompt receives a normalized 0–100 score with three verdicts: `pass`, `flag`, `block`.
- **Laravel-native** — Service Provider, Facade, middleware aliases, config publishing, events, container-driven extensibility.
- **Production-ready** — strict types, immutable value objects, PSR-3 logging, no third-party AI dependencies, fully testable.
- **Pluggable** — every scanner, validator, risk engine and tool policy is bound through the container and trivially overridable.

Threat Model
------------

[](#threat-model)

FlareShield is designed to mitigate the OWASP LLM Top 10 categories most relevant to application-layer code:

ThreatLayerLLM01 — Prompt Injection (direct)`scanPrompt`, role-override + heuristic scannersLLM01 — Prompt Injection (indirect)`sanitizeDocument`, indirect-injection scanner, RAG fenceLLM02 — Insecure Output Handling`scanOutput`, output validator (HTML/script/secret leak)LLM06 — Sensitive Information Disclosuresystem-prompt-leak scanner + secret detection in outputLLM07 — Insecure Plugin / Tool Design`authorizeTool`, ToolPermissionPolicyLLM08 — Excessive Agencyper-agent config + confirmation flag for high-impact toolsLLM09 — Overreliancestructured `ScanResult` you can act onFlareShield does **not** ship any AI model itself. It is a deterministic, auditable, framework-side guardrail — pair it with provider-side moderation (OpenAI Moderation, Llama Guard, AWS Bedrock Guardrails, etc.) for the strongest posture.

Installation
------------

[](#installation)

```
composer require flarex/flareshield
```

Publish the config (optional but recommended):

```
php artisan vendor:publish --tag=flareshield-config
```

The package auto-registers via Laravel's package discovery (`FlareShieldServiceProvider`) and exposes the `FlareShield` facade.

Requirements: PHP **8.2+**, Laravel **11 / 12 / 13**.

Quick Start
-----------

[](#quick-start)

```
use FlareX\FlareShield\Facades\FlareShield;
use FlareX\FlareShield\Exceptions\PromptInjectionException;

try {
    $safePrompt = FlareShield::guardPrompt($request->input('message'));
    $reply      = $myAiClient->chat($safePrompt);
    $safeReply  = FlareShield::guardOutput($reply);

    return response()->json(['reply' => $safeReply]);
} catch (PromptInjectionException $e) {
    return response()->json([
        'error'  => 'blocked',
        'reason' => $e->result()->toArray(),
    ], 422);
}
```

Need the structured result instead of an exception? Use `scanPrompt` / `scanOutput`:

```
$result = FlareShield::scanPrompt($input);

$result->passed();   // bool
$result->flagged();  // bool — suspicious but not blocked
$result->blocked();  // bool
$result->score;      // 0..100
$result->threats;    // Threat[] — type, severity, scanner, matches
```

Middleware
----------

[](#middleware)

Two middleware aliases are registered:

AliasClassPurpose`flareshield.prompt``ProtectAiPrompt`Validates inbound user prompt`flareshield.output``ProtectAiOutput`Validates outbound JSON reply```
Route::post('/chat', [ChatController::class, 'send'])
     ->middleware([
         'flareshield.prompt:message,support-bot',
         'flareshield.output:reply,support-bot',
     ]);
```

Parameters: `{field}`, `{agent?}`. Blocked prompts return `422` with a structured JSON body. The full `ScanResult` is also stashed on the request under `flareshield.prompt_result` so your controller can inspect it.

Guarding RAG Documents
----------------------

[](#guarding-rag-documents)

Indirect prompt injection is the #1 RAG threat. Sanitize every retrieved chunk before injecting it into the model context:

```
$cleanDoc = FlareShield::guardDocument($retrievedChunk);

$messages[] = ['role' => 'user', 'content' => "Context:\n" . $cleanDoc];
```

`guardDocument()` will:

1. Run all configured scanners against the chunk.
2. Strip HTML comments, zero-width / control characters and tag-style hidden text.
3. Quote suspicious imperative phrases so the model treats them as data.
4. Truncate to a configured maximum length.
5. Wrap the result in clearly labeled `` fences.
6. Throw `RagInjectionException` when the chunk crosses the block threshold.

Guarding Tool Calls
-------------------

[](#guarding-tool-calls)

```
use FlareX\FlareShield\Exceptions\ToolPermissionException;

try {
    FlareShield::authorizeTool('database.read', ['table' => 'orders']);
    $result = $tools->call('database.read', ...);
} catch (ToolPermissionException $e) {
    Log::warning('AI tried to call a forbidden tool.', ['ex' => $e->getMessage()]);
}

if (FlareShield::toolRequiresConfirmation('email.send')) {
    // present a confirmation step to the user
}
```

Configure in `config/flareshield.php` under the `tools` key.

Output Validation
-----------------

[](#output-validation)

`scanOutput()` runs the configured `output_validators`. The default `OutputValidator` flags:

- system-prompt echoes (`"system prompt:"`, `"initial instructions:"`)
- API keys / tokens (AWS, GitHub, OpenAI, JWTs, PEM private keys)
- Markdown image links that look like exfiltration beacons
- raw `` / `on*=` HTML

Per-Agent Configuration
-----------------------

[](#per-agent-configuration)

Every config key can be overridden per agent:

```
// config/flareshield.php
'agents' => [
    'support-bot' => [
        'level'    => 'strict',
        'denylist' => ['/refund all customers/i'],
    ],
    'docs-rag' => [
        'level' => 'enterprise',
    ],
],
```

```
FlareShield::for('support-bot')->scanPrompt($input);
```

Security Levels
---------------

[](#security-levels)

LevelFlag ≥Block ≥Use case`lenient`6090Local dev, demos`balanced`4070Production default`strict`2550Finance, health, internal admin bots`enterprise`2045Strict + verbose telemetryTune precisely in `config('flareshield.thresholds')`.

Events
------

[](#events)

```
use FlareX\FlareShield\Events\ThreatDetected;

Event::listen(ThreatDetected::class, function (ThreatDetected $e) {
    // forward to SIEM, increment Pulse counter, alert on Slack, etc.
});
```

Available events: `PromptScanned`, `OutputScanned`, `ThreatDetected`, `ToolCallBlocked`.

Extending FlareShield
---------------------

[](#extending-flareshield)

Write a custom scanner:

```
use FlareX\FlareShield\Contracts\Scanner;
use FlareX\FlareShield\Support\{ScanContext, Severity, Threat};

class CompanySecretScanner implements Scanner
{
    public function name(): string { return 'company_secret'; }

    public function scan(string $input, ScanContext $ctx): array
    {
        if (! preg_match('/PROJECT-NEPTUNE/', $input)) return [];

        return [new Threat(
            'internal_codename',
            'Internal codename leaked.',
            Severity::Critical,
            $this->name(),
        )];
    }
}
```

Then register it in `config/flareshield.php`:

```
'scanners' => [
    \FlareX\FlareShield\Scanners\HeuristicScanner::class,
    \App\Security\CompanySecretScanner::class,
    // ...
],
```

Need a different scoring strategy? Bind your own `RiskEngine`:

```
$this->app->bind(\FlareX\FlareShield\Contracts\RiskEngine::class, MyEngine::class);
```

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit
```

The suite uses Orchestra Testbench and exercises scanners, the risk engine, the manager and the HTTP middleware end-to-end with realistic attack payloads.

Architecture
------------

[](#architecture)

```
src/
├── FlareShield.php                 # Central manager (per-agent scoping + dispatch)
├── FlareShieldServiceProvider.php
├── Facades/FlareShield.php
├── Contracts/                      # Scanner, Guard, RiskEngine, ToolPolicy, ...
├── Support/                        # ScanResult, ScanContext, Threat, Severity
├── Scanners/                       # 8 detection strategies
├── Risk/DefaultRiskEngine.php      # Noisy-OR scoring + level thresholds
├── Validators/                     # OutputValidator, RagSanitizer
├── Policies/ToolPermissionPolicy.php
├── Middleware/                     # ProtectAiPrompt, ProtectAiOutput
├── Logging/DefaultAttackLogger.php
├── Events/                         # PromptScanned, OutputScanned, ...
└── Exceptions/                     # PromptInjection, Jailbreak, ToolPermission, ...

```

See [`docs/architecture.md`](docs/architecture.md) and [`docs/threat-model.md`](docs/threat-model.md) for deeper dives.

License
-------

[](#license)

MIT © FlareX. See [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance93

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/0ce63973c167688dc72d9d8f309ab2063d971d0991d4e33b3fba4e3ee37d7da8?d=identicon)[flarexsolutions](/maintainers/flarexsolutions)

---

Tags

laravelsecurityaichatbotllmragguardrailsprompt-injectionjailbreakflareshield

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/flarex-flareshield/health.svg)

```
[![Health](https://phpackages.com/badges/flarex-flareshield/health.svg)](https://phpackages.com/packages/flarex-flareshield)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.4k](/packages/larastan-larastan)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76318.2M110](/packages/laravel-mcp)[illuminate/routing

The Illuminate Routing package.

1239.0M2.8k](/packages/illuminate-routing)[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45344.0k1](/packages/pressbooks-pressbooks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)