Method: legacy.legacyStreamDetectionAlerts

Full name: projects.locations.instances.legacy.legacyStreamDetectionAlerts

Legacy StreamDetectionAlerts continuously streams new detection alerts as they are discovered. A detection alert is a special kind of detection. A detection is considered a "detection alert" if the rule that detected it had alerting enabled at the time of detection.

HTTP request

POST https://chronicle.googleapis.com/v1alpha/{instance}/legacy:legacyStreamDetectionAlerts

Path parameters

Parameters
instance

string

Required. Chronicle instance this request is sent to. Format: projects/{project}/locations/{location}/instances/{instance}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "continuation_time": string,
  "detection_batch_size": integer,
  "max_detections": integer,
  "page_token": string,
  "page_start_time": string,
  "composite_alert_handling": enum (CompositeAlertHandling)
}
Fields
continuation_time

string (Timestamp format)

Optional. DEPRECATED: Prefer using page_token or page_start_time instead. A continuation timestamp, from a previous LegacyStreamDetectionAlerts connection. When reconnecting, clients should provide the maximum continuation_time they have received.

All detection alerts discovered after continuation_time will be streamed to the client.

If the value is older than 1 week, the connection request will be rejected; other RPCs should be used to get older detections.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
detection_batch_size

integer

Optional. The maximum number of detections to return in each detection batch. Each batch may contain fewer than this value. If unspecified, at most 10000 detection alerts will be returned in each batch. The maximum value is 10000; values above 10000 will be coerced to 10000.
max_detections

integer

Optional. The maximum number of detections to return before closing the connection. If unspecified, this field will have no effect on the connection. If provided, the connection will be gracefully closed after this number of detections have been returned. Valid values are 1 - 1,000. Values above 1,000 will be coerced to 1,000. Specifying a matching detection_batch_size is strongly recommended. Failing to do so may result in the return of an incorrect continuation timestamp and missed detections.
page_token

string

Optional. A page token, from a previous StreamDetectionAlerts connection. When reconnecting, clients should provide the most recently received page_token they have received.

When using page_token, the detection_batch_size field will be respected. The page_token is opaque to the client.
page_start_time

string (Timestamp format)

Optional. A page start timestamp that indicates when to start listing alerts. This field is the equivalent of allowing the API to use connection timestamp but requires the client to specify the timestamp in order to use the page_token in subsequent requests.

Each request must provide zero, or exactly one of (continuation_time | page_token | page_start_time). If continuation_time, page_token, and page_start_time are all unspecified, the API will default to the time of the connection and return a continuation_time. If you provide (page_token | page_start_time), the response will contain a page_token instead of continuation_time and the detection_batch_size will always be respected.

When initiating the very first connection, clients should leave all of these fields unspecified to use continuation_time or specify a page_start_time to use the page_token behavior.

The default option is continuation_time rather than page_start_time to be backwards compatible.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
composite_alert_handling

enum (CompositeAlertHandling)

Optional. How composite alerts will be processed in the response. If unset or unspecified composite alerts will be treated the same as standard alerts.

Response body

LegacyStreamDetectionAlerts response message. This represents a single detection batch. Many detection batches will be sent over the stream response.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "detections": [
    {
      object (Collection)
    }
  ],
  "continuation_time": string,
  "heartbeat": boolean,
  "next_page_token": string,
  "next_page_start_time": string
}
Fields
detections[]

object (Collection)

List of detection alerts that were discovered since the last detection batch was streamed.
continuation_time

string (Timestamp format)

DEPRECATED: Prefer using page_token instead by specifying either page_start_time or page_token in the request.

A continuation timestamp that can be sent as continuation_time when reconnecting to this streaming RPC.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
heartbeat

boolean

A boolean indicating if the response is a "heartbeat" meant to keep the connection alive.
next_page_token

string

A page token that can be sent as page_token when reconnecting to this streaming RPC. Only one of continuation_time, next_page_token, or next_page_start_time will be populated in the response due to the distinct behaviors.
next_page_start_time

string (Timestamp format)

A page start timestamp that can be sent as page_start_time when reconnecting to this streaming RPC. This field will only be populated if there is no need for a page token.

Uses RFC 3339, where generated output will always be Z-normalized and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the instance resource:

  • chronicle.legacies.legacyStreamDetectionAlerts

For more information, see the IAM documentation.

CompositeAlertHandling

CompositeAlertHandling specifies how composite alerts will be included in the response.

Enums
COMPOSITE_ALERT_HANDLING_UNSPECIFIED Unspecified or unknown composite alert handling.
FLATTEN_EVENTS_ENTITIES Flatten_events_entities Events and entities in nested detections and alerts will be bubbled up to the top-level alert. The count of events and entities in the composite alert is capped at 500.