Database Traffic Capture (MySQL / PostgreSQL) ​

eCapture provides specialized probes for auditing database traffic by intercepting plaintext SQL statements directly within the database server process. By using eBPF uprobes, eCapture captures queries before they are processed (or as they are dispatched), allowing for high-performance monitoring without requiring database-level logging or network-layer decryption.

Supported Databases and Versions ​

The database probes are designed to target specific symbols within the server binaries.

Sources: cli/cmd/mysqld.go:30-35, cli/cmd/postgres.go:29-33, kern/postgres_kern.c:31-35

Implementation Principle ​

The database probes operate by attaching uprobes and uretprobes to the internal functions responsible for command dispatching.

MySQL / MariaDB Capture Flow ​

MySQL uses the dispatch_command function. The signature and data structures evolved between versions 5.6, 5.7, and 8.0, requiring different handling in the kernel-side eBPF program.

1. Entry Hook (uprobe): eCapture reads the command type. It specifically filters for COM_QUERY (0x03) to avoid capturing internal heartbeat or administrative traffic kern/mysqld_kern.c:60-62.
2. Data Extraction:
   • In MySQL 5.6, the query string and length are passed directly as parameters kern/mysqld_kern.c:71-85.
   • In MySQL 5.7/8.0, the query is wrapped in a COM_DATA union/struct, requiring a multi-stage bpf_probe_read_user to dereference the string pointer kern/mysqld_kern.c:190-193.
3. State Management: The query data is stored in a BPF Hash Map (sql_hash) keyed by the Thread Group ID (TGID/PID) kern/mysqld_kern.c:29-34.
4. Exit Hook (uretprobe): When dispatch_command returns, the probe captures the return value (status) and sends the complete event to userspace kern/mysqld_kern.c:93-125.

PostgreSQL Capture Flow ​

PostgreSQL is simpler, hooking exec_simple_query(const char *query_string). Since the query string is the first argument, eCapture extracts it using PT_REGS_PARM1 kern/postgres_kern.c:35-53.

Code Entity Mapping: MySQL Probe ​

The following diagram maps the logical capture flow to specific C and Go entities in the codebase.

Title: MySQL Capture Data Flow

Sources: kern/mysqld_kern.c:19-41, internal/probe/mysql/event.go:62-70

Configuration and Usage ​

MySQL / MariaDB ​

Users must specify the path to the mysqld or mariadbd binary. If symbols are stripped or the function name differs, the --offset or --funcname flags can be used.

# Capture from default MariaDB path
ecapture mysqld --mysqld /usr/sbin/mariadbd

# Capture from a specific MySQL 8.0 instance with manual offset
ecapture mysqld --mysqld /usr/local/mysql/bin/mysqld --offset 0x710410

PostgreSQL ​

Similar to MySQL, the path to the postgres server binary is required.

ecapture postgres --postgres /usr/lib/postgresql/14/bin/postgres

Key CLI Flags ​

• -m, --mysqld / --postgres: Path to the database server binary cli/cmd/mysqld.go:40, cli/cmd/postgres.go:37.
• -f, --funcname: Manually specify the function name to hook (e.g., if using a custom build) cli/cmd/mysqld.go:42.
• --offset: Hexadecimal offset for the function entry point cli/cmd/mysqld.go:41.
• --perf-reorder: Enables userspace reordering of events based on BPF ktime to ensure chronological output cli/cmd/mysqld.go:43.

Data Structures ​

MySQL Event (data_t) ​

The event captures the query, its original length (to detect truncation), and the execution return status.

Sources: kern/mysqld_kern.c:19-27, internal/probe/mysql/event.go:62-70

PostgreSQL Event (data_t) ​

PostgreSQL events are streamlined for query string capture.

Title: PostgreSQL Event Structure

Sources: kern/postgres_kern.c:17-22, internal/probe/postgres/event.go:42-47

Production Caveats ​

Performance Impact ​

• Uprobe Overhead: Every SQL query triggers a context switch into the eBPF program. For high-TPS (Transactions Per Second) environments, this can add a few microseconds of latency per query.
• Data Truncation: By default, SQL queries are truncated (typically to 256 bytes) to fit within the eBPF stack and map limits internal/probe/mysql/event.go:29. This can be adjusted via --truncate-size cli/cmd/mysqld.go:57.

Permissions ​

• Root/CAP_SYS_ADMIN: eCapture requires high privileges to load eBPF programs and attach uprobes to system processes.
• Binary Access: The eCapture process must have read access to the database server binary to parse symbols or apply offsets.

Stability ​

• Symbol Dependency: These probes rely on the presence of specific symbols (dispatch_command, exec_simple_query). If the database was compiled with --strip-all and no symbol table is available, the probe will fail to attach unless a manual --offset is provided.

Sources: cli/cmd/mysqld.go:41-45, internal/probe/mysql/event.go:145-157