Introduction | 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)  Introduction

 Version   v1      

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

  Introduction    
- [ 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)

  Laravel-suspicious-login 
==========================

 Detect suspicious logins and decide how to respond. 

### Useful links

- [Repository](https://github.com/spatie/laravel-suspicious-login)
- [Discussions](https://github.com/spatie/laravel-suspicious-login/discussions)

Introduction
------------

###  On this page 

1. [ Everything is customizable ](#content-everything-is-customizable)

A stolen password rarely looks like an attack. The attacker types the right email address and the right password, and to your app that's a perfectly normal login.

This package looks at everything around that login: the device, the IP address, where in the world it comes from, how many attempts failed before it, and what the user usually does. Each suspicious signal adds points to a risk score, and the risk score decides what happens next.

Here's an example. Anna logs in to your app every morning from Antwerp, on the same MacBook. One evening, someone logs in to her account from a Windows laptop in New York. With the default `Balanced` preset and a [geolocation driver](/docs/laravel-suspicious-login/v1/advanced-usage/geolocation-drivers) configured, the package scores that login like this:

```
Login from a new device                  +25
Login from a new IP address (5.6.7.8)    +10
Login from a new country (US)            +30
                                         ----
Risk score                                65  → medium risk
```

A medium risk login sends Anna an email that lists those reasons, so she can change her password if it wasn't her.

If that login had happened thirty minutes after her morning login in Antwerp, nobody could have traveled that far in time. The impossible travel check would add 60 points, and the login would be high risk. With the `Strict` preset, the package blocks a high risk login right away.

The package listens for Laravel's own login events, so it works with Breeze, Jetstream, Fortify and your own login controllers without any changes.

Everything is customizable
--------------------------------------------------------------------------------------------------------------------------------------

What the package checks and how it responds is decided by a preset. A preset is a small PHP class that lists the checks to run, how much each one weighs, where the risk levels start, and which actions run for each level. The package ships with four presets, and writing your own takes a few lines:

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

class MyPreset extends Preset
{
    public function checks(): array
    {
        return [
            NewDeviceCheck::new()->score(30),
            ImpossibleTravelCheck::new()->maxSpeedInKilometersPerHour(1000)->score(60),
            CountryCheck::new()->onlyAllow(['BE', 'NL', 'FR'])->score(60),
        ];
    }

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

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

This preset uses the default risk thresholds from `config/suspicious-login.php`: 40 for medium risk and 70 for high risk. You can change the config values, or [override either threshold in your preset](/docs/laravel-suspicious-login/v1/basic-usage/customizing-presets#configuring-risk-thresholds).

Checks, actions, geolocation and IP reputation lookups, device fingerprints and the model are all swappable. And when you want to react to something yourself, the package [fires events](/docs/laravel-suspicious-login/v1/responding-to-suspicious-logins/using-events) you can listen for.

 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)
