vSim

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

(★ 18)

The artifact of "vSim: Semantics-Aware Value Extraction for Efficient Binary Code Similarity Analysis," NDSS 2026. You may also have a look at https://doi.org/10.5281/zenodo.17751555

vSim Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Installation
```
pip install -r requirements.txt
```
Then, in the `vSim` directory, run
```bash
export PYTHONPATH=$(pwd)
export VSIM_HOME=$(pwd)
```

### Docker image
You may try our artifact using the docker image
```bash
# 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.
```bash
<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.
```bash
# 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

```py
from utils import *
import logging
from src.pool.pool import BinaryPool
from src.bin_analyzer import BinAnalyzer
from src.sim.base import SimBase

csv_path = 'xxx'
fingerprint_dir = 'yyy'

func_pool_path = csv_path + '.pkl'
expr_timeout = 30
workers = 32
e_workers = 1
mode = '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)
    if os.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.

```py
from scripts.pool_pairwise_match import SETTINGS, get_ppw, run

csv1 = '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 pairs
load_existing_key=False

setting='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
```bash
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:
```bash
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](https://drive.google.com/file/d/1QLuUNay0o_HAFjfCWY4AwhinFX6P7c14/view?usp=sharing) (this dataset has been included in the repository)
+ [GMN-D2.zip](https://drive.google.com/file/d/1Y1Umc9CV9xgE1Vwdevk9okOx1TFaWsY4/view?usp=sharing)
+ [binkit_xc.zip](https://drive.google.com/file/d/14J4tyShU3Oy2MPNAl8YQQrpU7dM_aHrB/view?usp=sharing)

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

Those binaries are also available from the released artifacts of [PEM](https://dl.acm.org/do/10.5281/zenodo.8271984/full),
[GMN](https://github.com/Cisco-Talos/binary_function_similarity),
and [BinKit](https://github.com/SoftSec-KAIST/BinKit) (we use the [ver. 2.0 dataset](https://drive.google.com/file/d/1TrjFnv6BMpVEXYukVxrhlQ78S0NPKEXa/view?usp=share_link)).

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](https://drive.google.com/file/d/1EoQWEJ1t6IOZjz7B_te0VzcG5dK-5Yi0/view?usp=sharing)
+ [cross-optimization.zip](https://drive.google.com/file/d/1kBx_ANUkHrGHjnkKFlRrf2IwF86-xsxF/view?usp=sharing)
+ [GMN-dataset-2.zip](https://drive.google.com/file/d/1jZsl80LuXNkR7GBZb6svdPpFdCXkAur9/view?usp=sharing)
+ [GMN-vul.zip](https://drive.google.com/file/d/13mZFz30p_6RRGfj2JEJyvEFmWDcvhdZJ/view?usp=sharing)

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
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](https://www.usenix.org/system/files/sec22-marcelli.pdf).

## Toy example
This is a toy example for demonstration. Please run
```bash
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.

```bash
# 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

```bash
# 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.
```bib
@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}
}
```

vSim

vSim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vSim

vSim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README