Event-Driven Automation

Automatically respond to events like low disk space or service failures using Beacon and Reactor.

Overview

Nefia's event-driven automation consists of two components:

Beacon — Monitors system state on the agent side and emits events
Reactor — Receives events on the operator side and executes actions based on rules

plaintext

[Agent]                    [Operator]
Beacon (disk/service/script)
  │ Event (TCP:9500)
  └──────────────────────► Reactor
                              ├─ Rule match → exec (command execution)
                              ├─ Rule match → playbook (auto-remediation)
                              └─ Rule match → alert (notification)

Beacon (Agent Side)

Beacon periodically monitors system state on the agent and emits events when thresholds are exceeded.

Built-in Beacons

Disk Usage (disk.usage)

Monitors disk usage percentage for specified mount points.

yaml

beacons:
  disk_usage:
    enabled: true
    interval: "5m"
    warning_percent: 80
    critical_percent: 90
    paths:
      - "/"
      - "/home"

Event data:

Field	Description
`path`	Checked path
`used_percent`	Usage percentage (%, string type e.g. "92.5")
`total_bytes`	Total capacity
`free_bytes`	Free space

Service Status (service.status)

Detects state changes of systemd services (Linux only).

yaml

beacons:
  service_check:
    enabled: true
    interval: "30s"
    services:
      - nginx
      - postgresql
      - docker

Uses systemctl is-active to retrieve service state and emits events only on state transitions (no event is emitted on the initial check).

Event data:

Field	Description
`service`	Service name
`state`	Current state
`previous_state`	Previous state

Custom Script (script.result)

Periodically executes arbitrary shell scripts and emits events based on exit codes.

yaml

beacons:
  scripts:
    - name: "check-ssl-expiry"
      command: "/opt/scripts/check-ssl.sh"
      interval: "1h"
    - name: "check-backup"
      command: "/opt/scripts/check-backup.sh"
      interval: "6h"

Exit Code	Severity	Behavior
0	—	Normal (no event emitted)
1	`warning`	Warning event
2 or higher	`critical`	Critical event

Output (stdout + stderr) is recorded up to a maximum of 4KB.

Event Format

json

{
  "type": "disk.usage",
  "source": "disk-beacon",
  "host_id": "web-01",
  "timestamp": "2026-03-10T15:30:00Z",
  "severity": "critical",
  "data": {
    "path": "/",
    "used_percent": "92.5",
    "total_bytes": 107374182400,
    "free_bytes": 8053063680
  }
}

Event Control

Setting	Default	Description
`MaxEventsPerMin`	10	Maximum events per minute (rate limit)
`DedupWindow`	5 minutes	Deduplication window for identical events

Deduplication key: Type|Source|HostID|Severity

Transport

Events are sent via TCP (JSONL) to port 9500 on the operator's VPN address. On connection failure, reconnection is attempted with exponential backoff (1 second to 5 minutes).

Reactor (Operator Side)

Reactor receives events from Beacons on the operator side and executes automated actions based on rules.

Rule Configuration

yaml

reactor:
  enabled: true
  listen_port: 9500
 
  rules:
    - name: "critical-disk-alert"
      event_pattern: "disk\\..*"
      host_pattern: "prod-.*"
      severity: "critical"
      action:
        type: alert
        webhook_name: "slack"
 
    - name: "service-recovery"
      event_pattern: "service\\.status"
      severity: "warning"
      action:
        type: playbook
        playbook_path: "/opt/playbooks/restart-service.yaml"
 
    - name: "custom-script-alert"
      event_pattern: "script\\..*"
      severity: "critical"
      action:
        type: exec
        command: "echo 'Script failure detected' | mail -s 'Alert' ops@example.com"

Rule Fields

Field	Description
`name`	Rule name (must be unique)
`event_pattern`	Regex pattern for event type
`host_pattern`	Regex pattern for host ID (empty = all hosts)
`severity`	Minimum severity filter (empty = all severities)
`action`	Action to execute

Action Types

Type	Description	Configuration Field
`exec`	Remote command execution	`command`
`playbook`	Playbook execution	`playbook_path`
`alert`	Webhook notification	`webhook_name`

Severity Matching

Rule severity	Events matched
(empty)	info, warning, critical
`info`	info, warning, critical
`warning`	warning, critical
`critical`	critical only

Status Check

bash

nefia reactor status

Displays configured rules, hit counts, and recent events.

Example output:

plaintext

Rules:
  NAME                  EVENT PATTERN    HOST PATTERN   ACTION    HITS
  critical-disk-alert   disk\..*         prod-.*        alert     12
  service-recovery      service\.status  (all)          playbook  3
 
Recent Events:
  TIME                TYPE             HOST     SEVERITY  RULE                 ACTION    ERROR
  2026-03-10 15:30    disk.usage       web-01   critical  critical-disk-alert  alert     -
  2026-03-10 15:25    service.status   db-01    warning   service-recovery     playbook  -

Security

The listener only accepts connections from known VPN peer IPs
The maximum number of concurrent connections is limited to 64
Since communication occurs within the VPN tunnel, no additional encryption is required

HMAC-SHA256 Message Authentication

Beacon event transport supports optional HMAC-SHA256 message authentication. When a shared key is configured, each event is signed before transmission and verified on receipt using constant-time comparison to prevent timing attacks.

Wire format with HMAC enabled:

plaintext

<JSON payload>\n
<HMAC-SHA256 hex signature>\n

Each message consists of the JSON-encoded event on one line, followed by the hex-encoded HMAC-SHA256 signature on the next line. Events with missing or invalid signatures are rejected and the connection is closed.

To enable HMAC authentication, configure the same shared key on both the agent (beacon) and operator (reactor) sides. This provides an additional layer of integrity verification beyond the VPN tunnel, which is useful in defense-in-depth security models.

Managing Reactor Rules via MCP

AI agents can create and manage reactor rules programmatically:

Tool	Description
`nefia.reactor.status`	List configured reactor rules with hit counts.
`nefia.reactor.events`	View recent reactor events and matched rules.
`nefia.reactor.rule.create`	Create a new reactor rule with event pattern, action, and conditions.
`nefia.reactor.rule.delete`	Delete a reactor rule by ID.
`nefia.reactor.rule.enable`	Enable or disable a reactor rule.

Managing Webhooks via MCP

Webhooks can also be managed programmatically:

Tool	Description
`nefia.webhook.list`	List configured webhook endpoints.
`nefia.webhook.test`	Send a test event to a webhook endpoint.
`nefia.webhook.create`	Create a new webhook endpoint with URL, events, and optional HMAC secret.
`nefia.webhook.update`	Update an existing webhook's configuration.
`nefia.webhook.delete`	Delete a webhook endpoint.