Skip to main content
Skip table of contents

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

Option I, Option III

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: Ensure you have set the authentication mode to Local Database in PfSense. The setting is located at System > API > Settings.

  • API Token: Ensure you have set the authentication mode to API Token in PfSense. The setting is located at System > API > Settings. The generated client ID and API token are required for the integration connection.

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

  1. Log in to your PfSense console with an admin user account.

  2. Install the PfSense API package. You may skip this step if it has already been completed.

    1. Navigate to Diagnostics > Command Prompt.

    2. Copy and paste the shell command into the Execute Shell Command field.

      CODE
      pkg 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.

  1. 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.

  1. 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

  1. Log in to your PfSense console with an admin user account. Navigate to System > User Manager.

  2. Navigate to the Users tab, and click + Add.

  1. Input a username and password for the new user, and click Save.

  1. On the Users page, find the newly created user and click the pencil icon to edit the user.

  2. Under the Effective Privileges section, click + Add to add permissions to the user.

  1. 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.

  1. The selected privileges will appear under the Effective Privileges section. Click Save.

Configuring D3 SOAR to Work with PfSense

  1. Log in to D3 SOAR.

  2. Find the PfSense integration.

    Frame 59 (2)-20241101-180437.png
    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type PfSense 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.

  3. Configure the following fields to create a connection to PfSense.

    Frame 51 (8)-20241101-173303.png
    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, 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.

    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.

      Frame 58 (2)-20241101-173356.png
    9. 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.

      Frame 54 (6)-20241101-171608.png

      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.

      Frame 55 (4)-20241101-172419.png

      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.

    10. 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.

    11. 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.

  4. Test the connection.

    1. 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.

    2. Click OK to close the alert window.

    3. 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).

image-20240708-204319.png

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

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
[
    {
        "status": "ok",
        "code": 200,
        "return": 0,
        "message": "Success",
        "data": {
            "type": "block",
            "interface": "wan",
            "ipprotocol": "inet",
            "source": {
                "address": "***.***.***.***/***"
            },
            "destination": {
                "any": ""
            },
            "descr": "test block IP rule. ***.***.***.***/***",
            "tracker": 1658880664,
            "created": {
                "time": 1658880664,
                "username": "d3user@***.***.***.*** (API)"
            },
            "updated": {
                "time": 1658880664,
                "username": "d3user@***.***.***.*** (API)"
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE
{
  "Types": ["block"],
  "Interfaces": ["wan"],
  "Sources": [
    { "address": "***.***.***.***/***" }
  ],
  "Destinations": [
    { "any": "" }
  ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

code

return

message

data

ok

200

0

Success

{'type': 'block', 'interface': 'wan', 'ipprotocol': 'inet', 'source': {'address': '***.***.***.***/***'}, 'destination': {'any': ''}, 'descr': 'test block IP rule. ***.***.***.***/***', 'tracker': 1658880664, 'created': {'time': 1658880664, 'username': 'd3user@***.***.***.*** (API)'}, 'updated': {'time': 1658880664, 'username': 'd3user@***.***.***.*** (API)'}}

CODE
No Sample Data

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

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": "ok",
    "code": 200,
    "return": 0,
    "message": "Success",
    "data": [
        "Jul 26 17:56:00 pfSense newsyslog[11598]: logfile turned over due to size>500K",
        "Jul 26 17:56:22 pfSense filterlog[10236]: 4,,,1000000103,vmx0,match,block,in,4,0x0,,128,19717,0,none,17,udp,78,***.***.***.***,***.***.***.***,***.***.***.***",
        "Jul 26 17:56:22 pfSense filterlog[10236]: 4,,,1000000103,vmx0,match,block,in,4,0x0,,128,20633,0,none,17,udp,78,***.***.***.***,***.***.***.***,***.***.***.***"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

ok

code

200

return

0

message

Success

data

  • Jul 26 17:56:00 pfSense newsyslog[11598]: logfile turned over due to size>500K

  • Jul 26 17:56:22 pfSense filterlog[10236]: 4,,,1000000103,vmx0,match,block,in,4,0x0,,128,19717,0,none,17,udp,78,***.***.***.***,***.***.***.***,***.***.***.***

  • Jul 26 17:56:22 pfSense filterlog[10236]: 4,,,1000000103,vmx0,match,block,in,4,0x0,,128,20633,0,none,17,udp,78,***.***.***.***,***.***.***.***,***.***.***.***

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

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": "ok",
    "code": 200,
    "return": 0,
    "message": "Success",
    "data": [
        {
            "name": "wan",
            "descr": "WAN",
            "hwif": "vmx0",
            "enable": true,
            "if": "vmx0",
            "status": "up",
            "macaddr": "**:**:**:**:**:**",
            "mtu": 1500,
            "ipaddr": "***.***.***.***",
            "subnet": "***.***.***.***",
            "linklocal": "****::***:****:***:****%****",
            "ipaddrv6": null,
            "subnetv6": null,
            "inerrs": 0,
            "outerrs": 0,
            "collisions": 0,
            "inbytespass": 31908702,
            "outbytespass": 17089915,
            "inpktspass": 83574,
            "outpktspass": 86603,
            "inbytesblock": 1319255,
            "outbytesblock": 0,
            "inpktsblock": 14649,
            "outpktsblock": 0,
            "inbytes": 31908702,
            "outbytes": 17089915,
            "inpkts": 83574,
            "outpkts": 86603,
            "media": "autoselect",
            "gateway": "***.***.***.***",
            "gatewayv6": null
        },
        {
            "name": "lan",
            "descr": "LAN",
            "hwif": "vmx1",
            "enable": false,
            "if": "vmx1",
            "status": "down",
            "macaddr": "**:**:**:**:**:**",
            "mtu": 1500,
            "ipaddr": null,
            "subnet": null,
            "linklocal": null,
            "ipaddrv6": null,
            "subnetv6": null,
            "inerrs": 0,
            "outerrs": 0,
            "collisions": 0,
            "inbytespass": 0,
            "outbytespass": 0,
            "inpktspass": 0,
            "outpktspass": 0,
            "inbytesblock": 0,
            "outbytesblock": 0,
            "inpktsblock": 0,
            "outpktsblock": 0,
            "inbytes": 0,
            "outbytes": 0,
            "inpkts": 0,
            "outpkts": 0
        }
    ]
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE
{
  "InterfaceNames": ["wan"],
  "Enabled": [true],
  "Descriptions": ["WAN"],
  "Statuses": ["up"],
  "Interfaces": ["vmx0"]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

ok

code

200

return

0

message

Success

data

  • {'name': 'wan', 'descr': 'WAN', 'hwif': 'vmx0', 'enable': True, 'if': 'vmx0', 'status': 'up', 'macaddr': '**:**:**:**:**:**', 'mtu': 1500, 'ipaddr': '***.***.***.***', 'subnet': '***.***.***.***', 'linklocal': '****::***:****:***:****%****', 'ipaddrv6': None, 'subnetv6': None, 'inerrs': 0, 'outerrs': 0, 'collisions': 0, 'inbytespass': 31908702, 'outbytespass': 17089915, 'inpktspass': 83574, 'outpktspass': 86603, 'inbytesblock': 1319255, 'outbytesblock': 0, 'inpktsblock': 14649, 'outpktsblock': 0, 'inbytes': 31908702, 'outbytes': 17089915, 'inpkts': 83574, 'outpkts': 86603, 'media': 'autoselect', 'gateway': '***.***.***.***', 'gatewayv6': None}

  • {'name': 'lan', 'descr': 'LAN', 'hwif': 'vmx1', 'enable': False, 'if': 'vmx1', 'status': 'down', 'macaddr': '**:**:**:**:**:**', 'mtu': 1500, 'ipaddr': None, 'subnet': None, 'linklocal': None, 'ipaddrv6': None, 'subnetv6': None, 'inerrs': 0, 'outerrs': 0, 'collisions': 0, 'inbytespass': 0, 'outbytespass': 0, 'inpktspass': 0, 'outpktspass': 0, 'inbytesblock': 0, 'outbytesblock': 0, 'inpktsblock': 0, 'outpktsblock': 0, 'inbytes': 0, 'outbytes': 0, 'inpkts': 0, 'outpkts': 0}

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

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE
Successful
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "status": "ok",
    "code": 200,
    "return": 0,
    "message": "Success",
    "data": [
        {
            "type": "reject",
            "interface": "wan",
            "ipprotocol": "inet",
            "source": {
                "any": ""
            },
            "destination": {
                "address": "***.***.***.***"
            },
            "descr": "floating block IP rule 726a",
            "floating": "yes",
            "direction": "any",
            "tracker": "1658875322",
            "created": {
                "time": "1658875322",
                "username": "d3user@***.***.***.*** (API)"
            },
            "updated": {
                "time": "1658875322",
                "username": "d3user@***.***.***.*** (API)"
            }
        },
        {
            "type": "block",
            "interface": "wan",
            "ipprotocol": "inet",
            "source": {
                "address": "***.***.***.***00"
            },
            "destination": {
                "any": ""
            },
            "descr": "test block IP rule inbound 726a",
            "tracker": "1658871794",
            "created": {
                "time": "1658871794",
                "username": "d3user@***.***.***.*** (API)"
            },
            "updated": {
                "time": "1658871794",
                "username": "d3user@***.***.***.*** (API)"
            }
        },
        {
            "type": "reject",
            "interface": "wan",
            "ipprotocol": "inet",
            "source": {
                "any": ""
            },
            "destination": {
                "address": "***.***.***.***00"
            },
            "descr": "test block IP rule outbound 726a",
            "tracker": "1658871912",
            "created": {
                "time": "1658871912",
                "username": "d3user@***.***.***.*** (API)"
            },
            "updated": {
                "time": "1658871912",
                "username": "d3user@***.***.***.*** (API)"
            }
        },
        {
            "type": "pass",
            "ipprotocol": "inet",
            "descr": "Default allow LAN to any rule",
            "interface": "lan",
            "tracker": "0100000101",
            "source": {
                "network": "lan"
            },
            "destination": {
                "any": ""
            }
        },
        {
            "type": "pass",
            "ipprotocol": "inet6",
            "descr": "Default allow LAN IPv6 to any rule",
            "interface": "lan",
            "tracker": "0100000102",
            "source": {
                "network": "lan"
            },
            "destination": {
                "any": ""
            }
        }
    ]
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE
{
  "Types": ["reject"],
  "Interfaces": ["wan"],
  "Sources": [ { "any": "" } ],
  "Destinations": [ { "address": "***.***.***.***" } ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

status

ok

code

200

return

0

message

Success

data

  • {'type': 'reject', 'interface': 'wan', 'ipprotocol': 'inet', 'source': {'any': ''}, 'destination': {'address': '***.***.***.***'}, 'descr': 'floating block IP rule 726a', 'floating': 'yes', 'direction': 'any', 'tracker': '1658875322', 'created': {'time': '1658875322', 'username': 'd3user@***.***.***.*** (API)'}, 'updated': {'time': '1658875322', 'username': 'd3user@***.***.***.*** (API)'}}

  • {'type': 'block', 'interface': 'wan', 'ipprotocol': 'inet', 'source': {'address': '***.***.***.***00'}, 'destination': {'any': ''}, 'descr': 'test block IP rule inbound 726a', 'tracker': '1658871794', 'created': {'time': '1658871794', 'username': 'd3user@***.***.***.*** (API)'}, 'updated': {'time': '1658871794', 'username': 'd3user@***.***.***.*** (API)'}}

  • {'type': 'reject', 'interface': 'wan', 'ipprotocol': 'inet', 'source': {'any': ''}, 'destination': {'address': '***.***.***.***00'}, 'descr': 'test block IP rule outbound 726a', 'tracker': '1658871912', 'created': {'time': '1658871912', 'username': 'd3user@***.***.***.*** (API)'}, 'updated': {'time': '1658871912', 'username': 'd3user@***.***.***.*** (API)'}}

  • {'type': 'pass', 'ipprotocol': 'inet', 'descr': 'Default allow LAN to any rule', 'interface': 'lan', 'tracker': '0100000101', 'source': {'network': 'lan'}, 'destination': {'any': ''}}

  • {'type': 'pass', 'ipprotocol': 'inet6', 'descr': 'Default allow LAN IPv6 to any rule', 'interface': 'lan', 'tracker': '0100000102', 'source': {'network': 'lan'}, 'destination': {'any': ''}}

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

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.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE
Successful

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.