openapi: 3.0.0
info:
  title: Amazon Security Hub Administration Findings API
  description: Amazon Security Hub is a cloud security posture management service that aggregates security findings, performs best practice checks, and enables automated remediation across AWS accounts.
  version: '2018-10-26'
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
    url: https://aws.amazon.com/security-hub/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://securityhub.amazonaws.com
  description: Amazon Security Hub API endpoint
tags:
- name: Findings
  description: Operations for managing security findings.
paths:
  /findings:
    post:
      operationId: GetFindings
      summary: Amazon Security Hub Get Findings
      description: Returns a list of findings that match the specified criteria, with filtering, sorting, and pagination support.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                Filters:
                  type: object
                  description: The finding attributes used to define a condition to filter the returned findings.
                  properties:
                    SeverityLabel:
                      type: array
                      items:
                        type: object
                    ComplianceStatus:
                      type: array
                      items:
                        type: object
                    ProductName:
                      type: array
                      items:
                        type: object
                    ResourceType:
                      type: array
                      items:
                        type: object
                SortCriteria:
                  type: array
                  items:
                    type: object
                    properties:
                      Field:
                        type: string
                      SortOrder:
                        type: string
                        enum:
                        - asc
                        - desc
                NextToken:
                  type: string
                MaxResults:
                  type: integer
                  minimum: 1
                  maximum: 100
      responses:
        '200':
          description: List of findings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Findings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Finding'
                  NextToken:
                    type: string
              examples:
                GetFindings200Example:
                  summary: Default GetFindings 200 response
                  x-microcks-default: true
                  value:
                    AccountId: '123456789012'
                    Region: us-east-1
      tags:
      - Findings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /findings/import:
    post:
      operationId: BatchImportFindings
      summary: Amazon Security Hub Batch Import Findings
      description: Imports security findings generated from an integrated third-party product into Security Hub.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Findings:
                  type: array
                  description: A list of findings to import.
                  items:
                    $ref: '#/components/schemas/Finding'
              required:
              - Findings
      responses:
        '200':
          description: Batch import results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  FailedCount:
                    type: integer
                  SuccessCount:
                    type: integer
                  FailedFindings:
                    type: array
                    items:
                      type: object
              examples:
                BatchImportFindings200Example:
                  summary: Default BatchImportFindings 200 response
                  x-microcks-default: true
                  value:
                    AccountId: '123456789012'
                    Region: us-east-1
      tags:
      - Findings
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Finding:
      type: object
      description: An AWS Security Finding Format (ASFF) finding object that provides a normalized format for security findings.
      properties:
        SchemaVersion:
          type: string
          description: The schema version that a finding is formatted for.
        Id:
          type: string
          description: The identifier for the finding.
        ProductArn:
          type: string
          description: The ARN generated by Security Hub for the product that generated the finding.
        GeneratorId:
          type: string
          description: The identifier for the solution-specific component that generated the finding.
        AwsAccountId:
          type: string
          description: The AWS account ID where the finding was generated.
        Types:
          type: array
          description: One or more finding types in the format of namespace/category/classifier.
          items:
            type: string
        CreatedAt:
          type: string
          format: date-time
          description: Indicates when the finding was created.
        UpdatedAt:
          type: string
          format: date-time
          description: Indicates when the finding was most recently updated.
        Severity:
          type: object
          description: The severity of the finding.
          properties:
            Label:
              type: string
              enum:
              - INFORMATIONAL
              - LOW
              - MEDIUM
              - HIGH
              - CRITICAL
            Normalized:
              type: integer
              minimum: 0
              maximum: 100
        Title:
          type: string
          description: A finding title.
        Description:
          type: string
          description: A finding description.
        Resources:
          type: array
          description: A set of resource data types describing the resources the finding refers to.
          items:
            type: object
            properties:
              Type:
                type: string
              Id:
                type: string
              Partition:
                type: string
              Region:
                type: string
              Details:
                type: object
        Compliance:
          type: object
          properties:
            Status:
              type: string
              enum:
              - PASSED
              - WARNING
              - FAILED
              - NOT_AVAILABLE
            RelatedRequirements:
              type: array
              items:
                type: string
        Workflow:
          type: object
          properties:
            Status:
              type: string
              enum:
              - NEW
              - NOTIFIED
              - RESOLVED
              - SUPPRESSED
        RecordState:
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
      required:
      - SchemaVersion
      - Id
      - ProductArn
      - GeneratorId
      - AwsAccountId
      - CreatedAt
      - UpdatedAt
      - Severity
      - Title
      - Description
      - Resources