### Install flowcontainer

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Install the flowcontainer library using pip.

```bash
pip3 install flowcontainer
```

--------------------------------

### SSL/TLS Traffic Analysis Example

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This example demonstrates extracting SSL/TLS information, including SNI, cipher suites, and X.509 certificate details. Ensure the traffic captured is SSL/TLS.

```json
{
'pcapname': 'tid_ssl.pcap',
'src_ip': '119.78.131.162',
'sport': 50665,
'dst_ip': '23.56.20.10',
'dport': 443,
'protocol': 'tcp',
'ext_proto': 'TLSv1.2',
'start': 1597319999.645109,
'end': 1597319999.732076,
'sni': 'c.go-mpulse.net',
'cipher_suites': '49192,49191,49172,49171,159,158,57,51,157,156,61,60,53,47,49196,49195,49188,49187,49162,49161,106,64,56,50,10,19|49196',
'certificates': [
  {
    'issuer': {
      'countryName': 'US',
      'organizationName': 'DigiCert Inc',
      'organizationalUnitName': 'www.digicert.com',
      'commonName': 'DigiCert Secure Site ECC CA-1'
    },
    'subject': {
      'countryName': 'US',
      'stateOrProvinceName': 'Massachusetts',
      'localityName': 'Cambridge',
      'organizationName': 'Akamai Technologies',
      'organizationalUnitName': 'SOASTA',
      'commonName': 'akstat.io'
    },
    'not_valid_before': '2020-05-06 00:00:00',
    'not_valid_after': '2021-08-05 12:00:00',
    'seriral_number': 12148336732659377462193089635366108055,
    'version': 'v3'
  },
  {
    'issuer': {
      'countryName': 'US',
      'organizationName': 'DigiCert Inc',
      'organizationalUnitName': 'www.digicert.com',
      'commonName': 'DigiCert Global Root CA'
    },
    'subject': {
      'countryName': 'US',
      'organizationName': 'DigiCert Inc',
      'organizationalUnitName': 'www.digicert.com',
      'commonName': 'DigiCert Secure Site ECC CA-1'
    },
    'not_valid_before': '2019-02-15 12:45:24',
    'not_valid_after': '2029-02-15 12:45:24',
    'seriral_number': 15099003683604006848814258862226398944,
    'version': 'v3'
  }
]
}
```

--------------------------------

### HTTP Traffic Analysis Example

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This example demonstrates how to extract HTTP-specific information such as User-Agent and full request URI from network traffic. Ensure your environment can process HTTP traffic.

```json
{
'pcapname': 'nat.pcap',
'src_ip': '172.16.30.159',
'sport': 46648,
'dst_ip': '61.149.22.99',
'dport': 80,
'protocol': 'tcp',
'ext_proto': 'HTTP',
'start': 1521603003.580238,
'end': 1521603003.580238,
'http.user_agent': 'NeteaseMusic/5.0.0.1520384820(115);Dalvik/2.1.0 (Linux; U; Android 8.0.0; STF-AL00 Build/HUAWEISTF-AL00)',
'http.request.full_uri': 'http://p2.music.126.net/SbJn22gsq-Pv6WLm8PK98A==/564049465093755.jpg?imageView=1&thumbnail=360z360&type=webp&quality=80',
'http.host': 'p2.music.126.net'
}
```

--------------------------------

### DNS Traffic Analysis Example

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This example shows how to parse DNS records, specifically A records, from DNS traffic. It is useful for analyzing DNS queries and responses.

```json
{
'pcapname': 'dns.pcapng',
'src_ip': '192.168.172.51',
'sport': 51518,
'dst_ip': '8.8.8.8',
'dport': 53,
'protocol': 'udp',
'ext_proto': 'DNS',
'start': 1669704818,
'end': 1669704818,
'dns_records': [
  {
    'NAME': 'dns.google',
    'TYPE': 'A',
    'ADDRESS': '8.8.8.8'
  },
  {
    'NAME': 'dns.google',
    'TYPE': 'A',
    'ADDRESS': '8.8.4.4'
  }
]
}
```

--------------------------------

### Access Flow Start and End Timestamps

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Get the start and end timestamps of a flow using `time_start` and `time_end` attributes. These are derived from the timestamps of the valid payload sequences.

```python
    print('start timestamp :',value.time_start)
    print('end timestamp :',value.time_end)
```

--------------------------------

### Example Output of Flow Extraction

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This section displays the expected output format when running the basic flow extraction example. It shows the detailed information captured for both UDP and TCP flows, including source and destination IPs, ports, and various packet length and timestamp sequences.

```text
Flow ('1592993485_noise.pcap', 'udp', '150') info:
src ip: 192.168.0.100
dst ip: 223.111.239.177
sport: 44738
dport: 1516
payload lengths : [44, 44, 44, 44, 44, 44, 44, 44, 44, 44]
payload timestamps: [1592993550.021676, 1592993550.136188, 1592993550.258189, 1592993550.543668, 1592993550.646864, 1592993550.76075, 1592993550.866083, 1592993550.969658, 1592993551.071932, 1592993551.179754]
ip packets lengths: [64, 64, 64, 64, 64, 64, 64, 64, 64, 64]
ip packets timestamps: [1592993550.021676, 1592993550.136188, 1592993550.258189, 1592993550.543668, 1592993550.646864, 1592993550.76075, 1592993550.866083, 1592993550.969658, 1592993551.071932, 1592993551.179754]
default length sequence: [44, 44, 44, 44, 44, 44, 44, 44, 44, 44]
default timestamp sequence: [1592993550.021676, 1592993550.136188, 1592993550.258189, 1592993550.543668, 1592993550.646864, 1592993550.76075, 1592993550.866083, 1592993550.969658, 1592993551.071932, 1592993551.179754]
start timestamp:1592993550.021676, end timestamp :1592993551.179754
proto: UDP
extension: {}
Flow ('1592993485_noise.pcap', 'tcp', '94') info:
src ip: 192.168.0.100
dst ip: 164.90.117.68
sport: 42930
dport: 443
payload lengths : [213, -1448, -600, -816, -1448, -600, -832, -289, 126, -343]
payload timestamps: [1592993550.690015, 1592993551.035379, 1592993551.035632, 1592993551.035762, 1592993551.037588, 1592993551.037816, 1592993551.037952, 1592993551.03886, 1592993551.044419, 1592993551.08717]
ip packets lengths: [60, -60, 52, 265, -52, -1500, 52, -652, 52, -868, 52, -1500, 52, -652, 52, -884, 52, -341, 52, 178, -52, -395, 52, 52]
ip packets timestamps: [1592993550.677152, 1592993550.688842, 1592993550.689094, 1592993550.690015, 1592993550.69185, 1592993551.035379, 1592993551.035582, 1592993551.035632, 1592993551.035708, 1592993551.035762, 1592993551.035871, 1592993551.037588, 1592993551.037759, 1592993551.037816, 1592993551.037916, 1592993551.037952, 1592993551.038041, 1592993551.03886, 1592993551.039023, 1592993551.044419, 1592993551.046253, 1592993551.08717, 1592993551.12293, 1592993552.929707]
default length sequence: [213, -1448, -600, -816, -1448, -600, -832, -289, 126, -343]
default timestamp sequence: [1592993550.690015, 1592993551.035379, 1592993551.035632, 1592993551.035762, 1592993551.037588, 1592993551.037816, 1592993551.037952, 1592993551.03886, 1592993551.044419, 1592993551.08717]
start timestamp:1592993550.690015, end timestamp :1592993551.08717
proto: TLSv1.2|TCP
extension: {}

```

--------------------------------

### Verify tshark Availability and Path

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Ensures tshark is installed and accessible, with version >= 2.6.0 (>= 3.0.0 for SNI extraction). Uses absolute paths for the 'extract' function if tshark is not in the system's PATH.

```bash
# 验证 tshark 可用性
tshark --version   # 需要 >= 2.6.0（提取 SNI 需要 >= 3.0.0）

# 使用绝对路径调用 extract
result = extract(infile="/absolute/path/to/traffic.pcap", filter="tcp or udp")
```

--------------------------------

### Examine full IP packet sequences including handshake

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Use `ip_lengths` and `ip_timestamps` to get sequences for all IP packets, including handshake and ACK packets. This provides more complete connection information than `payload_*` sequences, useful for analyzing TCP handshake behavior.

```python
from flowcontainer.extractor import extract

result = extract("traffic.pcap", filter="tcp", extension=[])

for key, flow in result.items():
    ip_lens  = flow.ip_lengths      # 含空载荷包（握手、ACK 等）
    pay_lens = flow.payload_lengths # 仅含非零载荷包

    # IP 包序列比载荷序列更长（包含握手包）
    print(f"IP包数量:   {len(ip_lens)}")
    print(f"载荷包数量: {len(pay_lens)}")
    print(f"IP包长度序列（前10）: {ip_lens[:10]}")

    # 提取握手阶段（载荷为0的IP包）
    handshake_pkts = [(l, t) for l, t in zip(flow.ip_lengths, flow.ip_timestamps)
                      if abs(l) <= 60]  # TCP SYN/ACK 通常 ≤ 60 字节
    print(f"疑似握手包数: {len(handshake_pkts)}")
```

--------------------------------

### Extract network flows with extensions

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Use the `extract` function to get flow information, including custom Wireshark fields like TLS SNI and cipher suite. Set `verbose=True` for detailed output during extraction.

```python
from flowcontainer.extractor import extract

# 基本用法：提取 TCP/UDP 流，同时提取 TLS SNI 和加密套件
result = extract(
    infile="traffic.pcap",
    filter="(tcp or udp)",
    extension=["tls.handshake.extensions_server_name", "tls.handshake.ciphersuite"],
    verbose=True
)

for key in result:
    flow = result[key]
    # key 示例: ('traffic.pcap', 'tcp', '1')
    print(f"流标识: {key}")
    print(f"  源 IP:端口  = {flow.src}:{flow.sport}")
    print(f"  目的 IP:端口 = {flow.dst}:{flow.dport}")
    print(f"  协议类型     = {flow.ext_protocol}")        # 如 'TLSv1.2|TCP'
    print(f"  开始时间     = {flow.time_start}")
    print(f"  结束时间     = {flow.time_end}")
    print(f"  载荷长度序列 = {flow.payload_lengths}")     # 正数=C->S，负数=S->C
    print(f"  载荷时间序列 = {flow.payload_timestamps}")
    print(f"  IP包长序列   = {flow.ip_lengths}")
    print(f"  IP包时间序列 = {flow.ip_timestamps}")
    print(f"  扩展字段     = {flow.extension}")
```

--------------------------------

### Access Extended Protocol Information

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Retrieve the extended protocol information for a flow, such as DNS or TLS versions, using the `ext_protocol` attribute.

```python
    print("proto:", value.ext_protocol)
```

--------------------------------

### Access IP Packet Lengths and Timestamps

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Retrieve the sequence of IP packet lengths and their arrival timestamps, including packets with zero payload, using `ip_lengths` and `ip_timestamps`. Positive lengths indicate client-to-server traffic, negative indicate server-to-client.

```python
    ## access ip packet lengths, (including packets with zero payload, and ip header)
    print('ip packets lengths:',value.ip_lengths)
    ## access ip packet timestamp sequence, (including packets with zero payload)
    print('ip packets timestamps:',value.ip_timestamps)
```

--------------------------------

### Import and Extract Flow Data from PCAP

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Import the `extract` function and provide the path to a PCAP file. Optionally, specify filters and extension fields to extract. This is the primary function for initiating flow data extraction.

```python
__author__ = 'dk'
from flowcontainer.extractor import extract
result = extract(r"1592754322_clear.pcap",filter='',extension=["tls.handshake.extensions_server_name","tls.handshake.ciphersuite"])
```

--------------------------------

### Flow.ip_lengths / Flow.ip_timestamps

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Provides the sequence of lengths and timestamps for all IP packets in a flow, including those with zero payload (e.g., TCP handshake, ACK packets). This offers a more complete view of connection establishment and teardown.

```APIDOC
## Flow.ip_lengths / Flow.ip_timestamps — IP 数据包序列

### Description
返回流中**全部** IP 数据包的长度和时间戳序列，包含握手包、纯 ACK 等载荷为零的数据包。与 `payload_*` 序列的区别在于：IP 序列包含更完整的连接建立/拆除信息，适合需要分析 TCP 握手行为的场景。

### Parameters
This is a property of a `Flow` object returned by the `extract` function.

### Returns
- **ip_lengths** (list of int) - Sequence of all IP packet lengths in the flow.
- **ip_timestamps** (list of float) - Sequence of timestamps corresponding to the IP packet lengths.

### Request Example
```python
from flowcontainer.extractor import extract

result = extract("traffic.pcap", filter="tcp", extension=[])

for key, flow in result.items():
    ip_lens  = flow.ip_lengths      # 含空载荷包（握手、ACK 等）
    pay_lens = flow.payload_lengths # 仅含非零载荷包

    # IP 包序列比载荷序列更长（包含握手包）
    print(f"IP包数量:   {len(ip_lens)}")
    print(f"载荷包数量: {len(pay_lens)}")
    print(f"IP包长度序列（前10）: {ip_lens[:10]}")

    # 提取握手阶段（载荷为0的IP包）
    handshake_pkts = [(l, t) for l, t in zip(flow.ip_lengths, flow.ip_timestamps)
                      if abs(l) <= 60]  # TCP SYN/ACK 通常 ≤ 60 字节
    print(f"疑似握手包数: {len(handshake_pkts)}")
```

### Response Example
```
# 输出示例:
# IP包数量:   28
# 载荷包数量: 10
# IP包长度序列（前10）: [60, -60, 52, 232, -52, -1476, 52, -1492, 52, -242]
# 疑似握手包数: 12
```
```

--------------------------------

### Parse DNS Flows with FlowContainer

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Extracts DNS query names and response records (A, CNAME, NS) from DNS flows, organizing them into structured DNS records. Requires the 'flowcontainer' library and a PCAP file with DNS traffic.

```python
from flowcontainer import extractor
import os

def parse_dns_flows(pcap_file):
    result = extractor.extract(
        infile=pcap_file,
        filter="dns",
        extension=[
            "dns.qry.name",
            "dns.resp.name",
            "dns.resp.type",
            "dns.a",
            "dns.cname",
            "dns.ns",
        ]
    )
    type_map = {"1": "A", "5": "CNAME", "2": "NS"}
    flows = []
    for key, flow in result.items():
        ext = flow.extension
        try:
            types  = ext.get("dns.resp.type",  [[""]])[0][0].split(",")
            names  = ext.get("dns.resp.name",  [[""]])[0][0].split(",")
            addrs  = ext.get("dns.a",          [[""]])[0][0].split(",")
            cnames = ext.get("dns.cname",      [[""]])[0][0].split(",")

            records, addr_i, cname_i = [], 0, 0
            for i, t in enumerate(types):
                if t not in type_map: continue
                rec = {"NAME": names[i], "TYPE": type_map[t]}
                if t == "1":   rec["ADDRESS"] = addrs[addr_i];   addr_i += 1
                if t == "5":   rec["CNAME"]   = cnames[cname_i]; cname_i += 1
                records.append(rec)

            if records:
                flows.append({
                    "pcapname": os.path.basename(pcap_file),
                    "src_ip": flow.src, "sport": flow.sport,
                    "dst_ip": flow.dst, "dport": flow.dport,
                    "protocol": flow.protocol,
                    "start": int(flow.time_start),
                    "dns_records": records,
                })
        except Exception as e:
            print(f"解析异常: {e}")
    return flows

dns_flows = parse_dns_flows("dns.pcapng")
for f in dns_flows:
    print(f)

# 输出示例:
# {
#   'pcapname': 'dns.pcapng', 'src_ip': '192.168.172.51', 'sport': 51518,
#   'dst_ip': '8.8.8.8', 'dport': 53, 'protocol': 'udp',
#   'start': 1669704818,
#   'dns_records': [
#     {'NAME': 'dns.google', 'TYPE': 'A', 'ADDRESS': '8.8.8.8'},
#     {'NAME': 'dns.google', 'TYPE': 'A', 'ADDRESS': '8.8.4.4'}
#   ]
# }
```

--------------------------------

### Parse HTTP Flows with FlowContainer

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Extracts application-layer metadata like User-Agent, Request URI, Host, and Cookie from HTTP flows in a PCAP file. Requires the 'flowcontainer' library and a PCAP file with HTTP traffic.

```python
from flowcontainer import extractor
import os

def parse_http_flows(pcap_file):
    result = extractor.extract(
        infile=pcap_file,
        filter="http",
        extension=[
            "http.user_agent",
            "http.host",
            "http.request.full_uri",
            "http.cookie",
            "http.file_data",
        ]
    )
    flows = []
    for key, flow in result.items():
        ext = flow.extension
        record = {
            "pcapname": os.path.basename(pcap_file),
            "src_ip":   flow.src,   "sport": flow.sport,
            "dst_ip":   flow.dst,   "dport": flow.dport,
            "protocol": flow.protocol,
            "ext_proto": flow.ext_protocol,
            "start":    flow.time_start,
            "end":      flow.time_end,
        }
        if "http.user_agent"       in ext: record["user_agent"] = ext["http.user_agent"][0][0]
        if "http.request.full_uri" in ext: record["uri"]        = ext["http.request.full_uri"][0][0]
        if "http.host"             in ext: record["host"]       = ext["http.host"][0][0]
        if "http.cookie"           in ext: record["cookie"]     = ext["http.cookie"][0][0]
        flows.append(record)
    return flows

http_flows = parse_http_flows("nat.pcap")
for flow in http_flows:
    print(flow)

# 输出示例:
# {
#   'pcapname': 'nat.pcap', 'src_ip': '172.16.30.159', 'sport': 46648,
#   'dst_ip': '61.149.22.99', 'dport': 80, 'protocol': 'tcp', 'ext_proto': 'HTTP',
#   'start': 1521603003.580238, 'end': 1521603003.580238,
#   'user_agent': 'NeteaseMusic/5.0.0.1520384820(115);Dalvik/2.1.0 (Linux; U; Android 8.0.0; STF-AL00)',
#   'uri': 'http://p2.music.126.net/SbJn22gsq-Pv6WLm8PK98A==/564049465093755.jpg?...
#   'host': 'p2.music.126.net'
# }
```

--------------------------------

### Access Flow Payload Lengths and Timestamps

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Retrieve the sequence of payload lengths and their corresponding arrival timestamps using `payload_lengths` and `payload_timestamps` attributes. Positive lengths indicate client-to-server traffic, negative indicate server-to-client.

```python
## access payload packet lengths
    print('payload lengths :',value.payload_lengths)
    ## access payload packet timestamps sequence:
    print('payload timestamps:',value.payload_timestamps)
```

--------------------------------

### Basic Flow Extraction and Analysis in Python

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This snippet demonstrates the fundamental usage of the `extract` function to process a pcap file. It iterates through the results, accessing and printing various attributes of each flow object, such as IP addresses, ports, packet lengths, and timestamps. This is useful for initial network traffic inspection.

```python
__author__ = 'dk'
__author__ = 'dk'
#coding:utf8
import time
from flowcontainer.extractor import extract
stime = time.time()

result = extract(r"1592993485_noise.pcap",
                 filter='ip',
                 extension=[],
                 split_flag=False,
                 verbose=True
            )
for key in result:
    ### The return vlaue result is a dict, the key is a tuple (filename,procotol,stream_id)
    ### and the value is an Flow object, user can access Flow object as flowcontainer.flows.Flow's attributes refer.

    value = result[key]
    print('Flow {0} info:'.format(key))
    ## access ip src
    print('src ip:',value.src)
    ## access ip dst
    print('dst ip:',value.dst)
    ## access srcport
    print('sport:',value.sport)
    ## access_dstport
    print('dport:',value.dport)
    ## access payload packet lengths
    print('payload lengths :',value.payload_lengths)
    ## access payload packet timestamps sequence:
    print('payload timestamps:',value.payload_timestamps)
    ## access ip packet lengths, (including packets with zero payload, and ip header)
    print('ip packets lengths:',value.ip_lengths)
    ## access ip packet timestamp sequence, (including packets with zero payload)
    print('ip packets timestamps:',value.ip_timestamps)

    ## access default lengths sequence, the default length sequences is the payload lengths sequences
    print('default length sequence:',value.lengths)
    ## access default timestamp sequence, the default timestamp sequence is the payload timestamp sequences
    print('default timestamp sequence:',value.timestamps)

    print('start timestamp:{0}, end timestamp :{1}'.format(value.time_start,value.time_end))

    ## access the proto
    print('proto:', value.ext_protocol)
    ##access sni of the flow if any else empty str
    print('extension:',value.extension)

```

--------------------------------

### Access Default Length and Timestamp Sequences

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Access the default length and timestamp sequences, which by default correspond to the payload sequences, using the `lengths` and `timestamps` attributes. Positive lengths indicate client-to-server traffic, negative indicate server-to-client.

```python
    ## access default lengths sequence, the default length sequences is the payload lengths sequences
    print('default length sequence:',value.lengths)
    ## access default timestamp sequence, the default timestamp sequence is the payload timestamp sequences
    print('default timestamp sequence:',value.timestamps)
```

--------------------------------

### Access Flow Source and Destination Ports

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Access the source port using the `sport` attribute and the destination port using the `dport` attribute of the `Flow` object.

```python
## access srcport
    print('sport:',value.sport)
    ## access_dstport
    print('dport:',value.dport)
```

--------------------------------

### Access Extended Fields (e.g., SNI, Ciphersuites)

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Access custom-defined extension fields, such as SNI or ciphersuites, using the `extension` attribute. This attribute returns a dictionary where keys are the requested extension names and values are lists containing the extracted values and their corresponding packet indices.

```python
    ##access sni of the flow if any else empty str
    print('extension:',value.extension)
```

--------------------------------

### extract(infile, filter, extension, ip_layer, verbose, cmd_parameter, split_flag)

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

The core function to extract network flow information from a PCAP file. It returns a dictionary where keys are flow identifiers and values are Flow objects containing detailed flow data. Supports filtering, extension fields, and parallel parsing.

```APIDOC
## extract(infile, filter, extension, ip_layer, verbose, cmd_parameter, split_flag) — 核心提取函数

### Description
从指定 PCAP 文件中提取所有网络流信息，是整个库的唯一入口函数。返回值为字典，键为 `(文件名, 传输层协议, 流ID)` 三元组，值为 `Flow` 对象。`filter` 参数语义与 Wireshark 完全一致；`extension` 接受 Wireshark 字段名列表，用于提取默认字段之外的扩展信息；`split_flag=True` 时开启多线程并行解析，适合超大 PCAP 文件。

### Parameters
- **infile** (string) - Required - Path to the PCAP file.
- **filter** (string) - Optional - Wireshark-compatible filter string.
- **extension** (list of strings) - Optional - List of Wireshark field names for extended information.
- **ip_layer** (string) - Optional - Specifies the IP layer protocol (e.g., 'ipv4', 'ipv6').
- **verbose** (boolean) - Optional - If True, enables verbose output during extraction.
- **cmd_parameter** (string) - Optional - Additional command-line parameters for tshark.
- **split_flag** (boolean) - Optional - If True, enables multi-threaded parallel parsing for large PCAP files.

### Returns
- **dict** - A dictionary where keys are `(filename, transport_protocol, flow_id)` tuples and values are `Flow` objects.

### Request Example
```python
from flowcontainer.extractor import extract

# 基本用法：提取 TCP/UDP 流，同时提取 TLS SNI 和加密套件
result = extract(
    infile="traffic.pcap",
    filter="(tcp or udp)",
    extension=["tls.handshake.extensions_server_name", "tls.handshake.ciphersuite"],
    verbose=True
)

for key in result:
    flow = result[key]
    # key 示例: ('traffic.pcap', 'tcp', '1')
    print(f"流标识: {key}")
    print(f"  源 IP:端口  = {flow.src}:{flow.sport}")
    print(f"  目的 IP:端口 = {flow.dst}:{flow.dport}")
    print(f"  协议类型     = {flow.ext_protocol}")        # 如 'TLSv1.2|TCP'
    print(f"  开始时间     = {flow.time_start}")
    print(f"  结束时间     = {flow.time_end}")
    print(f"  载荷长度序列 = {flow.payload_lengths}")     # 正数=C->S，负数=S->C
    print(f"  载荷时间序列 = {flow.payload_timestamps}")
    print(f"  IP包长序列   = {flow.ip_lengths}")
    print(f"  IP包时间序列 = {flow.ip_timestamps}")
    print(f"  扩展字段     = {flow.extension}")
```

### Response Example
```
# 输出示例:
# 流标识: ('traffic.pcap', 'tcp', '1')
#   源 IP:端口  = 192.168.0.100:44525
#   目的 IP:端口 = 208.43.237.140:443
#   协议类型     = TLSv1.2|TCP
#   开始时间     = 1592993502.710372
#   结束时间     = 1592993527.49081
#   载荷长度序列 = [180, -1424, -1440, -190, 126, -274, 625, -1163, 31, -31]
#   扩展字段     = {'tls.handshake.ciphersuite': [('49195,49196,...,53', 3), ('49195', 5)]}
```
```

--------------------------------

### Iterate Through Extracted Flows

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

The `extract` function returns a dictionary where keys are tuples representing the flow (filename, protocol, stream_id) and values are `Flow` objects. Iterate through this dictionary to access individual flow information.

```python
for key in result:
    ### The return vlaue result is a dict, the key is a tuple (filename,procotol,stream_id)
    ### and the value is an Flow object, user can access Flow object as flowcontainer.flows.Flow's attributes refer.

    value = result[key]
    print('Flow {0} info:'.format(key))
```

--------------------------------

### Access Flow Source IP Address

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Access the source IP address of a flow using the `src` attribute of the `Flow` object.

```python
## access ip src
    print('src ip:',value.src)
```

--------------------------------

### Analyze payload sequences for traffic characteristics

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Access `payload_lengths` and `payload_timestamps` to analyze non-zero payload packets. Positive lengths indicate client-to-server traffic, while negative lengths indicate server-to-client. This is useful for encrypted traffic classification.

```python
from flowcontainer.extractor import extract

result = extract("1592993485_noise.pcap", filter="tcp or udp", extension=[])

for key, flow in result.items():
    lengths = flow.payload_lengths       # 有效载荷长度序列（带方向符号）
    timestamps = flow.payload_timestamps # 有效载荷到达时间序列

    # 计算包间隔（IAT）
    if len(timestamps) > 1:
        iats = [timestamps[i+1] - timestamps[i] for i in range(len(timestamps)-1)]
    else:
        iats = []

    # 区分上下行流量
    uplink   = [l for l in lengths if l > 0]   # C->S
    downlink = [abs(l) for l in lengths if l < 0]  # S->C

    print(f"流 {key}:")
    print(f"  载荷长度序列: {lengths}")
    print(f"  上行字节数:   {sum(uplink)}")
    print(f"  下行字节数:   {sum(downlink)}")
    print(f"  包间隔(IAT):  {iats[:5]}...")
```

--------------------------------

### Flow.payload_lengths / Flow.payload_timestamps

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Accesses the sequence of payload lengths and timestamps for non-zero payload packets within a flow. Payload lengths are signed to indicate direction (positive for client-to-server, negative for server-to-client). Useful for traffic classification.

```APIDOC
## Flow.payload_lengths / Flow.payload_timestamps — 有效载荷序列

### Description
返回流中所有 TCP/UDP 载荷非零数据包的长度和时间戳序列。长度值带正负号：**正数**表示客户端→服务端（C→S），**负数**表示服务端→客户端（S→C）。该序列过滤掉了握手包、ACK 空包等无载荷数据包，是加密流量分类任务中最常用的特征序列。

### Parameters
This is a property of a `Flow` object returned by the `extract` function.

### Returns
- **payload_lengths** (list of int) - Sequence of payload lengths, signed by direction.
- **payload_timestamps** (list of float) - Sequence of timestamps corresponding to the payload lengths.

### Request Example
```python
from flowcontainer.extractor import extract

result = extract("1592993485_noise.pcap", filter="tcp or udp", extension=[])

for key, flow in result.items():
    lengths = flow.payload_lengths       # 有效载荷长度序列（带方向符号）
    timestamps = flow.payload_timestamps # 有效载荷到达时间序列

    # 计算包间隔（IAT）
    if len(timestamps) > 1:
        iats = [timestamps[i+1] - timestamps[i] for i in range(len(timestamps)-1)]
    else:
        iats = []

    # 区分上下行流量
    uplink   = [l for l in lengths if l > 0]   # C->S
    downlink = [abs(l) for l in lengths if l < 0]  # S->C

    print(f"流 {key}:")
    print(f"  载荷长度序列: {lengths}")
    print(f"  上行字节数:   {sum(uplink)}")
    print(f"  下行字节数:   {sum(downlink)}")
    print(f"  包间隔(IAT):  {iats[:5]}...")
```

### Response Example
```
# 输出示例（UDP 流）:
# 流 ('1592993485_noise.pcap', 'udp', '150'):
#   载荷长度序列: [44, 44, 44, 44, 44, 44, 44, 44, 44, 44]
#   上行字节数:   440
#   下行字节数:   0
#   包间隔(IAT):  [0.114512, 0.122001, 0.285479, 0.103196, 0.113886]...
```
```

--------------------------------

### Troubleshooting ValueError: invalid literal for int() with base 10

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

This error can occur when processing non-TCP/UDP packets or when attempting to extract the same field multiple times. Ensure filters are set to 'tcp or udp' and avoid re-extracting fields like length or IP addresses within extensions.

```shell
if int(packet[9]) != 0:
ValueError: invalid literal for int() with base 10: ''
```

--------------------------------

### Access Flow Destination IP Address

Source: https://github.com/jmhicoding/flowcontainer/blob/master/README.md

Access the destination IP address of a flow using the `dst` attribute of the `Flow` object.

```python
## access ip dst
    print('dst ip:',value.dst)
```

--------------------------------

### Filter for TCP or UDP Traffic

Source: https://context7.com/jmhicoding/flowcontainer/llms.txt

Resolves ValueError by explicitly specifying 'tcp or udp' in the filter when PCAP contains non-TCP/UDP packets like ICMP, which can cause empty port fields.

```python
# 错误原因：PCAP 中包含非 TCP/UDP 数据包（如 ICMP），导致端口字段为空
# 解决方法：在 filter 中明确指定协议
result = extract("traffic.pcap", filter="tcp or udp", extension=[])
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.