AWS Security Hub Security Hub Findingsv2 API

openapi: 3.2.0
info:
  title: AWS SecurityHub Findingsv2 API
  version: '2018-10-26'
  description: Generated from AWS's published Smithy model for AWS SecurityHub. 3 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://securityhub.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Findingsv2
paths:
  /findingsv2/batchupdatev2:
    patch:
      operationId: BatchUpdateFindingsV2
      summary: Batch Update Findings V2
      description: 'Updates information about a customer''s investigation into a finding. Delegated administrator accounts can update findings for their account and their member accounts. Member accounts can update findings for their own account. BatchUpdateFindings and BatchUpdateFindingsV2 both use securityhub:BatchUpdateFindings in the Action element of an IAM policy statement. You must have permission to perform the securityhub:BatchUpdateFindings action. You can configure IAM policies to restrict access to specific finding fields or field values by using the securityhub:OCSFSyntaxPath/ condition key, where is one of the following supported fields: SeverityId, StatusId, or Comment. To prevent a user from updating a specific field, use a Null condition with securityhub:OCSFSyntaxPath/ set to "false". To prevent a user from setting a field to a specific value, use a StringEquals condition with securityhub:OCSFSyntaxPath/ set to the disallowed value or list of values. Updates from BatchUpdateFindingsV2 don''t affect the value of finding_info.modified_time, finding_info.modified_time_dt, time, or time_dt for a finding.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateFindingsV2Response'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateFindingsV2Request'
      tags:
      - Findingsv2
  /findingsv2/statistics:
    post:
      operationId: GetFindingStatisticsV2
      summary: Get Finding Statistics V2
      description: Returns aggregated statistical data about findings. You can use the Scopes parameter to define the data boundary for the query. Currently, Scopes supports AwsOrganizations, which lets you aggregate findings from your entire organization or from specific organizational units. Only the delegated administrator account can use Scopes. GetFindingStatisticsV2 uses securityhub:GetAdhocInsightResults in the Action element of an IAM policy statement. You must have permission to perform the securityhub:GetAdhocInsightResults action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFindingStatisticsV2Response'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: OrganizationalUnitNotFoundException; OrganizationNotFoundException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationalUnitNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFindingStatisticsV2Request'
      tags:
      - Findingsv2
  /findingsv2:
    post:
      operationId: GetFindingsV2
      summary: Get Findings V2
      description: Returns a list of findings that match the specified criteria. You can use the Scopes parameter to define the data boundary for the query. Currently, Scopes supports AwsOrganizations, which lets you retrieve findings from your entire organization or from specific organizational units. Only the delegated administrator account can use Scopes. You can use the Filters parameter to refine results based on finding attributes. You can use Scopes and Filters independently or together. When both are provided, Scopes narrows the data set first, and then Filters refines results within that scoped data set. GetFindings and GetFindingsV2 both use securityhub:GetFindings in the Action element of an IAM policy statement. You must have permission to perform the securityhub:GetFindings action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFindingsV2Response'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '400':
          description: OrganizationalUnitNotFoundException; OrganizationNotFoundException; ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationalUnitNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFindingsV2Request'
      tags:
      - Findingsv2
components:
  schemas:
    BatchUpdateFindingsV2Request:
      type: object
      properties:
        MetadataUids:
          type: array
          items:
            type: string
          description: The list of finding metadata.uid to indicate findings to update. Finding metadata.uid is a globally unique identifier associated with the finding. Customers cannot use MetadataUids together with FindingIdentifiers.
        FindingIdentifiers:
          type: array
          items:
            $ref: '#/components/schemas/OcsfFindingIdentifier'
          description: Provides information to identify a specific V2 finding.
        Comment:
          type: string
          description: The updated value for a user provided comment about the finding. Minimum character length 1. Maximum character length 512.
        SeverityId:
          type: integer
          description: The updated value for the normalized severity identifier. The severity ID is an integer with the allowed enum values [0, 1, 2, 3, 4, 5, 6, 99]. When customer provides the updated severity ID, the string sibling severity will automatically be updated in the finding.
        StatusId:
          type: integer
          description: The updated value for the normalized status identifier. The status ID is an integer with the allowed enum values [0, 1, 2, 3, 4, 5, 99]. When customer provides the updated status ID, the string sibling status will automatically be updated in the finding.
    GroupByResult:
      type: object
      properties:
        GroupByField:
          type: string
          description: The attribute by which filtered security findings should be grouped.
        GroupByValues:
          type: array
          items:
            $ref: '#/components/schemas/GroupByValue'
          description: An array of grouped values and their respective counts for each GroupByField.
    GetFindingsV2Response:
      type: object
      properties:
        Findings:
          type: array
          items:
            type: object
          description: An array of security findings returned by the operation.
        NextToken:
          type: string
          description: The pagination token to use to request the next page of results. Otherwise, this parameter is null.
    GroupByValue:
      type: object
      properties:
        FieldValue:
          type: string
          description: The value of the field by which findings are grouped.
        Count:
          type: integer
          description: The number of findings for a specific FieldValue and GroupByField.
    BatchUpdateFindingsV2ProcessedFinding:
      type: object
      properties:
        FindingIdentifier:
          $ref: '#/components/schemas/OcsfFindingIdentifier'
        MetadataUid:
          type: string
          description: The metadata.uid of a processed finding.
    OcsfIpFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - evidences.dst_endpoint.ip
          - evidences.src_endpoint.ip
          description: The name of the IP address field to filter on.
        Filter:
          $ref: '#/components/schemas/IpFilter'
    OcsfFindingFilters:
      type: object
      properties:
        CompositeFilters:
          type: array
          items:
            $ref: '#/components/schemas/CompositeFilter'
          description: Enables the creation of complex filtering conditions by combining filter criteria.
        CompositeOperator:
          type: string
          enum:
          - AND
          - OR
          description: The logical operators used to combine the filtering on multiple CompositeFilters.
    DateFilter:
      type: object
      properties:
        Start:
          type: string
          description: A timestamp that provides the start date for the date filter. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps.
        End:
          type: string
          description: A timestamp that provides the end date for the date filter. For more information about the validation and formatting of timestamp fields in Security Hub CSPM, see Timestamps.
        DateRange:
          $ref: '#/components/schemas/DateRange'
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    OcsfBooleanFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - compliance.assessments.meets_criteria
          - vulnerabilities.is_exploit_available
          - vulnerabilities.is_fix_available
          description: The name of the field.
        Filter:
          $ref: '#/components/schemas/BooleanFilter'
    OcsfNumberFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - activity_id
          - compliance.status_id
          - confidence_score
          - severity_id
          - status_id
          - finding_info.related_events_count
          - evidences.api.response.code
          - evidences.dst_endpoint.autonomous_system.number
          - evidences.dst_endpoint.port
          - evidences.src_endpoint.autonomous_system.number
          - evidences.src_endpoint.port
          - resources.image.in_use_count
          - vulnerabilities.cve.cvss.base_score
          - vendor_attributes.severity_id
          description: The name of the field.
        Filter:
          $ref: '#/components/schemas/NumberFilter'
    OcsfFindingIdentifier:
      type: object
      properties:
        CloudAccountUid:
          type: string
          description: Finding cloud.account.uid, which is a unique identifier in the Amazon Web Services account..
        FindingInfoUid:
          type: string
          description: Finding finding_info.uid, which is a unique identifier for the finding from the finding provider.
        MetadataProductUid:
          type: string
          description: Finding metadata.product.uid, which is a unique identifier for the product.
      required:
      - CloudAccountUid
      - FindingInfoUid
      - MetadataProductUid
    ValidationException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    BatchUpdateFindingsV2UnprocessedFinding:
      type: object
      properties:
        FindingIdentifier:
          $ref: '#/components/schemas/OcsfFindingIdentifier'
        MetadataUid:
          type: string
          description: The metadata.uid of an unprocessed finding.
        ErrorCode:
          type: string
          enum:
          - ResourceNotFoundException
          - ValidationException
          - InternalServerException
          - ConflictException
          description: Indicates the specific type of error preventing successful processing of a finding during a batch update operation.
        ErrorMessage:
          type: string
          description: A detailed description of why a finding could not be processed during a batch update operation.
    GetFindingStatisticsV2Request:
      type: object
      properties:
        GroupByRules:
          type: array
          items:
            $ref: '#/components/schemas/GroupByRule'
          description: Specifies how security findings should be aggregated and organized in the statistical analysis. It can accept up to 5 groupBy fields in a single call.
        Scopes:
          $ref: '#/components/schemas/FindingScopes'
        SortOrder:
          type: string
          enum:
          - asc
          - desc
          description: Orders the aggregation count in descending or ascending order. Descending order is the default.
        MaxStatisticResults:
          type: integer
          description: The maximum number of results to be returned.
      required:
      - GroupByRules
    AwsOrganizationScope:
      type: object
      properties:
        OrganizationId:
          type: string
          description: The unique identifier (ID) of the organization (for example, o-abcd1234567890). The organization must be the delegated administrator's own organization. If you omit this value and provide OrganizationalUnitId, Security Hub uses the caller's organization ID.
        OrganizationalUnitId:
          type: string
          description: The unique identifier (ID) of the organizational unit (OU) (for example, ou-ab12-cd345678). The OU must exist within the delegated administrator's own organization. When specified, the results include only data from accounts in this OU.
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    BooleanFilter:
      type: object
      properties:
        Value:
          type: boolean
          description: The value of the boolean.
    FindingScopes:
      type: object
      properties:
        AwsOrganizations:
          type: array
          items:
            $ref: '#/components/schemas/AwsOrganizationScope'
          description: A list of Organizations scopes to include in the query results. Each entry in the list specifies an organization or organizational unit to include for the delegated administrator's account. If the list specifies multiple entries, the entries are combined using OR logic.
    GetFindingsV2Request:
      type: object
      properties:
        Filters:
          $ref: '#/components/schemas/OcsfFindingFilters'
        Scopes:
          $ref: '#/components/schemas/FindingScopes'
        SortCriteria:
          type: array
          items:
            $ref: '#/components/schemas/SortCriterion'
          description: The finding attributes used to sort the list of returned findings.
        NextToken:
          type: string
          description: The token required for pagination. On your first call, set the value of this parameter to NULL. For subsequent calls, to continue listing data, set the value of this parameter to the value returned in the previous response.
        MaxResults:
          type: integer
          description: The maximum number of results to return.
    MapFilter:
      type: object
      properties:
        Key:
          type: string
          description: The key of the map filter. For example, for ResourceTags, Key identifies the name of the tag. For UserDefinedFields, Key is the name of the field.
        Value:
          type: string
          description: The value for the key in the map filter. Filter values are case sensitive. For example, one of the values for a tag called Department might be Security. If you provide security as the filter value, then there's no match.
        Comparison:
          type: string
          enum:
          - EQUALS
          - NOT_EQUALS
          - CONTAINS
          - NOT_CONTAINS
          description: 'The condition to apply to the key value when filtering Security Hub CSPM findings with a map filter. To search for values that have the filter value, use one of the following comparison operators: To search for values that include the filter value, use CONTAINS. For example, for the ResourceTags field, the filter Department CONTAINS Security matches findings that include the value Security for the Department tag. In the same example, a finding with a value of Security team for the Department tag is a match. To search for values that exactly match the filter value, use EQUALS. For example, for '
    OrganizationalUnitNotFoundException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    OcsfMapFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - resources.tags
          - compliance.control_parameters
          - databucket.tags
          - finding_info.tags
          description: The name of the field.
        Filter:
          $ref: '#/components/schemas/MapFilter'
    OcsfDateFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - finding_info.created_time_dt
          - finding_info.first_seen_time_dt
          - finding_info.last_seen_time_dt
          - finding_info.modified_time_dt
          - resources.image.created_time_dt
          - resources.image.last_used_time_dt
          - resources.modified_time_dt
          description: The name of the field.
        Filter:
          $ref: '#/components/schemas/DateFilter'
    GroupByRule:
      type: object
      properties:
        Filters:
          $ref: '#/components/schemas/OcsfFindingFilters'
        GroupByField:
          type: string
          enum:
          - activity_name
          - cloud.account.uid
          - cloud.provider
          - cloud.region
          - compliance.assessments.name
          - compliance.status
          - compliance.control
          - finding_info.title
          - finding_info.related_events.traits.category
          - finding_info.types
          - impact
          - likelihood
          - metadata.product.name
          - metadata.product.uid
          - resources.type
          - resources.cloud_partition
          - resources.criticality
          - resources.name
          - resources.owner.account.uid
          - resources.owner.org.uid
          - resources.owner.account.name
          - resources.provider
          - resources.region
          - resources.uid
          - severity
          - status
          - vulnerabilities.fix_coverage
          - class_name
          - vulnerabilities.affected_packages.name
          - finding_info.analytic.name
          - compliance.standards
          - cloud.account.name
          - vendor_attributes.severity
          - metadata.product.vendor_name
          description: The attribute by which filtered findings should be grouped.
      required:
      - GroupByField
    SortCriterion:
      type: object
      properties:
        Field:
          type: string
          description: The finding attribute used to sort findings.
        SortOrder:
          type: string
          enum:
          - asc
          - desc
          description: The order used to sort findings.
    DateRange:
      type: object
      properties:
        Value:
          type: integer
          description: A date range value for the date filter.
        Unit:
          type: string
          enum:
          - DAYS
          description: A date range unit for the date filter.
        Comparison:
          type: string
          enum:
          - WITHIN
          - OLDER_THAN
          description: The condition to apply to a date range filter. If you specify WITHIN, Security Hub filters for dates within the specified date range. If you specify OLDER_THAN, Security Hub filters for dates before the specified date range. If you don't specify a value, the default is WITHIN.
    GetFindingStatisticsV2Response:
      type: object
      properties:
        GroupByResults:
          type: array
          items:
            $ref: '#/components/schemas/GroupByResult'
          description: Aggregated statistics about security findings based on specified grouping criteria.
    BatchUpdateFindingsV2Response:
      type: object
      properties:
        ProcessedFindings:
          type: array
          items:
            $ref: '#/components/schemas/BatchUpdateFindingsV2ProcessedFinding'
          description: The list of findings that were updated successfully.
        UnprocessedFindings:
          type: array
          items:
            $ref: '#/components/schemas/BatchUpdateFindingsV2UnprocessedFinding'
          description: The list of V2 findings that were not updated.
      required:
      - ProcessedFindings
      - UnprocessedFindings
    CompositeFilter:
      type: object
      properties:
        StringFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfStringFilter'
          description: Enables filtering based on string field values.
        DateFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfDateFilter'
          description: Enables filtering based on date and timestamp fields.
        BooleanFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfBooleanFilter'
          description: Enables filtering based on boolean field values.
        NumberFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfNumberFilter'
          description: Enables filtering based on numerical field values.
        MapFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfMapFilter'
          description: Enables filtering based on map field values.
        IpFilters:
          type: array
          items:
            $ref: '#/components/schemas/OcsfIpFilter'
          description: A list of IP address filters that allowing you to filter findings based on IP address properties.
        NestedCompositeFilters:
          type: array
          items:
            $ref: '#/components/schemas/CompositeFilter'
          description: Provides an additional level of filtering, creating a three-layer nested structure. The first layer is a CompositeFilters array with a CompositeOperator (AND/OR). The second layer is a CompositeFilter object that contains direct filters and NestedCompositeFilters. The third layer is NestedCompositeFilters, which contains additional filter conditions.
        Operator:
          type: string
          enum:
          - AND
          - OR
          description: The logical operator used to combine multiple filter conditions.
    StringFilter:
      type: object
      properties:
        Value:
          type: string
          description: The string filter value. Filter values are case sensitive. For example, the product name for control-based findings is Security Hub CSPM. If you provide security hub as the filter value, there's no match.
        Comparison:
          type: string
          enum:
          - EQUALS
          - PREFIX
          - NOT_EQUALS
          - PREFIX_NOT_EQUALS
          - CONTAINS
          - NOT_CONTAINS
          - CONTAINS_WORD
          description: 'The condition to apply to a string value when filtering Security Hub CSPM findings. To search for values that have the filter value, use one of the following comparison operators: To search for values that include the filter value, use CONTAINS. For example, the filter Title CONTAINS CloudFront matches findings that have a Title that includes the string CloudFront. To search for values that contain a word matching the filter value, regardless of case, use CONTAINS_WORD. For example, the filter Title CONTAINS_WORD lambda matches a finding whose Title is GuardDuty Lambda Protection, because the '
    IpFilter:
      type: object
      properties:
        Cidr:
          type: string
          description: A finding's CIDR value.
    ConflictException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    OcsfStringFilter:
      type: object
      properties:
        FieldName:
          type: string
          enum:
          - metadata.uid
          - activity_name
          - cloud.account.uid
          - cloud.provider
          - cloud.region
          - compliance.assessments.category
          - compliance.assessments.name
          - compliance.control
          - compliance.status
          - compliance.standards
          - finding_info.desc
          - finding_info.src_url
          - finding_info.title
          - finding_info.types
          - finding_info.uid
          - finding_info.related_events.traits.category
          - finding_info.related_events.uid
          - finding_info.related_events.product.uid
          - finding_info.related_events.title
          - impact
          - likelihood
          - metadata.product.name
          - metadata.product.uid
          - metadata.product.vendor_name
          - remediation.desc
          - remediation.references
          - resources.cloud_partition
          - resources.criticality
          - resources.name
          - resources.owner.account.uid
          - resources.owner.org.uid
          - resources.owner.account.name
          - resources.provider
          - resources.region
          - resources.type
          - resources.uid
          - severity
          - status
          - comment
          - vulnerabilities.fix_coverage
          - class_name
          - databucket.encryption_details.algorithm
          - databucket.encryption_details.key_uid
          - databucket.file.data_classifications.classifier_details.type
          - evidences.actor.user.account.uid
          - evidences.api.operation
          - evidences.api.response.error_message
          - evidences.api.service.name
          - evidences.connection_info.direction
          - evidences.connection_info.protocol_name
          - evidences.dst_endpoint.autonomous_system.name
          - evidences.dst_endpoint.location.city
          - evidences.dst_endpoint.location.country
          - evidences.src_endpoint.autonomous_system.name
          - evidences.src_endpoint.hostname
          - evidences.src_endpoint.location.city
          - evidences.src_endpoint.location.country
          - finding_info.analytic.name
          - malware.name
          - malware_scan_info.uid
          - malware.severity
          - resources.cloud_function.layers.uid_alt
          - resources.cloud_function.runtime
          - resources.cloud_function.user.uid
          - resources.device.encryption_details.key_uid
          - resources.device.image.uid
          - resources.image.architecture
          - resources.image.registry_uid
          - resources.image.repository_name
          - resources.image.uid
          - resources.subnet_info.uid
          - resources.vpc_uid
          - vulnerabilities.affected_code.file.path
          - vulnerabilities.affected_packages.name
          - vulnerabilities.cve.epss.score
          - vulnerabilities.cve.uid
          - vulnerabilities.related_vulnerabilities
          - cloud.account.name
          - vendor_attributes.severity
          description: The name of the field.
        Filter:
          $ref: '#/components/schemas/StringFilter'
    NumberFilter:
      type: object
      properties:
        Gte:
          type: number
          description: The greater-than-equal condition to be applied to a single field when querying for findings.
        Lte:
          type: number
          description: The less-than-equal condition to be applied to a single field when querying for findings.
        Eq:
          type: number
          description: The equal-to condition to be applied to a single field when querying for findings.
        Gt:
          type: number
          description: The greater-than condition to be applied to a single field when querying for findings.
        Lt:
          type: number
          description: The less-than condition to be applied to a single field when querying for findings.
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
  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: securityhub
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/securityhub/service/2018-10-26/securityhub-2018-10-26.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)