Fortinet Document Library

Version:


Table of Contents

Have I Been Pwned

1.0.0
Copy Link

About the connector

The primary function of Have I Been Pwned is to provide the general public a means to check if their private information has been leaked or compromised. Visitors to the website can enter an email address, and see a list of all known data breaches with records tied to that email address. The website also provides details about each data breach, such as the backstory of the breach and what specific types of data were included in the data breach.

This document provides information about the Have I Been Pwned connector, which facilitates automated interactions, with a Have I Been Pwned server using FortiSOAR™ playbooks. Add the Have I Been Pwned connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching for breached sites associated with domains and emails ids that you have specified and retrieving a list of breached sites present on the system.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

  • You must have the URL of the Have I Been Pwned server from where the Have I Been Pwned connector receives notifications.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Have I Been Pwned connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL Server URL will always be https://haveibeenpwned.com
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Lookup Domain Searches for breached sites associated with the domain name that you have specified on the Have I Been Pwned server. get_domain_reputation
Investigation
Lookup Email Searches for breached sites associated with the email address that you have specified on the Have I Been Pwned server. get_email_reputation
Investigation
Get Breached Sites Retrieves the details of all the breached sites present on the system from the Have I Been Pwned server.  
Get Data Classes Retrieves the details of all the data classes present on the system from the Have I Been Pwned server.  
Get Pastes Searches through pastes that are exposed in potential data breaches on the Have I Been Pwned server that contain the email address that you have specified.  
Lookup for Pwned Password Searches for the password that you have specified on the Have I Been Pwned server and checks whether the password is found in the Pwned Password repository.
This operation returns how many times the password that you have specified is found in the Pwned Password repository.
 
Search for Passwords Searches for the partial password (hash) that you have specified, by the first five characters of the hash, on the Have I Been Pwned server and checks whether the password is found in the Pwned Password repository.
This operation returns the suffix of the hash values starting with the hash value you have specified and the count of times the partial password that you have specified is found in the Pwned Password repository.
 

 

operation: Lookup Domain

Input parameters

 

Parameter Description
Domain Name of the domain whose associated breached sites you want to search for on the Have I Been Pwned server.

 

Output

The JSON output contains a list and details of all breached sites, associated with the domain you have specified, present on the system from the Have I Been Pwned server, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Lookup Domain operation

 

operation: Lookup Email

Input parameters

 

Parameter Description
Email ID Email address whose associated breached sites you want to search for on the Have I Been Pwned server.
Domain (Optional) Filter results to retrieve breaches only against the specified domain name.
Truncate Response Select this option to return only the name of the breaches from the Have I Been Pwned server.
By default, this option is set to False (unchecked) so that the name and details of the breaches are retrieved from the Have I Been Pwned server.
Include Unverified Select this option to return breaches that are flagged as Unverified, from the Have I Been Pwned server.
By default, this option is set to False (unchecked) so only those that breaches are not flagged as Unverified are retrieved from the Have I Been Pwned server.

 

Output

The JSON output contains the details of the breached sites associated with the Email address you have specified, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Lookup URL operation

 

operation: Get Breached Sites

Input parameters

None.

Output

The JSON output contains the details of all the breached sites present on the system retrieved from the Have I Been Pwned server.

Following image displays a sample output:

 

Sample output of the Get Breached Sites operation

 

operation: Get Data Classes

Input parameters

None.

Output

The JSON output contains the details of all the data classes present on the system retrieved from the Have I Been Pwned server.

Following image displays a sample output:

 

Sample output of the Get Data Classes operation

 

operation: Get Pastes

Input parameters

 

Parameter Description
Email ID Email address that you want to search for in pastes that are exposed in potential data breaches on the Have I Been Pwned server.

 

Output

The JSON output contains the details of the pastes associated with the Email address you have specified, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Get Pastes operation

 

operation: Lookup for Pwned Password

Input parameters

 

Parameter Description
Password / Hash Password or Hash value that you want to search for in the Pwned Password repository.
You can enter the password in either plain text string or an SHA-1 Hash value of the password.
Original Password is a Hash Select this option if you want to search for a password which was originally an SHA-1 Hash value.
By default, this option is set to False.

 

Output

The JSON output contains the count of times the password that you have specified is found in the Pwned Password repository.

Following image displays a sample output:

 

Sample output of the Lookup for Pwned Password operation

 

operation: Search for Passwords

Input parameters

 

Parameter Description
Hash (First 5 chars) First five characters of the password Hash (SHA-1) value that you want to search for in the Pwned Password repository.

 

Output

The JSON output contains the suffix of the hash values starting with the hash value you have specified and the count of times the partial password that you have specified is found in the Pwned Password repository.

Following image displays a sample output:

 

Sample output of the Search for Passwords operation

 

Included playbooks

The Sample - Have-I-Been-Pwned - 1.0.0 playbook collection comes bundled with the Have I Been Pwned connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Have I Been Pwned connector.

  • Get Breached Sites
  • Get Data Classes
  • Get Pastes
  • Lookup Domain
  • Lookup Email
  • Lookup for Pwned Password
  • Search for Passwords

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

 

About the connector

The primary function of Have I Been Pwned is to provide the general public a means to check if their private information has been leaked or compromised. Visitors to the website can enter an email address, and see a list of all known data breaches with records tied to that email address. The website also provides details about each data breach, such as the backstory of the breach and what specific types of data were included in the data breach.

This document provides information about the Have I Been Pwned connector, which facilitates automated interactions, with a Have I Been Pwned server using FortiSOAR™ playbooks. Add the Have I Been Pwned connector as a step in FortiSOAR™ playbooks and perform automated operations, such as searching for breached sites associated with domains and emails ids that you have specified and retrieving a list of breached sites present on the system.

 

Version information

Connector Version: 1.0.0

Compatibility with FortiSOAR™ Versions: 4.10.3-161 and later

 

Installing the connector

For the procedure to install a connector, click here.

 

Prerequisites to configuring the connector

 

Configuring the connector

For the procedure to configure a connector, click here.

 

Configuration parameters

In FortiSOAR™, on the Connectors page, select the Have I Been Pwned connector and click Configure to configure the following parameters:

 

Parameter Description
Server URL Server URL will always be https://haveibeenpwned.com
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

 

 

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

 

Function Description Annotation and Category
Lookup Domain Searches for breached sites associated with the domain name that you have specified on the Have I Been Pwned server. get_domain_reputation
Investigation
Lookup Email Searches for breached sites associated with the email address that you have specified on the Have I Been Pwned server. get_email_reputation
Investigation
Get Breached Sites Retrieves the details of all the breached sites present on the system from the Have I Been Pwned server.  
Get Data Classes Retrieves the details of all the data classes present on the system from the Have I Been Pwned server.  
Get Pastes Searches through pastes that are exposed in potential data breaches on the Have I Been Pwned server that contain the email address that you have specified.  
Lookup for Pwned Password Searches for the password that you have specified on the Have I Been Pwned server and checks whether the password is found in the Pwned Password repository.
This operation returns how many times the password that you have specified is found in the Pwned Password repository.
 
Search for Passwords Searches for the partial password (hash) that you have specified, by the first five characters of the hash, on the Have I Been Pwned server and checks whether the password is found in the Pwned Password repository.
This operation returns the suffix of the hash values starting with the hash value you have specified and the count of times the partial password that you have specified is found in the Pwned Password repository.
 

 

operation: Lookup Domain

Input parameters

 

Parameter Description
Domain Name of the domain whose associated breached sites you want to search for on the Have I Been Pwned server.

 

Output

The JSON output contains a list and details of all breached sites, associated with the domain you have specified, present on the system from the Have I Been Pwned server, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Lookup Domain operation

 

operation: Lookup Email

Input parameters

 

Parameter Description
Email ID Email address whose associated breached sites you want to search for on the Have I Been Pwned server.
Domain (Optional) Filter results to retrieve breaches only against the specified domain name.
Truncate Response Select this option to return only the name of the breaches from the Have I Been Pwned server.
By default, this option is set to False (unchecked) so that the name and details of the breaches are retrieved from the Have I Been Pwned server.
Include Unverified Select this option to return breaches that are flagged as Unverified, from the Have I Been Pwned server.
By default, this option is set to False (unchecked) so only those that breaches are not flagged as Unverified are retrieved from the Have I Been Pwned server.

 

Output

The JSON output contains the details of the breached sites associated with the Email address you have specified, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Lookup URL operation

 

operation: Get Breached Sites

Input parameters

None.

Output

The JSON output contains the details of all the breached sites present on the system retrieved from the Have I Been Pwned server.

Following image displays a sample output:

 

Sample output of the Get Breached Sites operation

 

operation: Get Data Classes

Input parameters

None.

Output

The JSON output contains the details of all the data classes present on the system retrieved from the Have I Been Pwned server.

Following image displays a sample output:

 

Sample output of the Get Data Classes operation

 

operation: Get Pastes

Input parameters

 

Parameter Description
Email ID Email address that you want to search for in pastes that are exposed in potential data breaches on the Have I Been Pwned server.

 

Output

The JSON output contains the details of the pastes associated with the Email address you have specified, retrieved from Have I Been Pwned.

Following image displays a sample output:

 

Sample output of the Get Pastes operation

 

operation: Lookup for Pwned Password

Input parameters

 

Parameter Description
Password / Hash Password or Hash value that you want to search for in the Pwned Password repository.
You can enter the password in either plain text string or an SHA-1 Hash value of the password.
Original Password is a Hash Select this option if you want to search for a password which was originally an SHA-1 Hash value.
By default, this option is set to False.

 

Output

The JSON output contains the count of times the password that you have specified is found in the Pwned Password repository.

Following image displays a sample output:

 

Sample output of the Lookup for Pwned Password operation

 

operation: Search for Passwords

Input parameters

 

Parameter Description
Hash (First 5 chars) First five characters of the password Hash (SHA-1) value that you want to search for in the Pwned Password repository.

 

Output

The JSON output contains the suffix of the hash values starting with the hash value you have specified and the count of times the partial password that you have specified is found in the Pwned Password repository.

Following image displays a sample output:

 

Sample output of the Search for Passwords operation

 

Included playbooks

The Sample - Have-I-Been-Pwned - 1.0.0 playbook collection comes bundled with the Have I Been Pwned connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Have I Been Pwned connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.