2022-07-29 10:54:22 +02:00
# ESP8266 Firewall with API
## Example
2022-07-29 10:55:45 +02:00
Clone this repository and open the folder `esp8266example` in Visual Studio Code.
2022-07-29 10:54:22 +02:00
### 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 ](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide )
## API
Following endpoints can be used with the firewall (see `https://<IP_OF_ESP8266>:8080/api` ):
```json
[
{
"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 ](https://github.com/flohoss/esp8266_firewall_api#credentials ).
### Get rules
```sh
curl -u username:password \
https://10.93.0.246:8080/api/firewall/rules
```
```json
// 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
```sh
curl -u username:password \
https://10.93.0.246:8080/api/firewall/rules/1
```
```json
// 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
```sh
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
```
```json
// 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
```sh
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
```
```json
// 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
```sh
curl -X DELETE -u username:password \
https://10.93.0.246:8080/api/firewall/rules/2
```
```json
// 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"
}
```