LogWhispererAI/workflows/REPORT.md

# 📊 Report: Workflow LogWhisperer_Ingest Creato

## ✅ Stato: COMPLETATO

Il workflow n8n per l'ingestion sicura dei log è stato creato con successo seguendo il **Metodo Sacchi**.

---

## 📁 File Creati

| File | Descrizione | Dimensione |
|------|-------------|------------|
| `workflows/logwhisperer_ingest.json` | Export JSON del workflow n8n | 12.7 KB |
| `workflows/test_workflow.sh` | Test suite automatizzata | 6.3 KB |
| `workflows/README.md` | Documentazione workflow | 5.3 KB |
| `workflows/INTEGRATION.md` | Guida integrazione Bash ↔ n8n | 9.2 KB |

---

## 🔧 Architettura Workflow

```
┌──────────────────┐
│ Webhook Trigger  │ ◄── POST /webhook/logwhisperer/ingest
│ (POST /ingest)   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ HMAC Validation  │ ◄── Verifica firma HMAC-SHA256
│ (Code Node)      │     Anti-replay (max 5 min)
└────────┬─────────┘
         │
         ▼
    ┌─────────┐
    │Valid?   │
    └────┬────┘
    Yes  │  No
       ┌─┴─┐
       ▼   ▼
┌──────────┐ ┌──────────┐
│Data Val. │ │ 401 Resp │
└────┬─────┘ └──────────┘
     │
     ▼
┌──────────────────┐
│ Store Log        │ ◄── PostgreSQL INSERT
│ (PostgreSQL)     │     Tabella: logs
└────────┬─────────┘
         │
         ▼
    ┌───────────┐
    │Critical?  │
    └─────┬─────┘
    Yes   │   No
        ┌─┴─┐
        ▼   ▼
┌──────────┐ ┌──────────┐
│AI Process│ │200 OK    │
│(Sprint 3)│ └──────────┘
└──────────┘
```

---

## 🔐 Sicurezza Implementata

### HMAC Validation
- **Algoritmo**: HMAC-SHA256
- **Formato**: `timestamp:signature` in header `X-LogWhisperer-Signature`
- **Anti-replay**: Timestamp max 5 minuti di differenza
- **Timing-safe**: Comparazione signature con `crypto.timingSafeEqual()`

### Data Validation
- `client_id`: UUID v4 obbligatorio (regex validazione)
- `raw_log`: Non vuoto dopo trim
- `severity`: Solo `low`, `medium`, `critical`
- **Normalizzazione**: Severity convertito a lowercase

### Database
- **Tabella**: `logs` con vincoli CHECK su severity
- **Indici**: client_id, severity, timestamp
- **Audit**: created_at automatico

---

## 🚀 Istruzioni per Attivazione

### 1. Importa il Workflow

```bash
# Via n8n UI
curl -X POST http://192.168.254.12:5678/api/v1/workflows \
  -H "Content-Type: application/json" \
  -H "X-N8N-API-KEY: your-api-key" \
  -d @workflows/logwhisperer_ingest.json
```

### 2. Configura Variabile Ambiente

```bash
# Nel container n8n
docker exec n8n sh -c 'export LOGWHISPERER_SECRET="your-32-char-secret-here"'

# O in docker-compose.yml
environment:
  - LOGWHISPERER_SECRET=your-32-char-secret-here
```

### 3. Configura Credenziali PostgreSQL

1. Vai su http://192.168.254.12:5678/settings/credentials
2. Crea credenziale **PostgreSQL**
3. Nome: `PostgreSQL LogWhisperer`
4. Inserisci host, port, database, user, password

### 4. Attiva il Workflow

1. Apri il workflow in n8n UI
2. Clicca **Activate** (toggle in alto a destra)
3. Verifica stato **Active**

---

## 🧪 Test Suite

```bash
# Esegui tutti i test
cd /home/google/Sources/LucaSacchiNet/LogWhispererAI
./workflows/test_workflow.sh

# Output atteso:
# ==========================================
# LogWhisperer AI - Workflow Test Suite
# Target: http://192.168.254.12:5678
# ==========================================
#
# [INFO] Test 1: Invio log con HMAC valido...
# [INFO] ✓ Test 1 PASSATO: Risposta 200 OK
#
# [INFO] Test 2: Invio log con HMAC invalido...
# [INFO] ✓ Test 2 PASSATO: Risposta 401 Unauthorized (atteso)
#
# [INFO] Test 3: Invio log con dati invalidi...
# [INFO] ✓ Test 3 PASSATO: Risposta 400 Bad Request (atteso)
#
# [INFO] Test 4: Invio log con severity=medium...
# [INFO] ✓ Test 4 PASSATO: Risposta 200 OK (no AI trigger)
#
# ==========================================
# [INFO] Tutti i test PASSATI! ✓
```

---

## 🔗 Integrazione con Script Bash

### Configurazione Script

```bash
# config.env
CLIENT_ID="550e8400-e29b-41d4-a716-446655440000"
CLIENT_SECRET="your-32-char-secret-here"
WEBHOOK_URL="http://192.168.254.12:5678/webhook/logwhisperer/ingest"
```

**⚠️ IMPORTANTE**: `CLIENT_SECRET` deve essere identico a `LOGWHISPERER_SECRET` su n8n!

### Esempio di Chiamata

```bash
# Genera payload
PAYLOAD=$(./scripts/secure_logwhisperer.sh --encode-json '{
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "server-01",
    "source": "/var/log/syslog",
    "severity": "critical",
    "raw_log": "kernel: Out of memory",
    "matched_pattern": "OOM"
}')

# Genera firma HMAC
TIMESTAMP=$(date +%s)
SIGNATURE=$(./scripts/secure_logwhisperer.sh --generate-hmac "$PAYLOAD" "$CLIENT_SECRET" "$TIMESTAMP")

# Invia a n8n
curl -X POST "$WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -H "X-LogWhisperer-Signature: ${TIMESTAMP}:${SIGNATURE}" \
    -H "X-LogWhisperer-Timestamp: ${TIMESTAMP}" \
    -d "$PAYLOAD"
```

---

## 📊 Schema Database

```sql
CREATE TABLE IF NOT EXISTS logs (
    id SERIAL PRIMARY KEY,
    client_id VARCHAR(36) NOT NULL,
    hostname VARCHAR(255),
    source VARCHAR(500),
    severity VARCHAR(20) CHECK (severity IN ('low', 'medium', 'critical')),
    timestamp TIMESTAMP WITH TIME ZONE,
    raw_log TEXT,
    matched_pattern VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_logs_client_id ON logs(client_id);
CREATE INDEX idx_logs_severity ON logs(severity);
CREATE INDEX idx_logs_timestamp ON logs(timestamp);
```

---

## ⚡ Codici Risposta

| HTTP | Significato | Causa |
|------|-------------|-------|
| 200  | Success | Log salvato correttamente |
| 400  | Bad Request | Validazione dati fallita |
| 401  | Unauthorized | HMAC invalido o timestamp troppo vecchio |
| 500  | Server Error | Errore database o nodo code |

---

## 🛡️ Metodo Sacchi Applied

✅ **Safety First**: Validazione HMAC prima di qualsiasi operazione
- Il nodo HMAC Validation è il primo filtro
- Nessun dato viene processato senza autenticazione valida

✅ **Little Often**: Un nodo per funzione
- Webhook trigger separato
- HMAC validation isolata
- Data validation dedicata
- Storage separato
- Conditional alerting

✅ **Double Check**: Verifiche multiple
- Validazione UUID formato
- Validazione severity values
- Controllo non-empty raw_log
- Verifica timestamp (anti-replay)
- Timing-safe HMAC comparison

---

## 📝 Note per Sprint 3

Il nodo **AI Processing (Placeholder)** è pronto per essere esteso:
- Riceve i dati del log quando severity = critical
- Non espone raw_log nei log (sicurezza)
- Pronto per integrazione con LLM/API AI

---

## 📚 Documentazione

- **README**: `workflows/README.md` - Guida completa workflow
- **Integrazione**: `workflows/INTEGRATION.md` - Integrazione Bash ↔ n8n
- **Test**: `workflows/test_workflow.sh` - Test suite
- **Changelog**: Aggiornato in `CHANGELOG.md`

---

**Creato da**: @n8n-specialist  
**Data**: 2026-04-02  
**Status**: ✅ Pronto per deployment