:doc:`SecurityHub <../../securityhub>` / Client / create_automation_rule_v2

*************************
create_automation_rule_v2
*************************



.. py:method:: SecurityHub.Client.create_automation_rule_v2(**kwargs)

  

  Creates a V2 automation rule.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/securityhub-2018-10-26/CreateAutomationRuleV2>`_  


  **Request Syntax**
  ::

    response = client.create_automation_rule_v2(
        RuleName='string',
        RuleStatus='ENABLED'|'DISABLED',
        Description='string',
        RuleOrder=...,
        Criteria={
            'OcsfFindingCriteria': {
                'CompositeFilters': [
                    {
                        'StringFilters': [
                            {
                                'FieldName': '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'|'metadata.product.name'|'metadata.product.uid'|'metadata.product.vendor_name'|'remediation.desc'|'remediation.references'|'resources.cloud_partition'|'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',
                                'Filter': {
                                    'Value': 'string',
                                    'Comparison': 'EQUALS'|'PREFIX'|'NOT_EQUALS'|'PREFIX_NOT_EQUALS'|'CONTAINS'|'NOT_CONTAINS'|'CONTAINS_WORD'
                                }
                            },
                        ],
                        'DateFilters': [
                            {
                                'FieldName': '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',
                                'Filter': {
                                    'Start': 'string',
                                    'End': 'string',
                                    'DateRange': {
                                        'Value': 123,
                                        'Unit': 'DAYS'
                                    }
                                }
                            },
                        ],
                        'BooleanFilters': [
                            {
                                'FieldName': 'compliance.assessments.meets_criteria'|'vulnerabilities.is_exploit_available'|'vulnerabilities.is_fix_available',
                                'Filter': {
                                    'Value': True|False
                                }
                            },
                        ],
                        'NumberFilters': [
                            {
                                'FieldName': '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',
                                'Filter': {
                                    'Gte': 123.0,
                                    'Lte': 123.0,
                                    'Eq': 123.0,
                                    'Gt': 123.0,
                                    'Lt': 123.0
                                }
                            },
                        ],
                        'MapFilters': [
                            {
                                'FieldName': 'resources.tags'|'compliance.control_parameters'|'databucket.tags'|'finding_info.tags',
                                'Filter': {
                                    'Key': 'string',
                                    'Value': 'string',
                                    'Comparison': 'EQUALS'|'NOT_EQUALS'|'CONTAINS'|'NOT_CONTAINS'
                                }
                            },
                        ],
                        'IpFilters': [
                            {
                                'FieldName': 'evidences.dst_endpoint.ip'|'evidences.src_endpoint.ip',
                                'Filter': {
                                    'Cidr': 'string'
                                }
                            },
                        ],
                        'NestedCompositeFilters': {'... recursive ...'},
                        'Operator': 'AND'|'OR'
                    },
                ],
                'CompositeOperator': 'AND'|'OR'
            }
        },
        Actions=[
            {
                'Type': 'FINDING_FIELDS_UPDATE'|'EXTERNAL_INTEGRATION',
                'FindingFieldsUpdate': {
                    'SeverityId': 123,
                    'Comment': 'string',
                    'StatusId': 123
                },
                'ExternalIntegrationConfiguration': {
                    'ConnectorArn': 'string'
                }
            },
        ],
        Tags={
            'string': 'string'
        },
        ClientToken='string'
    )
    
  :type RuleName: string
  :param RuleName: **[REQUIRED]** 

    The name of the V2 automation rule.

    

  
  :type RuleStatus: string
  :param RuleStatus: 

    The status of the V2 automation rule.

    

  
  :type Description: string
  :param Description: **[REQUIRED]** 

    A description of the V2 automation rule.

    

  
  :type RuleOrder: float
  :param RuleOrder: **[REQUIRED]** 

    The value for the rule priority.

    

  
  :type Criteria: dict
  :param Criteria: **[REQUIRED]** 

    The filtering type and configuration of the automation rule.

    .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``OcsfFindingCriteria``. 

  
    - **OcsfFindingCriteria** *(dict) --* 

      The filtering conditions that align with OCSF standards.

      

    
      - **CompositeFilters** *(list) --* 

        Enables the creation of complex filtering conditions by combining filter criteria.

        

      
        - *(dict) --* 

          Enables the creation of filtering criteria for security findings.

          

        
          - **StringFilters** *(list) --* 

            Enables filtering based on string field values.

            

          
            - *(dict) --* 

              Enables filtering of security findings based on string field values in OCSF.

              

            
              - **FieldName** *(string) --* 

                The name of the field.

                

              
              - **Filter** *(dict) --* 

                A string filter for filtering Security Hub findings.

                

              
                - **Value** *(string) --* 

                  The string filter value. Filter values are case sensitive. For example, the product name for control-based findings is ``Security Hub``. If you provide ``security hub`` as the filter value, there's no match.

                  

                
                - **Comparison** *(string) --* 

                  The condition to apply to a string value when filtering Security Hub 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 exactly match the filter value, use ``EQUALS``. For example, the filter ``AwsAccountId EQUALS 123456789012`` only matches findings that have an account ID of ``123456789012``.
                   
                  * To search for values that start with the filter value, use ``PREFIX``. For example, the filter ``ResourceRegion PREFIX us`` matches findings that have a ``ResourceRegion`` that starts with ``us``. A ``ResourceRegion`` that starts with a different value, such as ``af``, ``ap``, or ``ca``, doesn't match.
                  

                   

                  ``CONTAINS``, ``EQUALS``, and ``PREFIX`` filters on the same field are joined by ``OR``. A finding matches if it matches any one of those filters. For example, the filters ``Title CONTAINS CloudFront OR Title CONTAINS CloudWatch`` match a finding that includes either ``CloudFront``, ``CloudWatch``, or both strings in the title.

                   

                  To search for values that don’t have the filter value, use one of the following comparison operators:

                   

                  
                  * To search for values that exclude the filter value, use ``NOT_CONTAINS``. For example, the filter ``Title NOT_CONTAINS CloudFront`` matches findings that have a ``Title`` that excludes the string CloudFront.
                   
                  * To search for values other than the filter value, use ``NOT_EQUALS``. For example, the filter ``AwsAccountId NOT_EQUALS 123456789012`` only matches findings that have an account ID other than ``123456789012``.
                   
                  * To search for values that don't start with the filter value, use ``PREFIX_NOT_EQUALS``. For example, the filter ``ResourceRegion PREFIX_NOT_EQUALS us`` matches findings with a ``ResourceRegion`` that starts with a value other than ``us``.
                  

                   

                  ``NOT_CONTAINS``, ``NOT_EQUALS``, and ``PREFIX_NOT_EQUALS`` filters on the same field are joined by ``AND``. A finding matches only if it matches all of those filters. For example, the filters ``Title NOT_CONTAINS CloudFront AND Title NOT_CONTAINS CloudWatch`` match a finding that excludes both ``CloudFront`` and ``CloudWatch`` in the title.

                   

                  You can’t have both a ``CONTAINS`` filter and a ``NOT_CONTAINS`` filter on the same field. Similarly, you can't provide both an ``EQUALS`` filter and a ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filter on the same field. Combining filters in this way returns an error. ``CONTAINS`` filters can only be used with other ``CONTAINS`` filters. ``NOT_CONTAINS`` filters can only be used with other ``NOT_CONTAINS`` filters.

                   

                  You can combine ``PREFIX`` filters with ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filters for the same field. Security Hub first processes the ``PREFIX`` filters, and then the ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filters.

                   

                  For example, for the following filters, Security Hub first identifies findings that have resource types that start with either ``AwsIam`` or ``AwsEc2``. It then excludes findings that have a resource type of ``AwsIamPolicy`` and findings that have a resource type of ``AwsEc2NetworkInterface``.

                   

                  
                  * ``ResourceType PREFIX AwsIam``
                   
                  * ``ResourceType PREFIX AwsEc2``
                   
                  * ``ResourceType NOT_EQUALS AwsIamPolicy``
                   
                  * ``ResourceType NOT_EQUALS AwsEc2NetworkInterface``
                  

                   

                  ``CONTAINS`` and ``NOT_CONTAINS`` operators can be used only with automation rules V1. ``CONTAINS_WORD`` operator is only supported in ``GetFindingsV2``, ``GetFindingStatisticsV2``, ``GetResourcesV2``, and ``GetResourceStatisticsV2`` APIs. For more information, see `Automation rules <https://docs.aws.amazon.com/securityhub/latest/userguide/automation-rules.html>`__ in the *Security Hub User Guide*.

                  

                
              
            
        
          - **DateFilters** *(list) --* 

            Enables filtering based on date and timestamp fields.

            

          
            - *(dict) --* 

              Enables filtering of security findings based on date and timestamp fields in OCSF.

              

            
              - **FieldName** *(string) --* 

                The name of the field.

                

              
              - **Filter** *(dict) --* 

                A date filter for querying findings.

                

              
                - **Start** *(string) --* 

                  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, see `Timestamps <https://docs.aws.amazon.com/securityhub/1.0/APIReference/Welcome.html#timestamps>`__.

                  

                
                - **End** *(string) --* 

                  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, see `Timestamps <https://docs.aws.amazon.com/securityhub/1.0/APIReference/Welcome.html#timestamps>`__.

                  

                
                - **DateRange** *(dict) --* 

                  A date range for the date filter.

                  

                
                  - **Value** *(integer) --* 

                    A date range value for the date filter.

                    

                  
                  - **Unit** *(string) --* 

                    A date range unit for the date filter.

                    

                  
                
              
            
        
          - **BooleanFilters** *(list) --* 

            Enables filtering based on boolean field values.

            

          
            - *(dict) --* 

              Enables filtering of security findings based on boolean field values in OCSF.

              

            
              - **FieldName** *(string) --* 

                The name of the field.

                

              
              - **Filter** *(dict) --* 

                Boolean filter for querying findings.

                

              
                - **Value** *(boolean) --* 

                  The value of the boolean.

                  

                
              
            
        
          - **NumberFilters** *(list) --* 

            Enables filtering based on numerical field values.

            

          
            - *(dict) --* 

              Enables filtering of security findings based on numerical field values in OCSF.

              

            
              - **FieldName** *(string) --* 

                The name of the field.

                

              
              - **Filter** *(dict) --* 

                A number filter for querying findings.

                

              
                - **Gte** *(float) --* 

                  The greater-than-equal condition to be applied to a single field when querying for findings.

                  

                
                - **Lte** *(float) --* 

                  The less-than-equal condition to be applied to a single field when querying for findings.

                  

                
                - **Eq** *(float) --* 

                  The equal-to condition to be applied to a single field when querying for findings.

                  

                
                - **Gt** *(float) --* 

                  The greater-than condition to be applied to a single field when querying for findings.

                  

                
                - **Lt** *(float) --* 

                  The less-than condition to be applied to a single field when querying for findings.

                  

                
              
            
        
          - **MapFilters** *(list) --* 

            Enables filtering based on map field values.

            

          
            - *(dict) --* 

              Enables filtering of security findings based on map field values in OCSF.

              

            
              - **FieldName** *(string) --* 

                The name of the field.

                

              
              - **Filter** *(dict) --* 

                A map filter for filtering Security Hub findings. Each map filter provides the field to check for, the value to check for, and the comparison operator.

                

              
                - **Key** *(string) --* 

                  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** *(string) --* 

                  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** *(string) --* 

                  The condition to apply to the key value when filtering Security Hub 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 the ``ResourceTags`` field, the filter ``Department EQUALS Security`` matches findings that have the value ``Security`` for the ``Department`` tag.
                  

                   

                  ``CONTAINS`` and ``EQUALS`` filters on the same field are joined by ``OR``. A finding matches if it matches any one of those filters. For example, the filters ``Department CONTAINS Security OR Department CONTAINS Finance`` match a finding that includes either ``Security``, ``Finance``, or both values.

                   

                  To search for values that don't have the filter value, use one of the following comparison operators:

                   

                  
                  * To search for values that exclude the filter value, use ``NOT_CONTAINS``. For example, for the ``ResourceTags`` field, the filter ``Department NOT_CONTAINS Finance`` matches findings that exclude the value ``Finance`` for the ``Department`` tag.
                   
                  * To search for values other than the filter value, use ``NOT_EQUALS``. For example, for the ``ResourceTags`` field, the filter ``Department NOT_EQUALS Finance`` matches findings that don’t have the value ``Finance`` for the ``Department`` tag.
                  

                   

                  ``NOT_CONTAINS`` and ``NOT_EQUALS`` filters on the same field are joined by ``AND``. A finding matches only if it matches all of those filters. For example, the filters ``Department NOT_CONTAINS Security AND Department NOT_CONTAINS Finance`` match a finding that excludes both the ``Security`` and ``Finance`` values.

                   

                  ``CONTAINS`` filters can only be used with other ``CONTAINS`` filters. ``NOT_CONTAINS`` filters can only be used with other ``NOT_CONTAINS`` filters.

                   

                  You can’t have both a ``CONTAINS`` filter and a ``NOT_CONTAINS`` filter on the same field. Similarly, you can’t have both an ``EQUALS`` filter and a ``NOT_EQUALS`` filter on the same field. Combining filters in this way returns an error.

                   

                  ``CONTAINS`` and ``NOT_CONTAINS`` operators can be used only with automation rules. For more information, see `Automation rules <https://docs.aws.amazon.com/securityhub/latest/userguide/automation-rules.html>`__ in the *Security Hub User Guide*.

                  

                
              
            
        
          - **IpFilters** *(list) --* 

            A list of IP address filters that allowing you to filter findings based on IP address properties.

            

          
            - *(dict) --* 

              The structure for filtering findings based on IP address attributes.

              

            
              - **FieldName** *(string) --* 

                The name of the IP address field to filter on.

                

              
              - **Filter** *(dict) --* 

                The IP filter for querying findings.

                

              
                - **Cidr** *(string) --* 

                  A finding's CIDR value.

                  

                
              
            
        
          - **NestedCompositeFilters** *(list) --* 

            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** *(string) --* 

            The logical operator used to combine multiple filter conditions.

            

          
        
    
      - **CompositeOperator** *(string) --* 

        The logical operators used to combine the filtering on multiple ``CompositeFilters``.

        

      
    
  
  :type Actions: list
  :param Actions: **[REQUIRED]** 

    A list of actions to be performed when the rule criteria is met.

    

  
    - *(dict) --* 

      Allows you to configure automated responses.

      

    
      - **Type** *(string) --* **[REQUIRED]** 

        The category of action to be executed by the automation rule.

        

      
      - **FindingFieldsUpdate** *(dict) --* 

        The changes to be applied to fields in a security finding when an automation rule is triggered.

        

      
        - **SeverityId** *(integer) --* 

          The severity level to be assigned to findings that match the automation rule criteria.

          

        
        - **Comment** *(string) --* 

          Notes or contextual information for findings that are modified by the automation rule.

          

        
        - **StatusId** *(integer) --* 

          The status to be applied to findings that match automation rule criteria.

          

        
      
      - **ExternalIntegrationConfiguration** *(dict) --* 

        The settings for integrating automation rule actions with external systems or service.

        

      
        - **ConnectorArn** *(string) --* 

          The ARN of the connector that establishes the integration.

          

        
      
    

  :type Tags: dict
  :param Tags: 

    A list of key-value pairs associated with the V2 automation rule.

    

  
    - *(string) --* 

    
      - *(string) --* 

      


  :type ClientToken: string
  :param ClientToken: 

    A unique identifier used to ensure idempotency.

    This field is autopopulated if not provided.

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'RuleArn': 'string',
          'RuleId': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **RuleArn** *(string) --* 

        The ARN of the V2 automation rule.

        
      

      - **RuleId** *(string) --* 

        The ID of the V2 automation rule.

        
  
  **Exceptions**
  
  *   :py:class:`SecurityHub.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`SecurityHub.Client.exceptions.InternalServerException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ValidationException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ThrottlingException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ConflictException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ServiceQuotaExceededException`

  