> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cribl

> Route Forge security events through Cribl Stream using its Splunk HEC Source.

Cribl Stream receives Forge security events through its **Splunk HEC Source**, then routes them to your chosen storage or SIEM. Use a self-hosted Stream instance or a reachable Cribl.Cloud Worker Group. Forge does not require a Cribl management API key.

## Configure Cribl

1. Open **Data → Sources → Splunk HEC** in Stream. Add or enable a Source with the desired listening port (8088 by default).
2. Under **Auth Tokens**, create a dedicated token for Forge. Keep authentication enabled and scope allowed indexes if your routing uses them.
3. Enable **TLS Settings (Server Side)** with a valid server certificate. Forge verifies the certificate; use a hostname covered by the certificate.
4. Leave **Splunk HEC acks** disabled. Cribl's synthetic HEC acknowledgements do not attest to processing or downstream delivery.
5. Connect the Source to a Destination through QuickConnect or Routes. Configure any required processing and destination authentication. Consider Cribl persistent queues and monitor downstream backpressure according to your durability requirements.
6. Save and **Commit & Deploy** where required by your deployment.

Copy the **data-plane HEC URL**, for example:

```text theme={"system"}
https://cribl.example.com:8088/services/collector/event
```

The `/services/collector` endpoint is also supported, including reverse-proxy prefixes. Do not append a trailing slash. Use the worker's ingest endpoint, not the Stream management UI or REST API. Forge requires HTTPS and rejects credential-bearing query strings, URL user information, redirects, and unsafe production network targets.

## Connect Forge

Open **Settings → Integrations → Cribl**:

1. Paste the HEC endpoint URL and token.
2. Choose categories, minimum severity, and detail level in **Scope**.
3. Save, then select **Test**. Find the `security_export.test` event in Cribl **Live Data** or at the routed destination.
4. Select **Resume** to enable live exports. Check delivery health and verify that your downstream system receives the events.

The token field is masked. Forge encrypts pasted tokens as organization-scoped managed secrets and returns only a configured marker on reads. Leave a replacement token blank to retain the saved credential. Changing the endpoint requires a replacement token; saving connection changes pauses delivery and requires a fresh test before resuming.

## Event format

Forge reuses its HEC encoder: each HTTP body contains newline-separated HEC objects with `time`, `host`, `source`, `sourcetype`, `fields`, and **`event` containing the complete Forge event**. Defaults are `source=forge`, `sourcetype=forge:security_event`, and `host=forge-control-plane`. Cribl can use this metadata to route events. No index is forced by default.

Every Forge event contains `forge_schema = security_event.v1`, stable `event_id`, `organization_id`, UTC `occurred_at`, category, severity, action, outcome, and available identity, evidence, detail, and links. The schema and supported categories are shared with all [security exports](https://docs.forge.ai/integrations/security-exports.md):

* `agent_event`
* `agent_attribution`
* `identity_activity` (optional, unchecked by default)
* `governance_signal`
* `finding`
* `org_audit`
* `managed_config_audit`
* `compliance_assessment`
* `governance_workflow`

Cribl transformations and downstream mappings are customer-controlled. Check the received event before configuring parsers: Cribl may expose the JSON in `_raw`, depending on your Source and processing settings. Forge does not install a Cribl Pack, SIEM parser, or detection rules.

## Delivery, replay, and monitoring

* **Acceptance boundary:** Delivered means the Cribl HEC input returned success. It does not mean a downstream index committed the event. Monitor Cribl Source, pipeline, queue, and Destination health separately.
* **Buffering:** Forge keeps per-category cursors over retained source events and a delivery-attempt ledger. Failed delivery blocks that category's cursor; other destinations remain independent. Availability of raw body detail follows source retention.
* **Retries:** Network failures (including a 30-second HTTP timeout), HTTP 408, 429, and 5xx responses are retryable. Permanent rejections or exhausted retries make the destination unhealthy and create a dead letter. Correct the connection, Test, and Resume to recover the failed batch.
* **Replay:** Use **Replay 90d** for retained historical data. Replay has separate cursors and does not rewind live export progress. Detailed bodies may no longer be available even when their event metadata remains.
* **Deduplication:** Delivery is at least once. Retries or intentional replay can repeat an event; deduplicate by `organization_id` and `event_id` in your Cribl pipeline or downstream system. Forge suppresses already completed batches within its delivery-state retention window.
* **Monitoring:** The Forge UI exposes delivered/skipped counts, stream coverage, replay jobs, recent attempts, and unresolved dead letters. Existing export metrics and telemetry-loss alert rules include Cribl. Configure alert routing for your deployment.

## Self-hosted verification without a cloud account

Use Cribl's [official Docker image](https://hub.docker.com/r/cribl/cribl) and [deployment instructions](https://docs.cribl.io/stream/deploy-docker/). A local Stream instance provides the actual receiver, processing engine, Live Data view, and destinations; no cloud account is needed. Complete the local registration/license flow required by your version.

For reproducible transport checks, use a dedicated HEC Source with TLS and a task-local token, route it to a filesystem destination, and verify received `event_id` values after each operation:

1. Test the destination in Forge and inspect the test record in Cribl.
2. Resume live delivery and compare Forge's ledger with received records.
3. Disable the Source token. Confirm Forge becomes unhealthy without advancing the failed category cursor.
4. Re-enable/rotate the token, save the replacement in Forge, Test, and Resume. Confirm the failed batch recovers and its event IDs are unchanged.
5. Run replay and verify repeated IDs rather than assuming exactly-once delivery. A successful new replay resolves an earlier delivery-failure dead letter when the delivered category, batch event bounds, and event count match the failed batch. A replay with different batch bounds leaves that failure visible for investigation.

A local Cribl run proves that version's ingestion and configured routing behavior. It does not qualify every Cribl.Cloud topology, downstream SIEM, production load, or production alert route.

## References

* [Cribl Splunk HEC Source and acknowledgement semantics](https://docs.cribl.io/stream/sources-splunk-hec/)
* [Cribl persistent queues](https://docs.cribl.io/stream/persistent-queues/)
* [OpenTelemetry's HEC exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/splunkhecexporter): shared HEC envelope, auth headers, batching, and retries.
* [Cribl's official Helm charts](https://github.com/criblio/helm-charts/tree/master/helm-chart-sources/logstream-workergroup): real Worker Group deployment and HEC listener ports.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.