How a login is scored | 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  How a login is scored

 Version   v1      

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

  How a login is scored    
- [ 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)

 How a login is scored
=====================

###  On this page 

1. [ Risk levels ](#content-risk-levels)
2. [ An example ](#content-an-example)
3. [ What counts as known ](#content-what-counts-as-known)
4. [ Logins that aren't recorded ](#content-logins-that-arent-recorded)

Every time someone tries to log in, the package stores a `LoginAttempt`. Failed attempts are only recorded, because there is nothing to protect yet. Successful logins go through a few more steps:

1. The package looks up where the IP address is, using your [geolocation driver](/docs/laravel-suspicious-login/v1/advanced-usage/geolocation-drivers).
2. It runs every check of the [preset](/docs/laravel-suspicious-login/v1/basic-usage/choosing-a-preset). Each check compares the login with the user's earlier logins, or with what happened recently on the same IP address.
3. Each check that flags the login adds its score. The scores are added up, and the total is capped at 100.
4. The preset turns that score into a risk level: low, medium or high.
5. The attempt is saved with its score, level and reasons.
6. When the level is medium or high, the package runs the preset's actions for that level, such as notifying the user or blocking the login.

All of this happens during the login request, right after Laravel logs the user in. That's why an action can still block the login.

Risk levels
-----------------------------------------------------------------------------------------

Two thresholds decide where medium and high risk start. They default to 40 and 70 in `config/suspicious-login.php`, and a preset can override either value. With the default `Balanced` preset and config:

ScoreRisk level0 to 39`RiskLevel::Low`40 to 69`RiskLevel::Medium`70 to 100`RiskLevel::High`A low risk login is recorded and nothing else happens. Medium and high risk logins are considered suspicious.

See [configuring risk thresholds](/docs/laravel-suspicious-login/v1/basic-usage/customizing-presets#configuring-risk-thresholds) to change these values.

An example
--------------------------------------------------------------------------------------

Let's go back to Anna from the introduction. She has been logging in every morning from Antwerp on her MacBook. Tonight, someone logs in to her account from New York, using Firefox on Windows.

The `Balanced` preset runs its checks:

- `NewDeviceCheck` has never seen this device in one of Anna's logins. **+25**
- `NewIpCheck` has never seen this IP address. **+10**
- `NewCountryCheck` sees that Anna has never logged in from the United States. **+30**
- `ImpossibleTravelCheck` compares the location with her login this morning. Antwerp to New York in ten hours is possible by plane, so it passes.
- `FailedAttemptsCheck`, `CredentialStuffingCheck` and `SuspiciousUserAgentCheck` pass too.

The score is 65, which is medium risk. The `Balanced` preset notifies Anna, and the attempt is stored like this:

```
$attempt->risk_score; // 65
$attempt->risk_level; // RiskLevel::Medium
$attempt->isSuspicious(); // true

$attempt->reasons;
// [
//     ['check' => NewDeviceCheck::class, 'score' => 25, 'reason' => 'Login from a new device'],
//     ['check' => NewIpCheck::class, 'score' => 10, 'reason' => 'Login from a new IP address (5.6.7.8)'],
//     ['check' => NewCountryCheck::class, 'score' => 30, 'reason' => 'Login from a new country (US)'],
// ]
```

What counts as known
--------------------------------------------------------------------------------------------------------------------

Checks like `NewDeviceCheck` only compare a login with earlier logins that were **successful and not blocked**. Failed attempts and blocked logins never make a device, IP address or country "known". Otherwise an attacker could fail to log in a few times from their laptop, and then log in with a device that already looks familiar.

The first login of a user is never flagged for a new device, IP address or country. There is nothing to compare it with yet.

Logins that aren't recorded
---------------------------------------------------------------------------------------------------------------------------------------

Laravel also fires its `Login` event when it logs a user back in with a "remember me" cookie. Those aren't new logins, so the package skips them. Otherwise every visit of a remembered user would be scored.

To disable automatic recording through Laravel's auth events, set `enabled` to `false` in `config/suspicious-login.php`. Explicit calls to `recordSuccessfulLogin()`, `recordFailedLogin()` and `assess()` still work.

 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)
