esp-firewall/esp8266example

ESP8266 Firewall with API

Example

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

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 https://<IP_OF_ESP8266>:8080/api):

[
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
    "description": "Get all Firewall Rules",
    "method": "GET"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Get Firewall Rule by key",
    "method": "GET"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules",
    "description": "Create Firewall Rule",
    "method": "POST"
  },
  {
    "endpoint": "https://10.93.0.246:8080/api/firewall/rules/<key>",
    "description": "Update Firewall Rule by key",
    "method": "PUT"
  },
  {
    "endpoint": "https://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 \
https://10.93.0.246:8080/api/firewall/rules

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

Get rule

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

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 107
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "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 \
https://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
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "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 \
https://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
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "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 \
https://10.93.0.246:8080/api/firewall/rules/2

// HTTP/1.1 200 OK
// Content-Type: application/json; charset=utf-8
// Content-Length: 36
// Connection: keep-alive
// Keep-Alive: timeout=2000
{
  "message": "firewall rule deleted"
}