Clone wiki

virusbattle-sdk / Quick Start

Quick Start Guide (Linux)

This guide, and most other pages, give example commands for Linux. For quick experimentation WITHOUT UPLOADING ANY MALWARE, see below. Please contact us if you'd like Microsoft Windows (TM) specific commands.


  1. Download the git repo from

    git clone
  2. Request VIRUSBATTLE_KEY (Skip to 4, if you already have a key)

    cd virusbattle-sdk
    python  --email="<>" --name="<Firstname Lastname>"
  3. Wait to receive the key by email. Requires manual approval by admin.

  4. Setup environment variable with the key received by email.

    export VIRUSBATTLE_KEY=<keysentbyemail>


  1. Update vbSDK
    git pull


  1. Upload an exe file or a zip file for analysis

    python -a upload <path-to-binary-file/directory/archive>

    If the archive is password protected, also add the option "-p password"

  2. Query information about the file you uploaded.

    python -a query <sha1>

    <sha1> is the SHA1 hash of the file you uploaded. You may compute it some third-party program. Or it is also available in the file UploadedHashes.txt (written during upload and read during query by default if no sha1 is provided). python -a query cat UploadedHashes.txt

  3. Download analyses output files.

    python -a download <sha1>

    It will create a folder "Results", and put the downloaded files there. The unpacked files are not downloaded as they are in executable format.

  4. Download unpacked files along with other analyses output files.

    python -a download <sha1> --enable_malware_download

    It will create a folder "Results", and put the downloaded files there. The unpacked files are distributed as password protected zips. The password is "unpacked".

  5. Generate mappings to connect uploaded files with downloaded files.

    python -a map
  6. Search for similar files

    python -a matches <sha1>

    It will create a folder "Results", and save the similarity results in files similarity.csv and similarity.json in csv and json format respectively.

  7. Search for similar procedures to given procedure

    python -a search <sha1>/0x<rva-of-procedure>
  8. View the underlying feature set (juice, api, strings,..) generated from procedure/binary:

    python -a show <sha1-of-binary>
    python -a show <sha1>/0x<rva-of-procedure>


The repo contains hashes of some malware already uploaded on virusbattle. This should allow experimenting with the system without uploading any malware.

The hashes are contained in files in the tests/sample_hashes.txt files. Over time we may add other files in the tests directory, so please look at it for the most recent information.

Copy/paste these commands

mkdir Results
python -a query --lf tests/sample_hashes.txt > Results/query.json
python -a matches --lf tests/sample_hashes.txt        # look at file Results/similarity.csv
python -a show `head -1 tests/sample_hashes.txt`      # json output to the stdout