# Protocol Support Matrix

This guide explains what level of visibility Qtap provides for different network protocols commonly found in enterprise environments.

## Quick Reference Table

| Protocol                 | Default Port | l7Protocol Value | HTTP Parsing   | TLS Detection | Process Attribution | Use Case                     |
| ------------------------ | ------------ | ---------------- | -------------- | ------------- | ------------------- | ---------------------------- |
| **HTTP/1.1 (HTTPS)**     | 443          | `http1`          | ✅ Full         | ✅ Yes         | ✅ Yes               | Web APIs, REST services      |
| **HTTP/2 (HTTPS)**       | 443          | `http2`          | ✅ Full         | ✅ Yes         | ✅ Yes               | Modern web apps, HTTP/2 APIs |
| **WebSocket**            | 443          | `http2`          | ✅ Upgrade only | ✅ Yes         | ✅ Yes               | Real-time web applications   |
| **gRPC**                 | 443          | `http2`          | ⚠️ Partial\*   | ✅ Yes         | ✅ Yes               | Microservices RPC            |
| **DNS over HTTPS (DoH)** | 443          | `other`          | ❌ No           | ✅ Yes         | ✅ Yes               | Private DNS queries          |
| **MySQL**                | 3306         | `other`          | ❌ No           | ❌ No\*\*      | ✅ Yes               | Relational database          |
| **PostgreSQL**           | 5432         | `other`          | ❌ No           | ❌ No\*\*      | ✅ Yes               | Relational database          |
| **MongoDB**              | 27017        | `other`          | ❌ No           | ❌ No\*\*      | ✅ Yes               | NoSQL database               |
| **Redis**                | 6379         | `other`          | ❌ No           | ❌ No          | ✅ Yes               | In-memory cache              |
| **SSH**                  | 22           | `other`          | ❌ No           | ❌ No          | ✅ Yes               | Remote server access         |
| **SMTP (TLS)**           | 465, 587     | `other`          | ❌ No           | ✅ Yes         | ✅ Yes               | Email transmission           |
| **SMTP (plain)**         | 25           | `other`          | ❌ No           | ❌ No          | ✅ Yes               | Email transmission           |

\* gRPC uses HTTP/2 framing (detected), but payloads are binary protobuf (not parsed as JSON/text) \*\* Some databases support TLS; detection depends on the specific configuration

***

## Protocol Categories

### ✅ Full Visibility (HTTP/HTTPS)

Qtap provides **complete application-level visibility** for HTTP/1.1 and HTTP/2 traffic over HTTPS.

#### What You Get:

* **Connection Event**: Process attribution, endpoints, byte counts, TLS version
* **HttpTransaction Object**: Complete request and response
  * Request: method, URL, headers, body (base64-encoded)
  * Response: status code, headers, body (base64-encoded)
* **ArtifactRecord Event**: Transaction summary with status, duration, content types

#### Supported Protocols:

* Standard HTTP/1.1 over HTTPS
* HTTP/2 over HTTPS
* WebSocket upgrade requests (initial HTTP upgrade captured)
* REST APIs, GraphQL endpoints, web applications

#### Key Feature:

**TLS inspection without proxies** - Qtap uses eBPF to hook TLS libraries (OpenSSL, Go TLS, Java SSL, Node TLS) and sees plaintext data before encryption, eliminating the need for MITM proxies or certificate management.

***

### ⚠️ Partial Visibility (gRPC, WebSocket Data)

Some protocols use HTTP/2 framing but have binary or non-standard payloads.

#### gRPC

**l7Protocol**: `http2` **What You Get**:

* HTTP/2 connection detected and framed
* Initial HTTP headers (`:method`, `:path`, `:authority`)
* Connection metadata, process attribution, TLS detection

**What You Don't Get**:

* Parsed protobuf messages (binary encoded)
* RPC method arguments or return values
* Business logic data

**Why**: gRPC uses HTTP/2 as transport but encodes data in binary Protocol Buffers. Qtap detects the HTTP/2 framing but cannot decode protobuf without schema definitions.

#### WebSocket (After Upgrade)

**l7Protocol**: `http2` or `http1` **What You Get**:

* Initial HTTP upgrade request (full capture)
* Connection metadata for the WebSocket session

**What You Don't Get**:

* WebSocket frame payloads after the upgrade
* Real-time messages sent over the WebSocket

**Why**: After the HTTP upgrade completes, WebSocket uses its own binary framing. Qtap captures the upgrade handshake as HTTP but does not parse the subsequent WebSocket protocol.

***

### ⚠️ Metadata Only (Databases, SSH, SMTP)

For non-HTTP protocols, Qtap captures **connection-level metadata** but cannot parse application-layer data.

#### What You Get:

* **Connection Event** with:
  * Source process executable path and user ID (`source.exe`, `source.userId`)
  * Destination IP, port, and resolved domain (`destination.address`, `endpointId`)
  * Byte counts (`bytesSent`, `bytesReceived`)
  * TLS version and library detection (if applicable)
  * Connection timestamps and duration
  * Traffic direction (`egress`, `ingress`, etc.)

#### What You Don't Get:

* SQL queries (MySQL, PostgreSQL)
* Database commands (MongoDB, Redis)
* SSH commands or terminal output
* Email message content (SMTP)
* Any application-level protocol data

#### Example: MySQL Connection

```json
{
  "meta": {
    "connectionId": "abc123",
    "endpointId": "127.0.0.1"
  },
  "direction": "egress-external",
  "socketProtocol": "tcp",
  "l7Protocol": "other",
  "source": {
    "address": {"ip": "127.0.0.1", "port": 54321},
    "exe": "/usr/bin/python3",
    "userId": 1000
  },
  "destination": {
    "address": {"ip": "127.0.0.1", "port": 3306}
  },
  "bytesSent": 1024,
  "bytesReceived": 4096
}
```

**Interpretation**: A Python process connected to localhost MySQL, sent 1KB and received 4KB. You know the process, destination, and data volume, but not the SQL queries.

***

## Configuration Considerations

### Localhost Database Connections

By default, Qtap ignores localhost connections (`tap.ignore_loopback: true`).

**If you want to monitor local databases**:

```yaml
tap:
  direction: egress
  ignore_loopback: false  # Capture localhost connections
```

**Common localhost scenarios**:

* Local MySQL/PostgreSQL during development
* Redis on localhost
* MongoDB running locally
* Microservices communicating within the same host

***

## Use Case: What Qtap is Best For

### ✅ Ideal Use Cases

1. **HTTP/HTTPS API Monitoring**
   * Full request/response capture for debugging
   * Error detection (4xx, 5xx status codes)
   * Performance monitoring (request duration)
   * Security analysis (authentication tokens, sensitive data)
2. **Microservice Communication**
   * Service-to-service HTTP calls
   * Process attribution (which service made the call)
   * TLS inspection without service mesh complexity
3. **Third-Party API Integration**
   * Complete visibility into external API calls
   * Debug integration issues with full payloads
   * Monitor API rate limits and errors
4. **Compliance and Audit**
   * Capture API transactions for audit trails
   * Store sensitive data in your S3 (data sovereignty)
   * Process-level attribution for security investigations

### ⚠️ Limited Use Cases

1. **Database Query Analysis**
   * Qtap shows **which process** connected to the database
   * Qtap shows **data volume** (bytes sent/received)
   * Qtap **does not parse** SQL queries or results
   * Use database-specific tools (pg\_stat\_statements, MySQL slow query log) for query analysis
2. **SSH Session Monitoring**
   * Qtap shows **which user** initiated SSH connections
   * Qtap shows **destination servers**
   * Qtap **does not capture** SSH commands or terminal output
   * Use SSH logging or session recording tools for command auditing
3. **gRPC Method-Level Monitoring**
   * Qtap detects gRPC **connections**
   * Qtap **does not decode** protobuf messages
   * Use gRPC-specific instrumentation (OpenTelemetry, gRPC interceptors) for method-level tracing

***

## Combining Qtap with Other Tools

Qtap excels at HTTP/HTTPS visibility and provides valuable connection metadata for other protocols. For comprehensive monitoring:

| Protocol       | Qtap Provides       | Complement With                               |
| -------------- | ------------------- | --------------------------------------------- |
| **HTTP/HTTPS** | Full visibility     | Nothing needed - Qtap is complete             |
| **MySQL**      | Connection metadata | `pt-query-digest`, `performance_schema`       |
| **PostgreSQL** | Connection metadata | `pg_stat_statements`, `pgBadger`              |
| **MongoDB**    | Connection metadata | MongoDB Profiler, `mongotop`                  |
| **Redis**      | Connection metadata | `redis-cli MONITOR`, Redis Insights           |
| **SSH**        | Connection metadata | `sshd` logging, session recording (asciinema) |
| **gRPC**       | HTTP/2 framing      | OpenTelemetry, gRPC interceptors              |

***

## Protocol Detection Deep Dive

### How Qtap Detects Protocols

1. **Syscall Hooking**: Qtap uses eBPF to hook `read`/`write` syscalls
2. **TLS Library Detection**: Identifies OpenSSL, Go TLS, Java SSL, Node TLS libraries
3. **Plaintext Interception**: Captures data before TLS encryption
4. **HTTP Parsing**: Attempts to parse as HTTP/1.1 or HTTP/2
5. **Classification**: Sets `l7Protocol` to `http1`, `http2`, or `other`

### When HTTP Parsing Fails

HTTP parsing can fail for legitimate reasons:

1. **Binary Protocols**: MySQL, PostgreSQL, Redis, MongoDB wire protocols
2. **Custom Protocols**: Proprietary application protocols
3. **Encrypted Payloads**: Application-level encryption on top of TLS
4. **Non-Standard HTTP**: Malformed HTTP or custom HTTP-like protocols

### When HTTP Parsing Succeeds But Shows "other"

Rare cases where traffic is technically HTTP but shows as `other`:

1. **Unsupported TLS Library**: Application uses a TLS library Qtap doesn't hook
2. **HTTP/3 (QUIC)**: Uses UDP, not TCP (not currently supported)
3. **Custom HTTP Implementations**: Non-standard HTTP libraries

***

## Testing Protocol Support

To test what Qtap captures for your specific protocol:

```bash
# Start qtap
docker run -d --name qtap-test \
  --user 0:0 --privileged --pid=host --network=host \
  -v /sys:/sys \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/qtap.yaml:/app/config/qtap.yaml \
  us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
  --log-level=info \
  --log-encoding=console \
  --config=/app/config/qtap.yaml

# Wait for initialization
sleep 6

# Generate traffic (your application here)
# Example: HTTP request
docker run --rm --network host curlimages/curl:8.10.1 -s https://httpbin.org/get

# Check qtap logs
docker logs qtap-test 2>&1 | grep -E 'event store submission.*Connection'
```

Look for:

* `l7Protocol`: `http1`, `http2`, or `other`
* `tlsVersion`: TLS detected?
* `tlsProbeTypesDetected`: Which TLS library?
* `bytesSent`, `bytesReceived`: Data transferred?

***

## Summary

**Qtap is purpose-built for HTTP/HTTPS visibility** with process attribution and TLS inspection. For non-HTTP protocols, it provides valuable connection metadata (which process, what destination, how much data) but cannot parse application-level content.

**Key Takeaway**: If you need deep visibility into HTTP APIs, microservices, or web traffic, Qtap is ideal. For databases, SSH, or custom protocols, Qtap gives you connection context that complements protocol-specific monitoring tools.

For questions about specific protocols, check the [Qpoint Data Schema Reference](/appendix/qpoint-data-schema-reference.md) or contact support.


---

# 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.qpoint.io/appendix/protocol-support-matrix.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.