ET-BERT: classifying encrypted traffic by its burst structure

Encrypted traffic becomes a token sequence

ET-BERT is described as a method for learning datagram contextual relationships from encrypted traffic, which could be directly applied to different encrypted traffic scenarios and accurately identify classes of traffic. The mechanism it uses to do that is worth spelling out, because it is the idea the whole repository is built around.

The first step is that encrypted packets are turned into a corpus of bursts, and each burst is tokenised into the kind of sequence a transformer can consume. A burst is a group of packets that belong together, and the README points at a corpus file, corpora/encrypted_traffic_burst.txt, as the input to the preprocessing stage. The topics attached to the repository name the approach: burst analysis, encrypted traffic analysis, mask burst modeling, same-origin burst prediction.

The second step is that a transformer is pre-trained on a large scale of unlabelled traffic, learning both inter-datagram contextual relationships and inter-traffic transport relationships through multi-layer attention. No labels are needed for that stage, which is what makes it a pre-training step rather than a classifier.

The third step is application. Once the pre-trained model exists, it is applied to a specific scenario by fine-tuning on labelled encrypted traffic at packet level, on a small scale. That is the structure of most modern language model work, and the similarity is not accidental: the repository includes a BERT base configuration file, a vocabulary file, and a vocabulary_process directory that builds the encrypted traffic corpus.

The result is a model that can label traffic classes without decrypting a single byte, which is the property that makes it useful in a setting where you cannot or should not decrypt.

The pre-trained model, and how to fine-tune it

The quickest route in is the pre-trained model, which the README links to on Google Drive and also gives as a download command:

wget -O pretrained_model.bin https://drive.google.com/file/d/1r1yE34dU2W8zSqx1FkB8gCWri4DQWVtE/view?usp=sharing

With the model in hand, the documented path to a working classifier is fine-tuning at packet level on labelled network traffic:

python3 fine-tuning/run_classifier.py --pretrained_model_path models/pre-trained_model.bin \
                                   --vocab_path models/encryptd_vocab.txt \
                                   --train_path datasets/cstnet-tls1.3/packet/train_dataset.tsv \
                                   --dev_path datasets/cstnet-tls1.3/packet/valid_dataset.tsv \
                                   --test_path datasets/cstnet-tls1.3/packet/test_dataset.tsv \
                                   --epochs_num 10 --batch_size 32 --embedding word_pos_seg \
                                   --encoder transformer --mask fully_visible \
                                   --seq_length 128 --learning_rate 2e-5

Every argument in that line is worth reading, because the defaults tell you what the authors actually used. The embedding is word_pos_seg, meaning word, position and segment embeddings together, the encoder is a transformer, and the mask is fully_visible, so the model can attend to the whole sequence rather than a lower triangular one. Sequence length is 128 tokens, which is short compared with the 512 a standard BERT base uses, and the learning rate is 2e-5, the value that fine-tuning BERT normally uses.

The default output path is models/finetuned_model.bin, and inference runs through a separate script that takes the fine-tuned model, the same vocabulary and a test file, and writes predictions to a file you name:

python3 inference/run_classifier_infer.py --load_model_path models/finetuned_model.bin \
                                          --vocab_path models/encryptd_vocab.txt \
                                          --test_path datasets/cstnet-tls1.3/packet/nolabel_test_dataset.tsv \
                                          --prediction_path datasets/cstnet-tls1.3/packet/prediction.tsv \
                                          --labels_num 120 \
                                          --embedding word_pos_seg --encoder transformer --mask fully_visible

The labels_num argument is the one to check against your own data. The shipped dataset has 120 classes, and if your traffic contains a different number of categories, that argument is not optional. It is also a reminder that the label space is a property of the dataset, not of the model.

The dataset is one network, five months, and anonymised

The dataset section is short but has real consequences for anyone planning to use this work.

The real-world TLS 1.3 dataset was collected from March to July 2021 on China Science and Technology Network, CSTNET. For privacy considerations, only the anonymous data is released, and it is documented in a readme inside the CSTNET-TLS 1.3 directory of the repository.

The other datasets used for comparison experiments are publicly available, and the paper is referenced for details. The README also says what to do if you want to use your own data: check whether the data format is the same as the datasets/cstnet-tls1.3/ directory, and specify the data path in data_process/.

Two things follow from this. First, the shipped data comes from a single research network over a five-month window in 2021, so it is a specific slice of the traffic world, and a classifier fine-tuned on it will be tuned for the applications and the mix of that network. The paper's own comparison datasets exist precisely because one dataset is not enough for a general claim.

Second, the anonymisation is the right call and also limits the work. The privacy constraint means the released data is not the raw capture, so the preprocessing path that turns pcap into training data is a step you have to run for your own traffic. The README describes it as a two-step process: splitting pcap files by setting splitcap=True in datasets/main.py and saving as npy datasets, then generating the fine-tuning data. If you use the shared datasets instead, you need to create a folder under dataset_save_path named dataset and copy the datasets there.

SplitCap and tshark are both in the requirements list, and scapy is pinned to 2.4.4, so the toolchain for raw pcap is specified rather than assumed.

Reproducing pre-training means a full pipeline

The reproduce section is where the real cost of this repository becomes visible, and it is worth walking through because the README states it as a numbered sequence.

Step one is to run vocab_process/main.py to generate the encrypted traffic corpus, or to use the corpus that is already in corpora/. The README notes that you need to change the file paths and some configuration at the top of that file, which is the usual caveat for a research script that was written for one machine.

Step two is to pre-process the encrypted traffic burst corpus, and the command is given:

       python3 preprocess.py --corpus_path corpora/encrypted_traffic_burst.txt \
                             --vocab_path models/encryptd_vocab.txt \
                             --dataset_path dataset.pt --processes_num 8 --target bert

The target bert argument is what tells the preprocessor which dataset format to emit, and the output is a single dataset.pt file. The processes_num argument controls parallelism, so a machine with more cores shortens this step.

Step three is data generation for downstream tasks, which is the pcap splitting described earlier, and then pre-training itself runs through pretrain.py.

The requirements list is where the hardware expectation shows. The GPU named is a Tesla V100S and the CUDA version is 11.4, with torch 1.1 or newer and Python 3.6 or newer. The optional dependencies are worth noting as well: NVIDIA apex for mixed precision training, TensorFlow for the pre-trained model conversion, WordPiece from the Hugging Face tokenizers for tokenisation, and pytorch-crf for the CRF variant of the sequence labelling downstream task.

That last one is a sign of the scope of the original work. ET-BERT is not only a classifier. The CRF dependency means the framework also supports sequence labelling over the same pre-trained representation, and the paper describes the pre-trained model as applicable to specific scenarios by fine-tuning on labelled encrypted traffic. The repository ships the classification path as the primary example, but the underlying representation was designed to transfer.

Built on UER-py, and the tree tells you what is vendored

The README says plainly that this code is based on UER-py, with thanks to the authors, and the repository layout confirms it. There is a uer/ directory at the top level, alongside corpora/, data_process/, datasets/, fine-tuning/, inference/, models/, pre-training/ and vocab_process/, plus preprocess.py at the root and a bert_base_config.json.

That uer/ directory is the pretraining framework that UER-py provides, and it is what gives the repository a feature that would otherwise be missing: a general pretraining harness rather than a single model. The directory names are the standard vocabulary of that framework, and having it vendored means the corpus format, the vocabulary handling, the model definitions and the training loop all come from the same place.

The tradeoff is that you now depend on a vendored copy of another project's code. When the original framework moves, this repository does not follow unless someone updates it, and the requirements list here is minimal, listing only torch, argparse, six and packaging, which is much thinner than the full requirements section in the README body, where scapy, numpy 1.19.2, tshark, SplitCap, scikit-learn, apex, TensorFlow, WordPiece and pytorch-crf all appear. The requirements.txt file and the README's list are two different documents describing the same project, and the fuller one is the accurate picture of what a full reproduction needs.

The repository also has no GitHub releases, and the last push was on 2026-07-23, with the project not archived. The MIT licence covers the code. The dataset is released separately with its own documentation, so if you are using the data rather than the code, that is the document to read.

Editorial conclusion

Adopt ET-BERT if your research question is encrypted traffic classification, because the pre-trained model, the fine-tuning and inference scripts, and a real-world TLS 1.3 dataset with 120 classes are all provided and the pipeline is reproducible from the documentation. Do not adopt it as a turnkey network monitoring component, since the code is a research repository built on UER-py, the dataset was collected between March and July 2021 on one research network, and reproducing the pre-training needs a Tesla V100S plus a scapy, SplitCap and tshark toolchain. Before you commit, check the labels_num argument against the classes your own traffic contains, and read the licensing note, because the repository is MIT while the dataset it ships is released separately under its own terms.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. linwhitehat/ET-BERT on GitHub
4. README