secubox-deb/docs/LED-HEALTHBUMP.md

SecuBox LED HealthBump System

MOCHAbin 3-Tier Health Status Indicator — v2.0

The SecuBox HealthBump system uses the MOCHAbin's 3 RGB LEDs as a visual health status indicator, organized in a vertical "level meter" layout.

v2.0 Changes: Added 300ms I2C delays, timeout protection, and automatic I2C bus reset capability for reliable operation on Debian kernel 6.6.x LTS. Based on proven patterns from secubox-led-safe.

LED Layout

┌─────────────────────────────────────────────────────────────┐
│                     MOCHAbin Front Panel                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────┐                                                   │
│   │ LED3│  TOP - Security Layer                             │
│   │ SEC │  Alerts, attacks, CrowdSec bans                   │
│   └─────┘                                                   │
│                                                              │
│   ┌─────┐                                                   │
│   │ LED2│  MIDDLE - Services Layer                          │
│   │ SVC │  VHosts, certificates, HAProxy                    │
│   └─────┘                                                   │
│                                                              │
│   ┌─────┐                                                   │
│   │ LED1│  BOTTOM - Hardware Layer                          │
│   │ HW  │  Network, CPU, memory                             │
│   └─────┘                                                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Color Codes

Color	Status	Meaning
🟢 Green	ok	All systems healthy
🟡 Yellow/Orange	warn	Warning, elevated activity
🔴 Red	error	Critical, immediate action required
🔵 Blue	msg	Active mitigation in progress

Brightness & I2C Timing

The IS31FL3199 LED controller uses brightness value 100 (active) or 20 (sleep) for optimal visibility with reliable I2C timing.

Important: Uses same I2C timing values as secubox-led-safe:

• WRITE_DELAY=0.3 — 300ms between sysfs writes
• ERROR_BACKOFF=3 — 3 second wait after errors
• MAX_ERRORS=5 — Stop after 5 consecutive errors
• RESET_THRESHOLD=3 — Try I2C reset after 3 errors
• timeout 2 — 2 second max per write (prevents I2C lockup)

Higher values (e.g., 255) or faster timing cause I2C communication errors on Marvell Armada due to mv64xxx driver errata FE-8471889.

Activity Detection

HealthBump monitors system changes and adjusts LED brightness:

Mode	Brightness	Condition
ACTIVE	100	Metrics changed (CPU, memory, bans, or colors)
SLEEP	20	System stable, no changes since last check

This creates a visual "breathing" effect: brighter when activity occurs, dimmer when idle.

K2000 Party Mode

For boot/success announcements and alerts:

# K2000 sweep effect
secubox-healthbump k2000 2 cyan    # 2 cycles, cyan color
secubox-healthbump party 1 green   # 1 cycle, green

# Success announcement (boot complete)
secubox-healthbump success "SecuBox ready"
secubox-healthbump boot            # Alias

# Alert (red K2000)
secubox-healthbump alert 2         # 2 cycles red

# Rainbow party (all colors)
secubox-healthbump rainbow

Colors: red, orange, yellow, green, cyan, blue, purple

SPUNK ALERT

When critical services (HAProxy, CrowdSec) are down, all LEDs flash rapid red:

SPUNK ALERT: HAProxy down

The alert flashes 5 times then pauses 0.5s before rechecking. This overrides normal health status until services recover.

LED Layers

LED1 (Bottom) - Hardware Layer hw

Monitors base infrastructure health with gradient colors:

Resource Level	Color	Condition
Normal	🟢 Green	Load < 50%, Memory < 50%
Medium	🟡 Yellow-Green	Load 50-70%
High	🟠 Orange	Load 70-90%
Critical	🔴 Red	Load > 90% OR No WAN

LED2 (Middle) - Services Layer svc

Monitors application services and certificates:

Status	Color	Condition
OK	🟢 Green	HAProxy + Nginx running, certs valid
Warning	🟡 Yellow	Certificate expiring < 30 days
Error	🔴 Red	Service stopped OR cert expired

LED3 (Top) - Security Layer sec

Monitors security with rate-based detection:

Status	Color	Condition
Clear	🟢 Green	0 active bans
Mitigating	🔵 Blue	Bans active, rate < 5/min
Elevated	🟡 Yellow	Rate 5-20 bans/min
Attack	🔴 Red	Rate > 20/min OR > 1000 bans

Commands

Manual LED Control

# Set individual layer status
secubox-led hw ok       # Hardware: green
secubox-led svc warn    # Services: yellow
secubox-led sec error   # Security: red
secubox-led hw msg      # Hardware: blue (info)

# Set all layers at once
secubox-led all ok      # All green
secubox-led all off     # All off

# Layer aliases
secubox-led 1 ok        # LED1 (hw)
secubox-led 2 warn      # LED2 (svc)
secubox-led 3 error     # LED3 (sec)

secubox-led bottom ok   # Same as hw
secubox-led middle warn # Same as svc
secubox-led top error   # Same as sec

Automatic Health Check

# Run manual health check
secubox-healthbump

# Output examples:
# 08:03:46 HW:[yellow:medium(50%cpu,53%mem)] SVC:[green:ok] SEC:[blue:mitigating(100 bans)]
# 08:15:22 HW:[green:ok(12%cpu,45%mem)] SVC:[green:ok] SEC:[green:clear]
# 08:30:01 HW:[red:no-wan] SVC:[green:ok] SEC:[yellow:elevated(50 bans,12/min)]

Systemd Timer

The healthbump runs automatically every 30 seconds:

# Check timer status
systemctl status secubox-healthbump.timer

# View recent runs
journalctl -u secubox-healthbump.service --since "1 hour ago"

# Manually trigger
systemctl start secubox-healthbump.service

Integration with Health Monitor

External systems can update LED status via the secubox-led command:

# From health monitor API callback
curl -X POST http://localhost:8080/health/callback \
  -d '{"layer": "sec", "status": "error", "reason": "Attack detected"}'

# The API internally calls:
secubox-led sec error

Visual Status Examples

All Healthy

LED3: 🟢 Security OK
LED2: 🟢 Services OK
LED1: 🟢 Hardware OK

Security Alert

LED3: 🔴 ATTACK DETECTED
LED2: 🟢 Services OK
LED1: 🟢 Hardware OK

Service Degraded

LED3: 🟢 Security OK
LED2: 🟡 Certificate expiring
LED1: 🟢 Hardware OK

Network Down

LED3: 🟢 Security OK
LED2: 🟢 Services OK
LED1: 🔴 NO WAN CONNECTION

Information Mode

LED3: 🔵 New update available
LED2: 🔵 Config pending
LED1: 🟢 Hardware OK

Files

File	Purpose
/usr/sbin/secubox-led-safe	Safe LED control with I2C delays
/usr/sbin/secubox-healthbump	3-tier health checker (v2.0)
/etc/systemd/system/secubox-healthbump.service	Oneshot health check unit
/etc/systemd/system/secubox-healthbump.timer	30s health check timer
/tmp/secubox/led-status	Current LED status output
/tmp/secubox-ban-rate	CrowdSec ban rate tracking

Hardware

• Controller: ISSI IS31FL3199 (I2C address 0x64)
• Bus: I2C-1
• Driver: leds-is31fl319x (kernel built-in)
• Sysfs: /sys/class/leds/{red,green,blue}:led{1,2,3}/

Related

• GitHub Issue #39: LED heartbeat port
• GitHub Issue #45: IS31FL3199 driver
• GitHub Issue #60: Kernel LED build
• kernel-build/README.md: Kernel build instructions
• docs/reference/secubox-led-pulse-openwrt.sh: Original OpenWrt LED script (single LED)

---

CyberMind SecuBox — https://secubox.in