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, andgnutls. - Android 13/API 33 or newer:
tlsagainst 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, andpcapngmodes. - 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
--eventaddrand 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 with enriched connection tuple and no standalone connection records | 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/preprocess/dispatch errors, lost perf samples, and eBPF load/attach/start errors. The OpenSSL text case checks both capture and operational logs. 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 TARGET_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
¶
There is no documentation for this package.
Directories
¶
| Path | Synopsis |
|---|---|
|
fixtures
|
|
|
ecaptureq_assert
command
|
|
|
output_receiver
command
|
|
|
pcapng_check
command
|
|
|
tls_server
command
|