e2e

command
v2.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

README

eCapture E2E tests

This directory keeps the actively maintained TLS E2E scope small and explicit:

  • Linux on GitHub Actions Ubuntu 22.04 or newer: tls (OpenSSL), gotls, and gnutls.
  • Android 13/API 33 or newer: tls against the platform Conscrypt/BoringSSL library. CI covers every stable release from Android 13 through Android 16 (API 33-36).
  • Every module is exercised in text, keylog, and pcapng modes.
  • Every Linux TLS module exercises text, keylog, and pcapng over stdout, file, local TCP, and binary WebSocket ByteSinks. Each representation is also observed by a strict typed eCaptureQ receiver.
  • Every Linux TLS text suite performs same-probe HTTP reloads that inherit the original destination, switch to an explicit new destination only after success, and reject an invalid destination while the active output continues.
  • A separate strict common-config suite verifies file --eventaddr and operational-log isolation for Bash, Zsh, and the MySQL probe using local deterministic fixtures.

The tests require root and a real Linux/Android kernel with eBPF support. Building or running them on macOS is unsupported.

Test matrix

Platform Module/workload text assertion keylog assertion pcapng assertion
Ubuntu 22.04+ OpenSSL C client unique plaintext token valid TLS 1.2 and 1.3 NSS secrets SHB, IDB, packets, TLS DSB
Ubuntu 22.04+ advanced 256 OpenSSL connections (64 concurrent) n/a n/a at least 1024 packets, TLS DSB, no write/loss errors or per-packet INFO logs
Ubuntu 22.04+ Go HTTPS client unique plaintext token valid TLS 1.2 and 1.3 NSS secrets SHB, IDB, packets, TLS DSB
Ubuntu 22.04+ GnuTLS C client unique plaintext token valid TLS 1.2 and 1.3 NSS secrets SHB, IDB, packets, TLS DSB
Android 13+ app_process + Conscrypt unique plaintext token valid TLS 1.2 and 1.3 NSS secrets SHB, IDB, packets, TLS DSB

The maintained Linux destination matrix is complete for every TLS module:

Representation stdout file TCP binary WebSocket eCaptureQ receiver
operational log lifecycle records and event isolation lifecycle records and event isolation reconstructed lifecycle stream reconstructed lifecycle stream non-empty PROCESS_LOG
text plaintext and log isolation plaintext and log isolation reconstructed plaintext stream reconstructed plaintext stream PROCESS_LOG plus normal EVENT
keylog valid NSS secrets and decryption valid NSS secrets and decryption valid NSS secrets and decryption valid NSS secrets and decryption PROCESS_LOG plus sensitive keylog EVENT
pcapng valid blocks, DSB, and decryption valid blocks, DSB, and decryption valid reconstructed artifact valid reconstructed artifact PROCESS_LOG plus sensitive packet EVENT

All traffic goes to a short-lived local TLS server. Linux uses loopback directly. Android reaches the same host-side server through adb reverse, so the suite does not depend on public DNS, public CAs, or a third-party response body.

The pcapng check parses the block structure instead of accepting any non-empty file. It requires:

  • a Section Header Block;
  • an Interface Description Block;
  • at least one Enhanced Packet Block;
  • at least one TLS Decryption Secrets Block.

Logs also fail on fatal errors, event-decode errors, lost perf samples, and eBPF load/attach/start errors. A probe merely staying alive is not considered a pass.

The output cases additionally exercise --logaddr over stdout, file, TCP, and binary WebSocket. They require CLI and BaseProbe lifecycle records, prohibit the deterministic plaintext and TLS secret labels there, and prohibit lifecycle text in raw event artifacts. Network receivers compare the actual byte stream. Pcapng network/stdout artifacts pass the same block and DSB decryption checks as files. The strict eCaptureQ receiver requires both a non-empty PROCESS_LOG and a correctly classified EVENT, including format, sensitivity, timestamp, sequence, payload length, and original length; connectivity alone cannot pass.

Layout

test/e2e/
├── fixtures/                 # deterministic TLS server and native clients
├── lib/testlib.sh            # shared assertions/result reporting
├── linux/                    # maintained Linux harness and module suites
├── android/                  # Android 13+ BoringSSL harness and workload
├── run_e2e.sh                # Linux suite runner
├── tls_e2e_test.sh           # compatibility entry points
├── gotls_e2e_test.sh
└── gnutls_e2e_test.sh

Older Bash/database scripts and the permissive legacy eCaptureQ script remain outside this maintained TLS scope. Typed eCaptureQ assertions now live in each maintained TLS module suite.

Linux

Install the test dependencies on Ubuntu:

sudo apt-get update
sudo apt-get install --yes \
  build-essential pkg-config libssl-dev libgnutls28-dev tshark

Build eCapture on Linux, then run all three modules:

make all
sudo make e2e-linux

Run one module or one mode:

sudo make e2e-tls
sudo make e2e-gotls
sudo make e2e-gnutls

sudo E2E_MODULES='tls gotls' E2E_MODES=text bash test/e2e/run_e2e.sh
sudo E2E_MODULES=gotls E2E_MODES='keylog pcapng' bash test/e2e/run_e2e.sh

Run the non-TLS common-config suite on a host with interactive Bash/Zsh and a C++ compiler. The database case uses a local dispatch_command fixture, so it does not depend on a particular installed MySQL build:

sudo env PATH="$PATH" bash test/e2e/linux/common_config_test.sh

make e2e and make e2e-basic run the maintained Linux matrix. make e2e-advanced also runs the OpenSSL pcapng burst regression case.

Android

The Android suite needs a rooted/userdebug Android 13+ device or emulator, adb, an Android build-tools installation containing d8, and an Android eCapture binary. The host user must also be allowed to capture packets with dumpcap; CI grants only the cap_net_raw and cap_net_admin capabilities to that binary.

Build the artifacts on Linux:

ANDROID=1 CROSS_ARCH=arm64 make nocore
ANDROID_API_LEVEL=33 bash test/e2e/android/build_boringssl_client.sh

Run the suite:

make setup-android-env
make e2e-android-all

The Java workload is intentional: Android HttpsURLConnection uses Conscrypt/BoringSSL. A statically built Go HTTPS client uses Go's own TLS implementation and therefore cannot validate the Android BoringSSL tls probe.

Configuration and artifacts

Variable Default Purpose
E2E_MODULES tls gotls gnutls Linux modules to run
E2E_MODES text keylog pcapng Modes to run
E2E_STRESS 0 Run burst regressions when set to 1
E2E_ARTIFACT_ROOT /tmp/ecapture-e2e* Host artifact parent directory
E2E_KEEP_ARTIFACTS 0 Preserve successful test artifacts when set to 1
ECAPTURE_BINARY bin/ecapture Override the eCapture binary
ADB_SERIAL unset Select a device when more than one is attached
ANDROID_BORINGSSL_CLIENT generated jar in android/ Override the Android workload jar

Failed-suite artifacts are always preserved. CI sets E2E_KEEP_ARTIFACTS=1 and uploads them.

Every successful mode prints a [PLAINTEXT] line containing at most 50 characters of plaintext from the verified capture. Text mode reads the eCapture event log; keylog mode decrypts a simultaneous packet capture with the keys emitted by eCapture; pcapng mode invokes tshark without an external keylog and decrypts eCapture's own pcapng output using its embedded TLS Decryption Secrets Block. Pcapng previews also include the 64-hex-character CLIENT_RANDOM extracted from the captured ClientHello. The preview is therefore capture evidence, not a copy of the workload's client output.

GnuTLS implementation status

The GnuTLS probe attaches version-specific data and master-secret uprobes plus TC programs for pcapng mode. Its strict text, keylog, and pcapng cases are CI gates, matching the observable contracts used for OpenSSL and GoTLS. Keep the version-to-asset mapping synchronized with the offsets in kern/gnutls_*_kern.c; do not weaken assertions to accept startup logs or empty artifacts.

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
fixtures
output_receiver command
pcapng_check command
tls_server command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL