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.
Connector Version: 2.1.0
Authored By: Fortinet.
Certified: Yes
Following enhancements have been made to the Have I Been Pwned connector in version 2.1.0:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command as a root user to install the connector:
yum install cyops-connector-have-i-been-pwned
For the procedure to configure a connector, click here
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. By default, this option is set to True. |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations:
| 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 List | 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 |
| Get Breaches List | Retrieves all breaches found for an account based on the email address that you have specified. The input is not case-sensitive and is trimmed of leading or trailing white spaces. | get_all_breaches_for_an_account Investigation |
| Get Breached Email Address List | Retrieves all breached email addresses found for a domain based on the domain name that you have specified.
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched. |
get_all_breached_email_addresses_for_a_domain Investigation |
| Get Subscribed Domains List | Retrieves all domains that have been successfully added to the domain search dashboard after verifying control are returned. | get_all_subscribed_domains Investigation |
| Get Most Recent Breach | Retrieves the most recently added breach based on the value of the AddedDate field.
NOTE: This may not be the most recent breach to occur as there may be significant lead time between a service being breached and the data later appearing on HIBP. |
get_the_most_recently_added_breach Investigation |
| Get Breached Site by Name | Retrieves a single breach based on the breach name that you have specified. | get_a_single_breached_site_by_name Investigation |
| Execute an API Request | Sends an API request to any API endpoint based on specified HTTP method, endpoint, and other input parameters that you have specified, enabling flexible API interactions tailored to user needs. | execute_api_request Investigation |
| Parameter | Description |
|---|---|
| Domain | Name of the domain whose associated breached sites you want to search for on the Have I Been Pwned server. |
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:
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
| 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. |
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:
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
| 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. |
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:
{
"count": "",
"message": ""
}
| 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. |
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.
[
{
"count": "",
"key": ""
}
]
None.
The JSON output contains the details of all the breached sites present on the system retrieved from the Have I Been Pwned server.
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
None.
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.
| 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. |
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:
[
{
"Date": "",
"Title": "",
"EmailCount": "",
"Source": "",
"Id": ""
}
]
| Parameter | Description |
|---|---|
| Account Email | Specify your account name or email address to retrieve all breaches associated with the specified account. |
The output contains the following populated JSON schema:
[
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
]
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched.
| Parameter | Description |
|---|---|
| Domain Name | Specify the domain name to fetch all breached email addresses associated with the specified domain. |
The output contains a non-dictionary value.
None.
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched.
The output contains a non-dictionary value.
None.
NOTE: This may not be the most recent breach to occur as there may be significant lead time between a service being breached and the data later appearing on HIBP.
The output contains the following populated JSON schema:
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
| Parameter | Description |
|---|---|
| Breach Name | (Optional) Specify the breach name to fetch breached site information. |
The output contains the following populated JSON schema:
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
| Parameter | Description |
|---|---|
| HTTP Method | Select an HTTP action for the request. You can select from the following options:
|
| Endpoint | Specify the target API URL path for the request. For example, if the website is https://example.com and URL path is https://example.com/api/v3, the endpoint would be /api/v3. |
| Query Parameters | (Optional) Specify any optional parameters to add to the URL and refine the request. |
| Request Payload | (Optional) Specify data, as JSON, to be sent as the request payload (typically for POST or PUT requests). |
The output contains a non-dictionary value.
The Sample - Have I Been Pwned - 2.1.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.
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.
Connector Version: 2.1.0
Authored By: Fortinet.
Certified: Yes
Following enhancements have been made to the Have I Been Pwned connector in version 2.1.0:
Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command as a root user to install the connector:
yum install cyops-connector-have-i-been-pwned
For the procedure to configure a connector, click here
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. By default, this option is set to True. |
The following automated operations can be included in playbooks, and you can also use the annotations to access operations:
| 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 List | 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 |
| Get Breaches List | Retrieves all breaches found for an account based on the email address that you have specified. The input is not case-sensitive and is trimmed of leading or trailing white spaces. | get_all_breaches_for_an_account Investigation |
| Get Breached Email Address List | Retrieves all breached email addresses found for a domain based on the domain name that you have specified.
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched. |
get_all_breached_email_addresses_for_a_domain Investigation |
| Get Subscribed Domains List | Retrieves all domains that have been successfully added to the domain search dashboard after verifying control are returned. | get_all_subscribed_domains Investigation |
| Get Most Recent Breach | Retrieves the most recently added breach based on the value of the AddedDate field.
NOTE: This may not be the most recent breach to occur as there may be significant lead time between a service being breached and the data later appearing on HIBP. |
get_the_most_recently_added_breach Investigation |
| Get Breached Site by Name | Retrieves a single breach based on the breach name that you have specified. | get_a_single_breached_site_by_name Investigation |
| Execute an API Request | Sends an API request to any API endpoint based on specified HTTP method, endpoint, and other input parameters that you have specified, enabling flexible API interactions tailored to user needs. | execute_api_request Investigation |
| Parameter | Description |
|---|---|
| Domain | Name of the domain whose associated breached sites you want to search for on the Have I Been Pwned server. |
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:
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
| 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. |
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:
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
| 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. |
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:
{
"count": "",
"message": ""
}
| 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. |
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.
[
{
"count": "",
"key": ""
}
]
None.
The JSON output contains the details of all the breached sites present on the system retrieved from the Have I Been Pwned server.
[
{
"IsSensitive": "",
"Description": "",
"IsFabricated": "",
"LogoType": "",
"DataClasses": [],
"PwnCount": "",
"AddedDate": "",
"IsRetired": "",
"IsVerified": "",
"Title": "",
"IsActive": "",
"BreachDate": "",
"Domain": "",
"ModifiedDate": "",
"Name": "",
"IsSpamList": ""
}
]
None.
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.
| 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. |
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:
[
{
"Date": "",
"Title": "",
"EmailCount": "",
"Source": "",
"Id": ""
}
]
| Parameter | Description |
|---|---|
| Account Email | Specify your account name or email address to retrieve all breaches associated with the specified account. |
The output contains the following populated JSON schema:
[
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
]
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched.
| Parameter | Description |
|---|---|
| Domain Name | Specify the domain name to fetch all breached email addresses associated with the specified domain. |
The output contains a non-dictionary value.
None.
NOTE: Only domains that have been successfully added to the domain search dashboard after verifying control can be searched.
The output contains a non-dictionary value.
None.
NOTE: This may not be the most recent breach to occur as there may be significant lead time between a service being breached and the data later appearing on HIBP.
The output contains the following populated JSON schema:
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
| Parameter | Description |
|---|---|
| Breach Name | (Optional) Specify the breach name to fetch breached site information. |
The output contains the following populated JSON schema:
{
"Name": "",
"Title": "",
"Domain": "",
"LogoPath": "",
"PwnCount": "",
"AddedDate": "",
"IsMalware": "",
"IsRetired": "",
"BreachDate": "",
"IsSpamList": "",
"IsVerified": "",
"DataClasses": [],
"Description": "",
"IsSensitive": "",
"IsFabricated": "",
"ModifiedDate": "",
"IsSubscriptionFree": ""
}
| Parameter | Description |
|---|---|
| HTTP Method | Select an HTTP action for the request. You can select from the following options:
|
| Endpoint | Specify the target API URL path for the request. For example, if the website is https://example.com and URL path is https://example.com/api/v3, the endpoint would be /api/v3. |
| Query Parameters | (Optional) Specify any optional parameters to add to the URL and refine the request. |
| Request Payload | (Optional) Specify data, as JSON, to be sent as the request payload (typically for POST or PUT requests). |
The output contains a non-dictionary value.
The Sample - Have I Been Pwned - 2.1.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.