Scoring a file

To score a file, the REST API uses the HTTP PUT method; the POST method is not supported. The file can be provided by:

A file path: The full path to the file that is visible to the

Cylance Engine

. The file path is passed via a small block of JSON. Note that this is the only way to specify a file to score using the Infinity Daemon Protocol.

A binary: Since the PUT method allows transfer of binary data, the file can be directly transferred to the TCP Service via the HTTP(S) connection. Because the

Cylance Engine

supports multiple compression formats, files can be compressed in order to reduce transmission bandwidth.

When scoring by file path, the client posts a JSON object with the file path to the

Cylance Engine

PUT /apiv1/score
Content-Type: application/json
Content-Length: 36

{
  "FilePath": "/tmp/infinityd.exe"
}

Cylance Engine

1.2 and later, you can score multiple files in a single request using both JSON and MIME multipart:

PUT /apiv1/score
Content-Type: application/json
Content-Length: 70
 
{
  "FilePaths": [ "C:/tmp/sample1.exe", "C:/tmp/sample2.exe" ]
}

If the body is not valid JSON, a 400 Bad Request error is returned. For a 200 OK response, a block of JSON is returned that represents the scoring result. When scoring multiple files, an array of results are returned.

[
    {
        "Status": "OK",
        "SamplePath": "C:/tmp/sample1.exe",
        "AggregateScore": 1.0,
        "Sha256": "5AE1246EAADE01C5840338850D7B35BF70243FC13A8E006642445DB08CB42A50",
        "MaxDepthExceeded": false,
        "SampleFormatUnknown": false,
        "Scores": [
            {
                "Score": 1.0,
                "Determinant": "MODEL",
                "SampleFormat": "PE",
                "ModelVersion": 133368370684345704,
                "Source": "LOCAL_ENDPOINT",
                "Classifier": "ML",
                "ParseStatus": "OK",
                "CentroidHash": "0"
            }
        ]
    },
    {
        "Status": "OK",
        "SamplePath": "C:/tmp/sample2.exe",
        "AggregateScore": 1.0,
        "Sha256": "7E668791A2089E7CB82B09D4574B63DCE1B13DA7278E5F98075F4A070C09AB6D",
        "MaxDepthExceeded": false,
        "SampleFormatUnknown": false,
        "Scores": [
            {
                "Score": 1.0,
                "Determinant": "MODEL",
                "SampleFormat": "PE",
                "ModelVersion": 133368370684345704,
                "Source": "LOCAL_ENDPOINT",
                "Classifier": "ML",
                "ParseStatus": "OK",
                "CentroidHash": "0"
            }
        ]
    }
]

The keys of the scoring-result object are:

Key	Description
Status	This indicates the status of the operation. If the file scored successfully, OK is returned. If an error occurs, a message describing the error is returned. This field is present only in top-level scoring-result objects; it is omitted for any objects in the Children field.
AggregateScore	If the file produced a single result, this is the aggregate score. If the file produced multiple results (for example if the file is an archive), the aggregate score is the lowest score produced among all of the files. This field may be interpreted as the overall score for the file but the individual scores are also available for inspection. Non-scores such as 'NaN' are filtered out before finding the lowest score so that nested files that could not be processed do not corrupt valid results.
MaxDepthExceeded	When scoring an archive, a value of true indicates that the entire archive was not explored because the nesting level was higher than the configured maximum. This means that only a partial result has been returned. A value of false indicates that the entire archive has been examined and all results are available.
SampleFormatUnknown	When the value for this key is true, the file could not be scored by any models that are currently loaded. This normally occurs because the file is not of a supported type.
Scores	This is the list of one or more scores for the file. In most cases, there is only one score unless the file was scored by multiple models.
Children	This is the list of child scoring results for this file. This key is normally seen only when scoring an archive or a MOFAT file. When present, it contains the list of scoring-result objects for any files inside the archive. If one of those file is also an archive, it too has child scoring results until the configured maximum nested depth is reached.
SamplePath	This is the file’s path. When scoring by filepath, this is equivalent to the request’s FilePath. When scoring using binary data, this is equal to the SHA256 of the file. For child scoring results (for example, in the case of files within an archive), the child’s relative file path (that is, its path within an archive) is prefixed with a pipe and appended to the parent SamplePath (for example: archive.zip\|path/to/sample.exe).

Each scoring result contains the following information:

Key	Description
Score	This is the score for the file. If an error is generated (the value in the Determinant field is PARSER, CONFIG, or ABORT), this field contains NaN (not a number). If the value in the Determinant field is WHITECENTROID or WHITELIST, this field is always +1.0. If the value in the Determinant field is BLACKCENTROID or BLACKLIST, this field is always -1.0.
Determinant	This specifies where the results were obtained from. MODEL indicates that the score was calculated by the machine-learning model. BLACKCENTROID and WHITECENTROID indicate that a centroid was hit and the score was changed accordingly. BLACKLIST and WHITELIST indicate that the file hash was explicitly disallowed (that is, appeared in the restricted list) or allowed (that is, appeared in the approved list). PARSER specifies an error while parsing the file. ABORT means that the file was aborted before processing was completed because the scoring took longer than the timeout period to complete. CONFIG indicates that the maximum nested depth was exceeded when processing an archive based on a setting from the Cylance TcpService.ini configuration file.
SampleFormat	This is the type of file that was scored.
ModelVersion	This is the version of the model that produced the score. Because JSON does not handle 64-bit integers well, the version is returned as a string.
Source	This specifies the source of the score. The values can be: LOCAL_ENDPOINT if the score was calculated locally INFINITY_CLOUD if the score came from the Infinity Cloud Service
ParseStatus	This is the status of the parsing of the file. An OK status indicates that the file was parsed successfully. If the status is not OK, two additional fields, StatusCause and CauseMessage, are included to provide more information about why the file could not be parsed.
Classifier	This further classifies where the score was obtained from. The most common value is ML, indicating that the machine-learning model calculated the score. Other valid values: INFINITY_GENERALSCORE indicates that the score came from a scoring operation in the Infinity Cloud Service. HUMAN indicates that the score came from human analysis of the file. INDUSTRY indicates that the score came from a third-party source.

When using a binary rather than a path, the request looks like:

PUT /apiv1/score
Content-Type: application/octet-stream
Content-Length: <length>

<binary data>

In this case, the Content-Type can be any type except for

application/json

, which indicates that a file path has been provided. The most generic is

application/octet-stream

, but others such as

application/gzip

can also be used.

For scoring multiple files as binary, the Content-Type is

multipart/form-data; boundary=something

. Both binary and JSON requests can be made in the multipart form, but each section must have the correct Content-Type (

application/json

application/octet-stream

). Nested multipart forms are not supported.

The output of an archive is hierarchical:

$ curl -X PUT -T test.tar http://localhost:9002/apiv1/score
{
  "Status": "OK",
  "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE",       
  "AggregateScore": 1.0,
  "Sha256": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE",
  "MaxDepthExceeded": false,
  "SampleFormatUnknown": false,
  "Scores": [
    {
      "Score": 1.0,
      "Determinant": "MODEL",
      "SampleFormat": "ARC",
      "ModelVersion": "131975059429967680",
      "Source": "LOCAL_ENDPOINT",
      "Classifier": "ML",
      "ParseStatus": "OK"
      "CentroidHash": "0"    
    }
  ],
  "Children": [
    {
      "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE|CommonUtils.dll",
      "AggregateScore": 1.0,
      "Sha256": "7F3FD0F31FA0C6C840D917567670DA3B4A01EF7D64826E7326DEE8B32454296D",
      "MaxDepthExceeded": false,
      "SampleFormatUnknown": false,
      "Scores": [
        {
          "Score": 1.0,
          "Determinant": "MODEL",
          "SampleFormat": "PE",
          "ModelVersion": "131786662583689000",
          "Source": "LOCAL_ENDPOINT",
          "Classifier": "ML",
          "ParseStatus": "OK"
          "CentroidHash": "1359238976895146529"
        }
      ]
    },
    {
      "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE|infinityd.exe",
      "AggregateScore": 1.0,
      "Sha256": "5AE1246EAADE01C5840338850D7B35BF70243FC13A8E006642445DB08CB42A50",
      "MaxDepthExceeded": false,
      "SampleFormatUnknown": false,
      "Scores": [
        {
          "Score": 1.0,
          "Determinant": "MODEL",
          "SampleFormat": "PE",
          "ModelVersion": "131786662583689000",
          "Source": "LOCAL_ENDPOINT",
          "Classifier": "ML",
          "ParseStatus": "OK"
          "CentroidHash": "1359238976895146529"
        }
      ]
    },
    {
      "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE|InfinityDotNet.dll",
      "AggregateScore": 1.0,
      "Sha256": "F0A7274835C6D32064ED1D1F09104E881F17ACF544A1ECDF2C430D30D9781EA4",
      "MaxDepthExceeded": false,
      "SampleFormatUnknown": false,
      "Scores": [
        {
          "Score": 1.0,
          "Determinant": "MODEL",
          "SampleFormat": "PE",
          "ModelVersion": "131786662583689000",
          "Source": "LOCAL_ENDPOINT",
          "Classifier": "ML",
          "ParseStatus": "OK"
          "CentroidHash": "1359238976895146529"
        }
      ]
    },
    {
      "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE|infinitydt.exe",
      "AggregateScore": 1.0,
      "Sha256": "19F30312D933256BD983DFC6F120F0521D7C97EFB62CB31C5C286F12E4F3C801",
      "MaxDepthExceeded": false,
      "SampleFormatUnknown": false,
      "Scores": [
        {
          "Score": 1.0,
          "Determinant": "MODEL",
          "SampleFormat": "PE",
          "ModelVersion": "131786662583689000",
          "Source": "LOCAL_ENDPOINT",
          "Classifier": "ML",
          "ParseStatus": "OK"
          "CentroidHash": "1359238976895146529"
        }
      ]
    },
    {
      "SamplePath": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE|InstallerIDCore.dll",
      "AggregateScore": 1.0,
      "Sha256": "40A3BD9E62336C60DAB2F43E81B8F708882D799D7FAE96746B047B036A3F47F1",
      "MaxDepthExceeded": false,
      "SampleFormatUnknown": false,
      "Scores": [
        {
          "Score": 1.0,
          "Determinant": "MODEL",
          "SampleFormat": "PE",
          "ModelVersion": "131786662583689000",
          "Source": "LOCAL_ENDPOINT",
          "Classifier": "ML",
          "ParseStatus": "OK"
          "CentroidHash": "1359238976895146529"
        }
      ]
    }
  ]
}

The archive test.tar contains five PE files. The top-level aggregate score is the overall score for the archive. In this example, all the files in the archive are benign, but if they were not, the aggregate score would be the lowest of the all the children.

Each file in the hierarchy gets an aggregate score and a list of individual scores. The reason for this is that any file may be an archive that itself contains multiple files. At each level of the hierarchy, the aggregate score gives a quick overview of that entire file tree.

Section:

Cylance RESTful API