# cythereal-magic
The API for accessing Cythereal MAGIC products and services.  # API Conventions  Properties MUST be named using `snake_case`.  This API is inspired by the [google json style guide](https://google.github.io/styleguide/jsoncstyleguide.xml). Any questions about conventions not documented here should be addressed by this style guide.  **All responses** MUST be of type `APIResponse` and contain the following fields:  * `api_version` |  The current api version * `success` | Boolean value indicating if the operation succeeded. * `code` | Status code. Typically corresponds to the HTTP status code.  * `message` | A human readable message providing more details about the operation. Can be null or empty.  **Successful operations** MUST return a `SuccessResponse`, which extends `APIResponse` by adding:  * `data` | Properties containing the response object. * `success` | MUST equal True  When returning objects from a successful response, the `data` object SHOULD contain a property named after the requested object type. For example, the `/matches` endpoint should return a response object with `data.matches`. This property SHOULD  contain a list of the returned objects. For the `/matches` endpoint, the `data.matches` property contains a list of MagicMatch objects. See the `/matches` endpoint documentation for an example.  **Failed Operations** MUST return an `ErrorResponse`, which extends `APIResponse` by adding:  * `errors` | Array of error objects. An error object contains the following properties:     * `ErrorObject.reason` | Unique identifier for this error. Example: \"FileNotFoundError\".     * `ErrorObject.message`| Human readable error message. * `success` | MUST equal False.   # Example Inputs  Here are some example inputs that can be used for testing the service:  * Binary SHA1: `ff9790d7902fea4c910b182f6e0b00221a40d616`   * Can be used for `file_hash` parameters. * Procedure RVA: `0x1000`   * Use with the above SHA1 for `proc_rva` parameters. 

This Python package is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:

- API version: 1
- Package version: 1.0.7
- Build package: io.swagger.codegen.languages.PythonClientCodegen
For more information, please visit [http://cythereal.com](http://cythereal.com)

## Requirements.

Python 2.7 and 3.4+

## Installation & Usage
### pip install

If the python package is hosted on Github, you can install directly from Github

```sh
pip install 'git+https://bitbucket.org/cythereal/magic-clients.git@v1#egg=cythereal_magic&subdirectory=clients/python'
```
(you may need to run `pip` with root permission: `sudo pip install 'git+https://bitbucket.org/cythereal/magic-clients.git@v1#egg=cythereal_magic&subdirectory=clients/python'`)

Then import the package:
```python
import cythereal_magic 
```

### Setuptools

Install via [Setuptools](http://pypi.python.org/pypi/setuptools).

```sh
python setup.py install --user
```
(or `sudo python setup.py install` to install the package for all users)

Then import the package:
```python
import cythereal_magic
```

## Getting Started

The API Key can be provided via environment variable `MAGIC_API_KEY`
rather than manually configuring as shown in the example below.

The use of the environment variable is the preferred method of providing
the api key.

Please follow the [installation procedure](#installation--usage) and then run the following:

```python
from __future__ import print_function
import time
import cythereal_magic
from cythereal_magic.rest import ApiException
from pprint import pprint
# create an instance of the API class
api_instance = cythereal_magic.AdminApi()

try:
    # Check if server is responding to queries.
    api_response = api_instance.ping()
    pprint(api_response)
except ApiException as e:
    print("Exception when calling AdminApi->ping: %s\n" % e)

```

## Documentation for API Endpoints

All URIs are relative to *https://api.magic.cythereal.com/v1*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*AdminApi* | [**ping**](docs/AdminApi.md#ping) | **GET** /ping/ | Check if server is responding to queries.
*CytherealMagicApi* | [**create_category**](docs/CytherealMagicApi.md#create_category) | **POST** /reports/{file_hash}/categories/ | Save category for a binary. **Alpha Level Feature**
*CytherealMagicApi* | [**create_file**](docs/CytherealMagicApi.md#create_file) | **POST** /files/ | Upload file for processing
*CytherealMagicApi* | [**download_file**](docs/CytherealMagicApi.md#download_file) | **GET** /files/{file_hash} | Download a file
*CytherealMagicApi* | [**get_binary_genomics**](docs/CytherealMagicApi.md#get_binary_genomics) | **GET** /genomics/{file_hash}/ | Show the genomic features for a given binary.
*CytherealMagicApi* | [**get_file_info**](docs/CytherealMagicApi.md#get_file_info) | **GET** /files/{file_hash}/info/ | Get file info and analysis status
*CytherealMagicApi* | [**get_owned_files**](docs/CytherealMagicApi.md#get_owned_files) | **GET** /files/ | List files owned by the authenticated user.
*CytherealMagicApi* | [**get_procedure_genomics**](docs/CytherealMagicApi.md#get_procedure_genomics) | **GET** /genomics/{file_hash}/{proc_rva}/ | Show the genomic features for a given procedure.
*CytherealMagicApi* | [**get_report**](docs/CytherealMagicApi.md#get_report) | **GET** /reports/{file_hash}/ | Get the Magic report for a binary.
*CytherealMagicApi* | [**get_report_categories**](docs/CytherealMagicApi.md#get_report_categories) | **GET** /reports/{file_hash}/categories/ | Retrieve the MAGIC categories for a binary.
*CytherealMagicApi* | [**get_report_matches**](docs/CytherealMagicApi.md#get_report_matches) | **GET** /reports/{file_hash}/matches/ | Retrieve the MAGIC matches for a binary.
*CytherealMagicApi* | [**get_similar_binaries**](docs/CytherealMagicApi.md#get_similar_binaries) | **GET** /similarities/{file_hash}/ | Search for similar binaries.
*CytherealMagicApi* | [**get_similar_procedures**](docs/CytherealMagicApi.md#get_similar_procedures) | **GET** /similarities/{file_hash}/{proc_rva}/ | Search for procedures similar to a given procedure.
*CytherealMagicApi* | [**reprocess_file**](docs/CytherealMagicApi.md#reprocess_file) | **GET** /files/{file_hash}/reprocess/ | Reprocess a previously uploaded file


## Documentation For Models

 - [Address](docs/Address.md)
 - [ApiResponse](docs/ApiResponse.md)
 - [BinaryGenomics](docs/BinaryGenomics.md)
 - [BinarySimilarity](docs/BinarySimilarity.md)
 - [BinarySimilarityBinaries](docs/BinarySimilarityBinaries.md)
 - [BlockGenomics](docs/BlockGenomics.md)
 - [ChildInfo](docs/ChildInfo.md)
 - [ControlFlowGraph](docs/ControlFlowGraph.md)
 - [FileInfo](docs/FileInfo.md)
 - [MD5](docs/MD5.md)
 - [MagicCategories](docs/MagicCategories.md)
 - [MagicCategory](docs/MagicCategory.md)
 - [MagicCategoryList](docs/MagicCategoryList.md)
 - [MagicMatches](docs/MagicMatches.md)
 - [MagicMatchesMatchSubtypes](docs/MagicMatchesMatchSubtypes.md)
 - [MagicMatchesMatches](docs/MagicMatchesMatches.md)
 - [MagicReport](docs/MagicReport.md)
 - [MagicReportDetectionStats](docs/MagicReportDetectionStats.md)
 - [OwnedFilesList](docs/OwnedFilesList.md)
 - [OwnedFilesListFiles](docs/OwnedFilesListFiles.md)
 - [ProcedureGenomics](docs/ProcedureGenomics.md)
 - [ProcedureSimilarity](docs/ProcedureSimilarity.md)
 - [ProcedureSimilarityProcedures](docs/ProcedureSimilarityProcedures.md)
 - [SHA1](docs/SHA1.md)
 - [SHA256](docs/SHA256.md)
 - [SHA512](docs/SHA512.md)
 - [ErrorResponse](docs/ErrorResponse.md)
 - [SuccessResponse](docs/SuccessResponse.md)
 - [BinaryGenomicsResponse](docs/BinaryGenomicsResponse.md)
 - [BinarySimilarityResponse](docs/BinarySimilarityResponse.md)
 - [FileInfoResponse](docs/FileInfoResponse.md)
 - [FileUploadResponse](docs/FileUploadResponse.md)
 - [MagicCategoriesResponse](docs/MagicCategoriesResponse.md)
 - [MagicMatchesResponse](docs/MagicMatchesResponse.md)
 - [MagicReportResponse](docs/MagicReportResponse.md)
 - [OwnedFilesListResponse](docs/OwnedFilesListResponse.md)
 - [ProcedureGenomicsResponse](docs/ProcedureGenomicsResponse.md)
 - [ProcedureSimilarityResponse](docs/ProcedureSimilarityResponse.md)


## Documentation For Authorization


## api_key_query_param

- **Type**: API key
- **API key parameter name**: key
- **Location**: URL query string


## Author

support@cythereal.com

