### Install and Start MySQL/MariaDB Source: https://github.com/gojue/ecapture/blob/master/test/e2e/QUICK_REFERENCE.md Instructions for installing MySQL/MariaDB server and client packages and starting the service, necessary for MySQL-related tests. ```bash # Install MySQL/MariaDB sudo apt-get install mysql-server mysql-client # Start service sudo systemctl start mysql ``` -------------------------------- ### Install wrk and Setup HTTPS Server Source: https://github.com/gojue/ecapture/blob/master/docs/performance-benchmarks.md Installs the `wrk` HTTP benchmarking tool and provides a placeholder for setting up an HTTPS server. ```bash # Install wrk (HTTP benchmarking tool) sudo apt-get install wrk ``` ```bash # Start an HTTPS server (using nginx or a simple Go server) # Ensure it uses the system's OpenSSL/libssl ``` -------------------------------- ### Implement Probe Start Method in Go Source: https://github.com/gojue/ecapture/blob/master/docs/refactoring-guide.md Starts the probe, including loading eBPF bytecode, setting up and starting the eBPF manager, and initializing event readers. ```go func (p *Probe) Start(ctx context.Context) error { // Call BaseProbe.Start if err := p.BaseProbe.Start(ctx); err != nil { return err } // Load eBPF bytecode bpfFileName := p.BaseProbe.GetBPFName("bytecode/probe_kern.o") byteBuf, err := assets.Asset(bpfFileName) if err != nil { return errors.NewEBPFLoadError(bpfFileName, err) } // Setup and initialize eBPF manager if err := p.setupManager(); err != nil { return err } if err := p.bpfManager.InitWithOptions(bytes.NewReader(byteBuf), p.getManagerOptions()); err != nil { return errors.NewEBPFLoadError("manager init", err) } // Start eBPF manager if err := p.bpfManager.Start(); err != nil { return errors.NewEBPFAttachError("manager start", err) } // Get event maps eventsMap, found, err := p.bpfManager.GetMap("events") if err != nil || !found { return errors.NewResourceNotFoundError("eBPF map: events") } p.eventMaps = []*ebpf.Map{eventsMap} // Start event readers if err := p.StartPerfEventReader(eventsMap, p); err != nil { return err } return nil } ``` -------------------------------- ### Implement New Probe with Base Probe and Manager Source: https://github.com/gojue/ecapture/blob/master/internal/README.md Implement a new probe by embedding `base.BaseProbe` and potentially other managers. The `NewMyProbe` function initializes the probe, and the `Start` method handles probe-specific setup like loading eBPF programs. ```go // internal/probe/myprobe/myprobe.go type MyProbe struct { *base.BaseProbe manager *manager.Manager } func NewMyProbe() (*MyProbe, error) { return &MyProbe{ BaseProbe: base.NewBaseProbe("myprobe"), }, nil } func (p *MyProbe) Start(ctx context.Context) error { if err := p.BaseProbe.Start(ctx); err != nil { return err } // Load eBPF program // Attach probes // Start event readers return nil } ``` -------------------------------- ### GitHub Actions CI Configuration Example Source: https://github.com/gojue/ecapture/blob/master/test/e2e/README.md An example GitHub Actions workflow for setting up a CI environment to run e2e tests. Includes dependency installation and building eCapture. ```yaml # Example GitHub Actions workflow jobs: e2e-tests: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Install dependencies run: | sudo apt-get update sudo apt-get install -y clang llvm golang - name: Build ecapture run: make nocore - name: Run basic e2e tests run: sudo make e2e-basic ``` -------------------------------- ### Start eCapture with eCaptureQ enabled Source: https://github.com/gojue/ecapture/blob/master/docs/event-forward-api.md Starts eCapture and enables the WebSocket server for streaming logs and events. The listening address can be customized. ```bash sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/ ``` -------------------------------- ### OpenSSL Server Application Label Example Source: https://github.com/gojue/ecapture/blob/master/kern/README.md Example code snippet demonstrating the setup for server application traffic secret derivation in OpenSSL. ```c insecret = s->master_secret; label = server_application_traffic; labellen = sizeof(server_application_traffic) - 1; log_label = SERVER_APPLICATION_LABEL; ``` -------------------------------- ### Setup eBPF Probe Manager Source: https://github.com/gojue/ecapture/blob/master/docs/refactoring-guide.md Sets up the eBPF manager with probe and map configurations. Requires a binary path to be specified in the configuration. ```go func (p *Probe) setupManager() error { binaryPath := p.config.BinaryPath if binaryPath == "" { return errors.NewConfigurationError("binary_path required", nil) } p.Logger().Info(). Str("binary_path", binaryPath). Msg("Setting up eBPF probes") p.bpfManager = &manager.Manager{ Probes: []*manager.Probe{ { Section: "uprobe/my_function", EbpfFuncName: "uprobe_my_function", AttachToFuncName: "target_function", BinaryPath: binaryPath, }, }, Maps: []*manager.Map{ {Name: "events"}, }, } return nil } ``` -------------------------------- ### Start eCapture Server (Network Interface) Source: https://github.com/gojue/ecapture/blob/master/examples/ecaptureq_client/TESTING.md Start the eCapture server listening on a specific network interface for WebSocket connections. The URL must end with a trailing slash. ```bash sudo ./ecapture tls --ecaptureq=ws://192.168.1.100:28257/ ``` -------------------------------- ### Initialize eCapture Compilation Environment on Ubuntu Source: https://github.com/gojue/ecapture/blob/master/docs/compilation.md Run this script on Ubuntu 20.04+ to set up the necessary compilation environment. Ensure you have curl installed. ```shell /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)" ``` -------------------------------- ### Test 1: Localhost Connection Scenario Source: https://github.com/gojue/ecapture/blob/master/examples/ecaptureq_client/TESTING.md Demonstrates a full test scenario connecting the client to the eCapture server running on localhost. This involves starting the server, client, and generating traffic. ```bash # Terminal 1 sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/ # Terminal 2 ./ecaptureq_client -server ws://127.0.0.1:28257/ # Terminal 3 curl https://www.baidu.com ``` -------------------------------- ### CI Integration Example for eCapture Tests Source: https://github.com/gojue/ecapture/blob/master/test/e2e/QUICK_REFERENCE.md This YAML configuration sets up a GitHub Actions workflow to automatically run eCapture's end-to-end tests on push and pull request events. It includes steps for checking out code, installing dependencies, building eCapture, running tests, and uploading logs on failure. ```yaml # .github/workflows/e2e-tests.yml name: E2E Tests on: [push, pull_request] jobs: basic-tests: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Install dependencies run: | sudo apt-get update sudo apt-get install -y clang llvm golang-go curl - name: Build eCapture run: make nocore - name: Run basic e2e tests run: sudo make e2e-basic - name: Upload test logs on failure if: failure() uses: actions/upload-artifact@v3 with: name: test-logs path: /tmp/ecapture_* ``` -------------------------------- ### Run eCapture Protobuf Debugger (Default) Source: https://github.com/gojue/ecapture/blob/master/utils/protobuf_visualizer/README.md Connect to the default WebSocket address (ws://127.0.0.1:28257) to start debugging. ```bash ./pb_debugger ``` -------------------------------- ### Go WebSocket Integration Example Source: https://github.com/gojue/ecapture/blob/master/protobuf/PROTOCOLS.md Demonstrates how to connect to the eCapture WebSocket endpoint, receive protobuf messages, and unmarshal them into LogEntry objects. Ensure the correct protobuf package path and necessary libraries are imported. ```go import ( pb "github.com/gojue/ecapture/protobuf/gen/v1" "golang.org/x/net/websocket" "google.golang.org/protobuf/proto" ) // Connect ws, err := websocket.Dial("ws://127.0.0.1:28257/", "", "http://localhost/") if err != nil { // Handle error } defer ws.Close() // Receive messages for { var msgData []byte err := websocket.Message.Receive(ws, &msgData) if err != nil { break } var logEntry pb.LogEntry err = proto.Unmarshal(msgData, &logEntry) if err != nil { continue } // Process logEntry based on logEntry.LogType } ``` -------------------------------- ### Benchmark with eCapture (PcapNG Mode) Source: https://github.com/gojue/ecapture/blob/master/docs/performance-benchmarks.md Starts eCapture in pcapng mode to capture TLS traffic to a file and then runs the `wrk` benchmark. Requires the PID of the target process. ```bash # Terminal 1: Start eCapture in pcapng mode sudo ecapture tls -m pcap -i lo --pcapfile=/tmp/bench.pcapng --pid= ``` ```bash # Terminal 2: Run the same benchmark wrk -t4 -c100 -d60s https://localhost:8443/ ``` -------------------------------- ### Install required tools for Ubuntu/Debian Source: https://github.com/gojue/ecapture/blob/master/docs/e2e-tests.md Installs necessary packages including curl, python3, openssl, and netcat-openbsd on Ubuntu/Debian systems to resolve missing tools errors. ```bash # Ubuntu/Debian sudo apt-get install curl python3 openssl netcat-openbsd ``` -------------------------------- ### Successful eCapture Test Output Example Source: https://github.com/gojue/ecapture/blob/master/test/e2e/QUICK_REFERENCE.md This example shows the expected output for a successful eCapture test case. It indicates the test being started, the action performed, and a clear success message. ```text [INFO] === Test 1: HTTP/1.1 Capture === [INFO] Starting ecapture in text mode [INFO] Making HTTP/1.1 request to https://www.github.com [SUCCESS] ✓ HTTP/1.1 capture test PASSED ``` -------------------------------- ### Benchmark with eCapture (Text Mode) Source: https://github.com/gojue/ecapture/blob/master/docs/performance-benchmarks.md Starts eCapture in text mode to capture TLS traffic and then runs the `wrk` benchmark. Requires the PID of the target process. ```bash # Terminal 1: Start eCapture sudo ecapture tls -m text --pid= ``` ```bash # Terminal 2: Run the same benchmark wrk -t4 -c100 -d60s https://localhost:8443/ ``` -------------------------------- ### Prepare Kernel Headers for Cross-Compilation Source: https://github.com/gojue/ecapture/blob/master/docs/compilation.md Install kernel source and prepare header files for cross-compilation. This is necessary for targeting different architectures. ```shell sudo apt-get install -y linux-source cd /usr/src source_file=$(find . -maxdepth 1 -name "*linux-source*.tar.bz2") source_dir=$(echo "$source_file" | sed 's/\.tar\.bz2//g') sudo tar -xf $source_file cd $source_dir test -f .config || yes "" | sudo make oldconfig ``` -------------------------------- ### Clean Up eCapture Binaries Source: https://github.com/gojue/ecapture/blob/master/examples/ecaptureq_client/TESTING.md Remove the built eCaptureQ client binary from the examples directory. ```bash rm examples/ecaptureq_client/ecaptureq_client ``` -------------------------------- ### Install build dependencies for eCapture Source: https://github.com/gojue/ecapture/blob/master/docs/e2e-tests.md Installs essential build dependencies like clang, llvm, libelf-dev, pkg-config, and golang-go on Ubuntu/Debian systems for manual eCapture builds. ```bash # Install build dependencies sudo apt-get install clang llvm libelf-dev pkg-config golang-go ``` -------------------------------- ### Build the eCapture Client Source: https://github.com/gojue/ecapture/blob/master/examples/ecaptureq_client/README.md Build the eCapture WebSocket client from the source code. This can be done within the example directory or from the repository root. ```bash cd examples/ecaptureq_client go build -o ecaptureq_client main.go ``` ```bash go build -o ecaptureq_client ./examples/ecaptureq_client ``` -------------------------------- ### Start eCapture with WebSocket Server Source: https://github.com/gojue/ecapture/blob/master/examples/ecaptureq_client/README.md Initiate the eCapture process with the WebSocket server enabled. Specify the host and port for the WebSocket connection. Ensure a specific IP address is used, not '0.0.0.0'. ```bash # Example: Listen on localhost port 28257 sudo ./ecapture tls --ecaptureq=ws://127.0.0.1:28257/ ``` ```bash # Example: Listen on all interfaces port 28257 # Note: Use a specific IP address, not 0.0.0.0 sudo ./ecapture tls --ecaptureq=ws://192.168.1.100:28257/ ``` -------------------------------- ### Install required tools for RHEL/CentOS Source: https://github.com/gojue/ecapture/blob/master/docs/e2e-tests.md Installs necessary packages including curl, python3, openssl, and nc on RHEL/CentOS systems to resolve missing tools errors. ```bash # RHEL/CentOS sudo yum install curl python3 openssl nc ``` -------------------------------- ### GoTLS Module Command Source: https://github.com/gojue/ecapture/blob/master/docs/example-outputs.md This demonstrates how to start the GoTLS module to capture TLS traffic from a specific Go binary. It requires running eCapture in one terminal and the target Go program in another. ```bash # Terminal 1: Start eCapture targeting a Go binary sudo ecapture gotls --elfpath=/home/cfc4n/go_https_client --hex # Terminal 2: Run the Go program /home/cfc4n/go_https_client ``` -------------------------------- ### Failure eCapture Test Output Example Source: https://github.com/gojue/ecapture/blob/master/test/e2e/QUICK_REFERENCE.md This example demonstrates a failed eCapture test. It shows an error message indicating eCapture died during startup, followed by a clear failure message for the test case. ```text [INFO] === Test 5: Concurrent Connections === [ERROR] eCapture died during startup [ERROR] ✗ Concurrent connections test FAILED ``` -------------------------------- ### Adding New Tests to Makefile Source: https://github.com/gojue/ecapture/blob/master/test/e2e/README.md Example of how to add a new end-to-end test target to the Makefile. ```makefile .PHONY: e2e-mytest e2e-mytest: bash ./test/e2e/my_new_test.sh ``` -------------------------------- ### Commit Message Format Example Source: https://github.com/gojue/ecapture/blob/master/CONTRIBUTING.md Follow this format for commit messages to clearly indicate what changed and why. Ensure the subject is concise and the body explains the reasoning. ```git cli: update module name "mysqld56" to "mysqld" . add shortflag for "debug" flag. Fixes #6 ``` ```git :