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.

NEW USER

  1. Download the git repo from bitbucket.org

    git clone http://bitbucket.org/srl/virusbattle-sdk.git
    
  2. Request VIRUSBATTLE_KEY (Skip to 4, if you already have a key)

    cd virusbattle-sdk
    python vbregister.py  --email="<youremail@domain.com>" --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>
    

REGISTERED USER

  1. Update vbSDK

    git pull http://bitbucket.org/srl/virusbattle-sdk.git
    

USING VIRUSBATTLE

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

    python vbclient.py -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 vbclient.py -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 vbclient.py -a query cat UploadedHashes.txt

  3. Download analyses output files.

    python vbclient.py -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 vbclient.py -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 vbclient.py -a map
    
  6. Search for similar files

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

    python vbclient.py -a show <sha1-of-binary>
                     or
    python vbclient.py -a show <sha1>/0x<rva-of-procedure>
    

EXPERIMENTING WITHOUT UPLOADING ANY MALWARE

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 vbclient.py -a query --lf tests/sample_hashes.txt > Results/query.json
python vbclient.py -a matches --lf tests/sample_hashes.txt        # look at file Results/similarity.csv
python vbclient.py -a show `head -1 tests/sample_hashes.txt`      # json output to the stdout

TROUBLESHOOTING

Updated