README

Deterministic anomaly detection, with an AI that explains — never decides. Fixed rules open anomaly cases (e.g. OTP bombing) from your audit log; an optional LLM can then describe a case in plain language. The AI only ever sees sanitized prompts (no PII, no OTPs, no tokens) and its output is advisory — humans review, destructive actions stay manual. Part of the padosoft/laravel-rebel-* suite.

What it is
The golden rule
Why this package
Rebel AI Guard vs the alternatives
Installation
Usage
Security notes
.env.example
Testing & License

What it is

Two things, deliberately separated:

Deterministic anomaly detection — AnomalyDetector scans rebel_auth_events and opens anomaly cases from fixed, auditable rules (v0.1.0: OTP bombing; more rules to come). No black box decides anything.
An AI explainer (optional) — AiExplainer can ask an LLM you provide to describe a case for an operator. It is advisory only, sees only sanitized input, and is absent unless you bind an AiClient.

Depends on padosoft/laravel-rebel-core.

The golden rule

The rules decide. The AI explains. Humans approve anything destructive.

The AI never opens, closes, or mitigates a case. It turns a case's signals into a sentence. Everything that acts is deterministic and auditable.

Why this package

★	What	In short
★★★	Deterministic, auditable detection	Cases come from fixed rules you can read and test — not a model's whim.
★★★	AI input is sanitized	Emails, phones, OTP/digit runs (incl. Unicode) and Bearer/Basic/JWT/key tokens are scrubbed before any prompt leaves the app.
★★★	AI is advisory + injection-resistant	The system prompt forbids deciding and treats case data as opaque (no prompt injection).
★★	Optional AI	No `AiClient` bound? Detection still works; the explainer just returns null.
★★	Idempotent + tenant-aware	Cases de-duplicate by a stable key; re-runs update in place; rows are tenant-scoped.
★★	Bring your own model	Bind OpenAI, Anthropic, or a local model behind a one-method contract.

Rebel AI Guard vs the alternatives

Capability	Rebel AI Guard	Shopify	"AI fraud" black boxes	DIY log scripts
Deterministic, testable rules you own	✅	❌	❌	➖
AI explains, never decides	✅	❌	❌	n/a
Prompt sanitization (no PII/secret leak to LLM)	✅	❌	❌	n/a
Prompt-injection-resistant system prompt	✅	❌	➖	n/a
Works with NO AI configured	✅	➖	❌	✅
Idempotent, de-duplicated cases	✅	➖	➖	❌
Self-hosted over your own audit log	✅	❌	❌	✅
Tenant-aware + audit-native (your app)	✅	❌	❌	❌

Legend: ✅ built-in · ➖ partial / hosted-only / not exposed to you · ❌ not available.

Note: Shopify is a hosted, closed commerce platform — it runs its own opaque fraud scoring on its checkout, but never gives you a deterministic anomaly engine, a sanitized explain-not-decide AI, or rules you can read, test, and self-host over your own audit log.

Installation

composer require padosoft/laravel-rebel-ai-guard
php artisan vendor:publish --tag="rebel-ai-guard-migrations"
php artisan migrate

Usage

Run detection (schedule it, e.g. every few minutes):

use Padosoft\Rebel\AiGuard\Detection\AnomalyDetector;

$opened = app(AnomalyDetector::class)->detect(
    now()->subHour(),
    now(),
); // returns how many cases were opened/updated

Explain a case (optional AI):

use Padosoft\Rebel\AiGuard\AiExplainer;
use Padosoft\Rebel\AiGuard\Models\AnomalyCase;

$explainer = app(AiExplainer::class);
$case = AnomalyCase::query()->findOrFail($id);

$text = $explainer->explain($case); // null if no AiClient is bound

Bring your own model — implement and bind the contract:

use Padosoft\Rebel\AiGuard\Contracts\AiClient;

$this->app->singleton(AiClient::class, MyOpenAiClient::class);

Security notes

No PII/secret to the LLM: PromptSanitizer scrubs emails, phone numbers, 4+ digit runs (incl. Unicode), and Bearer/Basic/JWT/sk-/ghp_/xox* tokens before sending.
No decisions by AI: the system prompt forbids deciding/recommending destructive actions and instructs the model to treat case data as opaque (prompt-injection resistant).
Deterministic core: cases come from fixed rules; the audit log already stores only HMAC'd identifiers, so cases carry hashes, not raw PII.
Tenant-scoped, idempotent: re-running the detector updates open cases instead of duplicating them.

`.env.example`

REBEL_AIGUARD_OTP_BOMBING_THRESHOLD=10

Testing & License

composer test      # Pest (detection, idempotency, severity, sanitizer, AI explainer)
composer phpstan   # static analysis, level max
composer pint      # code style

License: MIT — see LICENSE. Part of the padosoft/laravel-rebel suite.

padosoft / laravel-rebel-ai-guard

Maintainers

Package info

Statistics

Security