百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
P

pwned

> 编程语言
开源

使用 Pwned Passwords API 的简单 Ruby 方式。

449 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

使用 Pwned Passwords API 的简单 Ruby 方式。

Pwned

An easy, Ruby way to use the Pwned Passwords API.

API docs | GitHub repository

Table of Contents

  • Table of Contents
  • About
  • Installation
  • Usage
    • Plain Ruby
      • Custom request options
        • HTTP Headers
        • HTTP Proxy
    • ActiveRecord Validator
      • I18n
      • Threshold
      • Network Error Handling
      • Custom Request Options
        • HTTP Headers
        • HTTP Proxy
    • Using Asynchronously
    • Devise
    • Rodauth
    • Command line
    • Unpwn
  • How Pwned is Pi?
  • Development
  • Contributing
  • License
  • Code of Conduct

About

Troy Hunt's Pwned Passwords API allows you to check if a password has been found in any of the huge data breaches.

Pwned is a Ruby library to use the Pwned Passwords API's k-Anonymity model to test a password against the API without sending the entire password to the service.

The data from this API is provided by Have I been pwned?. Before using the API, please check the acceptable uses and license of the API.

Here is a blog post I wrote on how to use this gem in your Ruby applications to make your users' passwords better.

Installation

Add this line to your application's Gemfile:

ruby
gem 'pwned'

And then execute:

$ bundle

Or install it yourself as:

$ gem install pwned

Usage

There are a few ways you can use this gem:

  1. Plain Ruby
  2. Rails
  3. Rails and Devise

Plain Ruby

To test a password against the API, instantiate a Pwned::Password object and then ask if it is pwned?.

ruby
password = Pwned::Password.new("password")
password.pwned?
#=> true
password.pwned_count
#=> 3303003

You can also check how many times the password appears in the dataset.

ruby
password = Pwned::Password.new("password")
password.pwned_count
#=> 3303003

Since 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.

ruby
begin
  password = Pwned::Password.new("password")
  password.pwned?
rescue Pwned::Error => e
  # Ummm... don't worry about it, I guess?
end

Most 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:

ruby
Pwned.pwned?("password")
#=> true
Pwned.pwned_count("password")
#=> 3303003

Custom request options

You 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.

You can pass the options to the constructor:

ruby
password = Pwned::Password.new("password", read_timeout: 10)

You can also specify global defaults:

ruby
Pwned.default_request_options = { read_timeout: 10 }
HTTP Headers

The :headers option defines HTTP headers. These headers must be string keys.

ruby
password = Pwned::Password.new("password", headers: {
  'User-Agent' => 'Super fun new user agent'
})
HTTP Proxy

An 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 for full details on how Ruby detects a proxy from the environment.

ruby
# Set in the environment
ENV["http_proxy"] = "https://username:[email protected]:12345"

# Will use the above proxy
password = Pwned::Password.new("password")

You can specify a custom HTTP proxy with the :proxy option:

ruby
password = Pwned::Password.new(
  "password",
  proxy: "https://username:[email protected]:12345"
)

If 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:

ruby
password = Pwned::Password.new("password", ignore_env_proxy: true)

ActiveRecord Validator

There is a custom validator available for your ActiveRecord models:

ruby
class User (record, error) { Raven.capture_exception(error) }
  }
end

Custom Request Options

You can configure network requests made from the validator using :request_options (see Net::HTTP.start for the list of available options).

ruby
  validates :password, not_pwned: {
    request_options: {
      read_timeout: 5,
      open_timeout: 1
    }
  }

These options override the globally defined default options (see above).

In addition to these options, you can also set the following:

HTTP Headers

HTTP headers can be specified with the :headers key (e.g. "User-Agent")

ruby
  validates :password, not_pwned: {
    request_options: {
      headers: { "User-Agent" => "Super fun user agent" }
    }
  }
HTTP Proxy

An 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 for full details on how Ruby detects a proxy from the environment.

ruby
  # Set in the environment
  ENV["http_proxy"] = "https://username:[email protected]:12345"

  validates :password, not_pwned: true

You can specify a custom HTTP proxy with the :proxy key:

ruby
  validates :password, not_pwned: {
    request_options: {
      proxy: "https://username:[email protected]:12345"
    }
  }

If 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:

ruby
  validates :password, not_pwned: {
    request_options: {
      ignore_env_proxy: true
    }
  }

Using Asynchronously

You 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:

ruby
hashed_password = Pwned.hash_password(password)
# some time later
Pwned::HashedPassword.new(hashed_password, request_options).pwned?

The Pwned::HashedPassword constructor takes all the same options as the regular Pwned::Password constructor.

Devise

If you are using Devise I recommend you use the devise-pwned_password extension which is now powered by this gem.

Rodauth

If you are using Rodauth then you can use the rodauth-pwned feature which is powered by this gem.

Command line

The gem provides a command line utility for checking passwords. You can call it from your terminal application like this:

bash
$ pwned password
Pwned!
The password has been found in public breaches 3645804 times.

If you don't want the password you are checking to be visible, call:

bash
$ pwned --secret

You will be prompted for the password, but it won't be displayed.

Unpwn

To cut down on unnecessary network requests, the unpwn project 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.

How Pwned is Pi?

@daz shared a fantastic example of using this gem to show how many times the digits of Pi have been used as passwords and leaked.

ruby
require 'pwned'

PI = '3.14159265358979323846264338327950288419716939937510582097494459230781640628620899862803482534211706798214808651328230664709384460955058223172535940812848111'

for n in 1..40
  password = Pwned::Password.new PI[0..(n + 1)]
  str = [ n.to_s.rjust(2) ]
  str << (password.pwned? ? '' : '')
  str << password.pwned_count.to_s.rjust(4)
  str << password.password

  puts str.join ' '
end

The results may, or may not, surprise you.

…

Development

After 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.

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 tags, and push the .gem file to rubygems.org.

Contributing

Bug 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 code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Pwned project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Issues· 5 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rubyactiverecord-validatorgemhaveibeenpwnedpassword

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言