Malware family detection (TCA-0305)

The Malware Family Detection API takes a file hash and returns all malware families to which that sample belongs, based on the detections from the latest AV scan.

General Info about Requests/Responses

• All requests accept the format query field which supports two options: XML or JSON.
• The default response format is JSON (for bulk query, the default is the same as the post format)
• All bulk query rules will accept post payload in XML or JSON
• The number of hashes in a bulk request must not be larger than 100

Malware Family Detection Single Query

Request

GET /api/malware/family/detection/v1/query/{hash_type}/{hash_value}[?format=xml|json]

Path parameters:

• hash_type accepts these options: md5, sha1, sha256
• hash_value must be a valid hash defined by the hash_type parameter

Query parameters:

• format parameter specifies the desired return format: xml or json (default)
• If an entry is not found in single query, HTTP response 404 is returned

Response

{
  "rl": {
    "sample": {
      "sha1": "string",
      "family": {
        "entries": [
          "string"
        ]
      }
    }
  }
}

• sha1
  • The SHA1 hash of the sample.
• family
  • Malware family. Can contain several entries.

Malware Family Detection Bulk Query

This query retrieves the same data as single query does, but for multiple hashes.

Request

POST /api/malware/family/detection/v1/bulk_query/{post_format}[?format=xml|json]

Path parameters:

• post_format parameter defines the post's payload format
• post_format parameter accepts the following options: xml or json

Query parameters:

• format defines the desired return format (xml or json). If not specified, it returns the same format as post_format

Request body:

{
  "rl": {
    "query": {
      "hash_type": "string",
      "hashes": [
        "string"
      ]
    }
  }
}

Response

{
  "rl": {
    "entries": [
      {
        "sample": {
          "sha1": "string",
          "family": {
            "entries": [
              "string"
            ]
          }
        }
      }
    ],
    "invalid_hashes": [
      "string"
    ],
    "unknown_hashes": [
      "string"
    ]
  }
}

• sha1
  • The SHA1 hash of the sample.
• family
  • Malware family. Can contain several entries.
• invalid_hashes
  • List of malformed hashes from the request
• unknown_hashes
  • List of hashes from the request that were not found in the database

Examples

Single query

Request:

/api/malware/family/detection/v1/query/sha1/7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb?format=json

Response:

{
  "rl": {
    "sample": {
      "sha1": "7d8f177243cfa055c95cbbf32ebc2d7e8c71d4fb",
      "family": {
        "entries": [
          "Barys",
          "ADH"
        ]
      }
    }
  }
}

Bulk query

Request:

/api/malware/family/detection/v1/bulk_query/json

{
  "rl": {
    "query": {
      "hash_type": "md5",
      "hashes": [
        "0001f757f6b9523707462066100aa543",
        "000202ed4a0fb4c95e68824bc7777a78",
        "00026f63fd5a2600b73a866d7ef08b6f",
        "6c2eb9d1a094d362bcc7631f2551f5a4",
        "a82c781ce0f43d06c28fe5fc8ebb1ca9",
        "920f5ba4d08f251541c5419ea5fb3f"
      ]
    }
  }
}

Response:

{
  "rl": {
    "unknown_hashes": [
      "6c2eb9d1a094d362bcc7631f2551f5a4",
      "a82c781ce0f43d06c28fe5fc8ebb1ca9"
    ],
    "invalid_hashes": [
      "920f5ba4d08f251541c5419ea5fb3f"
    ],
    "entries": [
      {
        "sample": {
          "sha1": "0001f757f6b9523707462066100aa543",
          "family": {
            "entries": [
              "SWIZZOR",
              "Vundo",
              "Swizz",
              "Swizzor",
              "Packer",
              "PolyCrypt",
              "Agent_r",
              "Lop",
              "000155a11",
              "Swizzor DP",
              "C2Lop BB5",
              "Win 121",
              "C2Lop"
            ]
          }
        }
      },
      {
        "sample": {
          "sha1": "000202ed4a0fb4c95e68824bc7777a78",
          "family": {
            "entries": [
              "Ntfs",
              "Cutwail",
              "04c4f2e11",
              "Kobcka",
              "PushInf",
              "Backdoor2 GCGE",
              "DownLoad 47257",
              "Win 4126",
              "CUTWAIL",
              "Protector",
              "Pandex"
            ]
          }
        }
      },
      {
        "sample": {
          "sha1": "00026f63fd5a2600b73a866d7ef08b6f",
          "family": {
            "entries": [
              "SHIZ",
              "Shiz NCF",
              "Shiz",
              "Shiz VP",
              "Shiz mhUAm0d46pg",
              "MalOb",
              "0040f2501",
              "20771",
              "Simda",
              "EncPk"
            ]
          }
        }
      }
    ]
  }
}