PfSense
LAST UPDATED: NOV 1, 2024
Overview
PfSense is a free and open source firewall and router that also features unified threat management, load balancing, and multi WAN. It is based on the FreeBSD operating system with a custom kernel and includes third-party free software packages for additional functionality.
D3 SOAR is providing REST operations to function with PfSense.
For example, you can use PfSense as a proxy and a firewall to monitor all the traffic to your network.
PfSense is available for use in:
D3 SOAR | V15.0.17.0+ |
Category | Network Security |
Deployment Options |
Known Limitations
PfSense's XML configuration was not designed for quick simultaneous writes like a traditional database. Delaying API calls in sequence may be necessary to prevent unexpected behavior, including configuration overwrites.
By design, PfSense's XML configuration values can only be parsed as strings, arrays or objects. This means that even though request data requires data to be of a particular type, it will not necessarily be stored as that type. Data read from the API may be represented differently than in the requested format.
Please refer to https://{{pfsense_instance_serverurl}}/api/documentation/ for detailed information.
Connection
To connect to PfSense from D3 SOAR, please follow this part to collect the required information below:
Parameter | Description | Example |
Server URL | The PfSense instance URL, which is identical to the PfSense web console base URL. | https://***.***.***.*** |
Authentication Type | The authentication method (local database or API token) for the API connection. Note:
| Local Database |
API Version | The version of the API to use for the API connection. | v1 |
Local Database (Basic Authentication) | ||
User Name | The PfSense user name for basic authentication. | d3user |
Password | The PfSense password for basic authentication. | YOUR PASSWORD |
API Token | ||
Client ID | The client ID from the PfSense WebGUI for the API authentication. | ***** |
API Token | The API token generated from the PfSense GUI for the API connection authentication. | ***** |
Permission Requirements
Each endpoint in the PfSense API requires a certain permission scope. The following are required scopes for the commands in this integration:
Command | Required Permission (at least one) |
Block IPs | WebCfg - All pages; WebCfg - Firewall: Rules: Edit |
Get Firewall Log | WebCfg - All pages; WebCfg - Status: Logs: Firewall |
Get Interface Status | WebCfg - All pages; WebCfg - Status: Interfaces |
List Firewall Rules | WebCfg - All pages; WebCfg - Firewall: Rules |
Test Connection | WebCfg - All pages; WebCfg - Firewall: Rules |
The PfSense API uses the same privileges as the PfSense webConfigurator. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the PfSense console for each command in this integration. See User Management and Authentication from PfSense’s documentation for more about managing user privileges.
Configuring PfSense to Work with D3 SOAR
Log in to your PfSense console with an admin user account.
Install the PfSense API package. You may skip this step if it has already been completed.
Navigate to Diagnostics > Command Prompt.
Copy and paste the shell command into the Execute Shell Command field.
CODEpkg add https://github.com/jaredhendrickson13/pfsense-api/releases/latest/download/pfSense-2.6-pkg-API.txz && /etc/rc.restart_webgui
Click the Execute button to install the API package, then restart the web GUI.

Navigate to Systems > API after the web GUI has restarted.
If you are using the API Token connection: Click API and go to the Settings Tab. If you want to use an API token for authentication, you must select API Token for the Authentication Mode.
If you are using the Local Database (Basic Authentication): Click API and go to the Settings Tab. Select Local Database for the Authentication Mode.
Upon clicking the Generate button, a notification will appear with the created API key.
Copy and save the API key in a secure location. The client token hash is not required to build the integration connection in D3 SOAR.
READER NOTE
The API key is only viewable once upon its creation, and cannot be viewed again. Store the API key in a secure location for future reference.

Creating a New User
Log in to your PfSense console with an admin user account. Navigate to System > User Manager.
Navigate to the Users tab, and click + Add.
Input a username and password for the new user, and click Save.

On the Users page, find the newly created user and click the pencil icon to edit the user.
Under the Effective Privileges section, click + Add to add permissions to the user.

In the Assigned privileges section, select the Permission Requirements. Click Save.
READER NOTE
Hold down the Ctrl (Windows)/Cmd (MacOS) key to select multiple permissions.

The selected privileges will appear under the Effective Privileges section. Click Save.
Configuring D3 SOAR to Work with PfSense
Log in to D3 SOAR.
Find the PfSense integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type PfSense in the search box to find the integration, then click it to select it.
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 PfSense.
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 appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy 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 your desired description for the connection.
Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share 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.
Authentication Type: Local Database (Basic Authentication)
You must select the Local Database for the Authentication Mode. See step 3 of Configuring PfSense to Work with D3 SOAR for more information.1. Input your domain-level Server URL.
2. Use the dropdown list to select the Local Database (Basic Authentication).
3. Input your User Name.
4. Input your Password.
5. Input the API version. The default version is v1.
Authentication Type: API Token
You must select the API Token for the Authentication Mode. See step 3 of Configuring PfSense to Work with D3 SOAR for more information.1. Input your domain level Server URL.
2. Use the dropdown list to select the API Token.
3. Input your Client ID.
4. Input your API token.
5. Input your API version. The default version is v1.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.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.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click Add to create and add the configured connection.
Commands
PfSense 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 PfSense API, please refer to the PfSense API reference: https://{{pfsense_instance_serverurl}}/api/documentation/
READER NOTE
Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring PfSense to Work with D3 SOAR for details.
Block IPs
Blocks specified inbound and/or outbound IP addresses or network CIDRs.
READER NOTE
See the table below for the required interfaces of each block IP direction. Run the Get Interface Status command, and check the “InterfaceNames” field for a list of interface types (WAN or LAN).

Input
Input Parameter | Required/Optional | Description | Example |
Direction | Required | The block direction for the specified IP addresses. The available block directions are Inbound, Outbound or All. The default value is All. Note: If you select Inbound, you must have a LAN interface. If you select All direction, you must have both a WAN and a LAN interface. You may reference the list of interface statuses by using the Get Interface Status command. | All |
Description | Optional | A description for the block IP rule. | test block IP rule. ***.***.***.***/*** |
IPs | Required | The IPs to block. Both IP addresses and network CIDRs are supported. | [ "***.***.***.***/***" ] |
Output
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 IPs 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 PfSense 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: Authentication failed. |
Error Sample Data Block IPs failed. Status Code: 401. Message: Authentication failed. |
Get Firewall Log
Returns the PfSense firewall log.
Input
N/A
Output
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. | Get Firewall Log 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 PfSense 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: Authentication failed. |
Error Sample Data Get Firewall Log failed. Status Code: 401. Message: Authentication failed. |
Get Interface Status
Returns all interface status in your PfSense instance.
Input
N/A
Output
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. | Get Interface Status 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 PfSense 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: Authentication failed. |
Error Sample Data Get Interface Status failed. Status Code: 401. Message: Authentication failed. |
List Firewall Rules
Lists existing PfSense firewall rules.
Input
N/A
Output
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 Firewall Rules 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 PfSense 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: Authentication failed. |
Error Sample Data List Firewall Rules failed. Status Code: 401. Message: Authentication failed. |
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
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 PfSense 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: Authentication failed. |
Error Sample Data Test Connection failed. Failed to check the connector. Status Code: 401. Message: Authentication failed. |