Getting Started ​

This page serves as the primary entry point for new users of eCapture. It provides a high-level overview of the setup process, from environment verification to running your first plaintext capture. By following the sub-pages linked here, you can move from a fresh installation to viewing decrypted TLS traffic in under five minutes.

Overview of the Setup Process ​

The journey to using eCapture involves four main stages: preparing your environment, obtaining the binary, ensuring correct permissions, and executing a capture module.

1. Installation: Choose between prebuilt binaries, Docker images, or building from source.
2. Environment Check: Verify your Linux kernel version and CPU architecture (x86_64 or aarch64).
3. Permissions: Configure necessary Linux Capabilities or use root access.
4. First Capture: Run a simple tls probe to intercept plaintext data from tools like curl or wget.

High-Level Component Interaction ​

The following diagram illustrates how a user interacts with the eCapture CLI to initiate a capture session, and how the internal components facilitate the flow from the kernel to the final output.

CLI to Kernel Data Path

Sources: cli/cmd/root.go:105-137, internal/factory/factory.go:1-50, pkg/event_processor/processor.go:89-107, README.md:106-119

2.1 Installation and Prerequisites ​

eCapture supports multiple installation methods to suit different environments. The most common method is downloading the ELF binary directly from GitHub Releases. For containerized environments, a Docker image is provided, though it requires specific privileges to interact with the host kernel.

Supported Platforms:

• Linux x86_64: Kernel >= 4.18
• Linux aarch64: Kernel >= 5.5
• Android: GKI kernels (arm64)

For detailed installation steps and system requirements, see Installation and Prerequisites.

Sources: README.md:12-15, README.md:48-72

2.2 Minimum Privileges ​

Because eCapture utilizes eBPF to hook into system libraries, it requires elevated privileges. While running as root is the simplest method, production environments often require restricted permissions. eCapture can run with a subset of Linux Capabilities, such as CAP_BPF, CAP_PERFMON, and CAP_SYS_PTRACE.

For instructions on configuring specific capabilities and Kubernetes security contexts, see Minimum Privileges.

Sources: README.md:14-14, cli/cmd/root.go:124-124

2.3 Quick Start (Run the First Example) ​

The fastest way to verify your setup is by running the tls module. By default, eCapture will search for OpenSSL or BoringSSL libraries on your system and begin capturing plaintext.

Example Command:

sudo ecapture tls

Once running, executing a command like curl https://google.com in another terminal will trigger the capture, displaying the HTTP/1.1 or HTTP/2 headers and body in your console.

For a full walkthrough including PID filtering and specific application examples, see Quick Start (Run the First Example in 5 Minutes).

Sources: README.md:74-90, cli/cmd/root.go:118-121

2.4 Output Formats (Text / Pcap / Keylog) ​

eCapture provides flexible output options depending on your analysis needs:

• Text Mode: Direct human-readable output to the console.
• Pcap/Pcapng Mode: Generates files compatible with Wireshark for deep packet analysis.
• Keylog Mode: Exports TLS Master Secrets (NSS Key Log format) to decrypt traffic captured by other tools like tcpdump.

The underlying EventProcessor handles the conversion of raw eBPF events into these formats using specialized parsers like HTTPRequest and HTTPResponse.

For details on choosing and configuring output modes, see Output Formats (text / pcap / keylog).

Internal Output Flow

Sources: pkg/event_processor/processor.go:28-48, pkg/event_processor/iworker.go:174-227, cli/cmd/root.go:78-86, cli/cmd/root.go:168-171