Tutorial¶

This tutorial helps you get started using MAGIC through a walk through of several capabilities MAGIC provides.

If you haven’t yet, first go through Accessing API.

In this tutorial, we will assume that the following variables are available:

Variable	Description
MAGIC_API_KEY	The API key used to access the MAGIC API.
BINARY_HASH	The SHA1 of a binary. `2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0` in this tutorial

Upload file for analysis¶

To start, let’s upload our binary to MAGIC. In addition to individual binaries, archives, such as zip or tar, are also supported.

curl -X POST \
     -F "filedata=@./sample.exe" \
     -F "filename=sample.exe" \
     "https://api.magic.cythereal.com/v1/files/?key=${MAGIC_API_KEY}"

You can also use the cythereal-magic command line utility:

cythereal-magic --key=${MAGIC_API_KEY} upload ./sample.exe

Check status of Analysis¶

In order to check the status of our uploaded file, we need to know the sha1sum of this file. On linux, this can be found using the sha1sum command.

To get the result of analysis:

curl "https://api.magic.cythereal.com/v1/files/${BINARY_HASH}/info/?key=${MAGIC_API_KEY}"

This results in the following (See magic-api-format for description of communication protocol.):

{
  "api_version": "1.0.0"
  "success": true,
  "code": 200,
  "data": {
        "sha1": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
        "sha256": "338370573c7f275161f7d08cd9a309bcf41c078bf44d4fd50be997e7b83fc856",
        "sha512": "7a73805bdb8a6cf15d7b4c07b25edd17fe9fb3af7aa514497c47bdaaafa3526b929c757d26ca859a432c3295ed2ea352479f5b175eb6f72ef57c8c83d45f7f0d",
        "md5": "a7fd6503d8bc6d0e61b779d968568067"
        "unix_filetype": "PE32 executable (GUI) Intel 80386, for MS Windows",
        "filepath": [
          "./archive",
        ],
        "parents": [
          "fb74c17fad2458f6d8f1f0d3f4dfa7b9ce22a2ec",
        ],
        "uploadDate": "2017-01-10 06:03:52.720000",
        "object_class": "binary.pe32",
        "children": [
          {
                "service_name": "srlUnpacker",
                "status": "success",
                "child": "9bbc14d35aaa53283734826ef54a4e272ae51f01"
          },
          {
                "service_name": "srlJuice",
                "status": "sucess",
          },
          {
                "service_name": "srlSimilarity",
                "status": "success",
          }
        ],
  },
}

The status of the various analyses provided by MAGIC are present in the children field. A pending analysis will not have any entry in this field, a failed analysis will have its status field set to “failure” or “failed”, and a successful analysis will have its status set to success.

This file has been successfully unpacked, the genomic information has been successfully extracted, and the magic report correlations are ready. The unpacked version of this file has a SHA1 of 6efb5c849b400af96b993284f6d39746b6bdb2e6. To get the status of the unpacked file, an additional query would have to be made.

Download unpacked file¶

Note

Downloading files from MAGIC requires additional permissions. Please contact us for these permissions.

To download the unpacked version of a binary using curl, we need to know the SHA1 of the unpacked version. This hash can be located using the status query described last section. For our example of 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0, the unpacked version has a SHA1 of 9bbc14d35aaa53283734826ef54a4e272ae51f01.

curl "https://api.magic.cythereal.com/v1/files/9bbc14d35aaa53283734826ef54a4e272ae51f01/?key=${MAGIC_API_KEY}" > 9bbc14d35aaa53283734826ef54a4e272ae51f01

This will download the unpacked file to a file named 6efb5c849b400af96b993284f6d39746b6bdb2e6.

Get MAGIC Matches¶

To find binaries that “match”, i.e. are similar to our example binary, we retrieve the MAGIC correlations.

curl "https://api.magic.cythereal.com/v1/reports/${BINARY_HASH}/matches/?key={$MAGIC_API_KEY}"

See the Swagger UI for a description of the returned JSON document.

View Genomic Features¶

To get the genomic features for the entire binary:

curl "https://api.magic.cythereal.com/v1/genomics/${BINARY_HASH}/?key=${MAGIC_API_KEY}"

See the Swagger UI for a description of the returned JSON document.

To filter the output to the features in a single procedure, provide the RVA of the procedure in the path. For example, to get genomics for only the procedure with RVA 0x1000:

curl "https://api.magic.cythereal.com/v1/genomics/${BINARY_HASH}/0x1000/?key=${MAGIC_API_KEY}"

Currently, the only way to get the list of procedures in a binary is by retrieving the genomic features for the entire binary. This will be addressed in a future API version.

Search for similar procedures¶

curl "https://api.magic.cythereal.com/v1/similarities/${BINARY_HASH}/0x1000/?key=${MAGIC_API_KEY}"

See the Swagger UI for a description of the returned JSON document.