ids.alfacom.it/deployment/CLEANUP_DETECTIONS_GUIDE.md

IDS - Guida Cleanup Detections Automatico

📋 Overview

Sistema automatico di pulizia delle detections e gestione IP bloccati secondo regole temporali:

1. Cleanup Detections: Elimina detections non bloccate più vecchie di 48 ore
2. Auto-Unblock: Sblocca IP bloccati da più di 2 ore senza nuove anomalie

⚙️ Componenti

1. Script Python: python_ml/cleanup_detections.py

Script principale che esegue le operazioni di cleanup:

• Elimina detections vecchie dal database
• Marca come "sbloccati" gli IP nel DB (NON rimuove da MikroTik firewall!)
• Logging completo in /var/log/ids/cleanup.log

2. Wrapper Bash: deployment/run_cleanup.sh

Wrapper che carica le variabili d'ambiente e esegue lo script Python.

3. Systemd Service: ids-cleanup.service

Service oneshot che esegue il cleanup una volta.

4. Systemd Timer: ids-cleanup.timer

Timer che esegue il cleanup ogni ora alle XX:10 (es. 10:10, 11:10, 12:10...).

🚀 Installazione

Prerequisiti

Assicurati di avere le dipendenze Python installate:

# Installa dipendenze (se non già fatto)
sudo pip3 install psycopg2-binary python-dotenv

# Oppure usa requirements.txt
sudo pip3 install -r python_ml/requirements.txt

Setup Automatico

cd /opt/ids

# Esegui setup automatico (installa dipendenze + configura timer)
sudo ./deployment/setup_cleanup_timer.sh

# Output:
# [1/7] Installazione dipendenze Python...
# [2/7] Creazione directory log...
# ...
# ✅ Cleanup timer installato e avviato con successo!

Nota: Lo script installa automaticamente le dipendenze Python necessarie.

📊 Monitoraggio

Stato Timer

# Verifica che il timer sia attivo
sudo systemctl status ids-cleanup.timer

# Prossima esecuzione programmata
systemctl list-timers ids-cleanup.timer

Log

# Real-time log
tail -f /var/log/ids/cleanup.log

# Ultime 50 righe
tail -50 /var/log/ids/cleanup.log

# Log completo
cat /var/log/ids/cleanup.log

🔧 Uso Manuale

Esecuzione Immediata

# Via systemd (consigliato)
sudo systemctl start ids-cleanup.service

# Oppure direttamente
sudo ./deployment/run_cleanup.sh

Test con Output Verbose

cd /opt/ids
source .env
python3 python_ml/cleanup_detections.py

📝 Regole di Cleanup

Regola 1: Cleanup Detections (48 ore)

Query SQL:

DELETE FROM detections 
WHERE detected_at < NOW() - INTERVAL '48 hours'
  AND blocked = false

Logica:

• Se un IP è stato rilevato ma non bloccato
• E non ci sono nuove detections da 48 ore
• → Eliminalo dal database

Esempio:

• IP 1.2.3.4 rilevato il 23/11 alle 10:00
• Non bloccato (risk_score < 80)
• Nessuna nuova detection per 48 ore
• → 25/11 alle 10:10 → IP eliminato ✅

Regola 2: Auto-Unblock (2 ore)

Query SQL:

UPDATE detections
SET blocked = false, blocked_at = NULL
WHERE blocked = true
  AND blocked_at < NOW() - INTERVAL '2 hours'
  AND NOT EXISTS (
      SELECT 1 FROM detections d2
      WHERE d2.source_ip = detections.source_ip
        AND d2.detected_at > NOW() - INTERVAL '2 hours'
  )

Logica:

• Se un IP è bloccato
• E bloccato da più di 2 ore
• E nessuna nuova detection nelle ultime 2 ore
• → Sbloccalo nel DB

⚠️ ATTENZIONE: Questo sblocca solo nel database, NON rimuove l'IP dalle firewall list MikroTik!

Esempio:

• IP 5.6.7.8 bloccato il 25/11 alle 08:00
• Nessuna nuova detection per 2 ore
• → 25/11 alle 10:10 → blocked=false nel DB ✅
• → ANCORA nella firewall MikroTik ❌

Come rimuovere da MikroTik

# Via API ML Backend
curl -X POST http://localhost:8000/unblock-ip \
  -H "Content-Type: application/json" \
  -d '{"ip_address": "5.6.7.8"}'

🛠️ Configurazione

Modifica Intervalli

Cambia soglia cleanup (es. 72 ore invece di 48)

Modifica python_ml/cleanup_detections.py:

# Linea ~47
deleted_count = cleanup_old_detections(conn, hours=72)  # ← Cambia qui

Cambia soglia unblock (es. 4 ore invece di 2)

Modifica python_ml/cleanup_detections.py:

# Linea ~51
unblocked_count = unblock_old_ips(conn, hours=4)  # ← Cambia qui

Modifica Frequenza Esecuzione

Modifica deployment/systemd/ids-cleanup.timer:

[Timer]
# Ogni 6 ore invece di ogni ora
OnCalendar=00/6:10:00

Dopo le modifiche:

sudo systemctl daemon-reload
sudo systemctl restart ids-cleanup.timer

📊 Output Esempio

============================================================
CLEANUP DETECTIONS - Avvio
============================================================
✅ Connesso al database

[1/2] Cleanup detections vecchie...
Trovate 45 detections da eliminare (più vecchie di 48h)
✅ Eliminate 45 detections vecchie

[2/2] Sblocco IP vecchi...
Trovati 3 IP da sbloccare (bloccati da più di 2h)
  - 1.2.3.4 (tipo: ddos, score: 85.2)
  - 5.6.7.8 (tipo: port_scan, score: 82.1)
  - 9.10.11.12 (tipo: brute_force, score: 90.5)
✅ Sbloccati 3 IP nel database
⚠️  ATTENZIONE: IP ancora presenti nelle firewall list MikroTik!
💡 Per rimuoverli dai router, usa: curl -X POST http://localhost:8000/unblock-ip -d '{"ip_address": "X.X.X.X"}'

============================================================
CLEANUP COMPLETATO
  - Detections eliminate: 45
  - IP sbloccati (DB): 3
============================================================

🔍 Troubleshooting

Timer non parte

# Verifica che il timer sia enabled
sudo systemctl is-enabled ids-cleanup.timer

# Se disabled, abilita
sudo systemctl enable ids-cleanup.timer
sudo systemctl start ids-cleanup.timer

Errori nel log

# Controlla errori
grep ERROR /var/log/ids/cleanup.log

# Controlla connessione DB
grep "Connesso al database" /var/log/ids/cleanup.log

Test connessione DB

cd /opt/ids
source .env
python3 -c "
import psycopg2
conn = psycopg2.connect(
    host='$PGHOST',
    port=$PGPORT,
    user='$PGUSER',
    password='$PGPASSWORD',
    database='$PGDATABASE'
)
print('✅ DB connesso!')
conn.close()
"

📈 Metriche

Query per statistiche

-- Detections per età
SELECT 
    CASE 
        WHEN detected_at > NOW() - INTERVAL '2 hours' THEN '< 2h'
        WHEN detected_at > NOW() - INTERVAL '24 hours' THEN '< 24h'
        WHEN detected_at > NOW() - INTERVAL '48 hours' THEN '< 48h'
        ELSE '> 48h'
    END as age_group,
    COUNT(*) as count,
    COUNT(CASE WHEN blocked THEN 1 END) as blocked_count
FROM detections
GROUP BY age_group
ORDER BY age_group;

-- IP bloccati per durata
SELECT 
    source_ip,
    blocked_at,
    EXTRACT(EPOCH FROM (NOW() - blocked_at)) / 3600 as hours_blocked,
    anomaly_type,
    risk_score::numeric
FROM detections
WHERE blocked = true
ORDER BY blocked_at DESC;

⚙️ Integrazione con Altri Sistemi

Notifiche Email (opzionale)

Aggiungi a python_ml/cleanup_detections.py:

import smtplib
from email.mime.text import MIMEText

if unblocked_count > 0:
    msg = MIMEText(f"Sbloccati {unblocked_count} IP")
    msg['Subject'] = 'IDS Cleanup Report'
    msg['From'] = 'ids@example.com'
    msg['To'] = 'admin@example.com'
    
    s = smtplib.SMTP('localhost')
    s.send_message(msg)
    s.quit()

Webhook (opzionale)

import requests

requests.post('https://hooks.slack.com/...', json={
    'text': f'IDS Cleanup: {deleted_count} detections eliminate, {unblocked_count} IP sbloccati'
})

🔒 Sicurezza

• Script eseguito come root (necessario per systemd)
• Credenziali DB caricate da .env (NON hardcoded)
• Log in /var/log/ids/ con permessi 644
• Service con NoNewPrivileges=true e PrivateTmp=true

📅 Scheduler

Il timer è configurato per eseguire:

• Frequenza: Ogni ora
• Minuto: XX:10 (10 minuti dopo l'ora)
• Randomizzazione: ±5 minuti per load balancing
• Persistent: Recupera esecuzioni perse durante downtime

Esempio orari: 00:10, 01:10, 02:10, ..., 23:10

✅ Checklist Post-Installazione

• Timer installato: systemctl status ids-cleanup.timer
• Prossima esecuzione visibile: systemctl list-timers
• Test manuale OK: sudo ./deployment/run_cleanup.sh
• Log creato: ls -la /var/log/ids/cleanup.log
• Nessun errore nel log: grep ERROR /var/log/ids/cleanup.log
• Cleanup funzionante: verificare conteggio detections prima/dopo

🆘 Supporto

Per problemi o domande:

1. Controlla log: tail -f /var/log/ids/cleanup.log
2. Verifica timer: systemctl status ids-cleanup.timer
3. Test manuale: sudo ./deployment/run_cleanup.sh
4. Apri issue su GitHub o contatta il team