{"id":13878109,"url":"https://github.com/BaseSecrete/active_hashcash","last_synced_at":"2025-07-16T14:31:27.656Z","repository":{"id":41414943,"uuid":"506556788","full_name":"BaseSecrete/active_hashcash","owner":"BaseSecrete","description":"Protect Rails applications against bots and brute force attacks without annoying humans.","archived":false,"fork":false,"pushed_at":"2024-04-15T06:46:05.000Z","size":876,"stargazers_count":166,"open_issues_count":1,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-10T22:03:08.512Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BaseSecrete.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-23T08:25:39.000Z","updated_at":"2024-08-06T08:46:45.022Z","dependencies_parsed_at":"2024-04-15T08:08:24.276Z","dependency_job_id":null,"html_url":"https://github.com/BaseSecrete/active_hashcash","commit_stats":{"total_commits":23,"total_committers":1,"mean_commits":23.0,"dds":0.0,"last_synced_commit":"151445838b1dad092675baf41b75c5cb822ce89e"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseSecrete%2Factive_hashcash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseSecrete%2Factive_hashcash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseSecrete%2Factive_hashcash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaseSecrete%2Factive_hashcash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BaseSecrete","download_url":"https://codeload.github.com/BaseSecrete/active_hashcash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226138849,"owners_count":17579496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:01:40.040Z","updated_at":"2025-07-16T14:31:27.644Z","avatar_url":"https://github.com/BaseSecrete.png","language":"Ruby","readme":"# ActiveHashcash\n\nProtect Rails applications against bots and brute force attacks without annoying humans.\n\n\u003cdiv\u003e\u003cimg align=\"right\" width=\"200px\" src=\"logo.png\" alt=\"Active Hashcash logo\"/\u003e\u003c/div\u003e\n\nHashcash is proof-of-work algorithm, invented by Adam Back in 1997, to protect systems against denial of service attacks.\nActiveHashcash is an easy way to protect any Rails application against brute force attacks and bots.\n\nThe idea is to force clients to spend some time to solve a hard problem that is very easy to verify for the server.\nWe have developed ActiveHashcash after seeing brute force attacks against our Rails application monitoring service [RorVsWild](https://rorvswild.com).\n\nActiveHashcash is ideal to set up on sensitive forms such as login and registration.\nWhile the user is filling the form, the problem is solved in JavaScript and set the result into a hidden input text.\nThe form cannot be submitted while the proof of work has not been found.\nThen the user submits the form, and the stamp is verified by the controller in a before action.\n\nIt blocks bots that do not interpret JavaScript since the proof of work is not computed.\nMore sophisticated bots and brute force attacks are slow down.\nMoreover the complexity increases automatically for IP addresses sending many requests.\nThus it becomes very CPU costly for attackers.\n\nFinally legitimate users are not annoyed by asking to solve a puzzle or clicking on the all images containing a bus.\nHere is a [demo on a registration form](https://www.rorvswild.com/session) :\n\n![Active Hashcash GIF preview](demo.gif)\n\n---\n\n\u003cdiv\u003e\u003cimg align=\"left\" height=\"24px\" src=\"rorvswild_logo.jpg\" alt=\"RorVsWild logo\"/\u003eMade by \u003ca href=\"https://www.rorvswild.com\"\u003eRorVsWild\u003c/a\u003e, performances \u0026 exceptions monitoring for Ruby on Rails applications.\u003c/div\u003e\n\n---\n\n## Installation\n\nAdd this line to your application's Gemfile and run `bundle install`:\n\n```ruby\ngem \"active_hashcash\"\n```\n\nStamps are stored into the database to prevents from spending them more than once.\nYou must install and run a migration:\n\n```\nrails active_hashcash:install:migrations\nrails db:migrate\n```\n\nThen you have to include ActiveHashcash and add a `before_action :check_hashcash` in you controller:\n\n```ruby\nclass SessionController \u003c ApplicationController\n  include ActiveHashcash\n\n  # Only the action receiving the form needs to be protected\n  before_action :check_hashcash, only: :create\nend\n```\n\nThe action `SessionController#create` is now protected.\nThe final step is compute the hashcash from the client side.\nStart by adding a Hashcash hidden field into the form you want to protect.\n\n```erb\n\u003cform\u003e\n  \u003c%= hashcash_hidden_field_tag %\u003e\n\u003c/form\u003e\n```\n\nRequire hashcash from your JavaScript manifest.\n\n```js\n//= require hashcash\n```\n\nOr, link hashcash to your JavaScript manifest and load it to your head.\n\n```js\n//= link hashcash.js\n```\n\n```erb\n\u003c%= javascript_include_tag \"hashcash\", \"data-turbo-track\": \"reload\", defer: true %\u003e\n```\n\nThe hashcash stamp will be set in the hidden input once computed and the submit button enabled.\n\nTo customize behaviours, you can override methods of ActiveHashcash module.\n\n\n\n### Dashboard\n\nThere is a mountable dashboard which allows to see all spent stamps.\nIt's not mandatory, but useful for monitoring purpose.\n\n![ActiveHashcash dashboard](active_hashcash_dashboard.png \"ActiveHashcash dashboard\")\n\n```ruby\n# config/routes.rb\nmount ActiveHashcash::Engine, at: \"hashcash\"\n```\n\nActiveHashcash cannot guess how user authentication is handled, because it is different for all Rails applications.\nSo here is 3 options.\n\n#### Inheritance\n\nBy default ActiveHashcash extends `ActionController::Base`, but you can change it to any controller, such as `AdminController`.\n\n```ruby\n# config/initializers/active_hashcash.rb\nRails.application.configure do\n  ActiveHashcash.base_controller_class = \"AdminController\"\nend\n```\n#### Monkey patching\n\nMonkey patching `ActiveHashcash::ApplicationController` let you inject your own mechanism.\n\n```ruby\n# lib/patches/active_hashcash.rb\n\nActiveHashcash::ApplicationController.class_eval do\n    before_action :require_admin\n\n    def require_admin\n      # This example supposes there are current_user and User#admin? methods\n      raise ActionController::RoutingError.new(\"Not found\") unless current_user.try(:admin?)\n    end\n  end\nend\n```\n\nThen the patch has to be loaded from after initialization:\n\n```ruby\n# config/application.rb\nconfig.after_initialize do\n  require \"patches/active_hashcash\"\nend\n```\n\n#### With Devise\n\nPermission check can be achieved directly from routes.rb:\n\n```ruby\n# config/routes.rb\nauthenticate :user, -\u003e (u) { u.admin? } do # Supposing there is a User#admin? method\n  mount ActiveHashcash::Engine, at: \"hashcash\" # http://localhost:3000/hashcash\nend\n```\n\n### Before version 0.3.0\n\nYou must have Redis in order to prevent double spent stamps. Otherwise it will be useless.\nIt automatically tries to connect with the environment variables `ACTIVE_HASHCASH_REDIS_URL` or `REDIS_URL`.\nYou can also manually set the URL with `ActiveHashcash.redis_url = redis://user:password@localhost:6379`.\n\nYou should call `ActiveHashcash::Store#clean` once a day, to remove expired stamps.\n\nTo upgrade from 0.2.0 you must run the migration :\n\n```\nrails active_hashcash:install:migrations\nrails db:migrate\n```\n\n## Complexity\n\nComplexity is the most important parameter. By default its value is 20 and requires most of the time 5 to 20 seconds to be solved on a decent laptop.\nThe user won't wait that long, since he needs to fill the form while the problem is solving.\nHowever, if your application includes people with slow and old devices, then consider lowering this value, to 16 or 18.\n\nYou can change the minimum complexity with `ActiveHashcash.bits = 20`.\n\nSince version 0.3.0, the complexity increases with the number of stamps spent during le last 24H from the same IP address.\nThus it becomes very efficient to slow down brute force attacks.\n\n## Limitations\n\nThe JavaScript implementation is 10 to 20 times slower than the official C version.\nI first used the SubtleCrypto API but it is surprisingly slower than a custom SHA1 implementation.\nMaybe I did in an inefficient way 2df3ba5?\nAnother idea would be to compile the work algorithm in wasm.\n\nUnfortunately, I'm not a JavaScript expert.\nMaybe you have good JS skills to optimize it?\nAny help would be appreciate to better fights bots and brute for attacks!\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/BaseSecrete/active_hashcash.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\nMade by [Alexis Bernard](https://alexis.bernard.io/).\n","funding_links":[],"categories":["Ruby","Usage","HTML"],"sub_categories":["Tweaks:"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBaseSecrete%2Factive_hashcash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBaseSecrete%2Factive_hashcash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBaseSecrete%2Factive_hashcash/lists"}