Skip Navigation
  1. BlackBerry Docs
  2. Cylance Engine
  3. Cylance Engine Integration Guide
  4. File-scoring service protocols
  5. Cylance RESTful API
  6. Explaining the score for a file

Explaining the score for a file

To explain the score for a file, the REST API uses the HTTP PUT method. Like scoring, the file can be provided by a file path or binary. When explaining by file path, the client posts a JSON object with the file path to the TCP service:
PUT /apiv1/explain
Content-Type: application/json
Content-Length: 36

{
  "FilePath": "/tmp/sample.exe"
}
In
Cylance Engine
 1.2 and later, you can score multiple files in a single request:
PUT /apiv1/explain
Content-Type: application/json
Content-Length: 70

{
  "FilePaths": [ "C:/tmp/sample1.exe", "C:/tmp/sample2.exe" ]
}
When using a binary rather than a path, the request looks like:
PUT /apiv1/explain
Content-Type: application/octet-stream
Content-Length: <length>

<binary data>
A block of JSON is returned that represents the explaining result. When scoring multiple files, an array of results are returned.
curl -X PUT -T PEParser.dll http://localhost:9002/apiv1/explain
{
  "Status": "OK",
  "Explain": [
    {
      "TTM": {
        "features": {
          "Deception": {
            "ServiceDLL": true,
            "UsesCompression": true
          },
          "Misc": {
            "PrivEscalationCryptBase": true
          }
        },
        "scores": {
          "Destruction": 0,
          "Deception": 8,
          "Collection": 0,
          "DataLoss": 0,
          "Anomalies": 0,
          "Misc": 20,
          "Extended": 0
        }
      },
      "SampleFormat": "PE",
      "SamplePath": "D476484BD9E26928DCC740CCEB4B82C95FB5098BEDED638EF12F692BC8EE945E"
    }
  ]
}
The output of an explain operation is similar to that returned by the InfinityDaemonClient utility but the output differs in a few ways:
  • The entire output is valid JSON. The Infinity Daemon Client returns pseudo-JSON with some additional, non-JSON elements.
  • The Status field indicates the status of the operation. Normally this is OK, meaning the operation completed successfully. If the field displays any other value, it is a message with an indication of what went wrong with the request.
  • The Explain field contains the JSON for the explanation in a format similar to the Infinity Daemon Client.
  • The Explain field contains an additional SamplePath element. If the path of the file is known, it is returned in this field. If the path is not known, this field contains the SHA256 hash of the item. In the example above, because the file was submitted as part of the explain request, the original file name was not known and therefore the hash is provided.