Monitora le attività sul filesystem, consulta i log eventi e attiva workflow su WriteFinished con ingest sicuro.

Directory Monitor

Il Directory Monitor di Donutwork è un modulo nativo di sicurezza + automazione che traccia le attività sui file nelle cartelle osservate e trasforma questi eventi in azioni automatiche.

È pensato per team che hanno bisogno di:

Raccolta affidabile degli eventi filesystem
Visibilità centralizzata degli eventi
Trigger deterministici dei workflow

Architettura del Sistema

Il modulo è composto da quattro livelli connessi:

Agente Locale (Rust): osserva le directory ed emette eventi normalizzati (Create, Delete, WriteFinished).
API di Ingress Sicura: riceve i payload del monitor, valida l'autenticazione e deduplica tramite eventId.
Event Store: persiste gli eventi con indici per ricerca operativa e forense.
Workflow Dispatcher: pubblica trigger sia generici sia tipizzati per eseguire i workflow compatibili.

Compatibilità Retroattiva

I trigger generici restano supportati: DirectoryMonitor.{projectId}.notify. Puoi adottare gradualmente i trigger tipizzati come DirectoryMonitor.{projectId}.WriteFinished.notify.

Pipeline Eventi

Quando un file cambia, accade quanto segue:

Il monitor invia un payload con metadati evento (filename, event, filesize, opzionali sha256, uid, pid, timestampUtc, eventId).
L'ingress valida:
- API key (Authorization: Bearer ...)
- Token di progetto (X-Directory-Monitor-Token)
L'evento viene salvato nella collection eventi del monitor.
Vengono pubblicate due notifiche:
- Generica: DirectoryMonitor.{projectId}.notify
- Tipizzata: DirectoryMonitor.{projectId}.{event}.notify
I workflow corrispondenti vengono messi in coda ed eseguiti tramite la pipeline async esistente.

Log e Osservabilità

Il Directory Monitor include una vista Log dedicata per progetto con:

Filtri per:
- Tipo evento
- Path contiene
- Stato
- Intervallo date
Lista paginata con:
- Timestamp
- Tipo evento
- Percorso file
- Dimensione file
- Badge stato workflow (queued, workflow_triggered, workflow_failed)
Link diretti alle trace dei workflow correlati.

Retention

Gli eventi sono salvati con indice TTL (default 90 giorni).

Modello di Trigger Workflow

Per automazioni ad alta precisione, usa i trigger tipizzati:

Trigger	Scopo	Esempio
`DirectoryMonitor.{projectId}.WriteFinished.notify`	Esegue solo dopo la stabilizzazione della scrittura	Avvio scansione malware a upload completato
`DirectoryMonitor.{projectId}.Create.notify`	Reagisce alla creazione di oggetti	Tag/classificazione automatica di nuovi file
`DirectoryMonitor.{projectId}.Delete.notify`	Rileva cancellazioni	Alert su rimozioni inattese
`DirectoryMonitor.{projectId}.notify`	Trigger generico legacy	Compatibilità con workflow esistenti

Controlli di Sicurezza

L'ingress del monitor è protetto da controlli a più livelli:

Autenticazione API key aziendale
Validazione token segreto a livello progetto
Validazione payload sui campi obbligatori
Deduplica idempotente tramite eventId univoco

Questo approccio garantisce isolamento tra progetti mantenendo il comportamento attuale del gateway API.

Pattern di Automazione Reali

Controlli di Compliance File

Su WriteFinished esegui workflow di validazione (policy hash, naming convention, controlli estensione).

Risposta di Sicurezza

Attiva scansione, quarantena e alert quando compaiono file sospetti nelle cartelle monitorate.

Automazione Business

Lancia pipeline di ingestione, enrichment e webhook automatici a partire da eventi filesystem.

Panoramica Funzionalità

Monitoraggio Ricorsivo

Osserva interi alberi directory e cattura comportamenti di create, modify e delete.

Gestione Stabilità Scrittura

`WriteFinished` viene emesso dopo la finestra di stabilizzazione per evitare file parziali.

Heartbeat e Startup

I monitor inviano segnali di avvio e attività, utili per visibilità operativa per progetto.

Metadata Evento Ricchi

Allega `sha256`, `uid` e `pid` (quando disponibili) per audit e investigazioni più solide.

Workflow Event-Driven

Collega direttamente gli eventi filesystem al motore workflow già presente in Donutwork.

Directory Monitor & Automazione Eventi