titiomathias/sec-for-ble

# Offensive Security for Bluetooth Low Energy Laboratório didático para demonstrar ataques em BLE usando duas ESP32 vulneráveis e uma API externa que simula a casa inteligente em tempo real. ## Objetivo do cenário Este projeto foi desenhado para aulas práticas de segurança ofensiva em Bluetooth Low Energy: - `ESPA (home)` atua como periférico BLE vulnerável e controla o estado da casa. - `ESPB (client)` atua como central BLE e envia comandos. - `Smart Home API` representa a casa no navegador, registra eventos e facilita visualizar o impacto dos ataques. O foco é reproduzir, observar e explicar comportamentos inseguros como escrita não autenticada, replay e personificação de cliente BLE. ## Arquitetura [ESPB_CLIENT_VULN] --BLE plaintext--> [ESPA_HOME_VULN] --HTTP--> [Smart Home API + UI] | | | (comandos) (sem auth BLE) (estado + eventos) ## Estrutura do repositório . ├── espa_home_vuln/ │ └── espa_home_vuln.ino # ESPA: periférico BLE vulnerável + integração HTTP com API ├── espb_client_vuln/ │ └── espb_client_vuln.ino # ESPB: central BLE vulnerável (auto/demo/manual) └── smarthome/ ├── app/main.py # FastAPI + WebSocket + painel visual ├── app/state_store.py # Persistência e trilha de eventos ├── data/state.json # Estado da casa └── requirements.txt ## Vulnerabilidades intencionais No firmware `espa_home_vuln`: - Sem pairing/bonding obrigatório. - Sem criptografia de enlace BLE. - Comandos em texto plano (`SALA:ON`, `COZINHA:OFF`, etc.). - Sem nonce/counter/token anti-replay. - Characteristic de comando com permissão aberta para escrita. No firmware `espb_client_vuln`: - Cliente envia comandos em texto puro. - Fluxo de automação facilita gerar tráfego repetível para replay/demonstração. ## Protocolo BLE usado no lab - `BLE_DEVICE_NAME` (home): `ESP32_HOME_VULN` - `SERVICE_UUID`: `b7e15000-7d99-4c80-9a9e-b8d537d9e111` - `CMD_CHAR_UUID`: `b7e15001-7d99-4c80-9a9e-b8d537d9e111` (write) - `STATE_CHAR_UUID`: `b7e15002-7d99-4c80-9a9e-b8d537d9e111` (read/notify) Comandos aceitos pela casa: - `SALA:ON` / `SALA:OFF` - `COZINHA:ON` / `COZINHA:OFF` - `BANHEIRO:ON` / `BANHEIRO:OFF` - `STATUS` - `RESET` ## Subindo a API da casa (simulador externo) Pré-requisitos: - Python 3.10+ Passos: cd smarthome python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt cd app python3 main.py A API sobe em: - `http://127.0.0.1:8080` - `http://SEU_IP_LOCAL:8080` (para acesso na mesma rede das ESPs) ## Configuração das ESPs ### ESPA (casa vulnerável) Arquivo: `espa_home_vuln/espa_home_vuln.ino` Ajuste estes valores antes do upload: - `WIFI_SSID` - `WIFI_PASS` - `API_BASE_URL` (ex.: `http://192.168.0.10:8080`) Compile com stack NimBLE-Arduino e faça upload para a ESP32 da casa. ### ESPB (cliente vulnerável) Arquivo: `espb_client_vuln/espb_client_vuln.ino` Faça upload para a ESP32 cliente. Ela faz scan, conecta no serviço BLE e permite: - Modo automático (comandos aleatórios periódicos) - Modo demo (sequência guiada) - Modo manual via serial (qualquer comando de texto) ## Como rodar a demonstração 1. Suba a API (`python3 main.py`) e abra o painel web. 2. Ligue a ESPA (`ESP32_HOME_VULN`) e confirme que está em advertising. 3. Ligue a ESPB e aguarde conexão BLE. 4. Envie comandos via serial da ESPB (`demo`, `STATUS`, `SALA:ON`, etc.). 5. Observe no painel a alteração em tempo real (WebSocket + eventos). ## Cenários de ataque para visualizar em aula 1. Escrita BLE não autenticada Use outro central BLE (ex.: app genérico BLE no celular) para escrever direto em `CMD_CHAR_UUID`. Resultado esperado: estado da casa muda sem necessidade do cliente legítimo. 2. Replay de comando Reenvie comandos válidos capturados anteriormente. Resultado esperado: ações se repetem porque não há nonce/counter nem verificação de frescor. 3. Personificação de cliente Um atacante enviando payloads no formato esperado (`SALA:ON`, `COZINHA:OFF`, etc.) obtém o mesmo efeito operacional. Resultado esperado: API registra eventos com origem técnica, mas sem garantia de identidade confiável. ## Endpoints principais da API - `GET /api/state` -> snapshot atual da casa - `POST /api/command` -> aplica ação por alvo - `PATCH /api/state/{device_type}/{device_id}` -> muda estado direto - `GET /api/events?limit=20` -> histórico de eventos - `POST /api/reset` -> reseta cenário - `WS /ws` -> atualizações em tempo real para o painel Exemplo de comando via API: curl -X POST http://127.0.0.1:8080/api/command \ -H 'Content-Type: application/json' \ -d '{"target":"doors.front","action":"open","source":"attacker-replay"}' ## Uso responsável Projeto destinado a laboratório controlado, ambiente de ensino e pesquisa autorizada. Não utilize estas técnicas em dispositivos, redes ou sistemas sem permissão explícita.