# Spyderbat Event Forwarder {% hint style="info" %} The Event Forwarder only receives events when SIEM forwarding is enabled on at least one saved query. See [SIEM Forwarding](/concepts/integrations/siem-forwarding.md) for setup instructions. {% endhint %} The Event Forwarder is an open-source binary ([github.com/spyderbat/event-forwarder](https://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](/installation/spyderbat-event-forwarder.md). 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](/concepts/integrations/siem-forwarding.md#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: ```json { "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: ```bash 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](/concepts/integrations/siem-forwarding.md). For install-specific verification steps, see the [Helm Chart](/installation/spyderbat-event-forwarder/helm-chart.md) or [Traditional Installer](/installation/spyderbat-event-forwarder/traditional-installer.md) guides. ## Related pages * [SIEM Forwarding](/concepts/integrations/siem-forwarding.md) — full architecture and control plane setup * [SIEM Forwarding Quickstart](/tutorials/integrations/siem-forwarding-quickstart.md) — end-to-end setup guide * [Install: Helm Chart](/installation/spyderbat-event-forwarder/helm-chart.md) * [Install: Traditional Installer](/installation/spyderbat-event-forwarder/traditional-installer.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.spyderbat.com/concepts/integrations/spyderbat-event-forwarder.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.