Customizing presets | laravel-suspicious-login | Spatie       

 SPATIE  

laravel-suspicious-login
========================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-suspicious-login](https://spatie.be/docs/laravel-suspicious-login/v1)  Basic-usage  Customizing presets

 Version   v1      

 Other versions for crawler [v1](https://spatie.be/docs/laravel-suspicious-login/v1) 

  Customizing presets    
- [ Introduction ](https://spatie.be/docs/laravel-suspicious-login/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-suspicious-login/v1/support-us)
- [ Requirements ](https://spatie.be/docs/laravel-suspicious-login/v1/requirements)
- [ Installation &amp; setup ](https://spatie.be/docs/laravel-suspicious-login/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-suspicious-login/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-suspicious-login/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-suspicious-login/v1/about-us)

Basic usage
-----------

- [ Getting started ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/getting-started)
- [ How a login is scored ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/how-a-login-is-scored)
- [ Choosing a preset ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/choosing-a-preset)
- [ Customizing presets ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/customizing-presets)
- [ Working with login attempts ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/working-with-login-attempts)
- [ Adding custom properties ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/adding-custom-properties)
- [ Recording logins manually ](https://spatie.be/docs/laravel-suspicious-login/v1/basic-usage/recording-logins-manually)

Available checks
----------------

- [ Overview ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/overview)
- [ New device ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-device)
- [ New IP address ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-ip)
- [ New country ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/new-country)
- [ Impossible travel ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/impossible-travel)
- [ Allowed and blocked countries ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/country)
- [ Failed attempts ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/failed-attempts)
- [ Credential stuffing ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/credential-stuffing)
- [ Unusual time ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/unusual-time)
- [ Suspicious user agent ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/suspicious-user-agent)
- [ IP reputation ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/ip-reputation)
- [ Multiple countries ](https://spatie.be/docs/laravel-suspicious-login/v1/available-checks/multiple-countries)

Responding to suspicious logins
-------------------------------

- [ Notifying users ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/notifying-users)
- [ Blocking logins ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/blocking-logins)
- [ Writing your own actions ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/writing-your-own-actions)
- [ Using events ](https://spatie.be/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/using-events)

Advanced usage
--------------

- [ Creating custom checks ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/creating-custom-checks)
- [ Geolocation drivers ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/geolocation-drivers)
- [ IP reputation drivers ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/ip-reputation-drivers)
- [ Device fingerprints ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/device-fingerprints)
- [ Using your own model ](https://spatie.be/docs/laravel-suspicious-login/v1/advanced-usage/using-your-own-model)

 Customizing presets
===================

###  On this page 

1. [ Configuring risk thresholds ](#content-configuring-risk-thresholds)
2. [ Tweaking a shipped preset ](#content-tweaking-a-shipped-preset)
3. [ Writing your own preset ](#content-writing-your-own-preset)
4. [ Choosing scores and thresholds ](#content-choosing-scores-and-thresholds)

A preset is a plain PHP class. To change how the package behaves, you extend one of the shipped presets or write your own, and point the config file at it.

Configuring risk thresholds
-----------------------------------------------------------------------------------------------------------------------------------------

The default thresholds live in `config/suspicious-login.php`:

```
'risk_thresholds' => [
    'medium' => 40,
    'high' => 70,
],
```

`Balanced`, `MonitorOnly` and custom presets use these values unless they define their own thresholds. `Strict` overrides them with 30 and 60; `Lenient` uses 50 and 80.

To override either threshold in a preset, define `$mediumRiskThreshold` or `$highRiskThreshold`. A property takes precedence over the config value. Leave a property out to inherit the parent's threshold, or the config value when the parent doesn't define one.

Tweaking a shipped preset
-----------------------------------------------------------------------------------------------------------------------------------

Let's say you like `Balanced`, but you want to block logins from one country and you consider a new IP address meaningless because your users are mostly on mobile networks. Extend the preset and override what you need:

```
namespace App\SuspiciousLogin;

use Spatie\SuspiciousLogin\Actions\Action;
use Spatie\SuspiciousLogin\Actions\BlockLoginAction;
use Spatie\SuspiciousLogin\Actions\NotifyUserAction;
use Spatie\SuspiciousLogin\Checks\Check;
use Spatie\SuspiciousLogin\Checks\CountryCheck;
use Spatie\SuspiciousLogin\Checks\NewIpCheck;
use Spatie\SuspiciousLogin\Presets\Balanced;

class MyPreset extends Balanced
{
    protected int $highRiskThreshold = 60;

    public function checks(): array
    {
        $checks = array_filter(
            parent::checks(),
            fn (Check $check) => ! $check instanceof NewIpCheck,
        );

        return [
            ...$checks,
            CountryCheck::new()->block(['KP'])->score(100),
        ];
    }

    public function onHighRisk(): Action|array
    {
        return [NotifyUserAction::new(), BlockLoginAction::new()];
    }
}
```

Then register it in `config/suspicious-login.php`:

```
'preset' => App\SuspiciousLogin\MyPreset::class,
```

Writing your own preset
-----------------------------------------------------------------------------------------------------------------------------

To start from scratch, extend `Spatie\SuspiciousLogin\Presets\Preset`. It has one method you must implement, and two optional ones:

- `checks()` returns the checks to run, each configured with its score and options.
- `onMediumRisk()` and `onHighRisk()` return what happens to a login at that level: a single action, or an array of actions that run in order. Leave one out and that level takes no action.

The `$mediumRiskThreshold` and `$highRiskThreshold` properties are optional. The example below overrides both; omit them to use the configured defaults.

Only the actions for the matching risk level run. A high risk login does not also run `onMediumRisk()`. When extending a shipped preset, omitting an action method keeps the parent's behavior. Override it and return `[]` to disable those actions.

```
namespace App\SuspiciousLogin;

use Spatie\SuspiciousLogin\Actions\Action;
use Spatie\SuspiciousLogin\Actions\BlockLoginAction;
use Spatie\SuspiciousLogin\Actions\NotifyUserAction;
use Spatie\SuspiciousLogin\Checks\FailedAttemptsCheck;
use Spatie\SuspiciousLogin\Checks\ImpossibleTravelCheck;
use Spatie\SuspiciousLogin\Checks\NewDeviceCheck;
use Spatie\SuspiciousLogin\Presets\Preset;

class AdminPanelPreset extends Preset
{
    protected int $mediumRiskThreshold = 20;

    protected int $highRiskThreshold = 50;

    public function checks(): array
    {
        return [
            NewDeviceCheck::new()->score(30),
            ImpossibleTravelCheck::new()->score(60),
            FailedAttemptsCheck::new()->threshold(3)->withinMinutes(30)->score(30),
        ];
    }

    public function onMediumRisk(): Action|array
    {
        return NotifyUserAction::new();
    }

    public function onHighRisk(): Action|array
    {
        return [
            NotifyUserAction::new(),
            BlockLoginAction::new()->message('This login was blocked. Please contact support if this was you.'),
        ];
    }
}
```

Choosing scores and thresholds
--------------------------------------------------------------------------------------------------------------------------------------------------

Scores are points, not percentages. A few guidelines that work well:

- Give a check that is suspicious on its own, such as impossible travel or a blocked country, a score at or above the high risk threshold.
- Give weak signals, such as a new IP address, a low score. They only matter when they add up with other signals.
- The total is capped at 100, so scores above 100 behave the same as 100.

If you want a completely different mapping from score to risk level, override the `riskLevel(int $score): RiskLevel` method of your preset. `RiskLevel` is the `Spatie\SuspiciousLogin\Enums\RiskLevel` enum, with the cases `Low`, `Medium` and `High`.

 A good
match?
-------------

### What we do best

- All things Laravel
- Custom frontend components
- Building APIs
- AI-powered features
- Simplifying things
- Clean solutions
- Integrating services

### Not our cup of tea

- WordPress themes
- Cutting corners
- Free mockups to win a job
- "Just execute the briefing"

 In short: we'd like to be a **substantial part** of your project.

 [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)
