> ## 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.

# Falcon LogScale (Humio)

> Stream Forge security events to Falcon LogScale with replay and delivery monitoring.

Forge sends `security_event.v1` records to Falcon LogScale's structured ingest
API. Each event retains its Forge identifiers, category, severity, occurrence
time, and selected detail. Humio deployments use the same API.

See [Security Exports](/integrations/security-exports) for supported categories,
filters, content detail, delivery health, and replay.

## Connect LogScale

1. In LogScale, select the repository that should receive Forge events and
   create a dedicated **ingest token**. An API/query token cannot replace it.
   Use no parser unless you intentionally want to transform the structured fields.

2. Open **Integrations → SIEM and exports → Falcon LogScale** in Forge.

3. Enter your LogScale instance URL and ingest token. Use your deployment's
   regional URL, for example `https://cloud.us.humio.com`. You may also enter
   the complete `/api/v1/ingest/humio-structured` endpoint.

4. Choose event categories, minimum severity, and permitted content detail.

5. Save, send the test event, and find it in the target LogScale repository:

   ```logscale theme={"system"}
   #source=forge action="security_export.test"
   | table([@timestamp, event_id, forge_schema, category, action])
   ```

6. Activate the destination to begin continuous delivery.

The token selects the repository; Forge does not need its name or a query token.
Forge stores the token as an encrypted managed secret. TLS certificate validation
is always enabled. Changing the destination endpoint requires entering a new
token and testing again before activation.

See CrowdStrike's [structured ingest API](https://library.humio.com/logscale-api/api-ingest-structured-data.html)
and [HTTP ingest setup](https://library.humio.com/logscale-gdi/popular-ingest-methods-http-https-api-setup.html).

## Event format

The wire payload is a JSON array of batches with constant `source=forge` and
`forge_schema=security_event.v1` tags. Each event's `timestamp` is the UTC
`occurred_at` value, and its `attributes` contain the complete selected Forge
event. These become LogScale user fields; `timestamp` becomes `@timestamp`.
High-cardinality identifiers are attributes rather than tags.

```json theme={"system"}
[
  {
    "tags": { "source": "forge", "forge_schema": "security_event.v1" },
    "events": [
      {
        "timestamp": "2026-10-02T01:00:00Z",
        "attributes": {
          "forge_schema": "security_event.v1",
          "event_id": "fexp_example",
          "source_event_id": "oaud_example",
          "organization_id": "org_example",
          "occurred_at": "2026-10-02T01:00:00Z",
          "category": "org_audit",
          "action": "security_export.test",
          "outcome": "success",
          "severity": "info"
        }
      }
    ]
  }
]
```

The [versioned schema](https://github.com/a37ai/agent-sec/blob/staging/packages/contracts/event-schemas/security-event.v1.schema.json)
defines required fields and supported categories. Optional context objects may
gain fields within v1; consumers should tolerate unknown fields. Breaking envelope
changes require a new schema version. Filters and detail policy apply equally to
LogScale, Splunk, and S3.

## Delivery, buffering, and deduplication

Forge batches retained source events and records a durable cursor per destination
and category. A transient network failure, HTTP 408, HTTP 429, or HTTP 5xx leaves
the cursor unchanged and is retried on subsequent worker polls. Other rejected
HTTP responses stop delivery and require remediation. After retry exhaustion,
the destination becomes unhealthy and the failure is retained in the ledger and
dead letters. Other destinations and telemetry ingestion continue independently.

A 2xx response marks a batch delivered: it means LogScale accepted the request,
not that a search has verified indexing. The structured API has no Splunk indexer
acknowledgement handshake. Verify the synthetic event in LogScale before relying
on a new destination.

Delivery is **at least once**. Forge suppresses batches already recorded as
successful, but a lost response or crash after ingest acceptance can send the
same records again. Replay intentionally resends matching source events with the
same destination-scoped `event_id`; it does not rewind live cursors. LogScale does
not receive an exactly-once key from this API. Deduplicate downstream by
`event_id`, for example:

```logscale theme={"system"}
#source=forge
| groupBy([event_id], function=selectFromMax(field=@ingesttimestamp, include=[*]))
```

Keep `source_event_id` and `organization_id` when correlating across multiple
Forge destinations: `event_id` is scoped to a destination.

Buffering uses retained source data plus durable delivery state, not an unlimited
copy of every outbound payload. Default replay lookback is 90 days; available
source retention may be shorter. Replay cannot recover expired bodies. Use
retention longer than the expected outage and respond to blocked delivery promptly.

## Monitoring and telemetry-loss alerts

The destination page shows status, delivered and skipped counts, per-category
cursors, recent attempts, unresolved failures, and replay results. Inspect these
when delivery pauses or events appear missing.

Operators can load Forge's [Prometheus export alert rules](https://github.com/a37ai/agent-sec/blob/staging/infra/monitoring/security-export-alerts.yaml)
into the monitoring system scraping enabled telemetry-worker replicas and route
them through Alertmanager. Enable the worker's optional internal scrape listener
with `SECURITY_EXPORT_METRICS_ADDRESS` (for example `127.0.0.1:9091`) and set
`METRICS_BEARER_TOKEN`. Scrape `GET /metrics` using Bearer authentication. Keep
this listener on the private monitoring network, and scrape maintenance replicas
that run exports, rather than the control-plane API's process-local metrics.
The rules detect new dead letters, worker cycle errors,
and stopped polling. They apply to all export destinations, including LogScale.
Alert routing must be configured by the deployment; it is independent of the
failing SIEM destination. The delivery audit event `security_export.delivery_failed`
provides additional investigation context to healthy destinations that include
organization audit events. It cannot notify through a destination that is down.

After an alert: correct the endpoint or credentials, test the destination, then
resume live delivery. Recovery retains the failed batch boundaries even if new
events arrived during the outage, and resolves its delivery dead letter after
acceptance. Use replay for a bounded historical window when needed and
check any unavailable-detail counts. Skips caused by your configured filters are
intentional; dead letters indicate records or batches that require attention.

## Troubleshoot

| Symptom | Check |
| - | - |
| HTTP 401 or 403 | Dedicated ingest token, token rotation, and the correct region/instance. |
| HTTP 400 or 404 | Instance URL or structured ingest endpoint; remove query parameters and fragments. |
| HTTP 413 | Event size and content detail; narrow detail deliberately, then replay affected records. |
| HTTP 429 or 5xx | Receiver capacity and availability; Forge retries without advancing failed cursors. |
| TLS failure | Certificate chain and endpoint hostname. |
| Accepted but absent in search | Repository selected by the token, parser transforms, time range, and ingestion delay. |
| Duplicate events | Apply `event_id` deduplication to searches and downstream processing. |

## Validation without an account

The repository includes TLS receiver checks for the documented wire contract,
credential safety, status handling, replay IDs, and worker persistence. They
exercise Forge against an independent protocol receiver; they do not prove
CrowdStrike's hosted indexing or searches. A real ingest check is available when
you have a licensed LogScale instance:

```bash theme={"system"}
FORGE_LIVE_LOGSCALE=1 go test ./apps/control-plane/internal/securityexport \
  -run '^TestLiveLogScaleIngest$' -v
```

Supply `LOGSCALE_URL` and `LOGSCALE_INGEST_TOKEN` through your secret environment.
Then find the printed synthetic `event_id` in the selected repository.

### Verify against self-hosted LogScale

CrowdStrike distributes a [single-node Docker deployment for testing](https://library.humio.com/deployment/installation-containers-humio.html).
It runs the actual LogScale ingest and query engine, but still requires a valid
self-hosted trial or product license. The public community playground also
[requires a license](https://github.com/CrowdStrike/logscale-community-content/wiki/Event-Forwarding-Playground).
An open-source HTTP receiver alone cannot establish LogScale indexing or query behavior.

For an isolated local Forge development environment, start the vendor demo:

```bash theme={"system"}
docker run --rm --name forge-logscale-local \
  -p 127.0.0.1:18080:8080 --ulimit nofile=250000:250000 \
  -e AUTHENTICATION_METHOD=none -e PUBLIC_URL=http://localhost:18080 \
  -e KAFKA_SERVERS=127.0.0.1:9092 -e HUMIO_PORT=8080 \
  -v forge-logscale-local:/data humio/humio-single-node-demo:1.252.1
```

Open `http://localhost:18080`, install the license through the LogScale UI,
create an isolated repository and ingest token with no parser, then configure
Forge's LogScale destination through the UI. Use Test, activate delivery, and
replay a small retained window. Search the repository for `#source=forge`, inspect
the v1 fields, and verify that replay retains `event_id`. The same search and
field checks apply to a hosted deployment.

The loopback HTTP URL and authentication-free vendor configuration are for local
validation only. Production Forge destinations require HTTPS and a public
endpoint; use the deployment's normal authentication and TLS configuration.


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