Quick Start (Run the First Example in 5 Minutes) ​

This guide provides a hands-on walkthrough for running your first capture with eCapture. We will focus on the most common use case: capturing plaintext TLS traffic from curl using the tls probe.

1. Preparation ​

Ensure you have the eCapture binary installed and have the necessary privileges (root or specific capabilities). eCapture supports Linux x86_64 (kernel >= 4.18) and aarch64 (kernel >= 5.5) cli/cmd/root.go:114-115.

Verify Installation ​

ecapture version

2. Launch Your First Capture ​

The tls command is the primary tool for capturing SSL/TLS plaintext. It works by attaching eBPF uprobes to functions like SSL_read and SSL_write in shared libraries cli/cmd/tls.go:32-33.

Step 1: Start eCapture ​

Open a terminal and run eCapture in text mode (default). We will filter by the curl process once we start it, but for now, let's watch all OpenSSL traffic:

sudo ecapture tls -m text

Step 2: Trigger Traffic ​

In a second terminal, perform an HTTPS request using curl:

curl https://www.google.com

Step 3: Observe Output ​

Back in the first terminal, you will see the decrypted plaintext. The output format typically includes the PID, Process Name, and the Hex/String content of the request and response pkg/event_processor/iworker.go:205-206.

3. Practical Examples ​

Filtering by PID ​

To avoid noise from other processes, use the --pid (or -p) flag cli/cmd/root.go:166.

# 1. Find the PID of a running process (e.g., nginx)
pidof nginx

# 2. Capture only that process
sudo ecapture tls --pid 1234

Capturing from Specific Libraries ​

If your binary uses a non-standard OpenSSL path, use --libssl cli/cmd/tls.go:51.

sudo ecapture tls --libssl /usr/lib/x86_64-linux-gnu/libssl.so.1.1

Go Binaries (gotls) ​

For binaries compiled with Go's standard library (crypto/tls), use the gotls probe and specify the ELF path cli/cmd/gotls.go:32-35.

sudo ecapture gotls --elfpath /path/to/your/go_binary

4. Data Flow Architecture ​

The following diagram illustrates how a user command triggers the eBPF instrumentation and how data flows back to your terminal.

From CLI to Kernel Hook ​

"This diagram maps the CLI entry points to the internal factory and probe initialization."

Sources: cli/cmd/tls.go:47-80, cli/cmd/root.go:158-176, cli/cmd/gotls.go:58-72

Event Processing Pipeline ​

"This diagram shows how raw bytes from the kernel are processed into readable text."

Sources: pkg/event_processor/processor.go:64-87, pkg/event_processor/iworker.go:153-161, pkg/event_processor/iworker.go:174-227, pkg/event_processor/iparser.go:85-115

5. Expected Output Formats ​

Text Mode Example Output ​

When running ecapture tls, the eventWorker formats the output as follows:

PID:1234, Comm:curl, Src:192.168.1.5:44332, Dest:93.184.216.34:443,
GET / HTTP/1.1
Host: example.com
User-Agent: curl/7.74.0

Sources: pkg/event_processor/iworker.go:205-206

6. Troubleshooting Quick-Check ​

• Permission Denied: Ensure you are running with sudo. eCapture requires CAP_SYS_ADMIN or CAP_BPF cli/cmd/root.go:130-136.
• Empty Output:
  • Verify the process is actually using the library you think it is (e.g., check if it's using GnuTLS instead of OpenSSL).
  • Check if the kernel version meets the minimum requirements cli/cmd/root.go:114-115.
• BTF Errors: If your kernel doesn't support BTF, try forcing non-CORE mode with -b 2 cli/cmd/root.go:163.

Sources: cli/cmd/tls.go:1-80, cli/cmd/root.go:1-180, pkg/event_processor/processor.go:1-214, pkg/event_processor/iworker.go:1-265, pkg/event_processor/iparser.go:1-167