Get the PDF

InfinityDaemonClient utility

The InfinityDaemonClient utility is a simple utility to send commands to the

Cylance Engine

using the Infinity Daemon Protocol. It does not work when the

Cylance Engine

is running the

Cylance

Engine RESTful API (CERA).

The InfinityDaemonClient utility works with the

Cylance Engine

Protocol only. It does not work with the RESTful API.

The basic syntax is:

InfinityDaemonClient [<host>:<port>] p <command> <file>

The <host>:<port> specification is optional and defaults to localhost:9002. If the

Cylance Engine

is running on a different port, then you must be specify that port number.

The second argument is the command byte. Only two options are available for this:

Command	Description
p	This command processes a file, either scoring or explaining the file, depending on the <`command`> argument. The resulting response from the service is echoed to the terminal. You must include the <`command`> and <`file`> arguments.
s	If the shutdown command is enabled, this command shuts down the service. When you send a shutdown command, the <`command`> and <`file`> arguments are not required; if you include them, they are ignored.

The value for the <command> argument is either "Score" or "Explain" to score or explain a file or archive, respectively. The legacy commands "ScoreFile", "ScoreArchive", "ExplainFile", and "ExplainArchive", and class-based scoring are still supported but not recommended. For more information, see Classless-based and activity-class-based scoring.

The value for the <file> argument is the path to a file or archive. The InfinityDaemonClient utility can only process a single file or archive for each invocation.

InfinityDaemonClient processes the command and displays the results to the terminal.

The example output of scoring a single file is:

$ InfinityDaemonClient localhost:9002 p Score infinityd.exe
Routing tag: ""
1 features document(s)
----SampleScoring:infinityd.exe----
{
    "CentroidHash": "1359238976895146529",
    "SampleFormat": "PE",
    "Determinant": "MODEL",
    "ModelVersion": "131786662583688997",
    "SHA256": "5AE1246EAADE01C5840338850D7B35BF70243FC13A8E006642445DB08CB42A50",
    "ParseStatus": "OK",
    "Score": 1.0,
    "IsComplete": true
}

The first line of the response indicates the status of the operation. An empty routing tag signifies a successful operation. For a full explanation of the routing tag, see Appendix: CylanceTcpService Protocol.

The second line indicates how many features were generated for the file. For operations on a single file, there is usually only one feature but in some circumstances, multiple features may be produced depending on the type of file.

The third line indicates that it was a scoring operation (starting with SampleScoring) or an explaining operation (starting with TTMStatic).

The block within curly braces is a valid JSON object with the results of the operation. While each block is valid JSON, if multiple results were produced, the entire output is not valid JSON. See the archive example below.

Each scoring result includes the following information:

Field	Description
CentroidHash	This field indicates the hash of the centroids currently loaded into the model. A value of 0 indicates that the model had no centroids loaded.
SampleFormat	This field indicates the type of file that was scored.
Determinant	This field 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, it appeared in the restricted list) or allowed (that is, it appeared in the approved list), respectively. PARSER specifies an error while parsing the file. ABORT indicates that the operation 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 Cylance TcpService.ini configuration file.
ModelVersion	This field indicates 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.
SHA256	This field indicates the SHA256 hash of the file.
ParseStatus	This field indicates 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.
Score	This field indicates 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, it is always -1.0.
IsComplete	For a single file, this value is always true. When processing an archive, this value indicates whether the archive was completely processed. If the archive has archives inside that exceed the configured maximum nested depth, the value in this field is false to indicate that a partial score was generated, and the value in the Determinant field is CONFIG.

When scoring archives, multiple results are returned. In this example, the test.tar file contains five PE files:

$ InfinityDaemonClient localhost:9002 p Score test.tar
Routing tag: ""
  6 features document(s)
  ----SampleScoring:test.tar----
  {
  "CentroidHash": "0",
  "SampleFormat": "ARC",
  "Determinant": "MODEL",
  "ModelVersion": "131975059429967678",
  "SHA256": "5D6D21AB0283E17643B64E856D07ACFEBD6FC52EB4B50AFD3CE6891A2A36ECBE",
  "ParseStatus": "OK",
  "Score": 1.0,
  "IsComplete": true
  }
  ----SampleScoring:test.tar|CommonUtils.dll----
  {
  "CentroidHash": "1359238976895146529",
  "SampleFormat": "PE",
  "Determinant": "MODEL",
  "ModelVersion": "131786662583688997",
  "SHA256": "7F3FD0F31FA0C6C840D917567670DA3B4A01EF7D64826E7326DEE8B32454296D",
  "ParseStatus": "OK",
  "Score": 1.0,
  "IsComplete": true
}
---- SampleScoring:test.tar|infinityd.exe ----
{
  "CentroidHash": "1359238976895146529",
  "SampleFormat": "PE",
  "Determinant": "MODEL",
  "ModelVersion": "131786662583688997",
  "SHA256": "5AE1246EAADE01C5840338850D7B35BF70243FC13A8E006642445DB08CB42A50",
  "ParseStatus": "OK",
  "Score": 1.0,
  "IsComplete": true
}
---- SampleScoring:test.tar|InfinityDotNet.dll ----
{
  "CentroidHash": "1359238976895146529",
  "SampleFormat": "PE",
  "Determinant": "MODEL",
  "ModelVersion": "131786662583688997",
  "SHA256": "F0A7274835C6D32064ED1D1F09104E881F17ACF544A1ECDF2C430D30D9781EA4",
  "ParseStatus": "OK",
  "Score": 1.0,
  "IsComplete": true
}
---- SampleScoring:test.tar|infinitydt.exe ----
{
  "CentroidHash": "1359238976895146529",
  "SampleFormat": "PE",
  "Determinant": "MODEL",
  "ModelVersion": "131786662583688997",
  "SHA256": "19F30312D933256BD983DFC6F120F0521D7C97EFB62CB31C5C286F12E4F3C801",
  "ParseStatus": "OK",
  "Score": 1.0,
  "IsComplete": true
}
---- SampleScoring:test.tar|InstallerIDCore.dll ----
{
  "CentroidHash": "1359238976895146529",
  "SampleFormat": "PE",
  "Determinant": "MODEL",
  "ModelVersion": "131786662583688997",
  "SHA256": "40A3BD9E62336C60DAB2F43E81B8F708882D799D7FAE96746B047B036A3F47F1",
  "ParseStatus: "OK",
  "Score": 1.0,
  "IsComplete": true
}

For an archive, the first result should be of file format ARC, which indicates that an archive outer container was successfully opened. The score for this result is always +1.0. The IsComplete flag in this top-level result indicates whether the archive was completely explored or not. If the Determinant is PARSER, the archive is somehow corrupt and could not be opened.

The other results follow as described above. The only difference is that the archive name is added to the file path of each result, followed by a vertical bar (|). Multiple levels of archive nesting are each separated by a |. Because the size of the feature-name field is limited, the name may be truncated. For complete details, see Appendix: CylanceTcpService Protocol.

The Explain command produces threat indicators for a file:

$ InfinityDaemonClient localhost:9002 p Score infinityd.exe
Routing tag: ""
  1 features document(s)
  ----TTMStatic:infinityd.exe----
  {
      "features": {
          "Collection": {
              "OSInfoImports": true
          },
          "Deception": {
              "ProtectionExamination": true
            }
      },
      "scores": {
        "Destruction": 0,
        "Deception": 5,
        "Collection" 5,
        "DataLoss": 0,
        "Anomalies": 0
     },
     "SampleFormat": "PE"
}

The first three lines of the response are the same as for scoring except that SampleScoring is replaced with TTMStatic. Following the header is a JSON block with the threat indicators. It contains three top-level keys.

Field	Description
features	This field indicates the collection of threat-indicator features discovered in the file. The contents of this block change based on the features in the file. The keys are the category of the feature with the value of the threat indicator indexed by the threat-indicator name.
scores	This field indicates the total count of threat indicators for each category.
SampleFormat	This field indicates the format of the file.

For a complete list of the supported threat indicators and their categories, see Appendix: Threat indicators.

When explaining an archive, the TTMStatic header begins each result with a path with the name of the archive (or archives, if nested) separated by a vertical bar (|). Because the size of the feature-name field is limited, the name may be truncated. For complete details on how feature names are truncated, see Appendix: CylanceTcpService Protocol.

Section:

File-scoring applications