{"id":13878227,"url":"https://github.com/philnash/pwned","last_synced_at":"2025-05-15T13:04:13.725Z","repository":{"id":30112853,"uuid":"123917988","full_name":"philnash/pwned","owner":"philnash","description":"😱 An easy, Ruby way to use the Pwned Passwords API.","archived":false,"fork":false,"pushed_at":"2023-12-28T16:58:19.000Z","size":334,"stargazers_count":431,"open_issues_count":5,"forks_count":22,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-15T02:15:16.100Z","etag":null,"topics":["activerecord-validator","gem","haveibeenpwned","password","passwords","ruby"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/pwned/","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/philnash.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"philnash"}},"created_at":"2018-03-05T12:43:36.000Z","updated_at":"2025-02-19T19:33:41.000Z","dependencies_parsed_at":"2024-04-26T23:46:48.365Z","dependency_job_id":null,"html_url":"https://github.com/philnash/pwned","commit_stats":{"total_commits":118,"total_committers":14,"mean_commits":8.428571428571429,"dds":0.3305084745762712,"last_synced_commit":"5fc4d4351d678b3234d4a55b32c8b5de094e73c6"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fpwned","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fpwned/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fpwned/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philnash%2Fpwned/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philnash","download_url":"https://codeload.github.com/philnash/pwned/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991559,"owners_count":21194894,"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":["activerecord-validator","gem","haveibeenpwned","password","passwords","ruby"],"created_at":"2024-08-06T08:01:43.289Z","updated_at":"2025-04-15T02:15:22.969Z","avatar_url":"https://github.com/philnash.png","language":"Ruby","funding_links":["https://github.com/sponsors/philnash"],"categories":["Ruby","ruby"],"sub_categories":[],"readme":"# Pwned\n\nAn easy, Ruby way to use the Pwned Passwords API.\n\n[![Gem Version](https://badge.fury.io/rb/pwned.svg)](https://rubygems.org/gems/pwned) ![Build Status](https://github.com/philnash/pwned/workflows/tests/badge.svg) [![Maintainability](https://codeclimate.com/github/philnash/pwned/badges/gpa.svg)](https://codeclimate.com/github/philnash/pwned/maintainability) [![Inline docs](https://inch-ci.org/github/philnash/pwned.svg?branch=master)](https://inch-ci.org/github/philnash/pwned)\n\n[API docs](https://www.rubydoc.info/gems/pwned) | [GitHub repository](https://github.com/philnash/pwned)\n\n## Table of Contents\n\n* [Table of Contents](#table-of-contents)\n* [About](#about)\n* [Installation](#installation)\n* [Usage](#usage)\n  * [Plain Ruby](#plain-ruby)\n    * [Custom request options](#custom-request-options)\n      * [HTTP Headers](#http-headers)\n      * [HTTP Proxy](#http-proxy)\n  * [ActiveRecord Validator](#activerecord-validator)\n    * [I18n](#i18n)\n    * [Threshold](#threshold)\n    * [Network Error Handling](#network-error-handling)\n    * [Custom Request Options](#custom-request-options-1)\n      * [HTTP Headers](#http-headers-1)\n      * [HTTP Proxy](#http-proxy-1)\n  * [Using Asynchronously](#using-asynchronously)\n  * [Devise](#devise)\n  * [Rodauth](#rodauth)\n  * [Command line](#command-line)\n  * [Unpwn](#unpwn)\n* [How Pwned is Pi?](#how-pwned-is-pi)\n* [Development](#development)\n* [Contributing](#contributing)\n* [License](#license)\n* [Code of Conduct](#code-of-conduct)\n\n## About\n\nTroy Hunt's [Pwned Passwords API](https://haveibeenpwned.com/API/v3#PwnedPasswords) allows you to check if a password has been found in any of the huge data breaches.\n\n`Pwned` is a Ruby library to use the Pwned Passwords API's [k-Anonymity model](https://www.troyhunt.com/ive-just-launched-pwned-passwords-version-2/#cloudflareprivacyandkanonymity) to test a password against the API without sending the entire password to the service.\n\nThe data from this API is provided by [Have I been pwned?](https://haveibeenpwned.com/). Before using the API, please check [the acceptable uses and license of the API](https://haveibeenpwned.com/API/v3#AcceptableUse).\n\nHere is a blog post I wrote on [how to use this gem in your Ruby applications to make your users' passwords better](https://www.twilio.com/blog/2018/03/better-passwords-in-ruby-applications-pwned-passwords-api.html).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'pwned'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install pwned\n\n## Usage\n\nThere are a few ways you can use this gem:\n\n1. [Plain Ruby](#plain-ruby)\n2. [Rails](#activerecord-validator)\n3. [Rails and Devise](#devise)\n\n### Plain Ruby\n\nTo test a password against the API, instantiate a `Pwned::Password` object and then ask if it is `pwned?`.\n\n```ruby\npassword = Pwned::Password.new(\"password\")\npassword.pwned?\n#=\u003e true\npassword.pwned_count\n#=\u003e 3303003\n```\n\nYou can also check how many times the password appears in the dataset.\n\n```ruby\npassword = Pwned::Password.new(\"password\")\npassword.pwned_count\n#=\u003e 3303003\n```\n\nSince you are likely using this as part of a sign-up flow, it is recommended that you rescue errors so if the service does go down, your user journey is not disturbed.\n\n```ruby\nbegin\n  password = Pwned::Password.new(\"password\")\n  password.pwned?\nrescue Pwned::Error =\u003e e\n  # Ummm... don't worry about it, I guess?\nend\n```\n\nMost of the times you only care if the password has been pwned before or not. You can use simplified accessors to check whether the password has been pwned, or how many times it was pwned:\n\n```ruby\nPwned.pwned?(\"password\")\n#=\u003e true\nPwned.pwned_count(\"password\")\n#=\u003e 3303003\n```\n\n#### Custom request options\n\nYou can set HTTP request options to be used with `Net::HTTP.start` when making the request to the API. These options are documented in the [`Net::HTTP.start` documentation](https://ruby-doc.org/stdlib-3.0.0/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start).\n\nYou can pass the options to the constructor:\n\n```ruby\npassword = Pwned::Password.new(\"password\", read_timeout: 10)\n```\n\nYou can also specify global defaults:\n\n```ruby\nPwned.default_request_options = { read_timeout: 10 }\n```\n\n##### HTTP Headers\n\nThe `:headers` option defines HTTP headers. These headers must be string keys.\n\n```ruby\npassword = Pwned::Password.new(\"password\", headers: {\n  'User-Agent' =\u003e 'Super fun new user agent'\n})\n```\n\n##### HTTP Proxy\n\nAn HTTP proxy can be set using the `http_proxy` or `HTTP_PROXY` environment variable. This is the same way that `Net::HTTP` handles HTTP proxies if no proxy options are given. See [`URI::Generic#find_proxy`](https://ruby-doc.org/stdlib-3.0.1/libdoc/uri/rdoc/URI/Generic.html#method-i-find_proxy) for full details on how Ruby detects a proxy from the environment.\n\n```ruby\n# Set in the environment\nENV[\"http_proxy\"] = \"https://username:password@example.com:12345\"\n\n# Will use the above proxy\npassword = Pwned::Password.new(\"password\")\n```\n\nYou can specify a custom HTTP proxy with the `:proxy` option:\n\n```ruby\npassword = Pwned::Password.new(\n  \"password\",\n  proxy: \"https://username:password@example.com:12345\"\n)\n```\n\nIf you don't want to set a proxy and you don't want a proxy to be inferred from the environment, set the `:ignore_env_proxy` key:\n\n```ruby\npassword = Pwned::Password.new(\"password\", ignore_env_proxy: true)\n```\n\n### ActiveRecord Validator\n\nThere is a custom validator available for your ActiveRecord models:\n\n```ruby\nclass User \u003c ApplicationRecord\n  validates :password, not_pwned: true\n  # or\n  validates :password, not_pwned: { message: \"has been pwned %{count} times\" }\nend\n```\n\n#### I18n\n\nYou can change the error message using I18n (use `%{count}` to interpolate the number of times the password was seen in the data breaches):\n\n```yaml\nen:\n  errors:\n    messages:\n      not_pwned: has been pwned %{count} times\n      pwned_error: might be pwned\n```\n\n#### Threshold\n\nIf you are ok with the password appearing a certain number of times before you decide it is invalid, you can set a threshold. The validator will check whether the `pwned_count` is greater than the threshold.\n\n```ruby\nclass User \u003c ApplicationRecord\n  # The record is marked as valid if the password has been used once in the breached data\n  validates :password, not_pwned: { threshold: 1 }\nend\n```\n\n#### Network Error Handling\n\nBy default the record will be treated as valid when we cannot reach the [haveibeenpwned.com](https://haveibeenpwned.com/) servers. This can be changed with the `:on_error` validator parameter:\n\n```ruby\nclass User \u003c ApplicationRecord\n  # The record is marked as valid on network errors.\n  validates :password, not_pwned: true\n  validates :password, not_pwned: { on_error: :valid }\n\n  # The record is marked as invalid on network errors\n  # (error message \"could not be verified against the past data breaches\".)\n  validates :password, not_pwned: { on_error: :invalid }\n\n  # The record is marked as invalid on network errors with custom error.\n  validates :password, not_pwned: { on_error: :invalid, error_message: \"might be pwned\" }\n\n  # We will raise an error on network errors.\n  # This means that `record.valid?` will raise `Pwned::Error`.\n  # Not recommended to use in production.\n  validates :password, not_pwned: { on_error: :raise_error }\n\n  # Call custom proc on error. For example, capture errors in Sentry,\n  # but do not mark the record as invalid.\n  validates :password, not_pwned: {\n    on_error: -\u003e(record, error) { Raven.capture_exception(error) }\n  }\nend\n```\n\n#### Custom Request Options\n\nYou can configure network requests made from the validator using `:request_options` (see [Net::HTTP.start](http://ruby-doc.org/stdlib-2.6.3/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start) for the list of available options).\n\n```ruby\n  validates :password, not_pwned: {\n    request_options: {\n      read_timeout: 5,\n      open_timeout: 1\n    }\n  }\n```\n\nThese options override the globally defined default options (see above).\n\nIn addition to these options, you can also set the following:\n\n##### HTTP Headers\n\nHTTP headers can be specified with the `:headers` key (e.g. `\"User-Agent\"`)\n\n```ruby\n  validates :password, not_pwned: {\n    request_options: {\n      headers: { \"User-Agent\" =\u003e \"Super fun user agent\" }\n    }\n  }\n```\n\n##### HTTP Proxy\n\nAn HTTP proxy can be set using the `http_proxy` or `HTTP_PROXY` environment variable. This is the same way that `Net::HTTP` handles HTTP proxies if no proxy options are given. See [`URI::Generic#find_proxy`](https://ruby-doc.org/stdlib-3.0.1/libdoc/uri/rdoc/URI/Generic.html#method-i-find_proxy) for full details on how Ruby detects a proxy from the environment.\n\n```ruby\n  # Set in the environment\n  ENV[\"http_proxy\"] = \"https://username:password@example.com:12345\"\n\n  validates :password, not_pwned: true\n```\n\nYou can specify a custom HTTP proxy with the `:proxy` key:\n\n```ruby\n  validates :password, not_pwned: {\n    request_options: {\n      proxy: \"https://username:password@example.com:12345\"\n    }\n  }\n```\n\nIf you don't want to set a proxy and you don't want a proxy to be inferred from the environment, set the `:ignore_env_proxy` key:\n\n```ruby\n  validates :password, not_pwned: {\n    request_options: {\n      ignore_env_proxy: true\n    }\n  }\n```\n\n### Using Asynchronously\n\nYou may have a use case for hashing the password in advance, and then making the call to the Pwned Passwords API later (for example if you want to enqueue a job without storing the plaintext password). To do this, you can hash the password with the `Pwned.hash_password` method and then initialize the `Pwned::HashedPassword` class with the hash, like this:\n\n```ruby\nhashed_password = Pwned.hash_password(password)\n# some time later\nPwned::HashedPassword.new(hashed_password, request_options).pwned?\n```\n\nThe `Pwned::HashedPassword` constructor takes all the same options as the regular `Pwned::Password` constructor.\n\n### Devise\n\nIf you are using [Devise](https://github.com/heartcombo/devise) I recommend you use the [devise-pwned_password extension](https://github.com/michaelbanfield/devise-pwned_password) which is now powered by this gem.\n\n### Rodauth\n\nIf you are using [Rodauth](https://github.com/jeremyevans/rodauth) then you can use the [rodauth-pwned](https://github.com/janko/rodauth-pwned) feature which is powered by this gem.\n\n### Command line\n\nThe gem provides a command line utility for checking passwords. You can call it from your terminal application like this:\n\n```bash\n$ pwned password\nPwned!\nThe password has been found in public breaches 3645804 times.\n```\n\nIf you don't want the password you are checking to be visible, call:\n\n```bash\n$ pwned --secret\n```\n\nYou will be prompted for the password, but it won't be displayed.\n\n### Unpwn\n\nTo cut down on unnecessary network requests, [the unpwn project](https://github.com/indirect/unpwn) uses a list of the top one million passwords to check passwords against. Only if a password is not included in the top million is it then checked against the Pwned Passwords API.\n\n## How Pwned is Pi?\n\n[@daz](https://github.com/daz) [shared](https://twitter.com/dazonic/status/1074647842046660609) a fantastic example of using this gem to show how many times the digits of Pi have been used as passwords and leaked.\n\n```ruby\nrequire 'pwned'\n\nPI = '3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111'\n\nfor n in 1..40\n  password = Pwned::Password.new PI[0..(n + 1)]\n  str = [ n.to_s.rjust(2) ]\n  str \u003c\u003c (password.pwned? ? '😡' : '😃')\n  str \u003c\u003c password.pwned_count.to_s.rjust(4)\n  str \u003c\u003c password.password\n\n  puts str.join ' '\nend\n```\n\nThe results may, or may not, surprise you.\n\n```\n 1 😡   16 3.1\n 2 😡  238 3.14\n 3 😡   34 3.141\n 4 😡 1345 3.1415\n 5 😡 2552 3.14159\n 6 😡  791 3.141592\n 7 😡 9582 3.1415926\n 8 😡 1591 3.14159265\n 9 😡  637 3.141592653\n10 😡  873 3.1415926535\n11 😡  137 3.14159265358\n12 😡  103 3.141592653589\n13 😡   65 3.1415926535897\n14 😡  201 3.14159265358979\n15 😡   41 3.141592653589793\n16 😡   57 3.1415926535897932\n17 😡   28 3.14159265358979323\n18 😡   29 3.141592653589793238\n19 😡    1 3.1415926535897932384\n20 😡    7 3.14159265358979323846\n21 😡    5 3.141592653589793238462\n22 😡    2 3.1415926535897932384626\n23 😡    2 3.14159265358979323846264\n24 😃    0 3.141592653589793238462643\n25 😡    3 3.1415926535897932384626433\n26 😃    0 3.14159265358979323846264338\n27 😃    0 3.141592653589793238462643383\n28 😃    0 3.1415926535897932384626433832\n29 😃    0 3.14159265358979323846264338327\n30 😃    0 3.141592653589793238462643383279\n31 😃    0 3.1415926535897932384626433832795\n32 😃    0 3.14159265358979323846264338327950\n33 😃    0 3.141592653589793238462643383279502\n34 😃    0 3.1415926535897932384626433832795028\n35 😃    0 3.14159265358979323846264338327950288\n36 😃    0 3.141592653589793238462643383279502884\n37 😃    0 3.1415926535897932384626433832795028841\n38 😃    0 3.14159265358979323846264338327950288419\n39 😃    0 3.141592653589793238462643383279502884197\n40 😃    0 3.1415926535897932384626433832795028841971\n```\n\n## Development\n\nAfter checking out the repository, 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.\n\nTo 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/philnash/pwned. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Pwned project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/philnash/pwned/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilnash%2Fpwned","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilnash%2Fpwned","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilnash%2Fpwned/lists"}