github.com/gojue/ecapture@v0.8.2/README_CN.md (about) 1  2 3 中文介绍 | [English](./README.md) | [日本語](./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(旁观者): 基于eBPF技术实现TLS加密的明文捕获，无需CA证书。 11 12 > **Note:** 13 > 14 > 支持Linux系统内核x86_64 4.18及以上版本，aarch64 5.5及以上版本； 15 > 16 > 不支持Windows、macOS系统。 17 18 官方网站： [https://ecapture.cc](https://ecapture.cc) 19 20 ---- 21 22 23 <!-- MarkdownTOC autolink="true" --> 24 25 - [eCapture旁观者](#ecapture旁观者) 26 - [eCapture 工作原理](#ecapture-工作原理) 27 - [演示](#演示) 28 - [使用](#使用) 29 - [eCapture 系统架构](#ecapture-系统架构) 30 - [原理](#原理) 31 - [编译方法](#编译方法) 32 - [贡献](#贡献) 33 34 <!-- /MarkdownTOC --> 35 ---- 36 37 38 # eCapture旁观者 39 40 eCapture的中文名字为**旁观者**，即「**当局者迷，旁观者清**」，与其本身功能**旁路、观察**契合，且发音与英文有相似之处。 41 42 # eCapture 工作原理 43 44  45 46 eBPF `Uprobe`/`Traffic Control`实现的各种用户空间/内核空间的数据捕获，无需改动原程序。 47 48 * SSL/HTTPS数据导出功能，针对HTTPS的数据包抓取，不需要导入CA证书。 49 * 支持go tls类库的明文捕获，即使用golang语言编写的https/tls程序的加密通讯。 50 * bash的命令捕获，HIDS的bash命令监控解决方案。 51 * mysql query等数据库的数据库审计解决方案。 52 53 # 演示 54 55 ## eCapture 使用方法 56 ### 介绍文章 57 [eCapture：无需CA证书抓https明文通讯](https://mp.weixin.qq.com/s/DvTClH3JmncpkaEfnTQsRg) 58 59 ### 演示视频 60 #### Linux上使用eCapture 61  62 63 #### Android上使用eCapture 64 [](https://www.bilibili.com/video/BV1xP4y1Z7HB "eCapture for Android") 65 # 使用 66 67 ## 直接运行 68 69 下载 [release](https://github.com/gojue/ecapture/releases) 的二进制包，可直接使用。 70 71 系统配置要求 72 73 * 系统linux kernel版本必须高于4.18。 74 * 开启BTF [BPF Type Format (BTF)](https://www.kernel.org/doc/html/latest/bpf/btf.html) 支持。 (可选, 2022-04-17) 75 76 ## docker 容器化运行 77 78 ```shell 79 # 拉取镜像 80 docker pull gojue/ecapture:latest 81 # 运行 82 docker run --rm --privileged=true --net=host -v ${宿主机文件路径}:${容器内路径} gojue/ecapture ARGS 83 ``` 84 85 86 ## 命令参数 87 88 > **Note** 89 > 90 > 需要ROOT权限执行。 91 92 执行`./ecapture -h`查看详细帮助文档。 93 94 eCapture默认查找`/etc/ld.so.conf`文件，查找SO文件的加载目录，并查找`openssl`等动态链接路位置。你也可以通过`--libssl` 95 参数指定动态链接库路径。 96 97 如果目标程序使用静态编译方式，则可以直接将`--libssl`参数设定为该程序的路径。 98 99 ## 模块介绍 100 eCapture 有8个模块，分别支持openssl/gnutls/nspr/boringssl/gotls等类库的TLS/SSL加密类库的明文捕获、Bash、Mysql、PostGres软件审计。 101 * bash capture bash command 102 * gnutls capture gnutls text content without CA cert for gnutls libraries. 103 * gotls Capturing plaintext communication from Golang programs encrypted with TLS/HTTPS. 104 * mysqld capture sql queries from mysqld 5.6/5.7/8.0 . 105 * nss capture nss/nspr encrypted text content without CA cert for nss/nspr libraries. 106 * postgres capture sql queries from postgres 10+. 107 * tls use to capture tls/ssl text content without CA cert. (Support openssl 1.0.x/1.1.x/3.0.x or newer). 108 109 你可以通过`ecapture -h`来查看这些自命令列表。 110 111 ## openssl 模块 112 openssl模块支持3中捕获模式 113 * pcap/pcapng模式，将捕获的明文数据以pcap-NG格式存储。 114 * keylog/key模式，保存TLS的握手密钥到文件中。 115 * text模式，直接捕获明文数据，输出到指定文件中，或者打印到命令行。 116 ### Pcap 模式 117 你可以通过`-m pcap`或`-m pcapng`参数来指定，需要配合`--pcapfile`、`-i`参数使用。其中`--pcapfile`参数的默认值为`ecapture_openssl.pcapng`。 118 ```shell 119 ./ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng tcp port 443 120 ``` 121 将捕获的明文数据包保存为pcapng文件，可以使用`Wireshark`打开查看。 122 123 ### keylog 模式 124 你可以通过`-m keylog`或`-m key`参数来指定，需要配合`--keylogfile`参数使用，默认为`ecapture_masterkey.log`。 125 捕获的openssl TLS的密钥`Master Secret`信息，将保存到`--keylogfile`中。你也可以同时开启`tcpdump`抓包，再使用`Wireshark`打开，设置`Master Secret`路径，查看明文数据包。 126 ```shell 127 ./ecapture tls -m keylog -keylogfile=openssl_keylog.log 128 ``` 129 130 也可以直接使用`tshark`软件实时解密展示。 131 ```shell 132 tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0 133 ``` 134 ### text 模式 135 `./ecapture tls -m text ` 将会输出所有的明文数据包。（v0.7.0起，不再捕获SSLKEYLOG信息。） 136 137 138 ## gotls 模块 139 与openssl模块类似。 140 141 ### 验证方法： 142 143 ```shell 144 cfc4n@vm-server:~$# uname -r 145 4.18.0-305.3.1.el8.x86_64 146 cfc4n@vm-server:~$# cat /boot/config-`uname -r` | grep CONFIG_DEBUG_INFO_BTF 147 CONFIG_DEBUG_INFO_BTF=y 148 ``` 149 150 ### 启动eCapture 151 ```shell 152 ./ecapture gotls --elfpath=/home/cfc4n/go_https_client --hex 153 ``` 154 155 ### 启动该程序: 156 确保该程序会触发https请求。 157 ```shell 158 /home/cfc4n/go_https_client 159 ``` 160 ### 更多帮助 161 ```shell 162 ./ecapture gotls -h 163 ``` 164 165 166 ### bash的shell捕获 167 capture bash command : `ecapture bash` 168 ```shell 169 ps -ef | grep foo 170 ``` 171 172 # eCapture 系统架构 173  174 175 # 微信公众号 176  177 178 ## 自行编译 179 自行编译对编译环境有要求，参考**原理**章节的介绍。 180 181 # 原理 182 ## eBPF技术 183 参考[ebpf](https://ebpf.io)官网的介绍 184 185 # 编译方法 186 187 针对个别程序使用的openssl类库是静态编译，也可以自行修改源码实现。若函数名不在符号表里，也可以自行反编译找到函数的offset偏移地址，填写到`UprobeOffset`属性上，进行编译。 188 笔者环境`ubuntu 21.04`， Linux Kernel 4.18以上通用。 189 **推荐使用`UBUNTU 20.04` 及以上版本的Linux测试。** 190 191 > **Note** 192 > 193 > Android版本编译方法见 [eCapture旁观者：Android HTTPS明文抓包](https://mp.weixin.qq.com/s/KWm5d0uuzOzReRtr9PmuWQ) 194 195 ## 工具链版本 196 * golang 1.21 以上 197 * clang 9.0 以上 198 * cmake 3.18.4 以上 199 * clang backend: llvm 9.0 以上 200 * kernel config:CONFIG_DEBUG_INFO_BTF=y (可选，2022-04-17增加) 201 202 203 ## 编译环境 204 205 ### ubuntu 206 如果你使用的是ubuntu 20.04以及更新版本，可以使用一条命令即可完成编译环境的初始化。 207 ```shell 208 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gojue/ecapture/master/builder/init_env.sh)" 209 ``` 210 ### 其他Linux 211 编译环境除了上面`工具链版本`列出的软件外，还需要以下软件，请自行安装。 212 * linux-tools-common 213 * linux-tools-generic 214 * pkgconf 215 * libelf-dev 216 217 **克隆仓库代码，并进行编译** 218 219 注意：如果系统里没有 `/usr/local/lib/libpcap.a`，则下面 `make` 命令会将 libpcap 220 编译并安装到 `/usr/local/lib` 目录下。如果系统里已经安装了 libpcap 但没有 221 `/usr/local/lib/libpcap.a`，则 `make` 命令会破坏系统里的 libpcap 头文件。 222 223 ```shell 224 git clone --recurse-submodules git@github.com:gojue/ecapture.git 225 cd ecapture 226 make 227 bin/ecapture 228 ``` 229 230 如果你在中国，可以在`make`编译之前，设定GOPROXY来加速eCapture依赖的go package的安装。 231 ```shell 232 export GOPROXY=https://goproxy.cn 233 ``` 234 235 ## 未开启BTF的编译 236 2022/04/17起，eCapture支持了未开启BTF的系统编译，编译指令为：`make nocore`，即在不支持BTF的Linux上也可以正常工作。 237 238 ```shell 239 git clone git@github.com:gojue/ecapture.git 240 cd ecapture 241 make nocore 242 bin/ecapture 243 ``` 244 ## 交叉编译 245 ### 内核头文件 246 要交叉编译eCapture工具，您需要安装目标体系结构的内核头文件。需要安装`linux-source`软件包。 247 ```shell 248 kernel_ver=`uname -r | cut -d'-' -f 1` 249 sudo apt-get install -y linux-source-$kernel_ver 250 cd /usr/src 251 sudo tar -xf linux-source-${kernel_ver}.tar.bz2 252 cd /usr/src/linux-source-${kernel_ver} 253 test -f .config || yes "" | sudo make oldconfig 254 ``` 255 256 ### ToolChains 257 在amd64架构下，交叉编译aarch64架构的二进制文件，需要安装gcc-aarch64-linux-gnu工具链。同样，在aarch64架构下，交叉编译amd64架构的二进制文件，需要安装gcc-x86-64-linux-gnu工具链。 258 * amd64 arch: gcc-aarch64-linux-gnu 259 * arm64 arch: gcc-x86-64-linux-gnu 260 261 ### 编译命令 262 要在ubuntu `amd64` 系统上构建 `arm64`的产物，您可以设置 `CROSS_ARCH`环境变量来实现交叉编译。 263 ```shell 264 CROSS_ARCH=arm64 make 265 ``` 266 267 ## Stargazers over time 268 269 [](https://starchart.cc/gojue/ecapture) 270 271 272 # 贡献 273 参考 [CONTRIBUTING](./CONTRIBUTING.md)的介绍，提交issue、PR等，非常感谢。