# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/integrations/sources/packet-capture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.