Cythereal MAGIC User Documentation¶
Cythereal MAGIC extracts intelligence from malicious programs (malware) to aid in cyber defense and incidence response. It combines two orthogonal areas – semantic inference and statistical inference – along with big data analytics to create what may be termed as “Google for malware”. Using a patent-pending technology, Cythereal MAGIC can make connections between malware, peering through its protection mechanisms to discover intrinsic relationships that provide strong evidence for classification and attribution.
Accessing API¶
Request API Key¶
Access to the MAGIC service requires an API key.
To request a key, send an email to support@cythereal.com with the subject “Key Request”. Include your name and email address you want the key to be registered under.
Please note that as part of our minimal verification of identities, we do not provide keys to email addresses pointing to open email services, such as, gmail.com, yahoo.com, aol.com, and many others. Please request a key using your business or university email address.
API Endpoints¶
The MAGIC API can be directly accessed (using curl, for example) at:
The endpoints are documented at API Reference
MAGIC SDK¶
Note
The MAGIC SDK is the preferred way of programatically accessing the MAGIC API.
An SDK in several different languages can be found at:
Documentation of how to use the SDK can be found at the link given above.
MAGIC Client¶
The MAGIC Client is a command line utility named vbclient. This client
provides access to the functionality exposed by the MAGIC API.
This client requires python version 2.7. Older versions of python and python 3 are not supported at this time.
Access to the MAGIC service requires an API Key. If you don’t have one yet, please Request API Key.
There are three options for installing the MAGIC CLI Client:
All installation methods will result in the executable vbclient being
created. This executable provides the CLI interface to MAGIC.
Once installed, the client must be configured
Stand Alone Executable¶
A single executable is provided that packages all necessary libraries for the MAGIC client. Simply download the appropriate version, place it in your PATH, and configure the client.
| Version | Download URL |
|---|---|
| Linux | https://bitbucket.org/cythereal/virusbattle-sdk/downloads/vbclient |
| Windows | https://bitbucket.org/cythereal/virusbattle-sdk/downloads/vbclient.exe |
Install Using Pip¶
The cythereal-sdk package on PyPi is provided for installation via
pip.:
pip install -U cythereal-sdk
Build from Source¶
The source for the MAGIC CLI client is released under the Apache License and can be found at https://bitbucket.org/cythereal/virusbattle-sdk.
To install the client from source:
git clone http://bitbucket.org/cythereal/virusbattle-sdk.git
pip install ./virusbattle-sdk
This will create the vbclient command available in your path.
Configure the client before continuing.
Configure MAGIC Client¶
Accessing the MAGIC client requires an API Key. If you do not have one, first request a key.
The vbclient program expects an environment variable named
VIRUSBATTLE_KEY to contain your API key for accessing MAGIC.
On Linux, place the following in your .bashrc:
export VIRUSBATTLE_KEY=<your API key>
On Windows you can use the System Property Editor to add a new environment
variables and set the value.
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.
Upload file for analysis¶
Further Details: Uploading Files
To start, let’s upload our binary to MAGIC. In addition to individual binaries, archives, such as zip or tar, are also supported.
curl
curl -F "filedata=@./sample.exe" \
-F "origFilePath=sample.exe" \
https://api.magic.cythereal.com/upload/${VIRUSBATTLE_KEY}
vbclient
vbclient -a upload ./sample.exe
This vbclient command will create a file in the local directory
named UploadedHashes.txt that lists the SHA1s of all uploaded files.
Additional uploads in the same directory will append to, rather than
overwrite, this list. In addition, actions such as -a query or -a
status will read hashes from this file if no arguments are provided.
For the purposes of this tutorial, however, we will not make use of this
feature.
Check status of Analysis¶
Further Details: Querying Analysis Status
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. If the
file is uploaded using vbclient, the UploadedHashes.txt file will contain
this hash.
The hash for our example sample is 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0.
curl
To get the result of analysis:
curl https://api.magic.cythereal.com/query/${VIRUSBATTLE_KEY}/2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
This results in the following (See API Response Format for description of communication protocol.):
{
"status": "success",
"hash": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
"vb_version": "VB-0.4",
"answer": {
"sha1": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
"unix_filetype": "PE32 executable (GUI) Intel 80386, for MS Windows",
"filepath": [
"./archive"
],
"length": 1548288,
"parents": [
"fb74c17fad2458f6d8f1f0d3f4dfa7b9ce22a2ec"
],
"uploadDate": "2017-01-10 06:03:52.720000",
"object_class": "binary.pe32",
"children": [
{
"service_name": "srlUnpacker",
"status": "success",
"child": "6efb5c849b400af96b993284f6d39746b6bdb2e6"
},
{
"service_name": "srlJuice",
"status": "success",
"child": null
},
{
"service_name": "srlSimilarity",
"status": "success",
"child": null
}
],
"md5": "a7fd6503d8bc6d0e61b779d968568067"
},
"message": "Object found",
"statuscode": 0
}
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.
For a listing of all services and the analysis they perform, see Services Provided.
vbclient
vbclient -a status 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
sha1sum,object_class,uploadDate,UnpackerStatus,JuiceStatus,SimilarityStatus
2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0,binary.pe32,2017-01-10 06:03:52.720000,success,success,success
6efb5c849b400af96b993284f6d39746b6bdb2e6,binary.unpacked,2017-01-10 06:50:23.575000,n/a,success,success
The -a status command for vbclient returns a csv listing the status of
the query binary as well as all children of that binary. Each service lists
it’s status as success, failure, Pending, or n/a. A status of n/a means that
the service will not be run for the file.
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. The status of this unpacked file is automatically queried for and displayed as well. The unpacked file is not going to be unpacked (because it is already unpacked), its genomic features have been extracted, and the magic report correlations are ready.
For a listing of all services and the analysis they perform, see Services Provided.
Download unpacked file¶
Note
Downloading files from MAGIC requires additional permissions. Please contact us for these permissions.
Further Details: Downloading Unpacked File
curl
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 6efb5c849b400af96b993284f6d39746b6bdb2e6.
curl -O https://api.magic.cythereal.com/download/${VIRUSBATTLE_KEY}/6efb5c849b400af96b993284f6d39746b6bdb2e6
This will download the unpacked file to a file named 6efb5c849b400af96b993284f6d39746b6bdb2e6.
vbclient
Downloading the unpacked version of a binary using vbclient can be
done using either the SHA1 of the original binary, or the SHA1 of the
unpacked binary. Downloading using the SHA1 of the unpacked binary is
straightforward:
vbclient -a download 6efb5c849b400af96b993284f6d39746b6bdb2e6 --enable_malware_download
This will download the unpacked file to ./Results/6efb5c849b400af96b993284f6d39746b6bdb2e6.unp.exe. There may be additional files present in ./Results, but the use of these files is deprecated. They will be removed in the future.
The same action can be used to download both the original and unpacked file using the SHA1 of the original file:
vbclient -a download 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
This command will result in two files being created in the ./Results
directory: 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0.exe and
6efb5c849b400af96b993284f6d39746b6bdb2e6.unp.exe. Unpacked files will
end with the extension .unp.exe while original files will have the
extention exe.
To generate a mapping between the SHA1 of the original file and the SHA1 of the unpacked file, use the map command:
vbclient -a map 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
This command will result in the file ./Results/vb-srlUnpacker.map with the contents:
2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0,6efb5c849b400af96b993284f6d39746b6bdb2e6
The SHA1 values on the left are from original files while the SHA1 values on the right are for unpacked files.
Get MAGIC Correlations¶
Futher Details: MAGIC Correlations and Categories
To find binaries that “match”, i.e. are similar to our example binary, we retrieve the MAGIC correlations.
curl
curl https://api.magic.cythereal.com/magic/${VIRUSBATTLE_KEY}/2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
This results in:
{
"message": {
"different_packer_similar_payload": [
"67120136e48d1307470e22c3a26d3a94bb843d36",
"a527b9996f8f4c403271a7657f2ad66b6b5a95a8",
"ee073f6a20320d1a1e5cc435596c1ca27edcda5c"
],
"query": {
"sha1": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0"
},
"similar_packer_different_payload": [
"008019b0ebf88cbcc4feab0347e3e823fdb1a372",
"07d02e9aefdbc0f424df3ac15f2ff0075447a70a",
"0e32230d9d8fc115a8097533763a1bb9d506b1aa",
"0f3a6733d4ad682724a99b3d4cc061162a64d375",
"0fc3f46da56f89f4d3d1ded07d1abf7708e24a81",
],
"similar_packer_similar_payload": [
"01ab20c6bb66f5e393f53dd7f54bd2d829745a6e",
"09eeb0b5c965f8118eadf1a4e465886e14274a60",
"0b6963786d7ea185a78e6f47e14841636f4d9852",
],
"weak_similar": [
"0f5c62c1032beb536aa549930e37a83ade94a867",
"11e33b9cd16c6597f6cdb74a5d73016a6436b8f0",
"12481531df32b84c35c665023ecb4ac8586da1b6",
]
},
"status": "success",
"statuscode": 0,
"vb_version": "VB-0.4"
}
If you are following along with this tutorial, the output you get might contains many more entries. This is because as new binaries are added to our database, additional matches are found and added to the MAGIC report.
The various types of similarity classes in the MAGIC report are described in MAGIC Correlations.
vbclient
Not currently supported. Planned for future release.
View Genomic Features¶
Futher Details: MAGIC Genomic Features
curl
To get the genomic features for the entire binary:
curl https://api.magic.cythereal.com/show/binary/${VIRUSBATTLE_KEY}/2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
This will output the JSON document described in Genomic Features
To get filter the output to the features in a single procedure with RVA of 0x1000:
curl https://api.magic.cythereal.com/show/proc/${VIRUSBATTLE_KEY}/2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0/0x1000
Unfortunately, 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.
vbclient
For an entire binary.
vbclient -a show 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0
For a single procedure at RVA 0x1000.
vbclient -a show 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0/0x1000
Search for similar procedures¶
Futher Details: Finding Similar Procedures
curl
curl https://api.magic.cythereal.com/search/procs/${VIRUSBATTLE_KEY}/2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0/0x1000
This will result in the JSON document described in Similar Procedure Results.
vbclient
vbclient -a search 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0/0x1000
Usage Guide¶
API Response Format¶
All API Responses will have the following format:
{
"status": enum,
"hash": string | null,
"vb_version": string,
"answer": object,
"message": string,
"statuscode": int,
}
status- The result of the API call. One of: [“success”, “failure”, “error”].
hash- The SHA1 of the binary the query was related to. May be null.
vb_version- Current API version.
answer- Contains the body of the reponse.
message- A string providing additional context for the response. Contains the error message when an error occurs.
statuscode- A status code indicating error or success. 0 means success; all others mean error.
Uploading Files¶
Upload a file to MAGIC for analysis.
The types of files MAGIC can analyze are described in File Formats Supported.
CLI Command¶
vbclient -a upload [-p password] [--norecursive] [-f] [--lf listfile] arg ...
Options:
-h, --help show this help message and exit
-f, --force Force resubmission, if the file already exists
-p PASSWORD, --password=PASSWORD
Password for Zip and 7z encrypted archives
--norecursive Do not recursively visit subdirectories.
--lf=LISTFILE, --list-file=LISTFILE
File to keep list of filehashes that are
uploaded. Default is: UploadedHashes.txt
The CLI parameter -a upload selects the upload action. The -p,
--norecursive, -f, and --lf arguments are optional. Their default
values may be obtained by invoking vbclient using -h or --help.
For this command, arg may be a file or a directory. The program can take a
list of arguments. At least one arg must be provided.
The meaning (or effect) of the optional arguments are as follows.
-f- By default, when a previously analyzed file is re-uploaded to MAGIC,no
additional analysis is performed. If this option is set, the
uploaded file will be re-analyzed. This option provided to compensate
for potential errors that may terminate the processing prematurely.
We advise that
-fbe used only if you have a reason to believe that the previous analysis was faulty. -p PASSWORD- The password for unzipping
.zipor.7zarchive. --norecursive- If
argis a directory, do not recurse into subdirectories. Default is to recurse. --lf list-filevbclientstores the file identifiers uploaded files in theLISTFILE. These file identifiers may then be used for querying MAGIC for its analysis. To override this capability please use--lf /dev/null. DefaultLISTFILEisUploadedHashes.txt
File Formats Supported¶
Currently, MAGIC only fully supports analysis of Windows PE32 executables.
Partial support is also provided for ELF files and .NET executables. Unpacking is not supported for ELF files and some genomic features are not extracted for .NET executables. Full support is planned for a future release.
In addition to executables, we support the upload of archive formats: zip, tar, tar.gz, and 7z. Archives of this format will be extracted and any supported file types analyzed. Unsupported file types in the archive, such as plain text files for example, will simply be ignored. Nested archives are handled automatically.
MAGIC can also decrypt password protected archives, either with the
default password infected or using a password provided throught the
HTTP API. The only caveat is that nested archives must all use the same
password.
Examples¶
Upload single file¶
File can be either an EXE or an archive, such as zip file.
vbclient -a upload <filename>
If the archive is password protected, use the --password argument:
vbclient -a upload -p <password> <filename.zip>
The ID of the uploaded file will be stored in ./UploadedHashes.txt.
Upload directory¶
To upload all files found in the directory, including files in subdirectories:
vbclient -a upload <directoryname>
To upload without traversing sub-directories:
vbclient -a upload --norecursive <directoryname>
The ID of all uploaded files will be stored in ./UploadedHashes.txt.
Upload multiple files or directories¶
vbclient -a upload <file1> <dir2> <file3> <file4>
The ID of all uploaded files will be stored in ./UploadedHashes.txt.
Save file IDs to different location¶
To store the IDs of all uploaded files to file ./my-uploaded-files.txt:
vbclient -a upload --list-file ./my-uploaded-files.txt <path1> <path2> ...
Re-analyze file¶
To re-analyze file with ID SHA1 without re-uploading:
vbclient -a reprocess SHA1
To upload the file and re-analyze it:
vbclient -a upload --force <file path>
Querying Analysis Status¶
API Endpoints¶
-
GET/query/(api_key)/(sha1)¶ https://api.magic.cythereal.com/docs#!/query/Query_Info
Query various information, including analysis status, about file with SHA1 equal to (sha1). See Results Description for description of the output of this endpoint.
CLI Commands¶
Note
This sections assumes knowledge from the sections Results Description, File Object Classes, and Services Provided. Specifically, this sections assumes you know what object classes, services, and file children are.
status¶
vbclient -a status [--norecursive] SHA1 ...
The -a status action reports the analysis status for all query files as
well as for all children of the query binaries. Thus, if the file indicated by
SHA1 is an archive file, all files extracted from the archive will have their
analysis status reported. Only files with an object class of binary.* have
their status reported. The option --norecursive disables reporting of the
status of children.
The output of the -a status command is a CSV listing for each service type
whether the analysis was a success, failed, is pending, or will not be run
(n/a). An example is given below.
$ vbclient -a status 300489be43b6b8d95d2e0c5196885a0754f4adaf
sha1sum,object_class,uploadDate,UnpackerStatus,JuiceStatus,SimilarityStatus
0f5c62c1032beb536aa549930e37a83ade94a867,binary.pe32,2017-03-22 15:50:14.957000,success,success,success
f946360fa31b5a0ba3261a1c5be0b601b757cd3f,binary.unpacked,2017-03-22 15:51:14.450000,n/a,success,success
13ba811b3719803bb28b3bf6616a3192f0838ae5,binary.pe32,2017-03-22 15:50:15.045000,success,success,success
a5a615cbc13e77f9129e3bbf70dde30a45eab815,binary.unpacked,2017-03-22 16:13:11.953000,n/a,success,success
2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0,binary.pe32,2017-03-22 15:50:15.092000,success,success,success
6243a9a92c394dcd86f8f37ec020bdd5a503e1b1,binary.unpacked,2017-03-22 15:56:41.353000,n/a,success,success
41a5aa4588c7ca21d730845e0f4b2a26fdedd8dc,binary.pe32,2017-03-22 15:50:15.134000,success,success,Pending
ccf12ae854830481bae880fa852272a11bd114ae,binary.unpacked,2017-03-22 15:58:57.951000,n/a,success,Pending
query¶
vbclient -a query [--norecursive] SHA1 ...
The -a query action returns the same information as the query API
Endpoint. The main difference is that the CLI command will by default call the
query command recursively for all children of the query binaries. See
Results Description for a description of what the children a file
are. The recursive query can be disabled by providing the --norecursive
option.
Results Description¶
Warning
Any fields not documented here should be considered deprecated. Such fields may be removed in the future without warning.
There are two pieces of information returned by the query endpoint:
- Information about the queried file.
- Results of the analysis performed on the file.
An example query result is given below for the malware with SHA1 of 2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0.
{
"sha1": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
"md5": "a7fd6503d8bc6d0e61b779d968568067",
"uploadDate": "2017-01-10 06:03:52.720000",
"unix_filetype": "PE32 executable (GUI) Intel 80386, for MS Windows",
"origFilepath": [
"./archive"
],
"object_class": "binary.pe32",
"parents": [
"fb74c17fad2458f6d8f1f0d3f4dfa7b9ce22a2ec"
],
"children": [
{
"service_name": "srlUnpacker",
"status": "success",
"child": "6efb5c849b400af96b993284f6d39746b6bdb2e6"
},
{
"service_name": "srlJuice",
"status": "success",
"child": null
},
{
"service_name": "srlSimilarity",
"status": "success",
"child": null
}
],
}
All but the last two fields provide information about the queried file. The
fields sha1 and md5 contain the respective cryptographic hash of the
queried file. The uploadDate field records when the file was originally
uploaded to MAGIC and unix_filetype contains the result of the Unix
file command when run on the queried file. The origFilepath field
contains the file path of the file when it was uploaded to MAGIC. Finally, the
object_class field records the object class that MAGIC has placed the file
in. These object classes are documented in File Object Classes.
The results of any analysis or operation performed on a file is represented
through parent-child relationships between the analyzed file and the result of
the analysis. These relationships are captured by the parent and
children fields. When a particular analysis completes for a given file, the
results of that analysis are added to the list in the children while the
SHA1 of the analyzed file is added to the parent list of any newly created
files.
Each entry in the children list is a dictionary with the keys
service_name, status, and child. The service_name field
lists the type of analysis or action performed on the file. The full list
of services is documented at Services Provided. The status field
records if the analysis was a “success” or a “failure”. Finally, the child
field contains the SHA1 of any file created as a result of this analysis or
action. If no file resulted from the analysis, this field is null.
If a single type of analysis or action results in multiple files being created,
multiple entries in the children list will be created. Each of these
entries will contain the same value for service_name.
The contents of children will differ depending on what the object_class
(File Object Classes) of the file is. Binary files, i.e. object_class
equal to binary.*, will contain a list of the analysis results for the
binary. Archive files, i.e. object_class equal to archive.*, will
contain a list of files extracted from the archive. Each entry in the
children list will have service_name equal to srlArchive and
contain the SHA1 of the extracted file.
An example of the children for an archive file is given below:
{
"object_class": "archive.gz",
"children": [
{
"service_name": "srlArchive",
"status": "success",
"child": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0"
},
{
"service_name": "srlArchive",
"status": "success",
"child": "949728bb9ec8a5032ab89201932260e28cf73b7d"
}
],
}
File Object Classes¶
Warning
Any object class not documented here should be considered deprecated. Such object classes may be removed in the future without warning.
The object class of a file is the type of object MAGIC identified the file as. This object class file determines which services, i.e., types of analysis or processes, that will be run on a file. The object classes defined in MAGIC are documented in the table below. The services that will run for any given object class are documented in Services Provided.
| Object Class | Description |
|---|---|
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.elf |
An ELF executable |
binary.unpacked |
An unpacked binary |
The following diagram summarizes the various classes of object classes and their parent-child relations.
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.
The diagram below presents a more detailed view of how the various file types are related.
Services Provided¶
Warning
Any service not documented here should be considered deprecated. Such services may be removed in the future without warning.
The services, i.e. analysis or processes, provided by MAGIC are documented in
the table below. This table lists the name of the service as it will appear in
the children list documented in Results Description, the types
of object classes the service will be run on, the types of object classes the
service will produce, and a description of what the service does. Object
classes listed as something.* are interpreted as “all object classes that
start with substring something.”.
| service_name | Operates On | Produces | Description |
|---|---|---|---|
srlArchive |
archive.* |
Various | Extracts files from an uploaded archive file. Recursively submits all extracted files to MAGIC |
srlUnpacker |
binary.* |
binary.unpacked |
Unpacks binary files. |
srlJuice |
binary.* |
null | Extracts the genomic features from binary files. |
srlSimilarity |
binary.* |
null | Performs the calculations necessary for the MAGIC Report correlation |
MAGIC Correlations and Categories¶
The Cythereal MAGIC Report provides correlations between malware and categorization of the type of malware. The correlations are based on both similarity between binaries and the unpacked versions of binaries. These relationships are described in MAGIC Correlations. The categorizations are described in MAGIC Categories.
API Endpoints¶
Full reference documentation: https://api.magic.cythereal.com/docs
-
GET/magic/{api_key}/{file_hash}¶ Retrieve the MAGIC correlations for a binary.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Query Parameters: - details (boolean) – If false, omits the match details. Defaults to true.
- threshold (number) – Only similarity matches at value equal or above threshold will be considered. MUST be in range [0, 1]. Defaults to 0.7.
Status Codes: - 200 OK – Request received.
CLI Commands¶
Retrieving a MAGIC report is not currently supported by the MAGIC client.
Instead, normal utilities such as wget or curl can be used to access
the API Endpoints.
Example:
# Retrieve the correlations report
curl 'https://api.magic.cythereal.com/magic/(api_key)/(sha1)' > magic_correlation.json
# Retrieve the correlations report with additional details
curl 'https://api.magic.cythereal.com/magic/(api_key)/(sha1)?details=yes' > magic_correlation_with_details.json
# Retrieve the categories report
curl 'https://api.magic.cythereal.com/categories/(api_key)/(sha1)' > magic_categories.json
# Add a category
curl -X PUT 'https://api.magic.cythereal.com/categories/(api_key)/(sha1)' -d 'category=(category)'
MAGIC Correlations¶
An example MAGIC Correlations Report is given below. The fields are summarized
in Fields Summary with pointers to detailed
descriptions given as needed. The MAGIC correlations are in the answer
field. The remaining top-level fields are the fields from the API
Response Protocol.
{
"status": "success",
"statuscode": 0,
"vb_version": "VB-0.4",
"message": "MAGIC report found",
"hash": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
"answer": {
"version": "1.0.0",
"query": {
"sha1": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0"
},
"summary": {
"similar_packer_similar_payload": [
"01ab20c6bb66f5e393f53dd7f54bd2d829745a6e"
],
"similar_packer_different_payload": [
"008019b0ebf88cbcc4feab0347e3e823fdb1a372",
"fcf5100bc222fc21b7326bb9a99d1aeac83a0f3e"
],
"different_packer_similar_payload": [
"67120136e48d1307470e22c3a26d3a94bb843d36"
],
"weak_similar": [
"0f5c62c1032beb536aa549930e37a83ade94a867"
]
},
"details": [
{
"sha1": "01ab20c6bb66f5e393f53dd7f54bd2d829745a6e",
"match_type": "similar_packer_similar_payload",
"match_subtypes": [
{
"match_subtype": "matches_payload",
"similarity": 1
},
{
"match_subtype": "matches_original",
"similarity": 1
}
],
"max_similarity": 1
},
{
"sha1": "008019b0ebf88cbcc4feab0347e3e823fdb1a372",
"match_type": "similar_packer_different_payload",
"match_subtypes": [
{
"match_subtype": "matches_original",
"similarity": 0.8868
}
],
"max_similarity": 0.8868
},
{
"sha1": "fcf5100bc222fc21b7326bb9a99d1aeac83a0f3e",
"match_type": "similar_packer_different_payload",
"match_subtypes": [
{
"match_subtype": "matches_original",
"similarity": 0.8868
}
],
"max_similarity": 0.8868
},
{
"sha1": "67120136e48d1307470e22c3a26d3a94bb843d36",
"match_type": "different_packer_similar_payload",
"match_subtypes": [
{
"match_subtype": "matches_payload",
"similarity": 1
}
],
"max_similarity": 1
},
{
"sha1": "0f5c62c1032beb536aa549930e37a83ade94a867",
"match_type": "weak_similar",
"match_subtypes": [
{
"match_subtype": "matches_weak_down",
"similarity": 0.8877
},
{
"match_subtype": "matches_original",
"similarity": 0.8877
}
],
"max_similarity": 0.8877
}
]
}
}
Fields Summary¶
The query field records information about the binary this report is for.
Currently, it only contains the query.sha1 field, which records the SHA1 of
the binary the magic report is for.
The version field records the MAGIC report version. This is distinct from
the API version.
The details field records details about the binaries matched with
the query binary. This field is further described in
Match Details.
The summary field contains the SHA1 of binaries matched with the query
binary, i.e., the SHA1 values from details, separated by their MAGIC Match
Classification. This can be similar_packer_similar_payload,
similar_packer_different_payload, different_packer_different_payload,
or weak_similar. These classifications are described in
Match Classifications.
Match Classifications¶
There are four types of matches between binaries that Cythereal MAGIC reports. To understand the difference between the four similarities, it would be helpful to know how Cythereal MAGIC compares malware binaries.
Cythereal MAGIC compares malware binaries along two dimensions: a) comparing the original (i.e., packed) malware binary and b) comparing the payload resulting from unpacking the malware.
These two dimensions of similarity give four possibilities:
- Similar Packer Similar Payload: Two malware binaries have “strong” similarity if their original (i.e., packed) binaries are similar AND their payloads (i.e., unpacked) binaries are also similar. This is the strongest form of similarity.
- Similar Packer Different Payload: When the original/packed binaries are similar, but the payloads are not.
- Different Packer Similar Payload: When the original/unpacked binaries are not similar, but the payloads are similar.
- Weak Similar: When a packed form of a malware is similar to the payload of another malware.
The Weak Similar relation is named as such because we do not expect similarities between packed and unpacked binaries. Packing a binary generally results in a packed binary that shares little resemblance with the original, unpacked binary. Since we expect malware to be packed and that the unpacked binary will be dissimilar from the packed version, we separate out cases in which this expectation is violated. This can happen for a number of reasons such as a malware not being packed (thus resulting in an unpacked version identical to the packed version), malware defeating the unpackers (again resulting in identical packed and unpacked versions), or an unpacked file being misidentified as packed.
Match Details¶
The details of each match reported in the summary field of the MAGIC
correlation reports are present in the details field. This field is
included by default, but can be removed by setting the details parameter to
no for the magic correlation report API call.
The details field from the example in
MAGIC Correlations is given below.
{
"details": [
{
"sha1": "01ab20c6bb66f5e393f53dd7f54bd2d829745a6e",
"match_type": "similar_packer_similar_payload",
"match_subtypes": [
{
"match_subtype": "matches_payload",
"similarity": 1
},
{
"match_subtype": "matches_original",
"similarity": 1
}
],
"max_similarity": 1
},
{
"sha1": "008019b0ebf88cbcc4feab0347e3e823fdb1a372",
"match_type": "similar_packer_different_payload",
"match_subtypes": [
{
"match_subtype": "matches_original",
"similarity": 0.8868
}
],
"max_similarity": 0.8868
},
{
"sha1": "fcf5100bc222fc21b7326bb9a99d1aeac83a0f3e",
"match_type": "similar_packer_different_payload",
"match_subtypes": [
{
"match_subtype": "matches_original",
"similarity": 0.8868
}
],
"max_similarity": 0.8868
},
{
"sha1": "67120136e48d1307470e22c3a26d3a94bb843d36",
"match_type": "different_packer_similar_payload",
"match_subtypes": [
{
"match_subtype": "matches_payload",
"similarity": 1
}
],
"max_similarity": 1
},
{
"sha1": "0f5c62c1032beb536aa549930e37a83ade94a867",
"match_type": "weak_similar",
"match_subtypes": [
{
"match_subtype": "matches_weak_down",
"similarity": 0.8877
},
{
"match_subtype": "matches_original",
"similarity": 0.8877
}
],
"max_similarity": 0.8877
}
]
}
The details field contains list with a Match Details object for every
binary that matched with the query binary. This details object contains four
fields: sha1, match_type, match_subtypes, and max_similarity.
The sha1 field contains the SHA1 of the matched binary and the
match_type field contains the MAGIC Match Classification for the match. The
match_subtypes and max_similarity fields are described below.
The match_subtypes field contains a list of objects with the fields
match_subtype and similarity. As previously mentioned, MAGIC
uses similarities between both original (packed) binaries and the
unpacked version of these binaries (the payload). The match_subtypes
list will contain an entry for all similarity relationships between
these original and unpacked binaries with the match_subtype field
indicating the type of relationship (see below for the various types)
and the similarity field giving the actual simliarity score. This
will be a value between 0 and 1, with larger values indicating greater
similarity.
The max_similarity field lists the maximum similarity value from the
list in match_subtypes.
The figure below illustrates the possible match subtypes that can be
present in match_subtypes. In this figure A and B are
malware and a and b are their respective unpacked versions. The
malware A is the query binary.
The following match subtypes are possible. Note that all reported
relationships are reported between A and B. So a similar to
b results in relationship A matches_payload B
A similar_to B => matches_original
a similar_to b => matches_payload
A similar_to b => matches_weak_down
a similar_to B => matches_weak_up
In addition, if an original binary has been unpacked to two similar but
distinct unpacked versions, it can result in a matches_self class.
Similarity between two binaries, both packed and unpacked, is determined by the percent of their MAGIC Genome that is shared. The MAGIC Genome is described in MAGIC Genomic Features.
MAGIC Categories¶
Warning
MAGIC Report Categories is currently an alpha level feature and under active development. It may change without notice in backwards incompatible ways. It is not recommended for production environments.
The MAGIC Categories report assigns to the query binary a number of categories and associated category scores. A category describes the type of malware the binary is, such as ransomware, rogue antivirus, etc. The category score for a given category provides a “confidence level” for that category. The higher the category score is, the higher confidence that the malware belongs to that category.
An example MAGIC Categories report is given below:
{
"ground_truth": {
"total_categories": 3,
"categories": [
{"name": "cryptolocker", "score": 15},
{"name": "ransomeware", "score": 13} ,
]
},
"categorization_result": {
"total_categories": 5,
"categories": [
{"name": "cryptolocker", "score": 24},
{"name": "ransomeware", "score": 11},
{"name": "zeus", "score": 15},
]
}
}
The report consist of a single dictionary with two keys: ground_truth and
categorization_result. The ground_truth contains categories directly
assigned to the file while categorization_result contains categories assigned
to the file on the basis of its MAGIC Correlations.
If a binary is not assigned to any categories, this
dictionary will be empty. For each element in categories key, the associate value is a
dictionary containing the keys name and score. The name key
provides the category name. The score key
provides the category score for the associated category. The higher the
category score is, the higher confidence that the malware belongs to that
category. So in the example, the
score for the ransomware category in categorization_result is 11.
MAGIC Genomic Features¶
The MAGIC Genomic Features provide low level details of analyzed malware binaries and are extracted using cutting edge program analysis techniques.
API Endpoints¶
-
GET/show/binary/(api_key)/(sha1)¶ Retrieve the genomic features for binary with SHA1 of (sha1). See Genomic Features for a description of the features.
-
GET/show/binary/(api_key)/(sha1)/(rva)¶ Retrieve the genomic features for the procedure at address (rva) in binary with SHA1 of (sha1). See Genomic Features for a description of the genomic features.
CLI Commands¶
Usage: vbclient -a show SHA1 ...
Options:
-o OUTDIR, --outdir=OUTDIR
Directory to save downloaded files. Default is:
./Results
The -a show option for vbclient will create a file in OUTDIR
containing the JSON representation of the binary with SHA1 equal to SHA1.
See Genomic Features for a description of this JSON document.
Genomic Features¶
Warning
Any fields not documented here should be considered deprecated. Such fields may be removed in the future without warning.
A binary is represented as a set of functions and each function contains a set of genomic features characterizing the function. The genomic feature listing for a binary is simply a dictionary containing the set of features and their associated features. An abridged example is below.
{
"0x1000": {...},
"0x109f": {...},
"0x109f": {...},
...
}
Each key in the dictionary is the RVA of a function in the query binary. The values in this dictionary are the genomic features for each function.
An example genomic feature dictionary for a function is given below:
{
"_id": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0/0x113a0",
"binary_id": "2d9035b27ce5c1cce2fb8432c76e315a1a2a8de0",
"hardHash": "9536f45b50274da96806b2aad09119ef",
"startRVA": "0x113a0",
"isLibrary": false,
"isThunk": false,
"peSegment": "_text",
"procName": "sub_4113A0",
"api_calls": [
"VariantInit",
"VariantCopy",
...
],
"code": [
[
"push(ebp)",
"mov(ebp,esp)",
"push(ebx)",
...
],
...
],
"code_size": 187,
"gen_code": [
[
"push(A)",
"mov(A,B)",
"push(C)",
...
],
...
],
"gen_code_size": 187,
"semantics": [
[
"eax=A",
"ebp=C",
"esp=B",
...
],
...
],
"semantics_size": 149,
"gen_semantics": [
[
"A=R",
"B=Q",
"G=P",
...
],
...
],
"gen_semantics_size": 149,
}
The first few fields, _id, binary_id and hardHash provide
identifiers for this procedure. The next few fields base_address,
isLibary, isThunk, peSegment, and procName provide contextual
information about the function. The remaining fields provide the genomic
features.
Identification Fields¶
_id- The ID of the function. It takes the form “
binary_id/startRVA”. binary_id- The SHA1 of the binary this function is in.
hardHash- This is a special hash created by MAGIC to identify semantically equivalent
functions. If two functions have an equivalent
hardHash, then the semantics of both functions are the same, i.e. the functions can be considered functionally equivalent.
Contextual Fields¶
startRVA- The relative virtual address of the function.
isLibary- Indicates if this function was identified as a library function. Should be either true or false.
isThunk- Indicates if this function was identified as a thunk (jump) function. Should be either true or false.
peSegment- Lists the PE Segment that the function was located in.
procName- The name of the procedure. If debug symbols were not present in the
original file, this will be of the form
sub_xxxxxxwherexxxxxxis the virtual address of the function.
Feature Fields¶
The feature fields are summarized in this section. The details are in the paper “Fast location of similar code fragments using semantic juice”.
api_calls- The list of APIs called from this function.
code- The disassembly of this function. This is a list of lists where each sublist represents a disassembly block. Each block contains a list of the instructions that compose the block.
code_size- The number of instructions in the disassembly.
gen_code- Generalized disassembly. This is the same as
code, but with the operands in code abstracted to variables instead of register names. gen_code_size- The number of generalized instructions in
gen_code. semantics- The semantics of the instructions in
code. This is a list of lists where each inner list corresponds to a block fromcode. This inner list contains the effect that executing the represented block will have on registers and memory locations. semantics_size- The number of individual semantics statements in
semantics. gen_semantics- Generalized semantics. This is the same as
semanticsbut with registers and memory locations abstracted to variables. gen_semantics_size- The number of individual semantics statements in
gen_semantics.
Finding Similar Procedures¶
MAGIC is capable of locating procedures similar to a given procedure in a given binary. This similarity is based on shared genomic information.
The list of procedures in a binary can be retrieved using the show command.
API Endpoints¶
-
GET/search/procs/(api_key)/(binary_id)/(rva)¶ Get procedures similar to the procedure that occurs at relative virtual address (rva) in binary (binary_id). Reponse format documented at Similar Procedure Results
https://api.magic.cythereal.com/docs#!/search/Nn_Search_Procs_Byrva
CLI Commands¶
vbclient -a search [--noLibrary] sha1/0xrva1 sha1/0xrva2 ...
The search command searches procedures similar to a given one. A
procedures is identified as sha1/0xrva, where sha1 is the sha1
of the binary and rva is the relative virtual address of the
procedures in hex format.
The --noLibrary option removes library procedures from the search.
Similar Procedure Results¶
Warning
Fields not documented here should be considered deprecated. They may be removed without warning in the future.
The result returned by a similar procedure search is a dictionary containing the list of procedures found to match with the query procedure. Whether two procedures match or not is based on whether their genomic features are similar.
An example results dictionary is given below:
{
"semantically_equivalent_procedures": [
{
"procName": "sub_4113A0",
"proc_id": "e0fa6db29f00e0a0a30657aa07b2982a9f5ad5d9/0x113a0"
},
...
]
}
The list of matching procedures are found under the key
semantically_equivalent_procedures. The value for this key is a list of
dictionaries containing information on the matching procedures. The key
procName is the name of the procedure (this is the same as the procName
in the genomic features) while the key
proc_id is the ID of the matched procedure (same as _id in the
genomic features).
Downloading Unpacked File¶
Note
Downloading unpacked files requires additional permissions. Please contact us for these permissions.
MAGIC provides a fully automated generic unpacking service. All uploaded files are automatically sent to this service. The unpacked file will be available for download once the service completes. See Uploading Files for how to upload a file for analysis and Querying Analysis Status for how to check if unpacking is complete.
The unpacked relationship is not a one-to-one relationship. A single packed file may have more than one unpacked version and an unpacked file can have multiple sources. The former case usually occurs when the same file is unpacked multiple times. Running the same file through the MAGIC unpacker multiple times may result in unpacked files with different SHA1 values. These unpacked files should be similar to each other, they just aren’t guaranteed to be exactly the same. The latter case, when an unpacked file has multiple sources, occurs when different packing mechanisms were used on the same payload. This results in multiple distinct packed files that when unpacked result in files with the same SHA1.
API Endpoints¶
-
GET/download/(api_key)/(sha1)¶ Download the unpacked file with SHA1 of (sha1). See Querying Analysis Status for how to get the SHA1 of an unpacked file.
CLI Commands¶
There are two vbclient actions that are useful for downloading
unpacked files. The first action, -a download, downloads the
unpacked version directly using either the SHA1 of the unpacked file or
the SHA1 of the original file. The second action, -a map, creates a
csv that maps the SHA1 of the original, packed file to the SHA1 of the
unpacked version. This is useful when downloading multiple files at a
time, or when there is more than one unpacked version of a given file.
vbclient -a download SHA1 --enable_malware_download
The -a download action of the MAGIC client will download the file
with SHA1 to the folder ./Results. If the SHA1 is of an original file,
the unpacked version of the file will automatically be downloaded and
placed in the same folder. All original, packed files will be named
SHA1.exe where SHA1 is of the original file. All unpacked files
will be named UNP_SHA1.unp.exe where UNP_SHA1 is the SHA1 of the
unpacked file.
Warning
The download command downloads a number of additional files. The use of these additional files is deprecated and they will be removed in the future.
- ::
- vbclient -a map SHA1
The -a map action will create the csv file
./Results/vb-srlUnpacker.map that maps the SHA1 of original, packed
files to the SHA1 of their unpacked version. Each row of the csv file is
of the format:
original_file_sha1,packed_file_sha1
Warning
The map command creates a number of additional files. The use of these additional files is deprecated and they will be removed in the future.
Use Cases¶
Malware Intelligence¶
Cythereal MAGIC’s unique analysis method combines deep knowledge of Operating Systems Internals coupled with state-of-the-art programming languages theory for formal program analysis. This allows it to peer through most known obfuscations and easily analyze even the most complex malware and extract a wealth of information about the inner structure and workings of malware. Add Data Mining to mix and you get a very powerful tool to extract Intelligence from large repositories of malware at a scale that was previously un-thought of.
MAGIC can be used to find connections among malware families that were previously never even thought of. Further queries can be made to the system to find out the nature of the connection and also to show the evidence- semantically equivalent procedures that led the system to the conclude the connection.
Below image shows MAGIC identifying a connection between Gamarue Worms and Leechole Trojans. MAGIC found that certain variants of the two families share the same packer. MAGIC also successfully identified the set of procedures that were common to the two families and formed the unpacking stub. This is of immense help to reverse engineers wanting to unpack the malware manually for deeper analysis.
Below two images show two procedures found in several variants of DarkComet and Optima families. Variants of both families use different packers to hide these procedures from static analysis. The procedures were extracted by MAGIC’s unpacker using VM Introspection at runtime.
Malware Signature Generation¶
MAGIC can analyze large collection of labeled malware and generate semantic signatures common to the family. MAGIC analyses are capable of locating and identifying even the smallest set of procedures common to a family and generate obfuscation resistant, semantically meaningful signatures.
Additionally, MAGIC can also perform probabilistic analysis to calculate a confidence value with which it assigns a new malware variant to a known family.
Below graph show number of procedures (y-axis) vs percentage of nitol binaries they are found in (x-axis) as identified by MAGIC. The graph shows that MAGIC is capable of finding the needle in haystack! It successfully generated juice based signatures for the set of 5 procedures that were present in more than 95% of nitol executables.
Reverse Engineering¶
MAGIC uses VM introspection to observe malware execution at a level below ring 0. The intricate knowledge of Windows Internals is in-built the system to monitor the malware’s interaction with the Operating System as it is executing. This is followed by a rigorous static analysis of the original code, as well as, that of runtime generated code extracted during the execution.
MAGIC’s static analysis engine performs a variety of analyses. The most important to reverse engineers being the BinJuice analysis. Juice is an abstraction over semantics that can be computed and compared in a fast and scalable fashion.
Given a binary executable, in about a minute, MAGIC can calculate juice of all procedures in the binary and find out known procedures in the database which are semantically equivalent to procedures in the given binary. Users then have access to all the information and notes of malware analysts who have worked on the procedure before, leaving only the unique, never-seen-before, procedures to be reversed. This reduces the workload by orders of magnitude.
Propagating information from procedure to another juice equivalent procedure has interesting advantages. For instance, IDA more often than not, misses to identify library procedures. Reverse engineers thus often end up spending time reversing a library procedure which can be avoided.
Below image shows percentage of library procedures as identified by IDA followed by those identified by MAGIC by just propagating IDA isLibrary tag information across juice-equivalent procedures.
The above is just a glimpse of what can be achieved by propagating information across equivalent procedures. One can also throw in labeled open source code and propagate information from them to similar equivalent procedures in malware and use the labels to guide a reverse engineer trying to understand the malware behaviors.
To better aid in understanding new malware, MAGIC also reports on the ControlFlow Graph of the malware. Additionally, MAGIC also generates an APIFlow Graph. Since API calls are the most common way to interact with the OS, they can be used to understand malware behavior. APIFlow Graph thus may be understood as an abstraction of the ControlFlow Graph where each path describes the behavior of the program as it executed that path on the ControlFlow Graph.
API Reference¶
| Swagger UI | Swagger Spec (JSON) | Swagger Spec (YAML) |
-
GET/register¶ Register to receive a MAGIC API key.
Query Parameters: - email (string) – Email Address
- name (string) – Full Name
Status Codes: - 200 OK – Request received
-
POST/upload/{api_key}¶ Upload file for processing
Parameters: - api_key (string) – API Key for accessing the service
Query Parameters: - origFilePath (string) – Name of the file being uploaded
- password (string) – If uploading a password protected zip, this field MUST contain the password.
- priority (integer) – Analysis priority. Higher priority files are analyzed first. Priorities higher than default require special privileges.
- force (boolean) – If true, will force existing file to be reanalyzed.
Status Codes: - 200 OK – The upload request was received. This does not mean that the upload was a sucess. The status and statuscode fields contain the result of the upload.
-
GET/reprocess/{api_key}/{file_hash}¶ Reprocess a previously uploaded file
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Query Parameters: - priority (integer) – Analysis priority. Higher priority files are analyzed first. Priorities higher than default require special privileges.
Status Codes: - 200 OK – Request received
-
GET/download/{api_key}/{file_hash}¶ Download a file
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Status Codes: - 200 OK – File was successfully returned.
-
GET/query/{api_key}/{file_hash}¶ Query file info and analysis status
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Status Codes: - 200 OK – Request received.
-
GET/magic/{api_key}/{file_hash}¶ Retrieve the MAGIC correlations for a binary.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Query Parameters: - details (boolean) – If false, omits the match details. Defaults to true.
- threshold (number) – Only similarity matches at value equal or above threshold will be considered. MUST be in range [0, 1]. Defaults to 0.7.
Status Codes: - 200 OK – Request received.
-
GET/categories/{api_key}/{file_hash}¶ Retrieve the MAGIC categories for a binary. **Alpha Level Feature**
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Status Codes: - 200 OK – Request received.
-
PUT/categories/{api_key}/{file_hash}¶ Save category for a binary. **Alpha Level Feature**
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Status Codes: - 200 OK – Request received.
-
GET/search/procs/{api_key}/{file_hash}/{proc_rva}¶ Search for procedures similar to a given procedure.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
- proc_rva (string) – The RVA of the procedure to find similarities with. Formatted 0xnnnn
Status Codes: - 200 OK – Request received
-
GET/search/binary/{api_key}/{file_hash}¶ Search for similar binaries.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Query Parameters: - threshold (number) – Similarity threshold, default 0.7.
- level (integer) – Similarity Search Level from 1 through 5, default is 3.
Status Codes: - 200 OK – Request received
-
GET/show/binary/{api_key}/{file_hash}¶ Show the genomic features for a given binary.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
Status Codes: - 200 OK – Request received
-
GET/show/proc/{api_key}/{file_hash}/{proc_rva}¶ Show the genomic features for a given procedure.
Parameters: - api_key (string) – API Key for accessing the service
- file_hash (string) – A cryptographic hash of a file. Supported hashes are SHA1.
- proc_rva (string) – The RVA of the procedure to find similarities with. Formatted 0xnnnn
Status Codes: - 200 OK – Request received
Legalese¶
Privacy and Access Control¶
Though access to MAGIC is restricted using an API Key, anyone with a valid API Key may have access to all the uploaded files, unpacked binaries, and their analyses. This includes even the files that are not uploaded by the user.
Which means any data you upload and all the analyses we perform is available to everyone who has access to MAGIC. Please be aware of this before uploading any data.
More fine-grained access control is planned for future versions.
Disclaimers¶
The service is provided as is, without any claims of fitness for use. We offer no guaranties or warranties. There is also no assurance for any level of quality of service.
IP Rights¶
Access to use this service does not afford a user any rights on the SDK, the analyses results computed by the service, the underlying algorithms, or the implementation.
Contact Cythereal¶
Contact via Email: support@cythereal.com