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


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 
{
  "continuationTime": string,
  "detectionBatchSize": integer,
  "maxDetections": integer,
  "pageToken": string,
  "pageStartTime": string,
  "compositeAlertHandling": enum (CompositeAlertHandling)
}
Fields
continuationTime

string (Timestamp format)

Optional. DEPRECATED: Prefer using pageToken or pageStartTime instead. A continuation timestamp, from a previous legacy.legacyStreamDetectionAlerts connection. When reconnecting, clients should provide the maximum continuationTime they have received.

All detection alerts discovered after continuationTime 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".
detectionBatchSize

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

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 detectionBatchSize is strongly recommended. Failing to do so may result in the return of an incorrect continuation timestamp and missed detections.
pageToken

string

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

When using pageToken, the detectionBatchSize field will be respected. The pageToken is opaque to the client.
pageStartTime

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 pageToken in subsequent requests.

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

When initiating the very first connection, clients should leave all of these fields unspecified to use continuationTime or specify a pageStartTime to use the pageToken behavior.

The default option is continuationTime rather than pageStartTime 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".
compositeAlertHandling

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

legacy.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)
    }
  ],
  "continuationTime": string,
  "heartbeat": boolean,
  "nextPageToken": string,
  "nextPageStartTime": string
}
Fields
detections[]

object (Collection)

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

string (Timestamp format)

DEPRECATED: Prefer using pageToken instead by specifying either pageStartTime or pageToken in the request.

A continuation timestamp that can be sent as continuationTime 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.
nextPageToken

string

A page token that can be sent as pageToken when reconnecting to this streaming RPC. Only one of continuationTime, nextPageToken, or nextPageStartTime will be populated in the response due to the distinct behaviors.
nextPageStartTime

string (Timestamp format)

A page start timestamp that can be sent as pageStartTime 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.