esp-firewall/esp32example

ESP32 Firewall with API

Example

Clone this repository and open the folder esp32example in Visual Studio Code.

Arduino as an ESP-IDF component

To compile Arduino as an ESP-IDF component please execute following commands to include then necessary core inside the components folder (Arduino as an ESP-IDF component):

mkdir -p components && \
cd components && \
git clone https://github.com/espressif/arduino-esp32.git arduino && \
cd arduino && \
git submodule update --init --recursive && \
cd ../..

Credentials

After git is finished, add the WiFi credentials, username and password for basic auth by creating a theSecrets.h file based on the example that can be found in the include folder.

Compile and upload

Finally compile and upload with the official platformIO plugin

API

Following endpoints can be used with the firewall (see http://<IP_OF_ESP32>:8080/api):

[
  {
    "endpoint": "http://10.93.0.246:8080/api/firewall/rules",
    "description": "Get all Firewall Rules",
    "method": "GET"
  },
  {
    "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Get Firewall Rule by key",
    "method": "GET"
  },
  {
    "endpoint": "http://10.93.0.246:8080/api/firewall/rules",
    "description": "Create Firewall Rule",
    "method": "POST"
  },
  {
    "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Update Firewall Rule by key",
    "method": "PUT"
  },
  {
    "endpoint": "http://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Delete Firewall Rule by key",
    "method": "DELETE"
  }
]

Endpoints that show the rules and that can modify the rules are protected by basic auth. Username and password need to be set as described here.

Get rules

curl -u username:password \
http://10.93.0.246:8080/api/firewall/rules

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 109
[
  {
    "key": "1",
    "ip": "10.93.0.211",
    "port_from": "8080",
    "port_to": "8080",
    "protocol": "TCP",
    "target": "ACCEPT"
  }
]

Get rule

curl -u username:password \
http://10.93.0.246:8080/api/firewall/rules/1

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 107
{
  "key": "1",
  "ip": "10.93.0.211",
  "port_from": "8080",
  "port_to": "8080",
  "protocol": "TCP",
  "target": "ACCEPT"
}

Create rule

curl -X POST -u username:password \
http://10.93.0.246:8080/api/firewall/rules?ip=10.93.0.200&port_from=10&port_to=50&protocol=UDP&target=ACCEPT

// HTTP/1.1 201 Created
// Content-Type: application/json; charset=utf-8
// Content-Length: 104
{
  "key": "2",
  "ip": "10.93.0.200",
  "port_from": "10",
  "port_to": "50",
  "protocol": "UDP",
  "target": "ACCEPT"
}

Available protocols are TCP, UDP & ALL

Available targets are ACCEPT & DROP

Update rule

curl -X PUT -u username:password \
http://10.93.0.246:8080/api/firewall/rules/2?ip=10.93.0.100&port_from=20&port_to=100&protocol=ALL&target=DROP

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 103
{
  "key": "2",
  "ip": "10.93.0.100",
  "port_from": "20",
  "port_to": "100",
  "protocol": "ALL",
  "target": "DROP"
}

Available protocols are TCP, UDP & ALL

Available targets are ACCEPT & DROP

Delete rule

curl -X DELETE -u username:password \
http://10.93.0.246:8080/api/firewall/rules/2

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 36
{
  "message": "firewall rule deleted"
}