Download the PHP package masq/guardian without Composer

Guardian

A trust & abuse-scoring engine for Laravel.

Guardian watches any model (usually your User), gives it suspicion points when something looks off, lets those points fade over time, and as they add up moves the subject through trust states — trusted → watch → restricted → review → banned. Reaching "review" opens a moderator case; only a certain, physically-impossible violation bans automatically. It's domain-agnostic: it knows nothing about your app, only about points and states.

How it works (the whole idea in one minute)

Four things to know:

1. A signal is one observation. "Failed login #7", "impossible step count". It carries some points and a decay rule (how fast those points fade).
2. The score is recomputed, not stored. At any moment it's the sum of every signal's remaining (decayed) points. Good behaviour over time → score drops → the subject recovers on its own.
3. Thresholds turn the score into a state. You define the boundaries.
4. Soft vs. hard is the safety rule. Soft signals (heuristics) can climb to review at most — a human decides. Only a fatal hard signal (something physically impossible) bans automatically.

A track is an independent copy of all of this. The same user can have a separate default (anti-cheat) track and a behavior (chat conduct) track — different points, thresholds, detectors and bans, scored separately.

Install

Add the Guardable trait to the model you want to score:

Quick start

That's the whole loop: raise signals, read state, gate behaviour.

Core concepts

Signals

A signal is what a check emits. Three factory methods set the safety level:

detector, decay and reason accept a string or an enum (a backed enum becomes its value, a pure enum its name).

Score & decay

Every signal becomes a row; the score is the live sum of their remaining points. How fast points fade is the decay strategy:

Run the maintenance job daily so subjects recover as points fade:

States, thresholds & the safety clamp

You map a minimum score to each state. The highest boundary the score reaches wins:

The clamp: accumulated soft points can never push past soft_max_state (default review). Only a Signal::fatal() reaches banned automatically, and a ban stays even as the score decays. Set soft_max_state => null to remove the clamp (riskier — soft points can then ban).

Custom states (your own ladder)

The five states are the default ladder. To add or rename rungs, define your own enum implementing Guardian\Contracts\TrustStateContract and point state_enum at it — your cases are then used everywhere (thresholds, actions, middleware, reads), with full type-safety:

Now $user->trustState() returns your enum, guardian:probation works as middleware, and your thresholds/actions reference your cases.

Detectors

A detector is a reusable check. It implements one method and reads its own config options:

Register it in config (the array keys after class/enabled arrive as $options, read via $this->option('limit', 100)):

Then run checks:

$context is just the data your detectors need — you decide its shape.

Actions

When a subject enters a worse state, Guardian runs the action classes you mapped to it. Use the list form to pass the enum case directly (PHP can't use an enum as an array key), or a keyed map with string keys (the state's value or name) — both are accepted:

Shipped actions: FreezeAction (calls your guardianRestrict()), QueueForReviewAction (opens a deduplicated ModeratorReview with an evidence snapshot), BanAction (calls your guardianBan() + fires SubjectBanned). Write your own by implementing Guardian\Contracts\Action.

Tracks

Independent tracks for the same subject. Each track is fully defined under tracks.<name>; an undefined track inherits the default track's rules.

Every read helper and every Guardian method takes an optional track, so you can also write Guardian::report($user, $signal, [], 'behavior').

Caching

Trust standing (score / state / banned) and throttle counters live in the cache, so isBanned() in middleware never hits the database. The engine refreshes the cache on every change; if you edit the DB directly, call Guardian::reassess($user) or clear the cache. Configure the store under cache (see reference).

Recipes

Built-in: brute-force / throttle scoring

Guardian ships a ThrottleHitDetector. Feed it wherever you detect abuse — a failed login, a 429, a rejected rate-limiter:

It keeps a rolling per-subject counter in the cache (one per label) and scores once the count passes the allowance. Soft by design — it escalates toward review, never an automatic ban. Tune it in config:

Route middleware

The package registers the guardian alias. It blocks (403) when the subject's state is at or worse than the given one, in the given track:

Format: guardian:<state>[,<track>] — state defaults to banned, track to the default track.

Moderation

clear() wipes the subject's events for that track and resets it to trusted (also lifts a ban). Open cases live in the moderator_reviews table (Guardian\Models\ModeratorReview) with an evidence snapshot — list and resolve them from your admin UI.

Events

Hook listeners onto any of: SuspicionRaised, ThresholdCrossed, SentToReview, SubjectBanned.

Configuration reference

config/guardian.php — per-track rules live in tracks, everything else is shared:

API cheat-sheet

Facade Guardian\Facades\Guardian (every method takes an optional final track; or bind one with Guardian::track('x')->...):

Trait helpers on the subject (each takes an optional $track): trustState(), suspicionScore(), isBanned(), isFlagged(), needsReview(), raiseSuspicion($signals, $ctx = []), ban($reason = null), unban().

Testing

License

MIT © Roland Verner.