Amazon IoT Core Active Violations API

openapi: 3.1.0
info:
  title: AWS IoT Active Violations API
  version: '2015-05-28'
  description: Generated from AWS's published Smithy model for AWS IoT. 1 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://iot.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /active-violations:
    get:
      operationId: ListActiveViolations
      summary: List Active Violations
      description: The IoT Device Defender detect feature will no longer be available to new customers starting August 31,
        2026. If you would like to use the detect feature, sign up prior to August 31, 2026. To learn about alternatives to
        IoT Device Defender detect, see IoT Device Defender detect feature availability change in the IoT Device Defender
        Developer Guide. There is no change to IoT Device Defender audit availability. Lists the active violations for a given
        Device Defender security profile. Requires permission to access the ListActiveViolations action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListActiveViolationsResponse'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '400':
          description: InvalidRequestException; ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListActiveViolationsRequest'
      tags:
      - Active Violations
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: iot
  schemas:
    ActiveViolation:
      type: object
      properties:
        violationId:
          type: string
          description: The ID of the active violation.
        thingName:
          type: string
          description: The name of the thing responsible for the active violation.
        securityProfileName:
          type: string
          description: The security profile with the behavior is in violation.
        behavior:
          $ref: '#/components/schemas/Behavior'
        lastViolationValue:
          $ref: '#/components/schemas/MetricValue'
        violationEventAdditionalInfo:
          $ref: '#/components/schemas/ViolationEventAdditionalInfo'
        verificationState:
          type: string
          enum:
          - FALSE_POSITIVE
          - BENIGN_POSITIVE
          - TRUE_POSITIVE
          - UNKNOWN
          description: The verification state of the violation (detect alarm).
        verificationStateDescription:
          type: string
          description: The description of the verification state of the violation.
        lastViolationTime:
          type: string
          format: date-time
          description: The time the most recent violation occurred.
        violationStartTime:
          type: string
          format: date-time
          description: The time the violation started.
    Behavior:
      type: object
      properties:
        name:
          type: string
          description: The name you've given to the behavior.
        metric:
          type: string
          description: What is measured by the behavior.
        metricDimension:
          $ref: '#/components/schemas/MetricDimension'
        criteria:
          $ref: '#/components/schemas/BehaviorCriteria'
        suppressAlerts:
          type: boolean
          description: Suppresses alerts.
        exportMetric:
          type: boolean
          description: Value indicates exporting metrics related to the behavior when it is true.
      required:
      - name
    BehaviorCriteria:
      type: object
      properties:
        comparisonOperator:
          type: string
          enum:
          - less-than
          - less-than-equals
          - greater-than
          - greater-than-equals
          - in-cidr-set
          - not-in-cidr-set
          - in-port-set
          - not-in-port-set
          - in-set
          - not-in-set
          description: 'The operator that relates the thing measured (metric) to the criteria (containing a value or statisticalThreshold).
            Valid operators include: string-list: in-set and not-in-set number-list: in-set and not-in-set ip-address-list:
            in-cidr-set and not-in-cidr-set number: less-than, less-than-equals, greater-than, and greater-than-equals'
        value:
          $ref: '#/components/schemas/MetricValue'
        durationSeconds:
          type: integer
          description: Use this to specify the time duration over which the behavior is evaluated, for those criteria that
            have a time dimension (for example, NUM_MESSAGES_SENT). For a statisticalThreshhold metric comparison, measurements
            from all devices are accumulated over this time duration before being used to calculate percentiles, and later,
            measurements from an individual device are also accumulated over this time duration before being given a percentile
            rank. Cannot be used with list-based metric datatypes.
        consecutiveDatapointsToAlarm:
          type: integer
          description: If a device is in violation of the behavior for the specified number of consecutive datapoints, an
            alarm occurs. If not specified, the default is 1.
        consecutiveDatapointsToClear:
          type: integer
          description: If an alarm has occurred and the offending device is no longer in violation of the behavior for the
            specified number of consecutive datapoints, the alarm is cleared. If not specified, the default is 1.
        statisticalThreshold:
          $ref: '#/components/schemas/StatisticalThreshold'
        mlDetectionConfig:
          $ref: '#/components/schemas/MachineLearningDetectionConfig'
    InternalFailureException:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    InvalidRequestException:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    ListActiveViolationsRequest:
      type: object
      properties:
        thingName:
          type: string
          description: The name of the thing whose active violations are listed.
        securityProfileName:
          type: string
          description: The name of the Device Defender security profile for which violations are listed.
        behaviorCriteriaType:
          type: string
          enum:
          - STATIC
          - STATISTICAL
          - MACHINE_LEARNING
          description: The criteria for a behavior.
        listSuppressedAlerts:
          type: boolean
          description: A list of all suppressed alerts.
        verificationState:
          type: string
          enum:
          - FALSE_POSITIVE
          - BENIGN_POSITIVE
          - TRUE_POSITIVE
          - UNKNOWN
          description: The verification state of the violation (detect alarm).
        nextToken:
          type: string
          description: The token for the next set of results.
        maxResults:
          type: integer
          description: The maximum number of results to return at one time.
    ListActiveViolationsResponse:
      type: object
      properties:
        activeViolations:
          type: array
          items:
            $ref: '#/components/schemas/ActiveViolation'
          description: The list of active violations.
        nextToken:
          type: string
          description: A token that can be used to retrieve the next set of results, or null if there are no additional results.
    MachineLearningDetectionConfig:
      type: object
      properties:
        confidenceLevel:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          description: The sensitivity of anomalous behavior evaluation. Can be Low, Medium, or High.
      required:
      - confidenceLevel
    MetricDimension:
      type: object
      properties:
        dimensionName:
          type: string
          description: A unique identifier for the dimension.
        operator:
          type: string
          enum:
          - IN
          - NOT_IN
          description: 'Defines how the dimensionValues of a dimension are interpreted. For example, for dimension type TOPIC_FILTER,
            the IN operator, a message will be counted only if its topic matches one of the topic filters. With NOT_IN operator,
            a message will be counted only if it doesn''t match any of the topic filters. The operator is optional: if it''s
            not provided (is null), it will be interpreted as IN.'
      required:
      - dimensionName
    MetricValue:
      type: object
      properties:
        count:
          type: integer
          description: If the comparisonOperator calls for a numeric value, use this to specify that numeric value to be compared
            with the metric.
        cidrs:
          type: array
          items:
            type: string
          description: If the comparisonOperator calls for a set of CIDRs, use this to specify that set to be compared with
            the metric.
        ports:
          type: array
          items:
            type: integer
          description: If the comparisonOperator calls for a set of ports, use this to specify that set to be compared with
            the metric.
        number:
          type: number
          description: The numeral value of a metric.
        numbers:
          type: array
          items:
            type: number
          description: The numeral values of a metric.
        strings:
          type: array
          items:
            type: string
          description: The string values of a metric.
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    StatisticalThreshold:
      type: object
      properties:
        statistic:
          type: string
          description: The percentile that resolves to a threshold value by which compliance with a behavior is determined.
            Metrics are collected over the specified period (durationSeconds) from all reporting devices in your account and
            statistical ranks are calculated. Then, the measurements from a device are collected over the same period. If
            the accumulated measurements from the device fall above or below (comparisonOperator) the value associated with
            the percentile specified, then the device is considered to be in compliance with the behavior, otherwise a violation
            occurs.
    ViolationEventAdditionalInfo:
      type: object
      properties:
        confidenceLevel:
          type: string
          enum:
          - LOW
          - MEDIUM
          - HIGH
          description: The sensitivity of anomalous behavior evaluation. Can be Low, Medium, or High.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/iot/service/2015-05-28/iot-2015-05-28.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)