Spyderbat Event Forwarder

The Spyderbat Event Forwarder polls the SIEM forwarding API and delivers events to your SIEM, log management platform, or any HTTP endpoint.

The Event Forwarder only receives events when SIEM forwarding is enabled on at least one saved query. See SIEM Forwarding for setup instructions.

The Event Forwarder is an open-source binary (github.com/spyderbat/event-forwarder) that polls the Spyderbat API for events flagged by your saved queries and delivers them to a destination you configure. It supports file output, stdout, local syslog, and HTTP webhooks.

For installation guides, see Install the Spyderbat Event Forwarder.

The Event Forwarder does not filter events. To control which events are forwarded, enable SIEM forwarding on specific saved queries.

How the Spyderbat Event Forwarder works

The Event Forwarder runs as a long-lived process that polls GET /api/v1/org/{orgUID}/events/{iterator} in a loop. The iterator is an opaque cursor that marks the forwarder's position in the event stream.

Polling behavior

When the forwarder fetches a full batch of 10,000 records, it knows more data is available and polls again after 1 second. When it receives fewer than 10,000 records, it's caught up and waits 30 seconds before the next poll. On API errors, it backs off to 30 seconds and counts consecutive failures — after five consecutive failures it logs an error but keeps running.

On first run, the forwarder starts from the oldest available buffered event. If your org has a large backlog of matching events, expect an initial burst of high-volume polling before the forwarder catches up to real time. To skip the backlog, you can reset the position using a direct API call with LATEST as the cursor — see Accessing the API directly.

Forwarded events do not include metadata identifying which saved query matched them. If multiple queries in your org have SIEM forwarding enabled, their events are interleaved in the forwarder output. Use the schema field in each event to distinguish event types.

Iterator persistence

After each successful poll, the forwarder writes the next iterator to disk using a crash-safe write, which prevents corruption if the process is interrupted. On restart, it reads the saved iterator and resumes exactly where it left off. There is no data loss between restarts and no need to reconfigure a time window.

Runtime details enrichment

Every five minutes, the forwarder fetches source metadata from the Spyderbat API and caches it in memory. When writing each event, it injects a runtime_details object:

{
  "runtime_details": {
    "hostname": "prod-web-01",
    "ip_addresses": ["10.0.1.5", "172.16.0.3"],
    "mac_addresses": ["aa:bb:cc:dd:ee:ff"],
    "cloud_instance_id": "i-0abc123def456",
    "forwarder": "spyderbat-event-forwarder/v2.0"
  }
}

This enrichment lets your SIEM correlate Spyderbat events with host inventory without a separate lookup.

Output

The forwarder writes events as newline-delimited JSON (ndjson) to whichever output you configure:

Output	When to use
File	Default. Writes to {log_path}/spyderbat_events.log, auto-rotated at 10 MB. Use with Splunk Universal Forwarder or Filebeat.
Stdout	Container environments. Use stdout: true. Logs appear in kubectl logs or Docker log drivers.
Local syslog	Forward to /dev/log. Not recommended for remote or unencrypted syslog.
Webhook	Push directly to any HTTP endpoint (Panther, Splunk HEC, Elastic, custom). Supports gzip and zstd compression and four authentication methods.

Failed webhook deliveries are retried automatically with exponential backoff.

Event Forwarder validation

To confirm the forwarder is running and receiving events, check the logs for status messages. The forwarder logs as JSON — look for lines where the "message" field reports new record counts:

{"schema":"event_forwarder:meta:1.0.0","message":"5 new records (0 invalid, 5 logged)",...}

If using file output, you can also tail the output file directly for human-readable ndjson events:

tail -f /opt/spyderbat-events/var/log/spyderbat_events.log

If the forwarder runs but reports zero records after several minutes, verify that at least one saved query has SIEM forwarding enabled. See SIEM Forwarding.

For install-specific verification steps, see the Helm Chart or Traditional Installer guides.

Related pages

• SIEM Forwarding — full architecture and control plane setup

• SIEM Forwarding Quickstart — end-to-end setup guide

• Install: Helm Chart

• Install: Traditional Installer