Python SDK

You can download the Python SDK from here.

Authentication

All the HTTP requests have to include two additional headers:

The X-11Paths-Date header

The X-11Paths-Date header contains the value of the current UTC date and must have the following format: yyyy-MM-dd HH:mm:ss.

Where yyyy is the year, MM is the number of month, dd is the number of day, HH is the hour in 24h format, mm is the minute within the hour and ss is the second within the minute. All values must be zero-padded so that they are all 2 digit values except for the year which is 4.

It is very important that the value and format of this header is the exact same used in the process of creating the requestSignature for the authorization header as explained above.

Note you can still use the standard HTTP Header Date in whichever format you want, such as RFC 1123. Just make sure to not confuse both and always use the value you use in X-11Paths-Date in the signature process. The API will ignore the standard Date header.

The Authorization header

Is a composed field with the next values includes on it separated by spaces: 11PATHS api_id request_signature

11PATHS is a constant that determines the Authentication method.

api_id is an alphanumeric identifier obtained when registering a new API.

request_signature is a signature derived from the url, parameters, custom headers and date of the current request, all hashed using a secret that is also obtained with the API_ID when registering the API.

The request signature is a base64 encoded and HMAC-SHA1 signed string. The string must be created following this process:

  1. Start with an empty string.
  2. Append the uppercase method name. Currently, only the value GET is supported.
  3. Append a line separator, " " (unicode point U+000A).
  4. Append a string with the current date in the exact format yyyy-MM-dd HH:mm:ss. Everything in the format should be self explanatory, noting that everything is numeric and should be zero-padded if needed so that all numbers have two digits except the year, having four. This value must be kept to be used in the Date header. The signature checking process will fail if both don't match.
  5. Append a line separator, " " (unicode point U+000A).
  6. Serialize all headers specific to this API (not every HTTP header in the request). These headers all have their names starting with X-11paths-.
    1. Convert all header names to lower case.
    2. Order the headers by header name in alphabetical ascending order.
    3. For every header value, convert multiline headers into single line by replacing newline characters " " by single spaces " ".
    4. Create an empty string. Then, for every header after the order and transformations above, add to the newly created string the header name followed by a colon ":" and followed by the header value. Each name:value should be separated from the next by a single space " ".
    5. Trim the string to make sure it doesn't contain any spacing characters at the beginning or end.
  7. Append a line separator, " " (unicode point U+000A).
  8. Append the url encoded query string consisting on the path (starting with the first forward slash) and the query parameters. The query string must not contain the host name or port, and must not contain any spacing characters prefixing or suffixing it.
  9. Only for POST or PUT requests, attach a line separator, " " (Unicode Point U+000A).
  10. Only for POST or PUT requests, append the body of the request.

Once the string has been created following the process described above, it must be signed using the HMAC-SHA1 algorithm and the secret that was obtained when registering the API. After signing, its raw binary data must be encoded in base64. The resulting string is the request_signature to be added to Authorization header.

Errors

If an incorrect API request is done, the system will return the next response:

{"error":{"code":XXX,"message":"..."}}

The fields included in the response indicates:

  • Code, a code number identifying the error
  • Message, a string with a description of the error

CODE ERROR
101 Invalid Authorization header format
102 Invalid application signature
103 Authorization header missing
104 Date header missing
105 Invalid date format
106 Request expired, date is too old
110 File hash header missing
111 Body hash header missing
112 Action not authorised
201 User not found
202 Token not found
301 APIClient not found
302 APIClient already exists
401 Missing parameter in API call
402 Invalid parameter value
403 Invalid content-type value
404 Invalid http verb value
405 Invalid http verb
406 Document not found
407 Invalid model
408 Invalid model version
409 File not found
410 Invalid file type, you should use doc or pdf
411 Invalid prediction. User M for malware or G for Goodware
412 There is already a model training
501 Invalid request

  • file: a file as multipart form data
  • prediction: G o M (Only Admin) ADMIN
  • 112
  • 410
  • 411
  • 409
  • 501

{
    "hash": "2dd5154eb199fd7f08770fe0660ee8cf03a174576fab07a17bde5db30b8311ae"
}

  • hash
  • tags: A list of tags. The maximum number of tags per document and user is 5.
  • 401
  • 406
  • 414:This error can occur together with a valid result and can occur due to having added some invalid tag or having exceeded the maximum number of allowed tags
  • 501

{
    "data" : {
        "hash":"89016e0836e97c240e8b9c3b8ad44c1d44797b3392e034692f8ef7cbd2541b3d",
        "currentTags": [
                "tagone",
                "tagtwo",
                "tagthree",
                "tagfour",
                "tagfive"
            ]
        },"error":{
            "code":414,
            "message":"An error occurred while adding one or more tags"
        }
}

  • hash
  • file: A zip file as multipart file
  • 401
  • 409
  • 501

{
    "hash": "2dd5154eb199fd7f08770fe0660ee8cf03a174576fab07a17bde5db30b8311ae"
}

  • hash
  • 401
  • 409
  • 501


{
    "hash":"3ecbc40e4434f80fa63ad29d55e5953395a927aaacd0ae39843c824a48fd85c9",
    "javaScripts":[
        "d7f48262ce2acfa667e84efb6a2aff94eee8f7383e183dc6adf10e31f0bfe0a0",
        "fb6a2af2ce2a376b549372ace6a3e4b4c383e1a345835d3ce789ce3af2101fe1"
    ],
    "status":"A",
    "prediction":"M"
}

{
    "hash":"199b8c4b51c65d20163c3a8496310051e159a5cb6af0f5920040cce92df13aba",
    "macros":[
        "e1a62f2176eee7631ca4c4915864ddf2ee5121c86169b8a940e5cd202f8bacef",
        "d8ed31e6d9d2ac496aa84963c96a22b89431de25976275983de967ea4dc6434e",
        "d248fa1a71b11af05ead98a09d70837271246bc9cdfb426fa4ae3287fa8b2251",
        "c5e81fb378a3fab45860ea8a777527f1ee97fb239b75d8ce155bb622e7bdb688"
    ],
    "status":"A",
    "prediction":"G",
    "type": "word"
}

  • hash
  • prediction: G o M.
  • 112
  • 406
  • 411
  • 401

{
    "hash": "2dd5154eb199fd7f08770fe0660ee8cf03a174576fab07a17bde5db30b8311ae"
}

  • hash
  • 401
  • 416
  • 501

{
    "hash":"e1a62f2176eee7631ca4c4915864ddf2ee5121c86169b8a940e5cd202f8bacef",
    "officeDocuments":
        [
            {
                "type":"word",
                "hash":"199b8c4b51c65d20163c3a8496310051e159a5cb6af0f5920040cce92df13aba",
                "status":"A",
                "prediction":"M"
            }
        ],
    "code":"Attribute VB_Name = \"jebTrvly\"\r\nAttribute
            VB_Base = \"0{B4CEA4FC-9649-4564-851F-9D321139C761}{166DD405-4C39-486D-BB0F-F6B2F35DF844}\n\r\
            nAttribute VB_GlobalNameSpace = False\r\n
            Attribute VB_Creatable = False\r\nAttribute VB_PredeclaredId = True\r\n
            Attribute VB_Exposed = False\r\nAttribute VB_TemplateDerived = False\r\n
            Attribute VB_Customizable = False\r\n",
    "name":"jebTrvly.frm"
}

  • hash
  • 401
  • 416
  • 501

{
    "hash":"d7f48262ce2acfa667e84efb6a2aff94eee8f7383e183dc6adf10e31f0bfe0a0",
    "pdfDocuments":[
        {
            "hash":"3ecbc40e4434f80fa63ad29d55e5953395a927aaacd0ae39843c824a48fd85c9",
            "status":"A",
            "prediction":"M"
        }
    ],
    "code":"var test="HELLO WORLD;"
}


  • 112
  • 402
  • 501


[
    {
        "model": "rf",
        "version": 2,
    },
    {
        "model": "svm",
        "version": 1,
    },
    {
        "model": "nn",
        "version": 1,
    },
]


  • 112
  • 402
  • 501

{
    "model": "nn",
    "version": 2,
}

  • model
  • version
  • 112
  • 407
  • 408
  • 501

{
    "averagePrecision":0.9623350861591986,
    "matthewsCorrCoef":0.9069698076219501,
    "f1Score":0.9536981358989778,
    "recall":0.9658952496954933,
    "falsePositives":0.01696969696969697,
    "precision":0.9418052256532067,
    "falseNegatives":0.029696969696969697,
    "jaccardSimilarity":0.9533333333333334,
    "auRoc":0.778654117121578,
    "negatives":0.4806060606060606,
    "meanSquaredError":0.04666666666666667,
    "positives":0.4727272727272727,
    "accuracy":0.9533333333333334
}

  • model: nn,rf,svm or dt
  • 112
  • 402
  • 407
  • 501

{}

  • model: nn,rf,svm or dt
  • version
  • 112
  • 407
  • 408
  • 501

{}