172 lines
3.8 KiB
Markdown
172 lines
3.8 KiB
Markdown
# 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](https://docs.espressif.com/projects/arduino-esp32/en/latest/esp-idf_component.html)):
|
|
|
|
```
|
|
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](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide)
|
|
|
|
## API
|
|
|
|
Following endpoints can be used with the firewall (see `http://<IP_OF_ESP32>:8080/api`):
|
|
|
|
```json
|
|
[
|
|
{
|
|
"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](https://github.com/flohoss/esp32_firewall_api#credentials).
|
|
|
|
### Get rules
|
|
|
|
```sh
|
|
curl -u username:password \
|
|
http://10.93.0.246:8080/api/firewall/rules
|
|
```
|
|
|
|
```json
|
|
// 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
|
|
|
|
```sh
|
|
curl -u username:password \
|
|
http://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
|
|
{
|
|
"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 \
|
|
http://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
|
|
{
|
|
"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 \
|
|
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
|
|
```
|
|
|
|
```json
|
|
// 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
|
|
|
|
```sh
|
|
curl -X DELETE -u username:password \
|
|
http://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
|
|
{
|
|
"message": "firewall rule deleted"
|
|
}
|
|
```
|