lib.wKovacs64.hibp
Tag 5
Functions for querying the 'Have I been pwned?' API.
  Published by wKovacs64 on Aug 6th 2017, 9:11 PM
  # [hibp][hibp] microservice on [StdLib][stdlib] *Functions for querying the '[Have I been pwned?][haveibeenpwned]' API.* * [breach](#breach) * [breachedAccount](#breachedaccount) * [breaches](#breaches) * [dataClasses](#dataclasses) * [pasteAccount](#pasteaccount) * [pwnedPassword](#pwnedpassword) * [search](#search) ## breach ##### Description Fetches breach data for a single breach. ##### Parameters * `breachName`: the name of a breach in the system ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.breach --breachName Adobe ``` Shorthand for the same request: ```bash $ lib wKovacs64.hibp.breach Adobe ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breach/?breachName=Adobe ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breach } = lib.wKovacs64.hibp; breach({ breachName: 'Adobe' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## breachedAccount ##### Description Fetches all breach data for an account. ##### Parameters * `account`: a username or email address (required) * `domain`: a domain by which to filter the results (optional, default: all domains) * `truncate`: truncate the results to only include the name of each breach (optional, default: false) ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: Return a JSON object with breach information for the specified account: ```bash $ lib wKovacs64.hibp.breachedAccount --account foo ``` Truncate the same results to just the breach names: ```bash $ lib wKovacs64.hibp.breachedAccount --account foo --truncate true ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo ``` Limit to a specific domain: ```http https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo&domain=adobe.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breachedAccount } = lib.wKovacs64.hibp; breachedAccount({ account: 'foo' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## breaches ##### Description Fetches all breach data in the system. ##### Parameters * `domain`: a domain by which to filter the results (optional, default: all domains) ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.breaches ``` Filter by domain: ```bash $ lib wKovacs64.hibp.breaches --domain adobe.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breaches/ ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breaches } = lib.wKovacs64.hibp; breaches() .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## dataClasses ##### Description Fetches all data classes in the system. ##### Parameters * *none* ##### Data Returned See the [data classes][apidataclasses] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.dataClasses ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/dataClasses/ ``` ###### Web and Node.js: ```js const lib = require('lib'); const { dataClasses } = lib.wKovacs64.hibp; dataClasses() .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## pasteAccount ##### Description Fetches all pastes for an email address. ##### Parameters * `email`: the email address to query (required) ##### Data Returned See the [paste model][apipastemodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.pasteAccount --email foo@bar.com ``` Shorthand for the same request: ```bash $ lib wKovacs64.hibp.pasteAccount foo@bar.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/pasteAccount/?email=foo@bar.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { pasteAccount } = lib.wKovacs64.hibp; pasteAccount({ email: 'foo@bar.com' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## pwnedPassword ##### Description Fetches the pwned status for the given password, indicating whether or not it has been previously exposed in a breach. See the [Pwned Passwords][apipwnedpassword] section of the API documentation for more information. ##### Parameters * `password`: a password as a plain text string or SHA1 hash (required) * `sha1`: a boolean indicating the pre-hashed password is a hash (optional, default: false) ##### Data Returned `pwnedPassword` returns a boolean. ##### Usage ###### Command-line: Return a boolean corresponding to the pwned status of the specified password: ```bash $ lib wKovacs64.hibp.pwnedPassword --password Password1234 ``` Return a boolean corresponding to the pwned status of the specified SHA1 hash: ```bash $ lib wKovacs64.hibp.pwnedPassword --password 5e447cbeee6f483bf88c461d76994b0063ae81d5 ``` Override the [remote API's SHA1 hash auto-detection][apipwnedpassword] and specify that the password is actually a SHA1 hash: ```bash $ lib wKovacs64.hibp.pwnedPassword --password 5e447cbeee6f483bf88c461d76994b0063ae81d5 --sha1 true ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/pwnedPassword/?password=Password1234 ``` Specify a literal SHA1 password: ```http https://wkovacs64.lib.id/hibp/pwnedPassword/?password=5e447cbeee6f483bf88c461d76994b0063ae81d5&sha1=true ``` ###### Web and Node.js: ```js const lib = require('lib'); const { pwnedPassword } = lib.wKovacs64.hibp; pwnedPassword({ password: 'Password1234' }) .then((isPwned) => { // handle result }) .catch((err) => { // handle error }); ``` ## search ##### Description Fetches all breaches and all pastes associated with a given account. ##### Parameters * `account`: a username or email address (required) * `domain`: a domain by which to filter breach results (optional, default: all domains) * `truncate`: truncate the results to only include the name of each breach (optional, default: false) ##### Data Returned `search` returns a JSON object with a `breaches` key and a `pastes` key. See the [breach model][apibreachmodel] and [paste model][apipastemodel] sections of the API documentation (respectively) for descriptions of the values of those keys. Each value may independently be null if no corresponding data was found. ##### Usage ###### Command-line: Return a JSON object with breach and paste information for the specified account: ```bash $ lib wKovacs64.hibp.search --account foo ``` Return a JSON object with breach and paste information for the specified email address: ```bash $ lib wKovacs64.hibp.search --account foo@bar.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/search/?account=foo ``` Limit breach data to a specific domain: ```http https://wkovacs64.lib.id/hibp/search/?account=foo&domain=adobe.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { search } = lib.wKovacs64.hibp; search({ account: 'foo' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## ✍ Author's Note There's a good chance this project adds no value. I primarily did it as an introduction to microservices on [StdLib][stdlib]. The current access methods probably have superior, preexisting alternatives: * Command-line: [pwned][pwned] is more flexible. * HTTP: Just query the [API][api] endpoints directly? * Web and Node.js: [hibp][hibp] powers this microservice. Use that. [hibp]: https://github.com/wKovacs64/hibp [pwned]: https://github.com/wKovacs64/pwned [stdlib]: https://stdlib.com [haveibeenpwned]: https://haveibeenpwned.com [api]: https://haveibeenpwned.com/API/v2 [apibreachmodel]: https://haveibeenpwned.com/api/v2#BreachModel [apidataclasses]: https://haveibeenpwned.com/API/v2#AllDataClasses [apipastemodel]: https://haveibeenpwned.com/API/v2#PasteModel [apipwnedpassword]: https://haveibeenpwned.com/api/v2#PwnedPasswords
# [hibp][hibp] microservice on [StdLib][stdlib] *Functions for querying the '[Have I been pwned?][haveibeenpwned]' API.* * [breach](#breach) * [breachedAccount](#breachedaccount) * [breaches](#breaches) * [dataClasses](#dataclasses) * [pasteAccount](#pasteaccount) * [pwnedPassword](#pwnedpassword) * [search](#search) ## breach ##### Description Fetches breach data for a single breach. ##### Parameters * `breachName`: the name of a breach in the system ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.breach --breachName Adobe ``` Shorthand for the same request: ```bash $ lib wKovacs64.hibp.breach Adobe ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breach/?breachName=Adobe ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breach } = lib.wKovacs64.hibp; breach({ breachName: 'Adobe' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## breachedAccount ##### Description Fetches all breach data for an account. ##### Parameters * `account`: a username or email address (required) * `domain`: a domain by which to filter the results (optional, default: all domains) * `truncate`: truncate the results to only include the name of each breach (optional, default: false) ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: Return a JSON object with breach information for the specified account: ```bash $ lib wKovacs64.hibp.breachedAccount --account foo ``` Truncate the same results to just the breach names: ```bash $ lib wKovacs64.hibp.breachedAccount --account foo --truncate true ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo ``` Limit to a specific domain: ```http https://wkovacs64.lib.id/hibp/breachedAccount/?account=foo&domain=adobe.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breachedAccount } = lib.wKovacs64.hibp; breachedAccount({ account: 'foo' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## breaches ##### Description Fetches all breach data in the system. ##### Parameters * `domain`: a domain by which to filter the results (optional, default: all domains) ##### Data Returned See the [breach model][apibreachmodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.breaches ``` Filter by domain: ```bash $ lib wKovacs64.hibp.breaches --domain adobe.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/breaches/ ``` ###### Web and Node.js: ```js const lib = require('lib'); const { breaches } = lib.wKovacs64.hibp; breaches() .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## dataClasses ##### Description Fetches all data classes in the system. ##### Parameters * *none* ##### Data Returned See the [data classes][apidataclasses] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.dataClasses ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/dataClasses/ ``` ###### Web and Node.js: ```js const lib = require('lib'); const { dataClasses } = lib.wKovacs64.hibp; dataClasses() .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## pasteAccount ##### Description Fetches all pastes for an email address. ##### Parameters * `email`: the email address to query (required) ##### Data Returned See the [paste model][apipastemodel] section of the API documentation for a description of the data returned. ##### Usage ###### Command-line: ```bash $ lib wKovacs64.hibp.pasteAccount --email foo@bar.com ``` Shorthand for the same request: ```bash $ lib wKovacs64.hibp.pasteAccount foo@bar.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/pasteAccount/?email=foo@bar.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { pasteAccount } = lib.wKovacs64.hibp; pasteAccount({ email: 'foo@bar.com' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## pwnedPassword ##### Description Fetches the pwned status for the given password, indicating whether or not it has been previously exposed in a breach. See the [Pwned Passwords][apipwnedpassword] section of the API documentation for more information. ##### Parameters * `password`: a password as a plain text string or SHA1 hash (required) * `sha1`: a boolean indicating the pre-hashed password is a hash (optional, default: false) ##### Data Returned `pwnedPassword` returns a boolean. ##### Usage ###### Command-line: Return a boolean corresponding to the pwned status of the specified password: ```bash $ lib wKovacs64.hibp.pwnedPassword --password Password1234 ``` Return a boolean corresponding to the pwned status of the specified SHA1 hash: ```bash $ lib wKovacs64.hibp.pwnedPassword --password 5e447cbeee6f483bf88c461d76994b0063ae81d5 ``` Override the [remote API's SHA1 hash auto-detection][apipwnedpassword] and specify that the password is actually a SHA1 hash: ```bash $ lib wKovacs64.hibp.pwnedPassword --password 5e447cbeee6f483bf88c461d76994b0063ae81d5 --sha1 true ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/pwnedPassword/?password=Password1234 ``` Specify a literal SHA1 password: ```http https://wkovacs64.lib.id/hibp/pwnedPassword/?password=5e447cbeee6f483bf88c461d76994b0063ae81d5&sha1=true ``` ###### Web and Node.js: ```js const lib = require('lib'); const { pwnedPassword } = lib.wKovacs64.hibp; pwnedPassword({ password: 'Password1234' }) .then((isPwned) => { // handle result }) .catch((err) => { // handle error }); ``` ## search ##### Description Fetches all breaches and all pastes associated with a given account. ##### Parameters * `account`: a username or email address (required) * `domain`: a domain by which to filter breach results (optional, default: all domains) * `truncate`: truncate the results to only include the name of each breach (optional, default: false) ##### Data Returned `search` returns a JSON object with a `breaches` key and a `pastes` key. See the [breach model][apibreachmodel] and [paste model][apipastemodel] sections of the API documentation (respectively) for descriptions of the values of those keys. Each value may independently be null if no corresponding data was found. ##### Usage ###### Command-line: Return a JSON object with breach and paste information for the specified account: ```bash $ lib wKovacs64.hibp.search --account foo ``` Return a JSON object with breach and paste information for the specified email address: ```bash $ lib wKovacs64.hibp.search --account foo@bar.com ``` ###### HTTP: ```http https://wkovacs64.lib.id/hibp/search/?account=foo ``` Limit breach data to a specific domain: ```http https://wkovacs64.lib.id/hibp/search/?account=foo&domain=adobe.com ``` ###### Web and Node.js: ```js const lib = require('lib'); const { search } = lib.wKovacs64.hibp; search({ account: 'foo' }) .then((data) => { // handle data }) .catch((err) => { // handle error }); ``` ## ✍ Author's Note There's a good chance this project adds no value. I primarily did it as an introduction to microservices on [StdLib][stdlib]. The current access methods probably have superior, preexisting alternatives: * Command-line: [pwned][pwned] is more flexible. * HTTP: Just query the [API][api] endpoints directly? * Web and Node.js: [hibp][hibp] powers this microservice. Use that. [hibp]: https://github.com/wKovacs64/hibp [pwned]: https://github.com/wKovacs64/pwned [stdlib]: https://stdlib.com [haveibeenpwned]: https://haveibeenpwned.com [api]: https://haveibeenpwned.com/API/v2 [apibreachmodel]: https://haveibeenpwned.com/api/v2#BreachModel [apidataclasses]: https://haveibeenpwned.com/API/v2#AllDataClasses [apipastemodel]: https://haveibeenpwned.com/API/v2#PasteModel [apipwnedpassword]: https://haveibeenpwned.com/api/v2#PwnedPasswords
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters
(no parameters expected)
  code
Fetches breach data for a single breach.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
breachName
(required)
the name of a breach in the system
  code
Fetches breach data for the specified account.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
account
(required)
a username or email address
{string}
domain
= ""
a domain by which to filter the results (default: all domains)
{boolean}
truncate
= false
truncate the results to only include the name of each breach (default: false)
  code
Fetches all breached sites in the system.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
domain
= ""
a domain by which to filter the results (default: all domains)
  code
Fetches all data classes in the system.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters
(no parameters expected)
  code
Fetches all pastes for an account (email address).
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
email
(required)
the email address to query
  code
Fetches the pwned status for the given password, indicating whether or not it has been previously exposed in a breach.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
password
(required)
a password (plain text string or SHA1 hash)
{boolean}
sha1
= false
the pre-hashed password is a hash (default: false)
  code
Fetches all breaches and all pastes associated with the provided account.
  info
context
disabled
bg
info
pricing
free
rate limits
  parameters (click to modify)
{string}
account
(required)
a username or email address
{string}
domain
= ""
a domain by which to filter breach results (default: all domains)
{boolean}
truncate
= false
truncate the results to only include the name of each breach (default: false)
  code