X-Ray-TLS allows to inspect TLS-encrypted traffic made from local programs by extracting TLS session keys from process memory in a generic and transparent way.
If using this work, please cite our paper:
@inproceedings{10.1145/3634737.3637654,
author = {Moriconi, Florent and Levillain, Olivier and Francillon, Aur\'{e}lien and Troncy, Raphael},
title = {X-Ray-TLS: Transparent Decryption of TLS Sessions by Extracting Session Keys from Memory},
year = {2024},
isbn = {9798400704826},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3634737.3637654},
doi = {10.1145/3634737.3637654},
booktitle = {Proceedings of the 19th ACM Asia Conference on Computer and Communications Security},
pages = {35–48},
numpages = {14},
keywords = {TLS, transport layer security, TLS decryption, memory analysis},
location = {Singapore, Singapore},
series = {ASIA CCS '24}
}- Generic: no prior knowledge on target program internals
- Transparent: minimum intrusiveness, no program cooperation
- Practical: only Linux kernel facilities (no hypervisor)
- Support TLS hardening: Perfect Forward Secrecy, certificate pinning
Running TLS traffic analyzer in docker is supported on the following host OS:
- ubuntu:20.04
- debian:11 (to come soon)
- archlinux:latest (to come soon) You can use any of the name above in BASE_IMAGE build argument.
# Build the image with the same base OS as your host OS
# WARNING: you must recompile the image on host kernel updates
# Set BASE_IMAGE=... to one of the supported host OS (see above)
docker build -t tls-traffic-analyzer:latest --no-cache --build-arg BASE_IMAGE=ubuntu:20.04 -f docker/Dockerfile .
# Get interface of default route (or set the interface you want to listen on)
INTERFACE=$(ip -4 route | awk '/default/{print $5}')
# Run without saving traffic dumps for curl commands
# Add -vv for DEBUG
docker run --privileged -it --rm --network host --pid host tls-traffic-analyzer:latest -i $INTERFACE --commands curl
# Run with saving traffic dumps for curl commands
docker run --privileged -it --rm -v $(pwd)/dumps:/dumps --network host --pid host tls-traffic-analyzer:latest -i $INTERFACE -o /dumps --chown-traffic-dumps $UID --commands curlFollow instructions in docker/Dockerfile to setup required environment.
The program must be run as root
sudo python3 src/main.pyApplications executed in a Docker container run in a different namespace.
By providing --container parameter (container name or id), this tool will bind to the network namespace of the target container (but not other namespaces, like mount namespace).
It means traffic dumps will still be saved on the host filesystem.
In this context, --interface parameter should be adapted to match interface name in the docker container, often eth0.
Furthermore, if running the tool from a Docker container, you should give access to the host Docker daemon using a bind mount like below:
docker run --privileged -it --rm -v $(pwd)/dumps:/dumps -v /var/run/docker.sock:/var/run/docker.sock --network host --pid host tls-traffic-analyzer:latest -o /dumps --chown-traffic-dumps $UID --container my_container -vvDoing traffic analysis on all applications running on the host system is not probably not what you want.
Depending on the configuration, this tool may freeze applications for short periods of time and decrypt TLS sessions
that you would not expect to be decrypted and stored on disk.
Therefore, it is strongly encouraged to use --commands to limit the analysis to given commands.
If you know what you are doing, running on all commands on the host can be enabled using the environment variable ALLOW_ALL_COMMANDS_ON_HOST=true
- DUMP_METHOD: Set dump method. See paper for details. Available values: full-full, rst-partial, rst-partial-rst, full-partial, full-partial-rst
- DEBUG_SAVE_DIFF: If set, save memory diff to the path defined (new diff will erase old diff). E.g., DEBUG_SAVE_DIFF=/tmp/diff.bin
- CUSTOM_WIRESHARK_BIN_PATH: Path to custom version of wireshark/tshark.
Default to
/opt/wireshark-custom/bin.tsharkandeditcapbinaries are expected. - STATS_FILENAME: Name of the stats file relative to the dump directory (default to stats.json)
- MEM_REGIONS: Restrict memory dump to regions with paths defined here (separated by comma). Default is to dump all regions with writable flag.
Examples: "[heap]" (heap only), "[heap]," (head and anonymous regions), "[heap],/usr/lib/x86_64-linux-gnu/libnghttp2.so.14.19.0" (heap and a statically assigned memory region).
To only dump anonymous regions (i.e., dynamically assigned using mmap), use "," (do NOT use "" as it would disable the feature flag). - (not implemented) - MIN_DIFF_LENGTH_BYTES: If set, only changed parts of the memory larger than MIN_DIFF_LENGTH_BYTES will be added to the memory diff. If not set, all changed parts will be added (with a granularity of 8 bytes).
sudo python may refer to python2! Only Python3 is supported.