Skip to content

feat: add protected headless provisioning workflow #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JeremyWhittaker wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add protected headless provisioning workflow #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,5 +133,5 @@ $RECYCLE.BIN/
*.sln
*.sw?

scripts
/scripts/
*/certs/
13 changes: 9 additions & 4 deletions Bjorn.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
from init_shared import shared_data
from display import Display, handle_exit_display
from comment import Commentaireia
from webapp import web_thread, handle_exit_web
from webapp import web_thread, redirect_thread, handle_exit_web
from orchestrator import Orchestrator
from logger import Logger

Expand Down Expand Up @@ -110,7 +110,7 @@ def start_display():
display_thread.start()
return display_thread

def handle_exit(sig, frame, display_thread, bjorn_thread, web_thread):
def handle_exit(sig, frame, display_thread, bjorn_thread, web_thread, redirect_thread):
"""Handles the termination of the main, display, and web threads."""
shared_data.should_exit = True
shared_data.orchestrator_should_exit = True # Ensure orchestrator stops
Expand All @@ -122,7 +122,11 @@ def handle_exit(sig, frame, display_thread, bjorn_thread, web_thread):
if bjorn_thread.is_alive():
bjorn_thread.join()
if web_thread.is_alive():
web_thread.shutdown()
web_thread.join()
if redirect_thread.is_alive():
redirect_thread.shutdown()
redirect_thread.join()
logger.info("Main loop finished. Clean exit.")
sys.exit(0) # Used sys.exit(0) instead of exit(0)

Expand All @@ -148,9 +152,10 @@ def handle_exit(sig, frame, display_thread, bjorn_thread, web_thread):
if shared_data.config["websrv"]:
logger.info("Starting the web server...")
web_thread.start()
redirect_thread.start()

signal.signal(signal.SIGINT, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread, web_thread))
signal.signal(signal.SIGTERM, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread, web_thread))
signal.signal(signal.SIGINT, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread, web_thread, redirect_thread))
signal.signal(signal.SIGTERM, lambda sig, frame: handle_exit(sig, frame, display_thread, bjorn_thread, web_thread, redirect_thread))

except Exception as e:
logger.error(f"An exception occurred during thread start: {e}")
Expand Down
98 changes: 97 additions & 1 deletion INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ sudo apt-get update && sudo apt-get upgrade -y
libopenblas-dev \
bluez-tools \
bluez \
network-manager \
dhcpcd5 \
bridge-utils \
python3-pil
Expand Down Expand Up @@ -311,7 +312,102 @@ chmod +x /home/bjorn/Bjorn/kill_port_8000.sh
```


##### 7.3: USB Gadget Configuration
##### 7.3: Bluetooth Pairing Access

Create the Bluetooth pairing service:

```bash
sudo vi /etc/systemd/system/bjorn-bluetooth.service
```

Add:

```ini
[Unit]
Description=Bjorn Bluetooth Pairing Service
After=bluetooth.service local-fs.target
Requires=bluetooth.service

[Service]
ExecStart=/usr/bin/python3 /home/bjorn/Bjorn/bluetooth_manager.py
WorkingDirectory=/home/bjorn/Bjorn
StandardOutput=inherit
StandardError=inherit
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```

Enable pairing mode in `config/shared_config.json`:

```json
{
"bluetooth_pairing_enabled": true,
"bluetooth_ssh_user": "bjorn"
}
```

Reload and start the services:

```bash
sudo systemctl daemon-reload
sudo systemctl enable bjorn.service bjorn-bluetooth.service bjorn-connectivity.service
sudo systemctl restart bjorn.service bjorn-bluetooth.service bjorn-connectivity.service
```

When pairing mode is enabled, Bjorn shows the pairing prompt or code on the e-paper display and also shows the SSH user and best available host/IP.

##### 7.4: Connectivity Provisioning

Create the connectivity manager service:

```bash
sudo vi /etc/systemd/system/bjorn-connectivity.service
```

Add:

```ini
[Unit]
Description=Bjorn Connectivity Manager
After=NetworkManager.service bluetooth.service local-fs.target
Requires=NetworkManager.service bluetooth.service

[Service]
ExecStart=/usr/bin/python3 /home/bjorn/Bjorn/connectivity_manager.py
WorkingDirectory=/home/bjorn/Bjorn
StandardOutput=inherit
StandardError=inherit
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```

Optional provisioning defaults in `config/shared_config.json`:

```json
{
"bluetooth_pan_enabled": true,
"bluetooth_pan_address": "172.22.0.1/24",
"setup_ap_enabled": true,
"setup_ap_ssid": "bjorn-setup",
"setup_ap_password": "bjornsetup",
"setup_ap_address": "192.168.4.1/24",
"setup_ap_boot_timeout": 30
}
```

Behavior:
- if Bjorn is offline after the boot timeout, it starts the `bjorn-setup` hotspot
- the setup AP at `http://192.168.4.1:8000` is the primary phone provisioning path
- Bluetooth PAN is available at `http://172.22.0.1:8000` as a secondary Android-only link
- if the Bluetooth PAN URL does not load, turn off Wi-Fi and mobile data on the phone or fall back to the setup AP

##### 7.5: USB Gadget Configuration

Modify `/boot/firmware/cmdline.txt`:

Expand Down
7 changes: 7 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ The e-Paper HAT display and web interface make it easy to monitor and interact w
- **System Attacks**: Conducts brute-force attacks on various services (FTP, SSH, SMB, RDP, Telnet, SQL).
- **File Stealing**: Extracts data from vulnerable services.
- **User Interface**: Real-time display on the e-Paper HAT and web interface for monitoring and interaction.
- **Headless Bluetooth Pairing**: Optional Bluetooth pairing mode shows the pairing code and SSH target directly on the e-Paper display.

![Bjorn Display](https://github.com/infinition/Bjorn/assets/37984399/bcad830d-77d6-4f3e-833d-473eadd33921)

Expand Down Expand Up @@ -91,6 +92,12 @@ sudo chmod +x install_bjorn.sh && sudo ./install_bjorn.sh

For **detailed information** about **installation** process go to [Install Guide](INSTALL.md)

To enable the optional Bluetooth pairing screen after installation, set `"bluetooth_pairing_enabled": true` in `config/shared_config.json`, adjust `"bluetooth_ssh_user"` if needed, then restart `bjorn.service` and `bjorn-bluetooth.service`.

Bjorn also supports two headless provisioning paths:
- fallback setup AP at `http://192.168.4.1:8000` as the primary phone setup path when it cannot join Wi-Fi
- Bluetooth PAN at `http://172.22.0.1:8000` as a secondary Android-only link; some phones require disabling Wi-Fi and mobile data before the PAN URL is reachable

## ⚡ Quick Start

**Need help ? You struggle to find Bjorn's IP after the installation ?**
Expand Down
14 changes: 14 additions & 0 deletions TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,13 @@ journalctl -fu bjorn.service

# Check service status
sudo systemctl status bjorn.service
sudo systemctl status bjorn-bluetooth.service
sudo systemctl status bjorn-connectivity.service

# View detailed logs
sudo journalctl -u bjorn.service -f
sudo journalctl -u bjorn-bluetooth.service -f
sudo journalctl -u bjorn-connectivity.service -f

or

Expand All @@ -59,10 +63,20 @@ sudo usermod -a -G spi,gpio bjorn
# Check network interfaces
ip addr show

# Check NetworkManager state
nmcli general status
nmcli device status

# Check setup AP and Bluetooth PAN state
nmcli connection show --active
cat /home/bjorn/Bjorn/config/connectivity_state.json

# Test USB gadget interface
ip link show usb0
```

If `http://172.22.0.1:8000` will not load over Bluetooth PAN, turn off Wi-Fi and mobile data on the phone first. If that is still unreliable, use the `bjorn-setup` access point instead.

### Permission Issues

```bash
Expand Down
14 changes: 14 additions & 0 deletions config/shared_config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,20 @@
"ref_width": 122,
"ref_height": 250,
"epd_type": "epd2in13_V4",
"bluetooth_pairing_enabled": false,
"bluetooth_discoverable_timeout": 300,
"bluetooth_agent_capability": "DisplayYesNo",
"bluetooth_ssh_user": "bjorn",
"bluetooth_pairing_pin": "",
"bluetooth_alias": "bjorn",
"bluetooth_pan_enabled": true,
"bluetooth_pan_address": "172.22.0.1/24",
"setup_ap_enabled": true,
"setup_ap_ssid": "bjorn-setup",
"setup_ap_password": "bjornsetup",
"setup_ap_address": "192.168.4.1/24",
"setup_ap_boot_timeout": 30,
"setup_ap_idle_timeout": 0,
"__title_lists__": "List Settings",
"portlist": [
20,
Expand Down
Loading