Amazon Audit Manager Controls API

openapi: 3.1.0
info:
  title: AWS Audit Manager Controls API
  version: '2017-07-25'
  description: Generated from AWS's published Smithy model for AWS Audit Manager. 6 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://auditmanager.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /controls:
    post:
      operationId: CreateControl
      summary: Create Control
      description: Creates a new custom control in Audit Manager.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateControlResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateControlRequest'
      tags:
      - Controls
    get:
      operationId: ListControls
      summary: List Controls
      description: Returns a list of controls from Audit Manager.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListControlsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListControlsRequest'
      tags:
      - Controls
  /controls/{controlId}:
    delete:
      operationId: DeleteControl
      summary: Delete Control
      description: Deletes a custom control in Audit Manager. When you invoke this operation, the custom control is deleted
        from any frameworks or assessments that it’s currently part of. As a result, Audit Manager will stop collecting evidence
        for that custom control in all of your assessments. This includes assessments that you previously created before you
        deleted the custom control.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteControlResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteControlRequest'
      tags:
      - Controls
    get:
      operationId: GetControl
      summary: Get Control
      description: Gets information about a specified control.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetControlResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetControlRequest'
      tags:
      - Controls
    put:
      operationId: UpdateControl
      summary: Update Control
      description: Updates a custom control in Audit Manager.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateControlResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateControlRequest'
      tags:
      - Controls
  /assessments/{assessmentId}/controlSets/{controlSetId}/controls/{controlId}:
    put:
      operationId: UpdateAssessmentControl
      summary: Update Assessment Control
      description: Updates a control within an assessment in Audit Manager.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAssessmentControlResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAssessmentControlRequest'
      tags:
      - Controls
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: auditmanager
  schemas:
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    AssessmentControl:
      type: object
      properties:
        id:
          type: string
          description: The identifier for the control.
        name:
          type: string
          description: The name of the control.
        description:
          type: string
          description: The description of the control.
        status:
          type: string
          enum:
          - UNDER_REVIEW
          - REVIEWED
          - INACTIVE
          description: The status of the control.
        response:
          type: string
          enum:
          - MANUAL
          - AUTOMATE
          - DEFER
          - IGNORE
          description: The response of the control.
        comments:
          type: array
          items:
            $ref: '#/components/schemas/ControlComment'
          description: The list of comments that's attached to the control.
        evidenceSources:
          type: array
          items:
            type: string
          description: The list of data sources for the evidence.
        evidenceCount:
          type: integer
          description: The amount of evidence that's collected for the control.
        assessmentReportEvidenceCount:
          type: integer
          description: The amount of evidence in the assessment report.
    Control:
      type: object
      properties:
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the control.
        id:
          type: string
          description: The unique identifier for the control.
        type:
          type: string
          enum:
          - Standard
          - Custom
          - Core
          description: Specifies whether the control is a standard control or a custom control.
        name:
          type: string
          description: The name of the control.
        description:
          type: string
          description: The description of the control.
        testingInformation:
          type: string
          description: The steps that you should follow to determine if the control has been satisfied.
        actionPlanTitle:
          type: string
          description: The title of the action plan for remediating the control.
        actionPlanInstructions:
          type: string
          description: The recommended actions to carry out if the control isn't fulfilled.
        controlSources:
          type: string
          description: The data source types that determine where Audit Manager collects evidence from for the control.
        controlMappingSources:
          type: array
          items:
            $ref: '#/components/schemas/ControlMappingSource'
          description: The data mapping sources for the control.
        createdAt:
          type: string
          format: date-time
          description: The time when the control was created.
        lastUpdatedAt:
          type: string
          format: date-time
          description: The time when the control was most recently updated.
        createdBy:
          type: string
          description: The user or role that created the control.
        lastUpdatedBy:
          type: string
          description: The user or role that most recently updated the control.
        tags:
          type: object
          additionalProperties:
            type: string
          description: The tags associated with the control.
        state:
          type: string
          enum:
          - ACTIVE
          - END_OF_SUPPORT
          description: The state of the control. The END_OF_SUPPORT state is applicable to standard controls only. This state
            indicates that the standard control can still be used to collect evidence, but Audit Manager is no longer updating
            or maintaining that control.
    ControlComment:
      type: object
      properties:
        authorName:
          type: string
          description: The name of the user who authored the comment.
        commentBody:
          type: string
          description: The body text of a control comment.
        postedDate:
          type: string
          format: date-time
          description: The time when the comment was posted.
    ControlMappingSource:
      type: object
      properties:
        sourceId:
          type: string
          description: The unique identifier for the source.
        sourceName:
          type: string
          description: The name of the source.
        sourceDescription:
          type: string
          description: The description of the source.
        sourceSetUpOption:
          type: string
          enum:
          - System_Controls_Mapping
          - Procedural_Controls_Mapping
          description: The setup option for the data source. This option reflects if the evidence collection method is automated
            or manual. If you don’t provide a value for sourceSetUpOption, Audit Manager automatically infers and populates
            the correct value based on the sourceType that you specify.
        sourceType:
          type: string
          enum:
          - AWS_Cloudtrail
          - AWS_Config
          - AWS_Security_Hub
          - AWS_API_Call
          - MANUAL
          - Common_Control
          - Core_Control
          description: Specifies which type of data source is used to collect evidence. The source can be an individual data
            source type, such as AWS_Cloudtrail, AWS_Config, AWS_Security_Hub, AWS_API_Call, or MANUAL. The source can also
            be a managed grouping of data sources, such as a Core_Control or a Common_Control.
        sourceKeyword:
          $ref: '#/components/schemas/SourceKeyword'
        sourceFrequency:
          type: string
          enum:
          - DAILY
          - WEEKLY
          - MONTHLY
          description: Specifies how often evidence is collected from the control mapping source.
        troubleshootingText:
          type: string
          description: The instructions for troubleshooting the control.
    ControlMetadata:
      type: object
      properties:
        arn:
          type: string
          description: The Amazon Resource Name (ARN) of the control.
        id:
          type: string
          description: The unique identifier for the control.
        name:
          type: string
          description: The name of the control.
        controlSources:
          type: string
          description: The data source that determines where Audit Manager collects evidence from for the control.
        createdAt:
          type: string
          format: date-time
          description: The time when the control was created.
        lastUpdatedAt:
          type: string
          format: date-time
          description: The time when the control was most recently updated.
    CreateControlMappingSource:
      type: object
      properties:
        sourceName:
          type: string
          description: The name of the control mapping data source.
        sourceDescription:
          type: string
          description: The description of the data source that determines where Audit Manager collects evidence from for the
            control.
        sourceSetUpOption:
          type: string
          enum:
          - System_Controls_Mapping
          - Procedural_Controls_Mapping
          description: The setup option for the data source. This option reflects if the evidence collection method is automated
            or manual. If you don’t provide a value for sourceSetUpOption, Audit Manager automatically infers and populates
            the correct value based on the sourceType that you specify.
        sourceType:
          type: string
          enum:
          - AWS_Cloudtrail
          - AWS_Config
          - AWS_Security_Hub
          - AWS_API_Call
          - MANUAL
          - Common_Control
          - Core_Control
          description: Specifies which type of data source is used to collect evidence. The source can be an individual data
            source type, such as AWS_Cloudtrail, AWS_Config, AWS_Security_Hub, AWS_API_Call, or MANUAL. The source can also
            be a managed grouping of data sources, such as a Core_Control or a Common_Control.
        sourceKeyword:
          $ref: '#/components/schemas/SourceKeyword'
        sourceFrequency:
          type: string
          enum:
          - DAILY
          - WEEKLY
          - MONTHLY
          description: Specifies how often evidence is collected from the control mapping source.
        troubleshootingText:
          type: string
          description: The instructions for troubleshooting the control.
    CreateControlRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the control.
        description:
          type: string
          description: The description of the control.
        testingInformation:
          type: string
          description: The steps to follow to determine if the control is satisfied.
        actionPlanTitle:
          type: string
          description: The title of the action plan for remediating the control.
        actionPlanInstructions:
          type: string
          description: The recommended actions to carry out if the control isn't fulfilled.
        controlMappingSources:
          type: array
          items:
            $ref: '#/components/schemas/CreateControlMappingSource'
          description: The data mapping sources for the control.
        tags:
          type: object
          additionalProperties:
            type: string
          description: The tags that are associated with the control.
      required:
      - name
      - controlMappingSources
    CreateControlResponse:
      type: object
      properties:
        control:
          $ref: '#/components/schemas/Control'
    DeleteControlRequest:
      type: object
      properties:
        controlId:
          type: string
          description: The unique identifier for the control.
      required:
      - controlId
    DeleteControlResponse:
      type: object
      properties: {}
    GetControlRequest:
      type: object
      properties:
        controlId:
          type: string
          description: The identifier for the control.
      required:
      - controlId
    GetControlResponse:
      type: object
      properties:
        control:
          $ref: '#/components/schemas/Control'
    InternalServerException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ListControlsRequest:
      type: object
      properties:
        controlType:
          type: string
          enum:
          - Standard
          - Custom
          - Core
          description: A filter that narrows the list of controls to a specific type.
        nextToken:
          type: string
          description: The pagination token that's used to fetch the next set of results.
        maxResults:
          type: integer
          description: The maximum number of results on a page or for an API request call.
        controlCatalogId:
          type: string
          description: A filter that narrows the list of controls to a specific resource from the Amazon Web Services Control
            Catalog. To use this parameter, specify the ARN of the Control Catalog resource. You can specify either a control
            domain, a control objective, or a common control. For information about how to find the ARNs for these resources,
            see ListDomains , ListObjectives , and ListCommonControls . You can only filter by one Control Catalog resource
            at a time. Specifying multiple resource ARNs isn’t currently supported. If you want to filter by more than one
            ARN, we recommend that you run the ListControl
      required:
      - controlType
    ListControlsResponse:
      type: object
      properties:
        controlMetadataList:
          type: array
          items:
            $ref: '#/components/schemas/ControlMetadata'
          description: A list of metadata that the ListControls API returns for each control.
        nextToken:
          type: string
          description: The pagination token that's used to fetch the next set of results.
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
        resourceId:
          type: string
          description: The unique identifier for the resource.
        resourceType:
          type: string
          description: The type of resource that's affected by the error.
      required:
      - message
      - resourceId
      - resourceType
    ServiceQuotaExceededException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    SourceKeyword:
      type: object
      properties:
        keywordInputType:
          type: string
          enum:
          - SELECT_FROM_LIST
          - UPLOAD_FILE
          - INPUT_TEXT
          description: The input method for the keyword. SELECT_FROM_LIST is used when mapping a data source for automated
            evidence. When keywordInputType is SELECT_FROM_LIST, a keyword must be selected to collect automated evidence.
            For example, this keyword can be a CloudTrail event name, a rule name for Config, a Security Hub CSPM control,
            or the name of an Amazon Web Services API call. UPLOAD_FILE and INPUT_TEXT are only used when mapping a data source
            for manual evidence. When keywordInputType is UPLOAD_FILE, a file must be uploaded as manual evidence. When keywordInputType
            is INPUT_TEXT, text must be entered a
        keywordValue:
          type: string
          description: 'The value of the keyword that''s used when mapping a control data source. For example, this can be
            a CloudTrail event name, a rule name for Config, a Security Hub CSPM control, or the name of an Amazon Web Services
            API call. If you’re mapping a data source to a rule in Config, the keywordValue that you specify depends on the
            type of rule: For managed rules, you can use the rule identifier as the keywordValue. You can find the rule identifier
            from the list of Config managed rules. For some rules, the rule identifier is different from the rule name. For
            example, the rule name restricted-ssh has t'
    UpdateAssessmentControlRequest:
      type: object
      properties:
        assessmentId:
          type: string
          description: The unique identifier for the assessment.
        controlSetId:
          type: string
          description: The unique identifier for the control set.
        controlId:
          type: string
          description: The unique identifier for the control.
        controlStatus:
          type: string
          enum:
          - UNDER_REVIEW
          - REVIEWED
          - INACTIVE
          description: The status of the control.
        commentBody:
          type: string
          description: The comment body text for the control.
      required:
      - assessmentId
      - controlSetId
      - controlId
    UpdateAssessmentControlResponse:
      type: object
      properties:
        control:
          $ref: '#/components/schemas/AssessmentControl'
    UpdateControlRequest:
      type: object
      properties:
        controlId:
          type: string
          description: The identifier for the control.
        name:
          type: string
          description: The name of the updated control.
        description:
          type: string
          description: The optional description of the control.
        testingInformation:
          type: string
          description: The steps that you should follow to determine if the control is met.
        actionPlanTitle:
          type: string
          description: The title of the action plan for remediating the control.
        actionPlanInstructions:
          type: string
          description: The recommended actions to carry out if the control isn't fulfilled.
        controlMappingSources:
          type: array
          items:
            $ref: '#/components/schemas/ControlMappingSource'
          description: The data mapping sources for the control.
      required:
      - controlId
      - name
      - controlMappingSources
    UpdateControlResponse:
      type: object
      properties:
        control:
          $ref: '#/components/schemas/Control'
    ValidationException:
      type: object
      properties:
        message:
          type: string
        reason:
          type: string
          enum:
          - unknownOperation
          - cannotParse
          - fieldValidationFailed
          - other
          description: The reason the request failed validation.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: The fields that caused the error, if applicable.
      required:
      - message
    ValidationExceptionField:
      type: object
      properties:
        name:
          type: string
          description: The name of the validation error.
        message:
          type: string
          description: The body of the error message.
      required:
      - name
      - message
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/auditmanager/service/2017-07-25/auditmanager-2017-07-25.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)