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}
}
Running TLS traffic analyzer in docker is supported on the following host OS:
# 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 curl
Follow instructions in docker/Dockerfile
to setup required environment.
The program must be run as root
sudo python3 src/main.py
Applications 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 -vv
Doing 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
/opt/wireshark-custom/bin
. tshark
and editcap
binaries are expected.sudo python
may refer to python2! Only Python3 is supported.