Update README.md

README.md

@@ -1,36 +1,73 @@
-# UsualSuspect
-Detect unusual activity in your users!
+# UsualSuspect: Your Rails Guardian Against Suspicious Logins and Behaviour
+
+**UsualSuspect** is a cutting-edge 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 to 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 advanced 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.
+- **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 this line to your application's Gemfile:
+Add UsualSuspect to your application's Gemfile:
 
 ```ruby
 gem 'usual_suspect'
 ```
 
-And then execute:
+Then execute:
 
-    $ bundle install
+```bash
+$ bundle install
+$ bundle exec rake usual_suspect:setup
+$ rails db:migrate
+```
 
-Or install it yourself as:
+Configure UsualSuspect in an initializer with your VPN API key from [vpnapi.io](https://vpnapi.io/api-documentation):
 
-    $ gem install usual_suspect
+```ruby
+UsualSuspect.configure do |config|
+  config.vpn_api_key = 'YOUR_API_KEY'
+end
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+Add this to your User model:
+
+```ruby
+include UsualSuspect::UserExtension
+
+has_many :usual_suspect_events
+```
 
-## Development
+In your sessions controller add:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+include UsualSuspect::SessionsControllerExtension
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+And when your session is created and you have a current_user available then add this line:
+
+```ruby
+track_usual_suspect_login
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/usual_suspect.
+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
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+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!