HS-Esslingen/esp-firewall
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add README

Browse source
This commit is contained in:
Florian Hoss 2022-07-29 10:54:22 +02:00
parent 1d9b34f9ff
commit e10d26d9c6
3 changed files with 356 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
README.md Normal file
View file

@ -0,0 +1,15 @@
# IoT Firewall on ESP8266/ESP32
### [ESP32 Example](https://gitlab.hs-esslingen.de/toheer/iot-security-tools/-/tree/main/esp32example)
### [ESP8266 Example](https://gitlab.hs-esslingen.de/toheer/iot-security-tools/-/tree/main/esp8266example)
# Maintainer
Student: Florian Hoss
[flhoit00@hs-esslingen.de](mailto:flhoit00@hs-esslingen.de)
Professor: Prof. Dr. rer. nat. Tobias Heer
[tobias.heer@hs-esslingen.de](mailto:tobias.heer@hs-esslingen.de)

172
esp32example/README.md Normal file
View file

@ -0,0 +1,172 @@
# 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"
}
```

169
esp8266example/README.md Normal file
View file

@ -0,0 +1,169 @@
# ESP8266 Firewall with API
## Example
Clone this repository and open the folder `example` 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](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"
}
```