:doc:`NetworkFirewall <../../network-firewall>` / Client / start_flow_capture

******************
start_flow_capture
******************



.. py:method:: NetworkFirewall.Client.start_flow_capture(**kwargs)

  

  Begins capturing the flows in a firewall, according to the filters you define. Captures are similar, but not identical to snapshots. Capture operations provide visibility into flows that are not closed and are tracked by a firewall's flow table. Unlike snapshots, captures are a time-boxed view.

   

  A flow is network traffic that is monitored by a firewall, either by stateful or stateless rules. For traffic to be considered part of a flow, it must share Destination, DestinationPort, Direction, Protocol, Source, and SourcePort.

   

  .. note::

    

    To avoid encountering operation limits, you should avoid starting captures with broad filters, like wide IP ranges. Instead, we recommend you define more specific criteria with ``FlowFilters``, like narrow IP ranges, ports, or protocols.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/network-firewall-2020-11-12/StartFlowCapture>`_  


  **Request Syntax**
  ::

    response = client.start_flow_capture(
        FirewallArn='string',
        AvailabilityZone='string',
        VpcEndpointAssociationArn='string',
        VpcEndpointId='string',
        MinimumFlowAgeInSeconds=123,
        FlowFilters=[
            {
                'SourceAddress': {
                    'AddressDefinition': 'string'
                },
                'DestinationAddress': {
                    'AddressDefinition': 'string'
                },
                'SourcePort': 'string',
                'DestinationPort': 'string',
                'Protocols': [
                    'string',
                ]
            },
        ]
    )
    
  :type FirewallArn: string
  :param FirewallArn: **[REQUIRED]** 

    The Amazon Resource Name (ARN) of the firewall.

    

  
  :type AvailabilityZone: string
  :param AvailabilityZone: 

    The ID of the Availability Zone where the firewall is located. For example, ``us-east-2a``.

     

    Defines the scope a flow operation. You can use up to 20 filters to configure a single flow operation.

    

  
  :type VpcEndpointAssociationArn: string
  :param VpcEndpointAssociationArn: 

    The Amazon Resource Name (ARN) of a VPC endpoint association.

    

  
  :type VpcEndpointId: string
  :param VpcEndpointId: 

    A unique identifier for the primary endpoint associated with a firewall.

    

  
  :type MinimumFlowAgeInSeconds: integer
  :param MinimumFlowAgeInSeconds: 

    The reqested ``FlowOperation`` ignores flows with an age (in seconds) lower than ``MinimumFlowAgeInSeconds``. You provide this for start commands.

     

    .. note::

      

      We recommend setting this value to at least 1 minute (60 seconds) to reduce chance of capturing flows that are not yet established.

      

    

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

    Defines the scope a flow operation. You can use up to 20 filters to configure a single flow operation.

    

  
    - *(dict) --* 

      Defines the scope a flow operation. You can use up to 20 filters to configure a single flow operation.

      

    
      - **SourceAddress** *(dict) --* 

        A single IP address specification. This is used in the  MatchAttributes source and destination specifications.

        

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

          Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.

           

          Examples:

           

          
          * To configure Network Firewall to inspect for the IP address 192.0.2.44, specify ``192.0.2.44/32``.
           
          * To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify ``192.0.2.0/24``.
           
          * To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify ``1111:0000:0000:0000:0000:0000:0000:0111/128``.
           
          * To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify ``1111:0000:0000:0000:0000:0000:0000:0000/64``.
          

           

          For more information about CIDR notation, see the Wikipedia entry `Classless Inter-Domain Routing <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>`__.

          

        
      
      - **DestinationAddress** *(dict) --* 

        A single IP address specification. This is used in the  MatchAttributes source and destination specifications.

        

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

          Specify an IP address or a block of IP addresses in Classless Inter-Domain Routing (CIDR) notation. Network Firewall supports all address ranges for IPv4 and IPv6.

           

          Examples:

           

          
          * To configure Network Firewall to inspect for the IP address 192.0.2.44, specify ``192.0.2.44/32``.
           
          * To configure Network Firewall to inspect for IP addresses from 192.0.2.0 to 192.0.2.255, specify ``192.0.2.0/24``.
           
          * To configure Network Firewall to inspect for the IP address 1111:0000:0000:0000:0000:0000:0000:0111, specify ``1111:0000:0000:0000:0000:0000:0000:0111/128``.
           
          * To configure Network Firewall to inspect for IP addresses from 1111:0000:0000:0000:0000:0000:0000:0000 to 1111:0000:0000:0000:ffff:ffff:ffff:ffff, specify ``1111:0000:0000:0000:0000:0000:0000:0000/64``.
          

           

          For more information about CIDR notation, see the Wikipedia entry `Classless Inter-Domain Routing <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>`__.

          

        
      
      - **SourcePort** *(string) --* 

        The source port to inspect for. You can specify an individual port, for example ``1994`` and you can specify a port range, for example ``1990:1994``. To match with any port, specify ``ANY``.

        

      
      - **DestinationPort** *(string) --* 

        The destination port to inspect for. You can specify an individual port, for example ``1994`` and you can specify a port range, for example ``1990:1994``. To match with any port, specify ``ANY``.

        

      
      - **Protocols** *(list) --* 

        The protocols to inspect for, specified using the assigned internet protocol number (IANA) for each protocol. If not specified, this matches with any protocol.

        

      
        - *(string) --* 

        
    
    

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

    
    ::

      {
          'FirewallArn': 'string',
          'FlowOperationId': 'string',
          'FlowOperationStatus': 'COMPLETED'|'IN_PROGRESS'|'FAILED'|'COMPLETED_WITH_ERRORS'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **FirewallArn** *(string) --* 

        The Amazon Resource Name (ARN) of the firewall.

        
      

      - **FlowOperationId** *(string) --* 

        A unique identifier for the flow operation. This ID is returned in the responses to start and list commands. You provide to describe commands.

        
      

      - **FlowOperationStatus** *(string) --* 

        Returns the status of the flow operation. This string is returned in the responses to start, list, and describe commands.

         

        If the status is ``COMPLETED_WITH_ERRORS``, results may be returned with any number of ``Flows`` missing from the response. If the status is ``FAILED``, ``Flows`` returned will be empty.

        
  
  **Exceptions**
  
  *   :py:class:`NetworkFirewall.Client.exceptions.InvalidRequestException`

  
  *   :py:class:`NetworkFirewall.Client.exceptions.InternalServerError`

  
  *   :py:class:`NetworkFirewall.Client.exceptions.ResourceNotFoundException`

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

  