Directory Monitor & Event Automation
Monitor filesystem activity, inspect event logs, and trigger workflows on WriteFinished with secure ingest.
Directory Monitor
The Donutwork Directory Monitor is a native security + automation module that tracks file activity in watched paths and converts those events into actionable automations.
It is designed for teams that need:
- Reliable filesystem event capture
- Centralized event visibility
- Deterministic workflow triggering
System Architecture
The module is built on four connected layers:
- Local Agent (Rust): Watches directories and emits normalized events (
Create,Delete,WriteFinished). - Secure Ingress API: Accepts monitor payloads, validates auth, and deduplicates by
eventId. - Event Store: Persists monitor events with indexed search for operational and forensic review.
- Workflow Dispatcher: Publishes both generic and typed triggers to run matching workflows.
Backward Compatibility
Existing generic triggers remain supported: DirectoryMonitor.{projectId}.notify.
You can progressively adopt typed triggers such as DirectoryMonitor.{projectId}.WriteFinished.notify.
Event Pipeline
When a file changes, the following happens:
- The monitor emits a payload with event metadata (
filename,event,filesize, optionalsha256,uid,pid,timestampUtc,eventId). - Ingress validates:
- API key (
Authorization: Bearer ...) - Project token (
X-Directory-Monitor-Token)
- API key (
- Event is saved in the monitor event collection.
- Two notifications are dispatched:
- Generic:
DirectoryMonitor.{projectId}.notify - Typed:
DirectoryMonitor.{projectId}.{event}.notify
- Generic:
- Matching workflows are queued and executed through the existing workflow async pipeline.
Logs & Observability
Directory Monitor includes a dedicated Logs View per project with:
- Event filtering by:
- Event type
- Path contains
- Status
- Date range
- Paginated event list with:
- Timestamp
- Event type
- File path
- File size
- Workflow status badges (
queued,workflow_triggered,workflow_failed)
- Direct links to related workflow traces.
Retention
Events are stored with TTL indexing (default 90 days).
Workflow Triggering Model
For high-precision automation, prefer typed triggers:
| Trigger | Purpose | Example |
|---|---|---|
DirectoryMonitor.{projectId}.WriteFinished.notify | Run only after file write stabilization | Launch malware scan after upload completion |
DirectoryMonitor.{projectId}.Create.notify | React on object creation | Tag and classify newly dropped files |
DirectoryMonitor.{projectId}.Delete.notify | Detect deletions | Alert on unexpected file removal |
DirectoryMonitor.{projectId}.notify | Legacy generic trigger | Backward compatible workflows |
Security Controls
The monitor ingress path is protected with layered controls:
- Company API key authentication
- Project-level secret token validation
- Payload validation for required fields
- Idempotent dedupe through unique
eventId
This model allows multi-project isolation while preserving your current API gateway behavior.
Real World Automation Patterns
File Compliance Checks
On WriteFinished, run validation workflows (hash policy, naming convention, extension checks).
Security Response
Trigger scan, quarantine, and alert actions when suspicious files appear in watched paths.
Business Automation
Automatically launch ingestion pipelines, enrichment jobs, and webhook notifications from file events.
Feature Snapshot
Recursive Monitoring
Observe complete directory trees and capture create, modify, and delete behavior.
Write Stability Handling
`WriteFinished` is emitted after stabilization windows to avoid partial-file processing.
Heartbeat & Startup Signals
Monitors report startup and active status, enabling operational visibility per project.
Rich Event Metadata
Attach `sha256`, `uid`, and `pid` (when available) for stronger audit and investigation context.
Event-Driven Workflows
Bridge file system events directly into the existing Donutwork workflow engine.