Clone wiki

virusbattle-sdk / Data Model

Object Classes and Relations

The following diagram summarizes the various classes of objects and their parent-child relations.

vbdatamodel-overview.jpg

The `Archive' class represents the variety of compressed formats, such as, zip, tar, etc. An Archive object may contain another Archive object or an Executable. The 'Executable' class represents the original executable files contained in an Archive. The result of unpacking an Executable is an object of class Unpacked.

DATA MODEL DIAGRAM

vb0.2-datamodel-thumbnail.jpg

object_class property

The result of a query is a collection of objects (in json format), each object belonging to one of the three classes. The class of an object is available via the object_class property. Here is a list of values for object_class property and their meanings:

archive.7z  : 7z compressed archive
archive.tar : tar archive
archive.tgz : gzip compressed archive
archive.zip : zip compressed archive

binary.pe32 : Windows 32 PE executable

binary.unpacked.zip : Binary from unpacking a binary, in a password
          protected zip file

We anticipate adding support for other archive formats, such as, rar, and other binaries.

Object Class: archive.*

{
  "object_class": "archive.zip", 
  "sha1": "defa70e7c2c209d08bdb59d1dafa322368fba8ee", 
  "unix_filetype": "Zip archive data, at least v1.0 to extract", 
  "length": 318156, 
  "uploadDate": "2014-09-18 23:28:27.817000", 
  "children": [
    {
      "service_data": null, 
      "service_name": "archiveHandler", 
      "status": "success", 
      "child": "9e63fc2115a65f06b25c9541ad463a9c53dbccb1"
    }, 
    {
      "service_data": null, 
      "service_name": "archiveHandler", 
      "status": "success", 
      "child": "1661c84ab02129efa9461fc84b8f2c4290df407a"
    }, 
    {
      "service_data": null, 
      "service_name": "archiveHandler", 
      "status": "success", 
      "child": "3c8030b8e344c0bc9211652388621b90d8896290"
    }, 
    {
      "service_data": null, 
      "service_name": "archiveHandler", 
      "status": "success", 
      "child": "61a7409277ca86576a1006a4415701b95acda6b7"
    }
  ], 
  "md5": "522f3af3d85d2e9b5f49330a3c5b5c7c"
}

Object Class: binary.pe32

Here is an example json structure returned in response to query of information for 9e63fc2115a65f06b25c9541ad463a9c53dbccb1.

{
  "object_class": "binary.pe32", 
  "sha1": "9e63fc2115a65f06b25c9541ad463a9c53dbccb1", 
  "unix_filetype": "PE32 executable (GUI) Intel 80386, for MS Windows", 
  "filepath": [
    "user202/testData-1/f53d2ffe563347776f50af7856f1f8b7", 
    "./f53d2ffe563347776f50af7856f1f8b7"
  ], 
  "length": 144384, 
  "parents": [
    "defa70e7c2c209d08bdb59d1dafa322368fba8ee", 
    "3c8030b8e344c0bc9211652388621b90d8896290"
  ], 
  "uploadDate": "2014-09-18 23:33:34.926000", 
  "children": [
    {
      "service_name": "srlUnpacker", 
      "status": "success", 
      "child": "5fb25ea31fdb45377ccc6f0b7542d537d73b71d2",
      "service_data": {
        "unpacker_config": {
          "UNPACKER_MAX_TIME": "5", 
          "UNPACKER_DLLMODE": "0", 
          "UNPACKER_TIMEOUT": "100"
        }, 
        "unpacker_result": {
          "message": "unpacked", 
          "time": "0 sec"
        }
      }
    }
  ], 
  "md5": "f53d2ffe563347776f50af7856f1f8b7"
}

The object_class field tells the type of file. The above object has the class binary.pe32 implying that this is a Windows PE32 executable.
More details about the format are available in the field unix_filetype, which gives the file type identification using the file command.

Notice the values for children and parents. Both values are lists, implying that a Windows PE32 may have multiple parents and multiple children. A parent of a binary.pe32 file must be an archive. In this case, the binary was found in two archives: defa70e7c2c209d08bdb59d1dafa322368fba8ee and 3c8030b8e344c0bc9211652388621b90d8896290.

It is likely one may want the name of the file in the archive. The filepath field gives this information. In the above example it states that the file was found in the respective parents at the following paths: user202/testData-1/f53d2ffe563347776f50af7856f1f8b7 and ./f53d2ffe563347776f50af7856f1f8b7. The paths are given in the same order as the parents.

While it is obvious that an archive may have children, in our data model, a PE 32 executable can also have children. A child of a binary.pe32 file is the program resulting from unpacking the binary executable. In the above example, the program has one child described by the record:

 {
      "service_name": "srlUnpacker", 
      "status": "success", 
      "child": "5fb25ea31fdb45377ccc6f0b7542d537d73b71d2",
      "service_data": {
        "unpacker_config": {
          "UNPACKER_MAX_TIME": "5", 
          "UNPACKER_DLLMODE": "0", 
          "UNPACKER_TIMEOUT": "100"
        }, 
        "unpacker_result": {
          "message": "unpacked", 
          "time": "0 sec"
        }
      }
    }

The sevice_name field states the specific service used to create the child, the status field whether the service was successfully completed, and the child field gives the id associated with the child. In the above example, the child was created using the service srlUnpacker. The service was successfully completed and produced a child with the id 5fb25ea31fdb45377ccc6f0b7542d537d73b71d2.

The above qualification of the type of service indicates that Virusbattle supports multiple services on a binary. That is indeed the case. Virusbattle may also perform semantic reverse engineering of the binary or find semantic matches. This service is currently experimental, and is not yet released for general use.

Object class: binary.unpacked.zip

vbSDK provides the ability to recursively query information for the children of a parent. The following record provides the information extracted for the children stated above.

{
  "object_class": "binary.unpacked.zip", 
  "sha1": "5fb25ea31fdb45377ccc6f0b7542d537d73b71d2", 
  "unix_filetype": "Zip archive data, at least v2.0 to extract", 
  "length": 87607, 
  "parents": [
    "9e63fc2115a65f06b25c9541ad463a9c53dbccb1"
  ], 
  "uploadDate": "2014-09-18 23:33:53.217000", 
  "password": "unpacked", 
  "children": [], 
  "md5": "cc7823ad925e210b1a7e3ac91831fe58"
}

Updated