WatchGuard FireBox

LAST UPDATED: APRIL 22, 2025

Overview

WatchGuard Firebox is a unified security platform designed to provide enterprise-grade protection with enhanced network visibility. It delivers cloud and virtual firewall capabilities, AI-driven malware protection, and defense against intrusions, phishing, and ransomware.

D3 SOAR is providing REST operations to function with WatchGuard FireBox.

WatchGuard FireBox is available for use in:

D3 SOAR	V15.2.0+
Category	Network Security
Deployment Options	Option I, Option II, Option III, Option IV

Known Limitations

WatchGuard public APIs have quotas that limit the number of requests for each API key:

Maximum API requests per second - 500
Quota of API requests per day - 200,000

See API Limits for the latest information.

Connection

To connect to WatchGuard FireBox from D3 SOAR, please gather the following information:

Parameter	Description	Example
Server URL	The base URL of the WatchGuard platform API. Server base URL can be obtained from the WatchGuard GUI by navigating to Administration > Account > Managed Access.	https://api.usa.cloud.watchguard.com
Access ID (Read-Write)	The read-write access ID for authenticating API requests. Access ID (Read-Write) can be obtained from the WatchGuard GUI under Administration > Account > Managed Access.	fc73****rw_id
Password	The password used for authentication. Passwords can be generated from the WatchGuard GUI under Administration > Account > Managed Access.	****
API Key	The API key used for authentication. API key can be obtained from the WatchGuard GUI under Administration > Account > Managed Access.	qOTN****pHXG
Account ID	The WatchGuard Cloud account ID. Account ID can be obtained from the WatchGuard GUI by navigating to Account Manager > Administration > Account > My Account > Details.	ACC-*****
Managed Account	The managed account for which to submit API requests on behalf of. This is optional and primarily used by service providers. Managed account ID can be obtained from the WatchGuard GUI under Account Manager > Administration > Account > My Account > Details.	wGC-*****
API Version	The version of the API to use.	v1

Permission Requirements

Each endpoint in the WatchGuard FireBox API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permission for Access ID
Block Sites	Read-Write
Create Deployment	Read-Write
Deny Web Sites	Read-Write
List Blocked Sites	Read-only
List Denied Web Sites	Read-only
Unblock Sites	Read-Write
Undeny Web Sites	Read-Write
Test Connection	Read-only

READER NOTE

In the WatchGuard FireBox UI, one may encounter two Access IDs. D3 recommends using the Read-Write ID, as it supports all D3 commands.

Configuring WatchGuard FireBox to Work with D3 SOAR

Login to WatchGuard.
Enable API access.

READER NOTE *

One needs the Owner or Administrator role in WatchGuard Cloud to enable API access.
See Get Started with WatchGuard APIs.

Navigate to Administration > Managed Access, then store the following information:
- Access ID (Read-write)
- API URL (domain level only)
- API Key
Navigate to Administration > My Account, then store the Account ID.

Creating a Management Account

One might create a Service Provider management account in WatchGuard to manage multiple subscriber accounts. Steps to create a Service Provider management account:

Click on the + button to add an account.
Complete the required fields with Service Provider as the Account Type.
Save the changes.
Click on the newly created account, navigate to Administration > My Account, then store the Account ID.

Configuring D3 SOAR to Work with WatchGuard FireBox

Log in to D3 SOAR.
Find the WatchGuard FireBox integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type WatchGuard FireBox in the search box to find the integration, then click it to select it.
4. Click New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to WatchGuard FireBox.
1. Connection Name: The desired name for the connection.
2. 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.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. 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.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users have the option to choose the specific tenant sites to share the connection with. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the domain level server URL. The default value is https://api.usa.cloud.watchguard.com
  2. Input the access ID (Read-Write).
  3. Input the WatchGuard login password.
  4. Input the API key.
  5. Input the account ID. This parameter is not required to establish the connection, but must be provided to execute commands.
  6. (Optional) Input the managed account ID.
  7. Input API version. The default value is v1.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
11. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active. To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
1. 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.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

WatchGuard FireBox includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the WatchGuard FireBox API, please refer to the WatchGuard FireBox API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring WatchGuard FireBox to Work with D3 SOAR for details.

Block Sites

Blocks the specified IP addresses or FQDN domains.

READER NOTE

The same site under the same device ID can only be blocked once.
The address values must match the selected address type.
Ensure input IPv4 network ranges do not overlap with existing entries. Check for overlaps using tools like CIDRClash.
It is recommended to provide a device ID to ensure the block action is applied to a specific target.

Input

Input Parameter	Required/Optional	Description	Example
Address Type	Required	The type of the site addresses to be blocked. Valid options include: Fully Qualified Domain Name (e.g., example.com) IPv4 Host (e.g., 192.0.2.1) IPv4 Range (e.g., 192.0.2.1–192.0.2.5) IPv4 Network (e.g., 192.0.2.0/24)	IPv4 Network
Addresses	Required	The addresses to be blocked. All values must belong to the same address type.	JSON `[ "192.168.201.0/24" ]`
Descriptions	Required	The description for the site blocking.	"Block 192.168.201.0/24"
Device ID	Optional	The ID of the device to which this block action applies. Device ID appears in the URL of the Device Summary page. For example, if the URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345.	415471

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 you 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.	Block Sites 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 WatchGuard FireBox 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: xxx is not valid under any of the given schemas.

Error Sample Data

Block Sites failed.

Status Code: 400.

Message: xxx is not valid under any of the given schemas.

Create Deployment

Deploys configuration changes saved in WatchGuard Cloud to specified devices.

READER NOTE

To retrieve devices:

Navigate to Configure > Devices.
Navigate to Device Settings.

Select the device to which the action should be applied.

Check the URL– the device ID will appear in the URL path.

Input

Input Parameter	Required/Optional	Description	Example
Devices	Required	The IDs of the devices to deploy to. Device ID appears in the URL of the Device Summary page. For example, in https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345.	JSON `["415471"]`
Start Date	Optional	The time (in UTC) to deploy to the specified devices. By default, deployment occurs immediately.	Nov 04, 2022 00:00
Description	Optional	The description of the device deployment. The maximum length is 128 characters.	Deploy blocksites 1018a

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 you 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 Deployment 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 WatchGuard FireBox 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: Past start date. Date must be 'now' or a future RFC3339 date.

Error Sample Data

Create Deployment failed.

Status Code: 400.

Message: Past start date. Date must be 'now' or a future RFC3339 date.

Deny Web Sites

Denies access to the specified websites. The rule may deny an exact URL or IP address, or a pattern contained within the URL or IP address.

Input

Input Parameter	Required/Optional	Description	Example
Type	Required	The type of the rule for the websites to be denied. The options are: Exact Pattern By default, the value is Exact.	Pattern
Websites	Required	The exact strings or patterns of the websites to be denied. All values must belong to the same rule type. For example, the exact string "https://178.12.45.64" or the pattern "phishing.example.com/". The leading "http://" must be omitted, and "/" must be included at the end. The wildcard symbol "*" is used to match any character and may appear more than once in a pattern.	JSON `[ "phishing.example.com/*" ]`
Alarm	Optional	Whether the Firebox sends an alarm for the WebBlocker exception. By default, the value is False.	True
Device ID	Optional	The ID of the device to which this website deny action applies. Device ID appears in the URL of the Device Summary page. For example, in the URL https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345.	415471

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 you 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.	Deny Web Sites 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid Support account to call this API.

Error Sample Data

Deny Web Sites failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

List Blocked Sites

Retrieves all blocked sites in the WatchGuard Cloud account.

Input

Input Parameter	Required/Optional	Description	Example
Address Type	Optional	The type of the blocked site addresses. By default, all blocked site types are returned.	ipv4

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 you 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 Blocked Sites 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid Support account to call this API.

Error Sample Data

List Blocked Sites failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

List Denied Web Sites

Retrieves all denied websites configured under the WebBlocker exception for the WatchGuard Cloud account.

Input

N/A

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 you 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 Denied Web Sites 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid Support account to call this API.

Error Sample Data

List Denied Web Sites failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Unblock Sites

Unblocks the specified IP addresses or fully qualified domain names.

Input

Input Parameter	Required/Optional	Description	Example
Address Type	Required	The type of the site addresses to be unblocked. The options include: Fully Qualified Domain Name (e.g., example.com) IPv4 Host (e.g., 192.0.2.1) IPv4 Range (e.g., 192.0.2.1–192.0.2.5) IPv4 Network (e.g., 192.0.2.0/24)	ipv4_network
Addresses	Required	The values of the addresses to be unblocked. All values must be of the same address type.	JSON `[ "192.168.201.0/24" ]`
Device ID	Optional	The ID of the device to which the unblock action applies. Device ID appears in the URL of the Device Summary page. For example, the "FB-12345" portion in the URL https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary is the device ID. By default, the unblock applies to all devices.	415471

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 you 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.	Unblock Sites 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid Support account to call this API.

Error Sample Data

Unblock Sites failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Undeny Web Sites

Removes denial for the specified websites. The action may target an exact URL or IP address, or a defined pattern in the URL or IP address.

Input

Input Parameter	Required/Optional	Description	Example
Type	Required	The type of the rule for the websites to be undenied. The options are: Exact Pattern By default, the value is Exact.	Pattern
Websites	Required	The exact strings or patterns of websites to be undenied. Only websites of the same rule type can be provided. Exact string example: https://178.12.45.64. Pattern example: The phishing.example.com/* pattern.	JSON `[ "phishing.example.com/*" ]`
Device ID	Optional	The ID of the device this undeny action applies to. Device ID appears in the URL of the Device Summary page. For example, in https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. By default, the unblock applies to all devices.	415471

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 you 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.	Undeny Web Sites 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid Support account to call this API.

Error Sample Data

Undeny Web Sites failed.

Status Code: 403.

Message: You must have a valid Support account to call this API.

Test Connection

Allows you to perform a health check on an integration connection. You 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:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error 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 responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help you 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 WatchGuard FireBox portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: You must have a valid support account to call this API.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: You must have a valid Support account to call this API