From fc275fc5a1c192971e3dde1ea03774bb66859ac2 Mon Sep 17 00:00:00 2001 From: Shourie Ganguly Date: Thu, 11 Jun 2026 20:46:27 +0530 Subject: [PATCH] akamai: add OpenTelemetry collection mode via the akamai_siem receiver Add a siem_otel data stream exposing the native OTel akamai_siem receiver as a third input alongside CEL and GCS (Technical Preview). Requires stack 9.5.0: the receiver ships in 9.5 agents and Kibana supports otelcol inputs in integration packages from 9.4. The spec format_version moves to 3.6.0, which otelcol requires; the SVR00006/SVR00009 checks it activates are excluded because the existing pipeline predates them. The otelcol stream gets its own data stream because Fleet installs a .otel-suffixed index template pattern for any data stream containing an otelcol stream, which would orphan logs-akamai.siem-* for existing CEL/GCS users. Events are still routed to the akamai.siem dataset via the reserved data_stream.dataset variable and the receiver's bodymap-mode documents, reusing the existing ingest pipeline. dynamic_dataset/dynamic_namespace widen the agent API key because Fleet scopes otelcol stream permissions to a .otel-suffixed dataset that bodymap writes never target. String variables are quoted in the template so all-digit values are not decoded as YAML integers. A disabled-by-default enable_storage variable drafts a file_storage extension for cursor persistence; the receiver carries no storage reference since Fleet renames stream-declared extensions without rewriting such references. Co-Authored-By: Claude Fable 5 --- packages/akamai/_dev/build/docs/README.md | 13 +++ packages/akamai/changelog.yml | 6 + .../siem_otel/agent/stream/otelcol.yml.hbs | 28 +++++ .../siem_otel/fields/base-fields.yml | 12 ++ .../akamai/data_stream/siem_otel/manifest.yml | 107 ++++++++++++++++++ packages/akamai/docs/README.md | 13 +++ packages/akamai/manifest.yml | 11 +- packages/akamai/validation.yml | 2 + 8 files changed, 188 insertions(+), 4 deletions(-) create mode 100644 packages/akamai/data_stream/siem_otel/agent/stream/otelcol.yml.hbs create mode 100644 packages/akamai/data_stream/siem_otel/fields/base-fields.yml create mode 100644 packages/akamai/data_stream/siem_otel/manifest.yml diff --git a/packages/akamai/_dev/build/docs/README.md b/packages/akamai/_dev/build/docs/README.md index 93189b2635f..1997f52d100 100644 --- a/packages/akamai/_dev/build/docs/README.md +++ b/packages/akamai/_dev/build/docs/README.md @@ -22,6 +22,19 @@ See [Akamai API get started](https://techdocs.akamai.com/siem-integration/refere - The GCS input currently only accepts a service account JSON key or a service account JSON file for authentication. - The GCS input currently only supports JSON data. +### To collect data via the OpenTelemetry receiver (Technical Preview), follow the below steps: + +This collection mode uses the native OpenTelemetry `akamai_siem` receiver embedded in the Elastic Agent's EDOT collector instead of the CEL input. It polls the same [Akamai SIEM API](https://techdocs.akamai.com/siem-integration/reference/api) using the same EdgeGrid credentials. + +- Requires Elastic Stack (Kibana, Elastic Agent) version 9.5.0 or later. +- Configure the API Host, Security Configuration IDs and the EdgeGrid credentials (Client Token, Client Secret, Access Token) under the "Collect Akamai SIEM logs via OpenTelemetry receiver" section. +- Events are routed to the `akamai.siem` dataset, processed by the same ingest pipeline as the CEL input, and stored in `logs-akamai.siem-`. +- If the integration policy uses a namespace other than `default`, set the "Data Stream Namespace" option to the same value so that the `data_stream.namespace` field written into each event matches the target data stream. + +**Note**: +- The receiver supports persisting its poll cursor through an OpenTelemetry storage extension (equivalent to the CEL input's registry-based cursor), but Fleet cannot yet wire storage extensions into receiver configurations, so cursor persistence is not available in Fleet-managed deployments. After an agent restart the receiver re-fetches the configured Initial Lookback window; replayed events are deduplicated by the ingest pipeline's `event.original` fingerprint within the same backing index. +- Unlike the CEL input, events collected via the OTel receiver are not tagged with `akamai-siem`/`forwarded` tags. + {{fields "siem"}} {{event "siem"}} \ No newline at end of file diff --git a/packages/akamai/changelog.yml b/packages/akamai/changelog.yml index 12db09d2dcb..a811a989c90 100644 --- a/packages/akamai/changelog.yml +++ b/packages/akamai/changelog.yml @@ -1,4 +1,10 @@ # newer versions go on top +- version: "3.2.0" + changes: + - description: | + Add OpenTelemetry collection mode (Technical Preview) using the native akamai_siem receiver. Requires Elastic Stack 9.5.0 or later. + type: enhancement + link: https://github.com/elastic/integrations/pull/99999 - version: "3.1.1" changes: - description: Fix the issue of populating HTTP message headers. diff --git a/packages/akamai/data_stream/siem_otel/agent/stream/otelcol.yml.hbs b/packages/akamai/data_stream/siem_otel/agent/stream/otelcol.yml.hbs new file mode 100644 index 00000000000..7ed9c7db132 --- /dev/null +++ b/packages/akamai/data_stream/siem_otel/agent/stream/otelcol.yml.hbs @@ -0,0 +1,28 @@ +receivers: + akamai_siem: + endpoint: "{{endpoint}}" + config_ids: "{{config_ids}}" + authentication: + client_token: "{{client_token}}" + client_secret: "{{client_secret}}" + access_token: "{{access_token}}" + poll_interval: "{{poll_interval}}" + initial_lookback: "{{initial_lookback}}" + event_limit: {{event_limit}} + data_stream: + type: logs + dataset: akamai.siem + namespace: "{{namespace}}" +{{#if enable_storage}} +extensions: + file_storage: + directory: "${env:STATE_PATH:-/usr/share/elastic-agent/state}" + create_directory: true +{{/if}} +service: +{{#if enable_storage}} + extensions: [file_storage] +{{/if}} + pipelines: + logs: + receivers: [akamai_siem] diff --git a/packages/akamai/data_stream/siem_otel/fields/base-fields.yml b/packages/akamai/data_stream/siem_otel/fields/base-fields.yml new file mode 100644 index 00000000000..84b5bb1ec75 --- /dev/null +++ b/packages/akamai/data_stream/siem_otel/fields/base-fields.yml @@ -0,0 +1,12 @@ +- name: data_stream.type + type: constant_keyword + description: Data stream type. +- name: data_stream.dataset + type: constant_keyword + description: Data stream dataset name. +- name: data_stream.namespace + type: constant_keyword + description: Data stream namespace. +- name: '@timestamp' + type: date + description: Event timestamp. diff --git a/packages/akamai/data_stream/siem_otel/manifest.yml b/packages/akamai/data_stream/siem_otel/manifest.yml new file mode 100644 index 00000000000..f106bdfd452 --- /dev/null +++ b/packages/akamai/data_stream/siem_otel/manifest.yml @@ -0,0 +1,107 @@ +title: Akamai SIEM Logs (OpenTelemetry) +type: logs +elasticsearch: + # The receiver emits bodymap-mode documents that are routed to the existing + # akamai.siem dataset (see the data_stream.dataset stream var), not to an + # .otel-suffixed data stream. Fleet's permission generator assumes otelcol + # streams write to .otel-* and would scope the agent API key to + # logs-akamai.siem.otel-; dynamic_dataset/dynamic_namespace widen + # the grant to logs-*-* (same as OTel input packages) so writes to + # logs-akamai.siem- are authorized. + dynamic_dataset: true + dynamic_namespace: true +streams: + - input: otelcol + template_path: otelcol.yml.hbs + title: Akamai SIEM logs via OTel receiver + description: Collect Akamai SIEM logs with the OpenTelemetry akamai_siem receiver. Requires Elastic Agent and Elastic Stack version 9.5.0 or later. Events are routed to the akamai.siem dataset and processed by its ingest pipeline. + enabled: false + vars: + - name: endpoint + type: text + title: API Host + description: API Hostname in the form of http(s)://akzz-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net without path + multi: false + required: true + show_user: true + default: https://akzz-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net + - name: config_ids + type: text + title: Security Configuration IDs + description: Unique identifier for each security configuration. To report on more than one configuration, separate integer identifiers with semicolons or commas. ex. 12892;29182;82912 + multi: false + required: true + show_user: true + - name: client_token + type: password + title: Client Token + description: Client token provided by "Credentials" ui + multi: false + required: true + show_user: true + secret: true + - name: client_secret + type: password + title: Client Secret + description: Client secret provided by "Credentials" ui + multi: false + required: true + show_user: true + secret: true + - name: access_token + type: password + title: Access Token + description: Access token provided by "Authorizations" ui + multi: false + required: true + show_user: true + secret: true + - name: poll_interval + type: text + title: Poll Interval + description: Time between polling cycles. Supported units for this parameter are h/m/s. + multi: false + required: true + show_user: true + default: 1m + - name: initial_lookback + type: text + title: Initial Lookback + description: How far back to fetch events on the first poll. Default is the maximum allowed value of 12 hours (Akamai API limit). Supported units for this parameter are h/m/s. + multi: false + required: true + show_user: true + default: 12h + - name: event_limit + type: integer + title: Event Limit + description: Defines the approximate maximum number of security events each fetch returns. The default limit is 10000 and the maximum limit available is 600000. + multi: false + required: true + show_user: false + default: 10000 + - name: namespace + type: text + title: Data Stream Namespace + description: Must match the namespace configured on the integration policy. The receiver writes this value into each event body so that data_stream.namespace filters and mappings stay consistent with the target data stream. + multi: false + required: true + show_user: true + default: default + - name: data_stream.dataset + type: text + title: Dataset + description: Dataset used by Fleet to route events. Defaults to akamai.siem so events are processed by the existing Akamai SIEM ingest pipeline and stored in logs-akamai.siem-. Do not change unless you know what you are doing. + multi: false + required: true + show_user: false + default: akamai.siem + - name: enable_storage + type: bool + title: Enable Cursor Persistence (Technical Preview) + description: >- + Declares a file_storage OpenTelemetry extension in the stream so the akamai_siem receiver can persist its poll cursor across agent restarts. Requires an Elastic Agent whose akamai_siem receiver supports storage auto-binding; on agents without that support the extension is started but remains unused, and the receiver re-fetches the Initial Lookback window after a restart. The receiver configuration deliberately carries no storage reference, as Fleet renames stream-declared extensions and cannot rewrite such references. Disabled by default while this capability is under development. + multi: false + required: false + show_user: false + default: false diff --git a/packages/akamai/docs/README.md b/packages/akamai/docs/README.md index cd648917858..1437dc6b0c7 100644 --- a/packages/akamai/docs/README.md +++ b/packages/akamai/docs/README.md @@ -22,6 +22,19 @@ See [Akamai API get started](https://techdocs.akamai.com/siem-integration/refere - The GCS input currently only accepts a service account JSON key or a service account JSON file for authentication. - The GCS input currently only supports JSON data. +### To collect data via the OpenTelemetry receiver (Technical Preview), follow the below steps: + +This collection mode uses the native OpenTelemetry `akamai_siem` receiver embedded in the Elastic Agent's EDOT collector instead of the CEL input. It polls the same [Akamai SIEM API](https://techdocs.akamai.com/siem-integration/reference/api) using the same EdgeGrid credentials. + +- Requires Elastic Stack (Kibana, Elastic Agent) version 9.5.0 or later. +- Configure the API Host, Security Configuration IDs and the EdgeGrid credentials (Client Token, Client Secret, Access Token) under the "Collect Akamai SIEM logs via OpenTelemetry receiver" section. +- Events are routed to the `akamai.siem` dataset, processed by the same ingest pipeline as the CEL input, and stored in `logs-akamai.siem-`. +- If the integration policy uses a namespace other than `default`, set the "Data Stream Namespace" option to the same value so that the `data_stream.namespace` field written into each event matches the target data stream. + +**Note**: +- The receiver supports persisting its poll cursor through an OpenTelemetry storage extension (equivalent to the CEL input's registry-based cursor), but Fleet cannot yet wire storage extensions into receiver configurations, so cursor persistence is not available in Fleet-managed deployments. After an agent restart the receiver re-fetches the configured Initial Lookback window; replayed events are deduplicated by the ingest pipeline's `event.original` fingerprint within the same backing index. +- Unlike the CEL input, events collected via the OTel receiver are not tagged with `akamai-siem`/`forwarded` tags. + **Exported fields** | Field | Description | Type | diff --git a/packages/akamai/manifest.yml b/packages/akamai/manifest.yml index 27527029cfc..7c5c06d9545 100644 --- a/packages/akamai/manifest.yml +++ b/packages/akamai/manifest.yml @@ -1,13 +1,13 @@ name: akamai title: Akamai -version: "3.1.1" +version: "3.2.0" description: Collect logs from Akamai with Elastic Agent. type: integration -format_version: "3.3.2" -categories: [security, cdn_security] +format_version: "3.6.0" +categories: [security, cdn_security, opentelemetry] conditions: kibana: - version: "^8.18.0 || ^9.0.0" + version: "^9.5.0" icons: - src: /img/akamai_logo.svg title: Akamai @@ -24,6 +24,9 @@ policy_templates: - type: gcs title: "Collect Akamai SIEM logs via Google Cloud Storage" description: "Collecting SIEM logs from Akamai via Google Cloud Storage" + - type: otelcol + title: "Collect Akamai SIEM logs via OpenTelemetry receiver (Technical Preview)" + description: "Collecting SIEM logs from Akamai via the native OpenTelemetry akamai_siem receiver" owner: github: elastic/security-service-integrations type: community diff --git a/packages/akamai/validation.yml b/packages/akamai/validation.yml index a96151416a6..663e38f5453 100644 --- a/packages/akamai/validation.yml +++ b/packages/akamai/validation.yml @@ -1,3 +1,5 @@ errors: exclude_checks: - SVR00005 # Kibana version for saved tags. + - SVR00006 # Pipeline processor tags; pre-existing pipeline predates this check. + - SVR00009 # Pipeline on_failure error message format; pre-existing pipeline predates this check.