ESP32_ZACUS/AUDIT_QUICK_START.md

⚡ Quick Start – Audit Outputs (Lire en 5 min)

📋 TL;DR – Audit Complet en 3 Points

1. 🔴 Sécurité CRITIQUE: WiFi creds en dur + 0 auth API → Fix cette semaine (2-3 days)
2. 🟡 Architecture MOYEN: Race conditions (g_scenario), memory leak (audio) → Fix semaine 1-2
3. 🟢 Tests ABSENT: 0 unit tests C++ → Ajouter semaine 3-4 (40h)

Verdict: ⚠️ NOT PRODUCTION READY sans semaine 1.

---

📁 Fichiers Rapport Générés

Fichier	Taille	Audience	Lire si
AUDIT_COMPLET_2026-03-01.md	15KB	Tech Lead, Senior Dev	Veux comprendre détails profonds
PLAN_ACTION_SEMAINE1.md	12KB	Dev assigné	Besoin d'action concrète jour par jour
SECURITY_AUDIT_REPORT.json	8KB	Security Team	Analyse vuln structurée
REMEDIATION_GUIDE.md	10KB	Dev	Code samples + timetable
RISK_ANALYSIS.md	9KB	Management	Timeline business impact

👉 Commence par: PLAN_ACTION_SEMAINE1.md

---

🚨 Top3 Issues à Fixer IMMÉDIATEMENT

Issue #1: WiFi Credentials Hardcoded 🔴 CRITIQUE

Fichier: data/story/apps/APP_WIFI.json
Problem: SSID + password en texte clair = device contrôlable par n'importe qui
Fix (1h):

# Éditer le fichier et remplacer par placeholders
vi data/story/apps/APP_WIFI.json
# Changer "Les cils" → "YOUR_SSID" et "mascarade" → "YOUR_PASSWORD"
git commit -m "Security: Remove hardcoded WiFi credentials"

Status: 🟠 URGENT

---

Issue #2: API Sans Authentication 🔴 CRITIQUE

Files: ui_freenove_allinone/src/main.cpp (~40 endpoints /api/*)
Problem: Endpoints acceptent n'importe quelle requête
Fix (4h):

// Ajouter dans CHAQUE endpoint:
if (request->header("Authorization") != "Bearer " + g_auth_token) {
  request->send(401, "text/plain", "Unauthorized");
  return;
}

Status: 🟠 URGENT

---

Issue #3: Audio Memory Leak 🔴 HAUT

File: ui_freenove_allinone/src/audio_manager.cpp:159-160
Problem: Raw new sans garantie cleanup
Fix (3h):

// AVANT (BUG):
AudioFileSource* source = new AudioFileSource(...);
AudioGenerator* decoder = new AudioGenerator(...);

// APRÈS (FIX):
auto source = std::make_unique<AudioFileSource>(...);
auto decoder = std::make_unique<AudioGenerator>(...);

Status: 🟠 URGENT

---

📊 Risques par Catégorie

🔴 CRITICAL (Fix ce weekend)

• WiFi credentials → Remove
• API auth → Add Bearer token check
• Watchdog timer → Add esp_task_wdt_init()

🟡 HIGH (Fix semaine 1)

• Audio memory leak → unique_ptr
• Race conditions (g_scenario) → Add mutex
• LVGL non-reentrant → Dedicate core
• handleSerialCommand() 50+ cases → Refactor to command map

🟢 MEDIUM (Fix semaine 2-3)

• Buffer overflow (serial) → Add size validation
• Path traversal → Whitelist paths
• JSON parsing → Add size limits + schema validation
• No watchdog → Add TWDT

🔵 LOW (Fix semaine 4+)

• Memory fragmentation → Use pool allocator
• No tests (C++) → Setup gtest
• Docs outdated → Update ARCHITECTURE.md

---

🎯 Action Items – Copier/Coller

Aujourd'hui (30 min) – Audit Review

# Clone le repo localement
cd ~/Documents/Lelectron_rare/ESP32_ZACUS

# Lire les rapports
cat AUDIT_COMPLET_2026-03-01.md | head -100  # Vue générale
cat PLAN_ACTION_SEMAINE1.md | grep "LUNDI" -A 20  # Commencer lundi

# Identifier issues dans le code
grep -r "server.on.*api" ui_freenove_allinone/src/main.cpp | wc -l
# Output: 40+ endpoints sans auth

grep -n "new AudioFileSource\|new AudioGenerator" ui_freenove_allinone/src/audio_manager.cpp
# Output: Lines 159-160 are vulnerable

Demain (2h) – Sécurité

# Commit 1: WiFi credentials
vi data/story/apps/APP_WIFI.json
# Replace "Les cils" & "mascarade" with placeholders
git add .
git commit -m "Security: Remove hardcoded WiFi credentials"

# Commit 2: API Auth
# Edit main.cpp, add auth check in handlers
# (See PLAN_ACTION_SEMAINE1.md, MARDI section for details)
git commit -m "Feature: Bearer token authentication for web API"

# Commit 3: Watchdog
# Edit main.cpp setup(), add TWDT init
git commit -m "Feature: Add ESP32 Task Watchdog Timer"

Semaine 1 (40h) – Roadmap

# Each day, follow PLAN_ACTION_SEMAINE1.md schedule
# LUN: Security + Watchdog (3 commits)
# MAR: Audio leak + Mutex + Buffer (3 commits)
# WED: Path traversal + Serial refactor (2 commits)
# JEU: JSON validation + Telemetry + Docs (3 commits)
# VEN: Integration test + Code review (1 commit)

# Total: ~12 commits, ~40 hours, 3 P0/P1 fixes

---

🔍 How to Read Audit Report

If you have 5 min:

→ Read: "Executive Summary" section of AUDIT_COMPLET_2026-03-01.md

If you have 15 min:

→ Read: AUDIT_COMPLET_2026-03-01.md sections:

• Executive Summary
• Top 10 Risks Consolidated
• Roadmap Remediation (Phase 1)

If you have 60 min:

→ Read: AUDIT_COMPLET_2026-03-01.md fully (all 5 audit sections)

If you want action items:

→ Read: PLAN_ACTION_SEMAINE1.md with todo checkboxes

If you're security-focused:

→ Read: SECURITY_AUDIT_REPORT.json + REMEDIATION_GUIDE.md

If you're managing timeline:

→ Read: RISK_ANALYSIS.md + Roadmap Remediation phases

---

🧪 Testing Current Build

# Build (current = should work, but has issues)
pio clean
pio run -e freenove_esp32s3_full_with_ui
pio run -e freenove_esp32s3_full_with_ui -t buildfs
pio run -e freenove_esp32s3_full_with_ui -t uploadfs --upload-port /dev/cu.usbmodem5AB907*
pio run -e freenove_esp32s3_full_with_ui -t upload --upload-port /dev/cu.usbmodem5AB907*

# Test scenarios (python serial)
python lib/zacus_story_portable/test_story_4scenarios.py --port /dev/cu.usbmodem5AB907*

# Check for known issues
# 1. Look for "ERR" or "PANIC" in serial output
# 2. Check if reboot loop occurs (known issue)
# 3. Verify task watchdog NOT in logs (we'll add it)

---

📞 Questions Fréquentes

Q: Par où commencer?
A: PLAN_ACTION_SEMAINE1.md, lundi, section "Audit + Triage"

Q: Combien de temps pour corriger tout?
A: 6 semaines (P0=1w, P1=1w, P2=2w, P3=2w)

Q: Peut-on détoyer en production maintenant?
A: ❌ Non, abandon WiFi creds + API auth minimum avant production

Q: Qui doit faire quoi?
A: Voir AUDIT_COMPLET_2026-03-01.md, section "ROADMAP", column "Owner"

Q: Teste-t-on avant chaque commit?
A: Oui, PLAN_ACTION_SEMAINE1.md mentionne tests par jour

Q: Peut-on faire en parallèle?
A: Partiellement. Day 1-2 sécurité + stabilité en parallèle (2 devs), Day 3+ séquentiellement

---

📈 Success Metrics (End of Week 1)

Day 1 (LUN):
  ✅ 3 commits (WiFi, Auth, Watchdog)
  ✅ 0 new security issues
  
Day 2 (MAR):
  ✅ Audio leak fixed
  ✅ Race conditions identified
  ✅ 3 commits merged
  
Day 3 (WED):
  ✅ handleSerialCommand() cyclo < 20
  ✅ Path traversal fixed
  ✅ 2 commits merged
  
Day 4 (JEU):
  ✅ JSON validation added
  ✅ Telemetry task running
  ✅ Docs created (3 files)
  ✅ 3 commits merged
  
Day 5 (VEN):
  ✅ Tests passing (4 scenarios x10 = no crash)
  ✅ Memory stable (>80KB free internal heap)
  ✅ API requires Bearer token
  ✅ PR ready for review
  ✅ 1 final commit

Grand Total: 12+ commits, 40h effort, 3 critical issues fixed, production-ready baseline

---

🎓 Learning Resources

Security

• OWASP Embedded
• ESP32 Security

Architecture

• Effective C++ (Modern C++)
• Design Patterns for Embedded

Testing

• Google Test Framework
• Arduino Testing

FreeRTOS

• Task Watchdog Timer
• Mutex & Sync Primitives

---

🚀 PRX Steps (After Week 1)

1. Code Review (2h)

   • Senior dev reviews 12 commits
   • Security team spot-checks Bearer token impl

2. Merge to Main

   • Create feature branch: security/critical-fixes
   • All CI checks pass
   • Tag: v1.1.0-security

3. Phase 2 Planning

   • LVGL re-entrancy (core dedication)
   • Network async state machine
   • Unit test framework setup (gtest)

4. Release Notes

   ## v1.1.0-security (2026-03-08)
   
   ### Security Fixes 🔐
   - Removed hardcoded WiFi credentials
   - Added Bearer token auth to all API endpoints
   - Fixed serial buffer overflow
   - Added path traversal validation
   - JSON schema validation with size limits
   
   ### Stability Fixes ⚙️
   - Fixed audio memory leak (unique_ptr)
   - Added mutex protection for global state
   - Implemented ESP32 Task Watchdog Timer
   - Added memory telemetry task
   
   ### Code Quality 📝
   - Refactored handleSerialCommand() (50+ cases → command map)
   - Added ARCHITECTURE.md, SECURITY.md docs
   - Integration tests for auth + memory stability
   
   **Status**: ✅ Production-Ready
   

---

Tu as besoin d'aide pour démarrer? Demande moi de créer un code snippet ou un premier commit template. 💪