Fortinet Document Library

Version:


Table of Contents

Have I Been Pwned

2.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: 2.0.0

FortiSOAR™ Version Tested on: 5.1.0-464

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the Have I Been Pwned connector in version 2.0.0:

  • Added "API Key" as a configuration parameter.
  • Updated the connector to support version 3 of the Have I Been Pwned API.

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-have-i-been-pwned

Prerequisites to configuring the connector

  • You must have the Have I Been Pwned API Key.
  • 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, click the Have I Been Pwned connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL URL of the Have I Been Pwned server from where the Have I Been Pwned connector receives notifications, which will always be https://haveibeenpwned.com.
API Key API Key for Have I Been Pwned.
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_all_breached_sites
Investigation
Get Data Classes Retrieves the details of all the data classes present on the system from the Have I Been Pwned server. get_data_classes
Investigation
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. get_pastes
Investigation
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.
lookup_password
Investigation
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.
search_password
Investigation

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.

The output contains the following populated JSON schema:
[
 {
     "IsVerified": "",
     "ModifiedDate": "",
     "BreachDate": "",
     "LogoType": "",
     "PwnCount": "",
     "IsFabricated": "",
     "DataClasses": [],
     "IsActive": "",
     "Name": "",
     "IsSensitive": "",
     "Title": "",
     "IsSpamList": "",
     "AddedDate": "",
     "Domain": "",
     "Description": "",
     "IsRetired": ""
 }
]

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.

The output contains the following populated JSON schema:
[
 {
     "IsVerified": "",
     "ModifiedDate": "",
     "BreachDate": "",
     "LogoType": "",
     "PwnCount": "",
     "IsFabricated": "",
     "DataClasses": [],
     "IsActive": "",
     "Name": "",
     "IsSensitive": "",
     "Title": "",
     "IsSpamList": "",
     "AddedDate": "",
     "Domain": "",
     "Description": "",
     "IsRetired": ""
 }
]

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.

The output contains the following populated JSON schema:
[
 {
     "IsSensitive": "",
     "Description": "",
     "IsFabricated": "",
     "LogoType": "",
     "DataClasses": [],
     "PwnCount": "",
     "AddedDate": "",
     "IsRetired": "",
     "IsVerified": "",
     "Title": "",
     "IsActive": "",
     "BreachDate": "",
     "Domain": "",
     "ModifiedDate": "",
     "Name": "",
     "IsSpamList": ""
 }
]

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.

No output schema is available at this time.

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.

The output contains the following populated JSON schema:
[
 {
     "Title": "",
     "EmailCount": "",
     "Source": "",
     "Date": "",
     "Id": ""
 }
]

operation: Lookup for Pwned Password

Input parameters

Parameter Description
Password Password that you want to search for in the Pwned Password repository.
You can enter the password as a plain text string.

Output

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

The output contains the following populated JSON schema:
{
     "message": "",
     "count": ""
}

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.

The output contains the following populated JSON schema:
[
 {
     "key": "",
     "count": ""
 }
]

Included playbooks

The Sample - Have I Been Pwned - 2.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 the 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: 2.0.0

FortiSOAR™ Version Tested on: 5.1.0-464

Authored By: Fortinet.

Certified: Yes

Release Notes for version 2.0.0

Following enhancements have been made to the Have I Been Pwned connector in version 2.0.0:

Installing the connector

From FortiSOAR™ 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:

yum install cyops-connector-have-i-been-pwned

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, click the Have I Been Pwned connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details: 

Parameter Description
Server URL URL of the Have I Been Pwned server from where the Have I Been Pwned connector receives notifications, which will always be https://haveibeenpwned.com.
API Key API Key for Have I Been Pwned.
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_all_breached_sites
Investigation
Get Data Classes Retrieves the details of all the data classes present on the system from the Have I Been Pwned server. get_data_classes
Investigation
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. get_pastes
Investigation
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.
lookup_password
Investigation
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.
search_password
Investigation

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.

The output contains the following populated JSON schema:
[
 {
     "IsVerified": "",
     "ModifiedDate": "",
     "BreachDate": "",
     "LogoType": "",
     "PwnCount": "",
     "IsFabricated": "",
     "DataClasses": [],
     "IsActive": "",
     "Name": "",
     "IsSensitive": "",
     "Title": "",
     "IsSpamList": "",
     "AddedDate": "",
     "Domain": "",
     "Description": "",
     "IsRetired": ""
 }
]

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.

The output contains the following populated JSON schema:
[
 {
     "IsVerified": "",
     "ModifiedDate": "",
     "BreachDate": "",
     "LogoType": "",
     "PwnCount": "",
     "IsFabricated": "",
     "DataClasses": [],
     "IsActive": "",
     "Name": "",
     "IsSensitive": "",
     "Title": "",
     "IsSpamList": "",
     "AddedDate": "",
     "Domain": "",
     "Description": "",
     "IsRetired": ""
 }
]

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.

The output contains the following populated JSON schema:
[
 {
     "IsSensitive": "",
     "Description": "",
     "IsFabricated": "",
     "LogoType": "",
     "DataClasses": [],
     "PwnCount": "",
     "AddedDate": "",
     "IsRetired": "",
     "IsVerified": "",
     "Title": "",
     "IsActive": "",
     "BreachDate": "",
     "Domain": "",
     "ModifiedDate": "",
     "Name": "",
     "IsSpamList": ""
 }
]

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.

No output schema is available at this time.

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.

The output contains the following populated JSON schema:
[
 {
     "Title": "",
     "EmailCount": "",
     "Source": "",
     "Date": "",
     "Id": ""
 }
]

operation: Lookup for Pwned Password

Input parameters

Parameter Description
Password Password that you want to search for in the Pwned Password repository.
You can enter the password as a plain text string.

Output

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

The output contains the following populated JSON schema:
{
     "message": "",
     "count": ""
}

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.

The output contains the following populated JSON schema:
[
 {
     "key": "",
     "count": ""
 }
]

Included playbooks

The Sample - Have I Been Pwned - 2.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 the connector upgrade and delete.