ListViolationEvents - AWS IoT

ListViolationEvents

Lists the Device Defender security profile violations discovered during the given time period. You can use filters to limit the results to those alerts issued for a particular security profile, behavior, or thing (device).

Requires permission to access the ListViolationEvents action.

Request Syntax

GET /violation-events?behaviorCriteriaType=behaviorCriteriaType&endTime=endTime&listSuppressedAlerts=listSuppressedAlerts&maxResults=maxResults&nextToken=nextToken&securityProfileName=securityProfileName&startTime=startTime&thingName=thingName HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

behaviorCriteriaType

The criteria for a behavior.

Valid Values: STATIC | STATISTICAL | MACHINE_LEARNING

endTime

The end time for the alerts to be listed.

Required: Yes

listSuppressedAlerts

A list of all suppressed alerts.

maxResults

The maximum number of results to return at one time.

Valid Range: Minimum value of 1. Maximum value of 250.

nextToken

The token for the next set of results.

securityProfileName

A filter to limit results to those alerts generated by the specified security profile.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z0-9:_-]+

startTime

The start time for the alerts to be listed.

Required: Yes

thingName

A filter to limit results to those alerts caused by the specified thing.

Length Constraints: Minimum length of 1. Maximum length of 128.

Request Body

The request does not have a request body.

Response Syntax

HTTP/1.1 200 Content-type: application/json { "nextToken": "string", "violationEvents": [ { "behavior": { "criteria": { "comparisonOperator": "string", "consecutiveDatapointsToAlarm": number, "consecutiveDatapointsToClear": number, "durationSeconds": number, "mlDetectionConfig": { "confidenceLevel": "string" }, "statisticalThreshold": { "statistic": "string" }, "value": { "cidrs": [ "string" ], "count": number, "number": number, "numbers": [ number ], "ports": [ number ], "strings": [ "string" ] } }, "metric": "string", "metricDimension": { "dimensionName": "string", "operator": "string" }, "name": "string", "suppressAlerts": boolean }, "metricValue": { "cidrs": [ "string" ], "count": number, "number": number, "numbers": [ number ], "ports": [ number ], "strings": [ "string" ] }, "securityProfileName": "string", "thingName": "string", "violationEventAdditionalInfo": { "confidenceLevel": "string" }, "violationEventTime": number, "violationEventType": "string", "violationId": "string" } ] }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

nextToken

A token that can be used to retrieve the next set of results, or null if there are no additional results.

Type: String

violationEvents

The security profile violation alerts issued for this account during the given time period, potentially filtered by security profile, behavior violated, or thing (device) violating.

Type: Array of ViolationEvent objects

Errors

InternalFailureException

An unexpected error has occurred.

HTTP Status Code: 500

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

ThrottlingException

The rate exceeds the limit.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: