Firewall configuration API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to the Device Configuration APIs section in the VAPIX®.

warning

This API is in BETA stage and provided for testing purposes. It is subject to backward-incompatible changes, including modifications to its functionality, behavior and availability. The API should not be used in production environments.

Overview

The Firewall Configuration API makes it possible to add, fetch, edit, reorder, and remove existing firewall rules. With this API, you can also activate/deactivate the firewall, check if firewall is active, and test the firewall rules before saving.

note

This API includes operations on sensitive data. You must use a secured channel for the communication transmissions.

Use cases

Manage firewall

The Firewall Configuration API can activate or deactivate the firewall, and check if the firewall is activated.

Activate firewall

This example shows how to use firewall.v1.activated to activate the firewall.

JSON request:

PATCH /config/rest/firewall/v1beta/activated HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": true
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Check if the firewall is activated

This example shows how to use firewall.v1.activated to check if the firewall is activated.

JSON request:

GET /config/rest/firewall/v1beta/activated HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "true"
}

Manage firewall rules

You can apply the firewall rules to filter inbound traffic to the device.

During testing, the firewall rules are in the pendingRules list until they are either confirmed by using confirmRules, cleared by using clearPendingRules, or test timeout.

Get active default firewall policy

This example shows how to use firewall.v1.conf.rules.activeDefaultPolicy to get the active default firewall policy.

JSON request:

GET /config/rest/firewall/v1beta/conf/rules/activeDefaultPolicy HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "DROP"
}

Get pending default firewall policy

This example shows how to use firewall.v1.conf.rules.pendingDefaultPolicy to get the pending default firewall policy.

JSON request:

GET /config/rest/firewall/v1beta/conf/rules/pendingDefaultPolicy HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "DROP"
}

List all firewall rules

This example shows how to use firewall.v1.conf.rules to get a list of all firewall rules.

JSON request:

GET /config/rest/firewall/v1beta/conf/rules HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": {
    "activeRules": [
      {
        "ruleType": "FILTER",
        "ip": "192.168.0.14",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": "192.168.1.0/20",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": null,
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "DROP"
        }
      }
    ]
  },
     "activeDefaultPolicy": "ACCEPT",
     "pendingRules": [],
     "pendingDefaultPolicy": null,
     "testTimeLeft": 0
}

Edit firewall rules

This example shows how to use firewall.v1.conf.setRules to edit the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

JSON request:

PATCH /config/rest/firewall/v1beta/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
    "rules": [
      {
        "ruleType": "FILTER",
        "ip": "192.168.0.16",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": "192.168.1.0/20",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": null,
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "DROP"
        }
      }
    ],
     "fallbackTime": 30,
     "defaultPolicy": "ACCEPT"
  }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Reorder firewall rules

This example shows how to use firewall.v1.conf.setRules to reorder the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

JSON request:

PATCH /config/rest/firewall/v1beta/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
    "rules": [
      {
        "ruleType": "FILTER",
        "ip": null,
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "DROP"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": "192.168.0.16",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": "192.168.1.0/20",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      }
    ],
     "fallbackTime": 30,
     "defaultPolicy": "ACCEPT"
  }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Remove firewall rules

This example shows how to use firewall.v1.conf.setRules to remove the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

JSON request:

PATCH /config/rest/firewall/v1beta/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
    "rules": [
      {
        "ruleType": "FILTER",
        "ip": null,
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "DROP"
        }
      },
      {
        "ruleType": "FILTER",
        "ip": "192.168.0.16",
        "tcpPort": 80,
        "udpPort": null,
        "filter": {
          "policy": "ACCEPT"
        }
      }
    ],
     "fallbackTime": 30,
     "defaultPolicy": "ACCEPT"
  }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Confirm pending firewall rules

This example shows how to use firewall.v1.conf.confirmRules to confirm the pending firewall rules. It will move the pending firewall rules to the active list permanently.

JSON request:

PATCH /config/rest/firewall/v1beta/conf/confirmRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
  }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Clear pending firewall rules

This example shows how to use firewall.v1.conf.clearPendingRules to clear the pending firewall rules. It will cancel the active pending rules, restore the previous set of rules, and reset the fallback timer.

JSON request:

PATCH /config/rest/firewall/v1beta/conf/clearPendingRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
  "data": {
  }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Structure

firewall.v1 (Root Entity)
  activated (Property)
  conf (Entity)
    clearPendingRules (Action)
    confirmRules (Action)
    setRules (Action)
    rules (Entity)
      activeDefaultPolicy (Property)
      activeRules (Property)
      pendingDefaultPolicy (Property)
      pendingRules (Property)
      testTimeLeft (Property)

Objects

Object	Operations	Description
`firewall.v1` (Entity)	Get	Firewall management.
`firewall.v1.activated` (Property)	Get Trigger	Manages the firewall service state.
`firewall.v1.conf` (Entity)	Get	Manages the firewall rules.
`firewall.v1.conf.clearPendingRules` (Action)	Trigger	Clears the pending firewall rules and aborts any active test.
`firewall.v1.conf.confirmRules` (Action)	Trigger	Confirms the pending firewall rules.
`firewall.v1.conf.setRules`(Action)	Trigger	Sets the existing firewall rules.
`firewall.v1.conf.rules` (Entity)	Get	Gets information of the firewall rules. Firewall rules are read-only properties that show the current state of the rules.
`firewall.v1.conf.rules.activeDefaultPolicy` (Property)	Get	Gets the active default firewall policy. Default policy is `ACCEPT`.
`firewall.v1.conf.rules.activeRules` (Property)	Get	Gets the active firewall rules.
`firewall.v1.conf.rules.pendingDefaultPolicy` (Property)	Get	Gets the pending default firewall policy.
`firewall.v1.conf.rules.pendingRules` (Property)	Get	Gets the pending firewall rules.
`firewall.v1.conf.rules.testTimeLeft` (Property)	Get	Gets the remaining test time for pending firewall rules.

Data types

PositiveNumValue

{
  "description": "Positive number",
  "minimum": 0,
  "type": "integer"
}

Filter

{
  "description": "Firewall filter type",
  "properties": {
    "policy": {
      "description": "Filter policy",
      "type": "Policy"
    }
  },
  "type": "object"
}

Policy

{
  "description": "Valid policies",
  "enum": [
    "DROP",
    "ACCEPT"
  ],
  "type": "string"
}

RuleType

{
  "description": "Valid rule types",
  "enum": [
    "FILTER"
  ],
  "type": "string"
}

Rule

{
  "description": "Firewall rule entry type",
  "properties": {
    "filter": {
      "description": "Filter rule",
      "type": "Filter"
    },
    "ip": {
      "description": "IPv4/IPv6 address or network",
      "nullable": true,
      "type": "string"
    },
    "ruleType": {
      "description": "Firewall rule entry type",
      "type": "RuleType"
    },
    "tcpPort": {
      "description": "The TCP port",
      "nullable": true,
      "type": "Port"
    },
    "udpPort": {
      "description": "The UDP port",
      "nullable": true,
      "type": "Port"
    }
  },
  "type": "object"
}

SetRulesReqData

{
  "description": "Firewall rules set request data type",
  "properties": {
    "defaultPolicy": {
      "description": "Default firewall policy",
      "type": "Policy"
    },
    "fallbackTime": {
      "description": "The maximum time in seconds to wait before reverting back to previous active rules",
      "type": "PositiveNumValue"
    },
    "rules": {
      "description": "Rules to set as active",
      "type": "RuleList"
    }
  },
  "type": "object"
}

Port

{
  "description": "A valid port number",
  "maximum": 65535,
  "minimum": 1,
  "type": "integer"
}

RuleList

{
  "description": "Firewall rule list type",
  "items": {
    "type": "Rule"
  },
  "type": "array"
}

Overview​

Use cases​

Manage firewall​

Activate firewall​

Check if the firewall is activated​

Manage firewall rules​

Get active default firewall policy​

Get pending default firewall policy​

List all firewall rules​

Edit firewall rules​

Reorder firewall rules​

Remove firewall rules​

Confirm pending firewall rules​

Clear pending firewall rules​

Structure​

Objects​

Data types​

Overview

Use cases

Manage firewall

Activate firewall

Check if the firewall is activated

Manage firewall rules

Get active default firewall policy

Get pending default firewall policy

List all firewall rules

Edit firewall rules

Reorder firewall rules

Remove firewall rules

Confirm pending firewall rules

Clear pending firewall rules

Structure

Objects

Data types