Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/deadkennedyx/usualsuspect

Gem that tracks suspicious activity within your user sessions.
https://github.com/deadkennedyx/usualsuspect

device-fingerprinting fingerprinting gem geolocalization geolocation proxy rails ruby ruby-on-rails rubyonrails security security-audit security-tools tor user-behavior-analytics vpn

Last synced: 10 days ago
JSON representation

Gem that tracks suspicious activity within your user sessions.

Awesome Lists containing this project

README 

        
# UsualSuspect: Your Rails Guardian Against Suspicious Logins and Behaviour



**UsualSuspect** is a Ruby gem specifically tailored for Rails applications, designed to fortify your user authentication system against an array of security threats. With a focus on real-time analysis and monitoring of user logins, UsualSuspect acts as a vigilant guard, identifying unusual and potentially harmful activities, the response is up to you!



## Key Features



- **Password Change Monitoring**: Detects and logs suspicious password changes immediately after user login, providing an early warning system against account hijacking.

- **Geo-Velocity Tracking**: Utilizes algorithms to calculate the speed of user movement based on login locations, flagging physically impossible travel scenarios that may indicate account compromises or account multi sharing.

- **Device Fingerprinting**: Device fingerprinting support.

- **New Device Detection**: check saved fingerprints to detect new devices.

- **VPN, Proxy and Tor Detection**: Leverages [vpnapi.io](https://vpnapi.io/api-documentation) robust database to identify logins from VPNs and proxies, enhancing your defense against masked IP addresses and location spoofing.

- **Session-Specific Analysis**: Each login session is treated uniquely, ensuring precise and context-aware security checks.

- **Configurable and Extendable**: Tailor the gem's behavior to your application's specific needs with customizable settings and thresholds.

- **Seamless Rails Integration**: Designed to integrate effortlessly with Rails applications, allowing you to add an extra layer of security with minimal setup.



## Installation



Add UsualSuspect to your application's Gemfile:



```ruby

gem 'usual_suspect'

```



Then execute:



```bash

$ bundle install

$ bundle exec rake usual_suspect:setup

$ rails db:migrate

```



Configure UsualSuspect in an initializer with your VPN API key from [vpnapi.io](https://vpnapi.io/api-documentation):



```ruby

UsualSuspect.configure do |config|

  config.vpn_api_key = 'YOUR_API_KEY'

end

```

The free tier on [vpnapi.io](https://vpnapi.io/api-documentation) allows for 1k requests per day, you'll need to upgrade tier if you want more, if you want to make this gem to be available to use in more services feel free to open a pull request or an issue and I'll add support for more services!



## Usage



Add this to your User model:



```ruby

include UsualSuspect::UserExtension



has_many :usual_suspect_events

```



In your sessions controller add:



```ruby

include UsualSuspect::SessionsControllerExtension

```



And when your session is created and you have a current_user available then add this line:



```

track_usual_suspect_login

```

#### Suspicious password change:



To check for suspicious password change after login you can add this in the controller and method where the user password is updated:

```	

current_user.check_for_suspicious_password_change(session[:usual_suspect_session_token])

```

#### Device fingerprinting:

To add device fingerprinting you will need to send device_info parameters in your login form. you can get device_info this way with javascript, usual_suspect will take care of the rest.



This will save the device fingerprint as a sha256 digest `device_fingerprint: "c18ab96a22bece029c71a7229b48234786b3055880eeda6091942ef5cd136"` and if a new device logs with a different fingerprint it will save the `new_device` column as true.



```javascript

var formId = 'your_login_form_id'; // Replace with your actual form ID

var form = document.getElementById(formId);



var deviceInfo = {

    language: navigator.language,

    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,

    screen_width: screen.width,

    screen_height: screen.height,

    colorDepth: screen.colorDepth,

    sessionStorage: !!window.sessionStorage,

    localStorage: !!window.localStorage,

    cookiesEnabled: navigator.cookieEnabled,

    deviceMemory: navigator.deviceMemory || 'unknown',

    hardwareConcurrency: navigator.hardwareConcurrency,

};



function createAndAppendInput(name, value) {

    var input = document.createElement('input');

    input.type = 'hidden';

    input.name = 'device_info[' + name + ']';

    input.value = value;

    form.append(input);

}



for (var key in deviceInfo) {

    createAndAppendInput(key, deviceInfo[key]);

}

```

#### Data saved:

When the user logs in, it will create a new record in the table `UsualSuspectEvent`, and depending on the fields you can decide if you should block that user account.

Also when the user changes password it will update the `password_change_after_login` to true if the password change was before 5 minutes of being logged in.



UsualSuspectEvent Table:

```ruby

#

```



## Contributing



If you are cloning or using the gem, give me a little star :)!



Contributions are more than welcome! If you have ideas for improvements or encounter any issues, please feel free to fork the repository and submit a pull request or an issue and I'll find the time to fix it.



## License



Distributed under the MIT License. See `LICENSE` for more information.



## Acknowledgements



- [vpnapi.io](https://vpnapi.io/api-documentation)

- [Geocoder](https://github.com/alexreisner/geocoder)



Elevate your Rails application's security to the next level with UsualSuspect!