Imperva Cloud WAF (Incapsula WAF)
LAST UPDATED: APR 11, 2025
Overview
Imperva Cloud WAF provides a web application security firewall that safeguards against security threats, and an API enabling the management of accounts and sites.
D3 Security's integration with the Imperva Cloud WAF SaaS REST API V2 supports account management and bidirectional operations for WAF policies associated with each account.
Imperva Cloud WAF (Incapsula WAF) is available for use in:
Connection
To connect to Imperva Cloud WAF (Incapsula WAF) from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
API ID | The API ID used to authenticate the connection. | ******** |
API Key | The API Key used to authenticate the connection. | ******** |
API Version | The API version. The default value is v2. | v2 |
Permission Requirements
Each endpoint in the Imperva Cloud WAF (Incapsula WAF) API requires a certain permission scope. As Imperva Cloud WAF (Incapsula WAF) is using role-based access control (RBAC), the API ID and API Key are generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role.
Users need to configure their user profile with the Administrator role from the Imperva Cloud WAF (Incapsula WAF) console for all commands in this integration. Please refer to the Configuring Imperva Cloud WAF (Incapsula WAF) to Work with D3 SOAR for the role configuration.
Configuring Imperva Cloud WAF (Incapsula WAF) to Work with D3 SOAR
READER NOTE
Name change from Incapsula to Imperva Cloud WAF
The product name Incapsula has been retired. The new names reflect the package of services and updated product names by Imperva. This table maps the old names with new names:
Please review Understanding Updated Product Naming for more information.
Log into Imperva Cloud WAF (Incapsula WAF).
Click Account on the top menu bar, choose Account Management, then select Users under the left sidebar.
Create a new user with the Administrator role, then click on the Save button.
Find the account user created, then click Add API key on the right sidebar.
Input a name for the API key, set Status as Enabled, then click on the Save button.
Copy and store the API ID and API Key. Refer to step h sub-steps 1 and 2 in Configuring D3 SOAR to Work with Imperva Cloud WAF (Incapsula WAF).
The API ID and API key will not be retrievable beyond this point.
Configuring D3 SOAR to Work with Imperva Cloud WAF (Incapsula WAF)
Log in to D3 SOAR.
Find the Imperva Cloud WAF (Incapsula WAF) integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Imperva Cloud WAF (Incapsula WAF) in the search box to find the integration, then click it to select it.
Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Imperva Cloud WAF (Incapsula WAF).
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add a description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
1. Input the API ID from the Imperva Cloud WAF (Incapsula WAF) platform.
2. Copy the API Key from the Imperva Cloud WAF (Incapsula WAF) platform.
3. Input the Version. The default value is v2.Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
Click OK to close the alert window.
Click + Add to create and add the configured connection.
Commands
Imperva Cloud WAF (Incapsula WAF) includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command function, users can execute these commands independently for playbook troubleshooting.
Integration API Note
For more information about the Imperva Cloud WAF (Incapsula WAF) API, please refer to the Imperva Cloud WAF (Incapsula WAF) API reference.
Create Access Control Policy
Creates an access control policy for blocking IP addresses or URLs.
READER NOTE
Account ID is an optional parameter to run this command.
Run the List Policies command to obtain the Account ID. Account IDs can be found in the raw data at the path $.value[*].accountId.
Input
Input Parameter | Required/Optional | Description | Example |
Policy Name | Required | The name of the new policy. The maximum length is 100 characters. Excess characters will be cut off. | policy 10 to block IPs |
IP Addresses | Optional | The list of IP addresses to block. |
JSON
|
URLs | Optional | The list of URLs to block. The syntax of the parameter is Pattern1=URL1, Pattern2=URL2. Available patterns are: EQUALS, NOT_EQUALS, NOT_CONTAINS, PREFIX, SUFFIX, NOT_PREFIX, NOT_SUFFIX, CONTAINS. An invalid pattern is replaced with CONTAINS. For example: ["CONTAINS=https://*****.*****", "SUFFIX=index.php"]. |
JSON
|
Account ID | Optional | The ID of the account to be used when creating the policy. By default, the value is the ID of the current API user. Account ID can be obtained using the List Policies command. | ***** |
Description | Optional | The description for the new policy. The maximum length is 1500 characters. Excess characters will be cut off. | Block IP 10 rule policy. |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Create Access Control Policy failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid api_key or api_id. |
Error Sample Data Create Access Control Policy failed. Status Code: 400. Message: Invalid api_key or api_id. |
Delete Policies
Deletes the specified policies.
READER NOTE
Policy IDs is a required parameter to run this command.
Run the List Policies command to obtain the Policy IDs. Policy IDs can be found in the raw data at the path $.value[*].id.
Input
Input Parameter | Required/Optional | Description | Example |
Policy IDs | Required | The IDs of the policies to be deleted. Policy IDs can be obtained using the List Policies command. |
JSON
|
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Delete Policies failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: The value for parameter (Policy IDs) is invalid. |
Error Sample Data Delete Policies failed. Status Code: 400. Message: The value for parameter (Policy IDs) is invalid. |
List Policies
Retrieves a list of policies for the account.
Input
Input Parameter | Required/Optional | Description | Example |
Show Extend Detail | Optional | Whether to include detailed policy configuration information for each policy. By default, the value is False, returning only basic policy information. | True |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | List Policies failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 401. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid api_key or api_id. |
Error Sample Data List Policies failed. Status Code: 401. Message: Invalid api_key or api_id. |
Overwrite Access Control Policy
Overwrites the specified access control policy with new configurations.
READER NOTE
Policy ID is a required parameter to run this command.
Run the List Policies command to obtain the Policy ID. Policy IDs can be found in the raw data at the path $.value[*].id.
Account ID is an optional parameter to run this command.
Run the List Policies command to obtain the Account ID. Account IDs can be found in the raw data at the path $.value[*].accountId.
Input
Input Parameter | Required/Optional | Description | Example |
Policy ID | Required | The ID of the policy whose configurations will be overwritten. Policy ID can be obtained using the List Policies command. | ***** |
Policy Name | Required | The new name of the policy. The maximum length is 100 characters. Excess characters will be cut off. | policy 12 to block IPs update |
IP Addresses | Optional | The new list of IP addresses to block. This replaces the existing list. If left unspecified, the Block IP Settings for the policy will be removed. |
JSON
|
URLs | Optional | The new list of URLs to block. This replaces the existing list. The syntax of the parameter is Pattern1=URL1, Pattern2=URL2. Available patterns are: EQUALS, NOT_EQUALS, NOT_CONTAINS, PREFIX, SUFFIX, NOT_PREFIX, NOT_SUFFIX, CONTAINS. An invalid pattern is replaced with CONTAINS. For example: ["CONTAINS=https://*****.*****", "SUFFIX=index.php"]. If left unspecified, the Block IP Settings for the policy will be removed. |
JSON
|
Account ID | Optional | The ID of the account to be used when overwriting the policy. By default, the value is the ID of the current API user’s account. Account ID can be obtained using the List Policies command. | ***** |
Description | Optional | The description for the new policy. The max length of the description is 1500 characters. The exceeded characters will be cut off. | modified the policy name. |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Overwrite Access Control Policy failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid api_key or api_id. |
Error Sample Data Overwrite Access Control Policy failed. Status Code: 400. Message: Invalid api_key or api_id. |
Update Access Control Policy
Updates an existing access control policy by adding or modifying specified settings.
READER NOTE
Policy ID is a required parameter to run this command.
Run the List Policies command to obtain the Policy ID. Policy IDs can be found in the raw data at the path $.value[*].id.
Account ID is an optional parameter to run this command.
Run the List Policies command to obtain the Account ID. Account IDs can be found in the raw data at the path $.value[*].accountId.
Input
Input Parameter | Required/Optional | Description | Example |
Policy ID | Required | The ID of the policy to be updated. Policy ID can be obtained using the List Policies command. | ***** |
Policy Name | Optional | The new name for the policy. The maximum length is 100 characters. Excess characters will be cut off. | policy 4 block IP |
IP Addresses | Optional | The new IP addresses to block. These addresses will be appended to the existing block list. |
JSON
|
URLs | Optional | The new URLs to block. These URLs will be appended to the existing block list. This replaces the existing list. The syntax of the parameter is Pattern1=URL1, Pattern2=URL2. Available patterns are: EQUALS, NOT_EQUALS, NOT_CONTAINS, PREFIX, SUFFIX, NOT_PREFIX, NOT_SUFFIX, CONTAINS. An invalid pattern is replaced with CONTAINS. For example: ["CONTAINS=https://*****.*****", "SUFFIX=index.php"]. |
JSON
|
Account ID | Optional | The ID of the account to be used when updating the policy. By default, the value is the ID of the current API user’s account. Account ID can be obtained using the List Policies command. | ***** |
Description | Optional | The description of the updated policy. The maximum length is 1500 characters. Excess characters will be cut off. | modified the policy name. |
Output
To view the sample output data for all commands, refer to this article.
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Update Access Control Policy failed. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid api_key or api_id. |
Error Sample Data Update Access Control Policy failed. Status Code: 400. Message: Invalid api_key or api_id. |
Test Connection
Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Output Type | Description | Return Data Type |
Return Data | Indicates one of the possible command execution states: Successful or Failed. The Failed state can be triggered by any of the following errors:
More details about an error can be viewed in the Error tab. | String |
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.
Parts in Error | Description | Example |
Failure Indicator | Indicates the command failure that happened at a specific input and/or API call. | Test Connection failed. Failed to check the connector. |
Status Code | The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Imperva Cloud WAF (Incapsula WAF) portal. Refer to the HTTP Status Code Registry for details. | Status Code: 400. |
Message | The raw data or captured key error message from the integration API server about the API request failure. | Message: Invalid api_key or api_id. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 400. Message: Invalid api_key or api_id. |