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

Download the git repo from bitbucket.org

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

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>"

Wait to receive the key by email. Requires manual approval by admin.
Setup environment variable with the key received by email.
```
export VIRUSBATTLE_KEY=<keysentbyemail>
```

REGISTERED USER

Update vbSDK

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

USING VIRUSBATTLE

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"
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
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.
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".
Generate mappings to connect uploaded files with downloaded files.
```
python vbclient.py -a map
```
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.

Search for similar procedures to given procedure

python vbclient.py -a search <sha1>/0x<rva-of-procedure>

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

Troubleshooting installation issues

Wiki

virusbattle-sdk / Quick Start