Installation

pip install -r requirements.txt

Then, in the vSim directory, run

export PYTHONPATH=$(pwd)export VSIM_HOME=$(pwd)

Docker image

You may try our artifact using the docker image

# create image
docker build -t vsim:0.1 .# start container
docker run --name ndss26ae -it -d vsim:0.1
# use the bash
docker exec -it ndss26ae bash
cd /vSim &&source source.sh

Preprocess with IDA

The script ida/ida_script.py was tested with IDA v7.5.

<ida_path> -A -S"ida/ida_script.py <output_path>" bin_path

The output_path stores the extracted binary function entries.

For stripped binaries, vSim depends on IDA to identify the function entries.

Value Extraction

To run our customized symbolic execution engine, please run the following command. Please remember the dump_dir and cache_dir. In dump_dir, you will get many <func_addr>.pkl files. In cache_dir, there is a *.pkl file, which stores the preprocessed binary information.

# use ida's binary function entries
python ./src/bin_analyzer.py \
--bin <binary> \
--dump <dump_dir> \
--cache <cache_dir> \
--ida <ida_pkl_path> \
--loglevel 0 \
--workers <workers>

Fingerprint Generation

This process combines our Value Filtering, Normalization, Concretization.

Please prepare a CSV file, with columns binary,dump_dir,cache_dir,bin_id. binary, dump_dir, and cache_dir are the absolute paths used while value extraction. bin_id is the identifier of this binary. The binaries compiled from the same source should have the identical bin_id.

Please modify the paths for csv_path and fingerprint_dir.

• csv_path is the aforementioned CSV file.
• fingerprint_dir is the directory to store all generated fingerprints

fromutilsimport*importloggingfromsrc.pool.poolimportBinaryPoolfromsrc.bin_analyzerimportBinAnalyzerfromsrc.sim.baseimportSimBasecsv_path='xxx'fingerprint_dir='yyy'func_pool_path=csv_path+'.pkl'expr_timeout=30workers=32e_workers=1mode='refined'if__name__=='__main__':
expr_logger=get_logger_for_file(logging.ERROR, 'expr_sim')
get_logger_for_file(logging.ERROR, logname='binary_pool')
binary_pool=BinaryPool(csv_path, fingerprint_dir)
ifos.path.exists(func_pool_path):
func_pool=load_pkl(func_pool_path)
else:
func_pool=binary_pool.build_function_pool(
workers=workers,
expr_vec_workers=e_workers,
mode=mode,
expr_timeout=expr_timeout)
dump_pkl(func_pool, csv_path+'.pkl')

Function pool construction and similarity analysis

The above step have built pool of binaries. Given two bianry pools (e.g., gcc-O0 pool and gcc-O3 pool), we can perform pairwise match between them. Run the following code will perform Fingerprint Propagation, build pandas Dataframe as function pools, and compute their similarity pairwisely.

fromscripts.pool_pairwise_matchimportSETTINGS, get_ppw, runcsv1='xxx'csv2='yyy'fingerprints_dir='zzz'pool_size=10000# it should be false if you compare these two binary pools first time# Then, you can set it to True and always compare the same function pairsload_existing_key=Falsesetting='all_features'top_k, mrr, cost=run(csv1, csv2,
fingerprints_dir, pool_size, setting,
load_existing_key=load_existing_key,
key_path=key_file_path,
with_weights=True, workers=64)
res.append({'db_csv': csv1,
'input_csv': csv2,
'setting': setting,
'top_k': top_k,
'K_list': [1, 3, 5, 10, 50, 100],
'mrr': mrr,
'MRR_K_list': [None, 10, 100],
'pool_size': pool_size,
'cost': cost})
print(csv1, csv2, top_k, mrr)

Guidance for reproduce results

Assume the unzip vSim directory has a path $VSIM_HOME.

First of all, ensure two environment variables have been set

export PYTHONPATH=$(pwd)export VSIM_HOME=$(pwd)

In the docker image, running cd /vSim && source source.sh has the same effect.

Preparation

Please download the zip files for datasets and test first.

Please enter $VSIM_HOME/test folder and unzip all zip files:

unzip cross-optimization.zip
unzip cross-compiler.zip
unzip GMN-dataset-2.zip
unzip GMN-vul.zip

In the $VSIM_HOME directory, please run mkdir datasets;

Then, please download the datasets from the following links

• pem.zip (this dataset has been included in the repository)
• GMN-D2.zip
• binkit_xc.zip

Please unzip binkit_xc.zip.
Please unzip GMN-D2.zip with password ndss26ae.

Those binaries are also available from the released artifacts of PEM, GMN, and BinKit (we use the ver. 2.0 dataset).

After downloading all files, extract them in $VSIM_HOME/datasets.

If you are trying to reproduce the results in our paper, please also download the following zip files and put them in the test folder.

• cross-compiler.zip
• cross-optimization.zip
• GMN-dataset-2.zip
• GMN-vul.zip

After the preparation step, we have a folder structure like

vSim # $VSIM_HOME
├─ ida
│ └─ ida_script.py # the IDA Python script for preprocessing
├─ src # source code of vSim
├─ scripts # some useful scripts
├─ datasets # directory for storing raw binaries
│ ├─ pem-trex # binaries for cross-optimization
│ ├─ binkit_xc # binaries for cross-compiler
│ └─ Dataset-2 # GMN-dataset-2 for cross-architecture
│
├─ test
│ ├─ cross-optimization # directory for test cross-optimization
│ │ ├─ se_cmds.txt # command lines for value extraction
│ │ ├─ fp-gen.py # script for fingerprint generation
│ │ ├─ fp-no-refine-gen.py #script for fingerprint generation without filtering
│ │ ├─ test_pool_pairwise_match.py # script for running comparison
│ │ ├─ fp-refined # fingerprints with value filtering
│ │ ├─ fp-no-refined # fingerprints without value filtering
│ │ ├─ table_1 # directory for running comparison
│ │ │ ├─ O0_pool.csv
│ │ │ ├─ O2_pool.csv
│ │ │ └─ O3_pool.csv
│ │
│ ├─ cross-compiler # directory for test cross-compiler
│ │ ├─ ... # similar to cross-optimization folder
│ ├─ GMN-dataset-2
│ ├─ GMN-vul
│ │ └─Dataset-Vulnerability # GMN vulnerability dataset

Fast run

bash AE_fast_run.sh

Those commands will print the tables of vSim's results in our paper. Tables III, IV, V are self-explanatory.

The Retrieval time of Table V is the sum of printed time cost.

For Table VI, you will see

 x86:NETGEAR_R7000
0 0.875
x86:NETGEAR_R7000
0 2;1;1;1

x86:NETGEAR_R7000 means the result is the comparison between x86 and NETGEAR_R7000

0.875 is the MRR@10, 2;1;1;1 is the ranks of comparison cases. See Table 6 of GMN's paper.

Toy example

This is a toy example for demonstration. Please run

bash AE_toy.sh

Reproduce the comparison results

Use our provided fingerprints to perform comparison.

NOTE: Rerunning the comparison will require as many CPU cores as possible.

# Show vSim's result in Table III
bash AE_rerun_cross-optimization.sh
# Show vSim's result in Table IV
bash AE_rerun_cross-compiler.sh
# Show vSim's result in Table V
bash AE_rerun_GMN-D2.sh
# Show vSim's result in Table VI
bash AE_rerun_GMN-vul.sh

Fully reproduce the whole results, including fingerprint generation

Delete the cached fingerprints and re-generate the fingerprints

NOTE: This process is extremely time-consuming and may take several days

# Show vSim's result in Table III
bash AE_rerun_cross-optimization.sh full
# Show vSim's result in Table IV
bash AE_rerun_cross-compiler.sh full
# Show vSim's result in Table V
bash AE_rerun_GMN-D2.sh full
# Show vSim's result in Table VI
bash AE_rerun_GMN-vul.sh full

Bibtex

If this work are helpful for your research, please consider citing the following bibtex entry.

@inproceedings{wang2026vsim, title={{vSim}: Semantics-aware value extraction for efficient binary code similarity analysis}, author={Wang, Huaijin and Lin, Zhiqiang}, year={2026},
booktitle={Network and Distributed Systems Security (NDSS) Symposium}
}