Creating custom checks | 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)  Advanced-usage  Creating custom checks

 Version   v1      

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

  Creating custom checks    
- [ 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)

 Creating custom checks
======================

###  On this page 

1. [ Looking at earlier logins ](#content-looking-at-earlier-logins)
2. [ Injecting dependencies ](#content-injecting-dependencies)

Write a custom check when you want a signal the [built-in checks](/docs/laravel-suspicious-login/v1/available-checks/overview) don't cover, such as a login to an admin account or an account that has been inactive for months.

A check is a class that extends `Spatie\SuspiciousLogin\Checks\Check` and implements `evaluate`. It receives the `LoginAttempt` that is being scored and returns either `$this->pass()` or `$this->flag($reason)`:

```
namespace App\SuspiciousLogin\Checks;

use Spatie\SuspiciousLogin\Checks\Check;
use Spatie\SuspiciousLogin\Checks\CheckResult;
use Spatie\SuspiciousLogin\Models\LoginAttempt;

class AdminLoginCheck extends Check
{
    protected int $score = 20;

    public function evaluate(LoginAttempt $attempt): CheckResult
    {
        if (! $attempt->authenticatable?->is_admin) {
            return $this->pass();
        }

        return $this->flag('Login to an admin account');
    }
}
```

The `$score` property is the default score. Like every check, yours gets a `score()` method to change it in a preset. The reason you pass to `flag` is stored in the `reasons` of the login attempt and shown in the email to the user, so write it for a person.

To add it to the existing `Balanced` checks, create `app/SuspiciousLogin/MyPreset.php`:

```
namespace App\SuspiciousLogin;

use App\SuspiciousLogin\Checks\AdminLoginCheck;
use Spatie\SuspiciousLogin\Presets\Balanced;

class MyPreset extends Balanced
{
    public function checks(): array
    {
        return [
            ...parent::checks(),
            AdminLoginCheck::new()->score(30),
        ];
    }
}
```

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

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

This keeps `Balanced`'s notification actions. To choose your own actions and thresholds, see [customizing presets](/docs/laravel-suspicious-login/v1/basic-usage/customizing-presets).

Looking at earlier logins
-----------------------------------------------------------------------------------------------------------------------------------

Most interesting signals compare a login with what came before. `$attempt->history()` returns a query for the other login attempts of the same user, up to this one. Combine it with the `trusted()`, `failed()` and `since()` scopes.

Here's a check that flags the first login to an account that hasn't been used in months, with an option to configure how many:

```
namespace App\SuspiciousLogin\Checks;

use Spatie\SuspiciousLogin\Checks\Check;
use Spatie\SuspiciousLogin\Checks\CheckResult;
use Spatie\SuspiciousLogin\Models\LoginAttempt;

class DormantAccountCheck extends Check
{
    protected int $score = 20;

    protected int $days = 90;

    public function inactiveForDays(int $days): static
    {
        $this->days = $days;

        return $this;
    }

    public function evaluate(LoginAttempt $attempt): CheckResult
    {
        $previousLogin = $attempt->history()->trusted()->latest()->first();

        if (! $previousLogin) {
            return $this->pass();
        }

        if ($previousLogin->created_at->diffInDays($attempt->created_at) < $this->days) {
            return $this->pass();
        }

        return $this->flag("First login in more than {$this->days} days");
    }
}
```

```
DormantAccountCheck::new()->inactiveForDays(180)->score(25),
```

A check can also read [custom properties](/docs/laravel-suspicious-login/v1/basic-usage/adding-custom-properties) you add to every login, with `$attempt->getProperty()`.

Use `trusted()` when you compare with what the user normally does. It only returns successful logins that weren't blocked, so an attacker can't shape the history by failing to log in.

Injecting dependencies
--------------------------------------------------------------------------------------------------------------------------

Checks are resolved from the container by `new()`, so you can type-hint dependencies in the constructor:

```
use App\Services\BreachedPasswords;

class BreachedPasswordCheck extends Check
{
    public function __construct(
        protected BreachedPasswords $breachedPasswords,
    ) {}

    // ...
}
```

Checks run during the login request. If your check calls an external service, give it a short timeout and cache the result, the way the [geolocation drivers](/docs/laravel-suspicious-login/v1/advanced-usage/geolocation-drivers) do.

 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)
