github.com/gojue/ecapture@v0.8.2/README.md (about) 1  2 3 [中文介绍](./README_CN.md) | English | [日本語](./README_JA.md) 4 5 [](https://github.com/gojue/ecapture) 6 [](https://github.com/gojue/ecapture) 7 [](https://github.com/gojue/ecapture/actions/workflows/code-analysis.yml) 8 [](https://github.com/gojue/ecapture/releases) 9 10 ### eCapture(旁观者): capture SSL/TLS text content without a CA certificate using eBPF. 11 12 > **Note** 13 > 14 > Supports Linux/Android kernel versions x86_64 4.18 and above, **aarch64 5.5** and above. 15 > Does not support Windows and macOS system. 16 ---- 17 18 19 <!-- MarkdownTOC autolink="true" --> 20 21 - [How eCapture works](#how-ecapture-works) 22 - [eCapture User Manual](#ecapture-user-manual) 23 - [Getting started](#getting-started) 24 - [eCapture Architecture](#ecapture-architecture) 25 - [What's eBPF](#whats-ebpf) 26 - [How to compile](#how-to-compile) 27 - [Contributing](#contributing) 28 29 <!-- /MarkdownTOC --> 30 ---- 31 32 33 # How eCapture works 34 35  36 37 * SSL/TLS plaintext capture, support openssl\libressl\boringssl\gnutls\nspr(nss) libraries. 38 * GoTLS plaintext support go tls library, which refers to encrypted communication in https/tls programs written in the golang language. 39 * bash audit, capture bash command for Host Security Audit. 40 * mysql query SQL audit, support mysqld 5.6\5.7\8.0, and mariadDB. 41 42 # eCapture User Manual 43  44 45 Youtube video: [How to use eCapture v0.1.0](https://www.youtube.com/watch?v=CoDIjEQCvvA "eCapture User Manual") 46 47 # Getting started 48 49 ## use ELF binary file 50 51 Download ELF zip file [release](https://github.com/gojue/ecapture/releases) , unzip and use by 52 command `./ecapture --help`. 53 54 * Linux kernel version >= 4.18 is required. 55 * Enable BTF [BPF Type Format (BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html) (Optional, 2022-04-17) 56 57 ## use docker image 58 59 ```shell 60 # pull docker image 61 docker pull gojue/ecapture:latest 62 # run 63 docker run --rm --privileged=true --net=host -v ${HOST_PATH}:${CONTAINER_PATH} gojue/ecapture ARGS 64 ``` 65 66 ## Command line options 67 68 > **Note** 69 > 70 > Need ROOT permission. 71 > 72 eCapture search `/etc/ld.so.conf` file default, to search load directories of `SO` file, and search `openssl` shard 73 libraries location. or you can use `--libssl` 74 flag to set shard library path. 75 76 If target program is compile statically, you can set program path as `--libssl` flag value directly。 77 78 ## Modules 79 The eCapture tool comprises 8 modules that respectively support plaintext capture for TLS/SSL encryption libraries like OpenSSL, GnuTLS, NSPR, BoringSSL, and GoTLS. Additionally, it facilitates software audits for Bash, MySQL, and PostgreSQL applications. 80 * bash capture bash command 81 * gnutls capture gnutls text content without CA cert for gnutls libraries. 82 * gotls Capturing plaintext communication from Golang programs encrypted with TLS/HTTPS. 83 * mysqld capture sql queries from mysqld 5.6/5.7/8.0 . 84 * nss capture nss/nspr encrypted text content without CA cert for nss/nspr libraries. 85 * postgres capture sql queries from postgres 10+. 86 * tls use to capture tls/ssl text content without CA cert. (Support openssl 1.0.x/1.1.x/3.0.x or newer). 87 You can use `ecapture -h` to view the list of subcommands. 88 89 ## OpenSSL Module 90 91 The OpenSSL module supports three capture modes: 92 93 - `pcap`/`pcapng` mode stores captured plaintext data in pcap-NG format. 94 - `keylog`/`key` mode saves the TLS handshake keys to a file. 95 - `text` mode directly captures plaintext data, either outputting to a specified file or printing to the command line. 96 97 ### Pcap Mode 98 99 You can specify `-m pcap` or `-m pcapng` and use it in conjunction with `--pcapfile` and `-i` parameters. The default value for `--pcapfile` is `ecapture_openssl.pcapng`. 100 101 ```shell 102 ./ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng tcp port 443 103 ``` 104 105 This command saves captured plaintext data packets as a pcapng file, which can be viewed using `Wireshark`. 106 107 ### Keylog Mode 108 109 You can specify `-m keylog` or `-m key` and use it in conjunction with the `--keylogfile` parameter, which defaults to `ecapture_masterkey.log`. 110 111 The captured OpenSSL TLS `Master Secret` information is saved to `--keylogfile`. You can also enable `tcpdump` packet capture and then use `Wireshark` to open the file and set the `Master Secret` path to view plaintext data packets. 112 113 ```shell 114 ./ecapture tls -m keylog -keylogfile=openssl_keylog.log 115 ``` 116 117 You can also directly use the `tshark` software for real-time decryption and display: 118 119 ```shell 120 tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0 121 ``` 122 123 ### Text Mode 124 125 `./ecapture tls -m text` will output all plaintext data packets. (Starting from v0.7.0, it no longer captures SSLKEYLOG information.) 126 127 ## GoTLS Module 128 129 Similar to the OpenSSL module. 130 131 ### check your server BTF config： 132 133 ```shell 134 cfc4n@vm-server:~$# uname -r 135 4.18.0-305.3.1.el8.x86_64 136 cfc4n@vm-server:~$# cat /boot/config-`uname -r` | grep CONFIG_DEBUG_INFO_BTF 137 CONFIG_DEBUG_INFO_BTF=y 138 ``` 139 140 ### gotls command 141 142 capture tls text context. 143 144 Step 1: 145 ```shell 146 ./ecapture gotls --elfpath=/home/cfc4n/go_https_client --hex 147 ``` 148 149 Step 2: 150 ```shell 151 /home/cfc4n/go_https_client 152 ``` 153 ### more help 154 ```shell 155 ./ecapture gotls -h 156 ``` 157 158 ## bash Module 159 capture bash command : `ecapture bash` 160 ```shell 161 ps -ef | grep foo 162 ``` 163 164 # eCapture Architecture 165  166 167 # What's eBPF 168 [eBPF](https://ebpf.io) 169 170 # How to compile 171 Linux Kernel: >= 4.18. 172 173 ## Tools 174 * golang 1.21 or newer 175 * clang 9.0 or newer 176 * cmake 3.18.4 or newer 177 * clang backend: llvm 9.0 or newer 178 * kernel config:CONFIG_DEBUG_INFO_BTF=y (Optional, 2022-04-17) 179 180 ## command 181 182 ### ubuntu 183 If you are using Ubuntu 20.04 or later versions, you can use a single command to complete the initialization of the compilation environment. 184 ```shell 185 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)" 186 ``` 187 ### other Linux 188 In addition to the software listed in the 'Toolchain Version' section above, the following software is also required for the compilation environment. Please install it yourself. 189 * linux-tools-common 190 * linux-tools-generic 191 * pkgconf 192 * libelf-dev 193 194 **Clone the repository code and compile it** 195 196 Caution: The following `make` command will install libpcap into the system 197 directory if `libpcap.a` does not exist under `/usr/local/lib`. If you have 198 installed libpcap in system without `libpcap.a`, it maybe break your libpcap's 199 headers. 200 201 ```shell 202 git clone --recurse-submodules git@github.com:gojue/ecapture.git 203 cd ecapture 204 make 205 bin/ecapture 206 ``` 207 ## compile without BTF 208 eCapture support BTF disabled with command `make nocore` to compile at 2022/04/17. It can work normally even on Linux systems that do not support BTF. 209 ```shell 210 make nocore 211 bin/ecapture --help 212 ``` 213 214 ## cross-compilation 215 ### Kernel header files 216 To cross-compile the eCapture tool, you need to install the kernel header files for the target architecture. you need to install the `linux-source` package. 217 ```shell 218 kernel_ver=`uname -r | cut -d'-' -f 1` 219 sudo apt-get install -y linux-source-$kernel_ver 220 cd /usr/src 221 sudo tar -xf linux-source-${kernel_ver}.tar.bz2 222 cd /usr/src/linux-source-${kernel_ver} 223 test -f .config || yes "" | sudo make oldconfig 224 ``` 225 226 ### ToolChains 227 To cross-compile binary files for the aarch64 architecture on an amd64 architecture system, you need to install the gcc-aarch64-linux-gnu toolchain. Similarly, to cross-compile binary files for the amd64 architecture on an aarch64 system, you need to install the gcc-x86-64-linux-gnu toolchain. 228 * amd64 arch: gcc-aarch64-linux-gnu 229 * arm64 arch: gcc-x86-64-linux-gnu 230 231 ### Build Commands 232 To build an `arm64` artifact on an ubuntu `amd64` system, you can set the `CROSS_ARCH` environment variable to achieve cross-compilation. 233 ```shell 234 CROSS_ARCH=arm64 make 235 ``` 236 237 ## Stargazers over time 238 239 [](https://starchart.cc/gojue/ecapture) 240 241 # Contributing 242 See [CONTRIBUTING](./CONTRIBUTING.md) for details on submitting patches and the contribution workflow.