Command Line Interface ​

Purpose and Scope ​

This document describes eCapture's command-line interface (CLI), including the root command, global flags, module-specific subcommands, and their respective configuration options. The CLI is built using the Cobra framework and serves as the primary user interaction layer for initiating capture operations.

For information about how CLI commands translate into module execution and eBPF attachment, see Module System and Lifecycle. For details on the configuration structures used by each module, see Configuration System.

CLI Architecture Overview ​

The eCapture CLI follows a hierarchical command structure with a root command (ecapture) and multiple module-specific subcommands. Each subcommand corresponds to a capture module and accepts both global flags (inherited from root) and module-specific flags.

Command Hierarchy ​

Sources: cli/cmd/tls.go:29-48, cli/cmd/gotls.go:29-40, cli/cmd/gnutls.go:32-45, cli/cmd/nspr.go:30-41, cli/cmd/bash.go:27-33, cli/cmd/zsh.go:30-36, cli/cmd/mysqld.go:30-37, cli/cmd/postgres.go:30-34

Entry Point Flow ​

Sources: main.go:9-11

Global Flags ​

While not shown in the provided files, the root command (rootCmd) in cli/cmd/root.go defines global flags that are inherited by all subcommands. Based on the README examples and architecture, these include:

Global flags apply to all modules and can be combined with module-specific flags.

Sources: README.md:72-149

Module Subcommands ​

TLS/OpenSSL Module ​

Command: ecapture tls (alias: openssl)

The TLS module captures plaintext from OpenSSL/BoringSSL-encrypted connections. It supports three capture modes and can target all OpenSSL versions 1.0.x, 1.1.x, and 3.x.

Flags ​

Capture Modes ​

Sources: cli/cmd/tls.go:26-67

Usage Examples ​

# Text mode - capture all OpenSSL traffic
sudo ecapture tls

# PCAP mode - save to file with filter
sudo ecapture tls -m pcap -i eth0 -w output.pcapng tcp port 443

# Keylog mode - extract master secrets
sudo ecapture tls -m keylog -k keys.log

# Target specific library version
sudo ecapture tls --libssl=/lib/x86_64-linux-gnu/libssl.so.3 --ssl_version="openssl 3.0.5"

Sources: cli/cmd/tls.go:33-46, README.md:72-149

Configuration Structure ​

The OpensslConfig struct (user/config/openssl.go) is initialized at cli/cmd/tls.go:26:

var oc = config.NewOpensslConfig()

The configuration is passed to the OpenSSL module via runModule(module.ModuleNameOpenssl, oc) at cli/cmd/tls.go:66.

PCAP Filter Support ​

The TLS and GoTLS modules support pcap filter expressions in pcap mode. Filters are passed as trailing arguments:

sudo ecapture tls -m pcap -i eth0 host 192.168.1.1 and tcp port 443

The filter is extracted at cli/cmd/tls.go:63-65 and stored in oc.PcapFilter.

Sources: cli/cmd/tls.go:62-67

GoTLS Module ​

Command: ecapture gotls (alias: tlsgo)

Captures plaintext from Go programs using the native crypto/tls library. Requires specifying the target Go binary path.

Flags ​

Sources: cli/cmd/gotls.go:26-59

Usage Examples ​

# Capture specific Go binary
sudo ecapture gotls --elfpath=/usr/bin/my-go-app

# PCAP mode with filter
sudo ecapture gotls -m pcap -e /usr/bin/my-go-app -i eth0 -w output.pcapng tcp port 8443

# Keylog mode
sudo ecapture gotls -m keylog -k gotls_keys.log --elfpath=/usr/bin/my-go-app

Sources: cli/cmd/gotls.go:34-38, README.md:256-276

Configuration Structure ​

The GoTLSConfig struct is initialized at cli/cmd/gotls.go:26 and passed to the module at cli/cmd/gotls.go:57.

GnuTLS Module ​

Command: ecapture gnutls (alias: gnu)

Captures plaintext from applications using the GnuTLS library (e.g., wget).

Flags ​

Sources: cli/cmd/gnutls.go:29-64

Usage Examples ​

# Auto-detect GnuTLS library
sudo ecapture gnutls

# Specify library path
sudo ecapture gnutls --gnutls=/lib/x86_64-linux-gnu/libgnutls.so

# Keylog mode with version
sudo ecapture gnutls -m keylog -k keys.log --ssl_version="3.7.9"

Sources: cli/cmd/gnutls.go:37-43

NSS/NSPR Module ​

Command: ecapture nspr (alias: nss)

Captures plaintext from applications using Mozilla's NSS/NSPR libraries (e.g., Firefox).

Flags ​

Sources: cli/cmd/nspr.go:27-51

Usage Examples ​

# Auto-detect NSPR library
sudo ecapture nspr

# Specify library path
sudo ecapture nspr --nspr=/lib/x86_64-linux-gnu/libnspr44.so

Sources: cli/cmd/nspr.go:35-39

Bash Audit Module ​

Command: ecapture bash

Captures bash command input/output for security audit purposes by hooking the readline library.

Flags ​

Sources: cli/cmd/bash.go:24-55

Usage Examples ​

# Capture all bash commands
sudo ecapture bash

# Filter by specific error code
sudo ecapture bash -e 127

# Specify bash path
sudo ecapture bash --bash=/bin/bash

Sources: cli/cmd/bash.go:30-32

Configuration Structure ​

The BashConfig struct is initialized at cli/cmd/bash.go:24 and includes the ErrNo field for filtering command results by exit status (cli/cmd/bash.go:38).

Zsh Audit Module ​

Command: ecapture zsh

Captures zsh command input/output for security audit purposes, similar to the bash module.

Flags ​

Sources: cli/cmd/zsh.go:27-57

Usage Examples ​

# Capture all zsh commands
sudo ecapture zsh

# Specify zsh path
sudo ecapture zsh --zsh=/bin/zsh

Sources: cli/cmd/zsh.go:33-34

MySQL Audit Module ​

Command: ecapture mysqld

Captures SQL queries from MySQL/MariaDB servers (versions 5.6, 5.7, 8.0, and MariaDB 10.5+).

Flags ​

Sources: cli/cmd/mysqld.go:27-49

Usage Examples ​

# Auto-detect MySQL binary
sudo ecapture mysqld

# Specify MySQL path
sudo ecapture mysqld -m /usr/sbin/mysqld

Sources: cli/cmd/mysqld.go:33-35

PostgreSQL Audit Module ​

Command: ecapture postgres

Captures SQL queries from PostgreSQL servers (version 10 and above).

Flags ​

Sources: cli/cmd/postgres.go:27-45

Usage Examples ​

# Auto-detect PostgreSQL binary
sudo ecapture postgres

# Specify PostgreSQL path
sudo ecapture postgres -m /usr/bin/postgres

Sources: cli/cmd/postgres.go:32-33

Common Patterns and Conventions ​

Capture Mode Pattern ​

Several modules (TLS, GoTLS, GnuTLS) share a common -m, --model flag pattern with three standard values:

Sources: cli/cmd/tls.go:53, cli/cmd/gotls.go:45, cli/cmd/gnutls.go:50

Library Path Detection ​

All TLS-related modules support automatic library detection but allow manual override:

• --libssl for OpenSSL/BoringSSL (cli/cmd/tls.go:51)
• --gnutls for GnuTLS (cli/cmd/gnutls.go:49)
• --nspr for NSS/NSPR (cli/cmd/nspr.go:44)
• --elfpath for Go binaries (cli/cmd/gotls.go:43)

Command Execution Flow ​

Sources: cli/cmd/tls.go:62-67, cli/cmd/gotls.go:52-58

Config Structure to Module Mapping ​

Each subcommand maintains a package-level configuration variable and passes it to runModule():

Command-to-Code Entity Mapping ​

The following diagram shows how CLI commands map to concrete Go types and functions in the codebase:

Sources: cli/cmd/tls.go:62-67, cli/cmd/gotls.go:52-58, cli/cmd/bash.go:53-55

Platform-Specific Behavior ​

Some modules are conditionally compiled based on build tags:

Android GKI Exclusions ​

Modules excluded from Android GKI builds (//go:build !androidgki):

• gnutls (cli/cmd/gnutls.go:1-2)
• mysqld (cli/cmd/mysqld.go:1-2)
• postgres (cli/cmd/postgres.go:1-2)
• nspr (cli/cmd/nspr.go:1-2)
• zsh (cli/cmd/zsh.go:1-2)

These modules are unavailable when building for Android environments due to platform constraints or missing library dependencies.

Sources: cli/cmd/gnutls.go:1-2, cli/cmd/mysqld.go:1-2, cli/cmd/postgres.go:1-2, cli/cmd/nspr.go:1-2, cli/cmd/zsh.go:1-2

Summary Table: All Subcommands ​

Sources: All cli/cmd/*.go files