# Packet Capture

The Packet Capture (PCAP) source captures network packets and emits them as OpenTelemetry logs. It uses system-native tools (`tcpdump` on macOS/Linux, `Npcap` on Windows) to capture packets directly from a network interface.

### Supported Platforms

| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| macOS    |         | ✓    |        |
| Linux    |         | ✓    |        |
| Windows  |         | ✓    |        |

### Prerequisites

#### macOS/Linux

**Tool**: `tcpdump` is pre-installed on macOS and most Linux distributions.\
To verify:

```
tcpdump --version
```

#### Windows

**Tool**: Requires Npcap driver (included with Wireshark, or install standalone from <https://npcap.com/>).

* Install Npcap: <https://npcap.com/> (or install Wireshark which includes Npcap)
* List interfaces using PowerShell or the Npcap SDK tools
* Interface names on Windows use Npcap device paths (e.g., `\Device\NPF_{GUID}`)

### Configuration Table

| Parameter          | Type     | Default | Description                                                                      |
| ------------------ | -------- | ------- | -------------------------------------------------------------------------------- |
| network\_interface | `string` | ""      | Network interface to capture packets from.                                       |
| filter             | `string` | ""      | BPF (Berkeley Packet Filter) expression to filter packets.                       |
| parse\_attributes  | `bool`   | true    | The path to the `dumpcap` executable. Windows only (ignored on other platforms). |
| snaplen            | `int`    | 65535   | Maximum bytes to capture per packet (64-65535).                                  |
| promiscuous        | `bool`   | true    | Enable promiscuous mode to capture all network traffic.                          |

#### Interface Names

To list available interfaces on macOS/Linux:

```bash
tcpdump -D
```

To list available interfaces on Windows:

If you have Wireshark installed, use the `dumpcap` executable:

```powershell
C:\\path-to-wireshark-installation\dumpcap.exe -D
```

Otherwise, use `Get-NetAdapter`:

```powershell
Get-NetAdapter | Select-Object DeviceName
```

This result will have the interface names, but not in the Npcap format that the receiver expects. To convert it to the correct format, insert `\NPF_`

```
\Device\{1D5B8F34-3D34-47E7-960B-E18EBC729A13} -> \Device\NPF_{1D5B8F34-3D34-47E7-960B-E18EBC729A13}
```

#### BPF Filters

BPF filters allow you to capture only specific traffic. Examples:

```yaml
# Capture only HTTPS traffic
filter: "tcp port 443"

# Capture DNS queries and responses
filter: "udp port 53"

# Capture HTTP and HTTPS
filter: "tcp port 80 or tcp port 443"

# Capture traffic to/from specific IP
filter: "host 192.168.1.100"

# Complex filter with multiple conditions
filter: "(tcp port 80 or tcp port 443) and not src 192.168.1.1"
```

BPF filter syntax reference: [tcpdump manual](https://www.tcpdump.org/manpages/pcap-filter.7.html)