Process command
The process command (
p
) instructs the service to process a file located at the given path. There are two main process commands: Score and Explain; legacy commands ScoreFile, ScoreArchive, ExplainFile, ExplainArchive, and class names are still accepted but not recommended. Class names are explained in Classless-based and activity-class-based scoring.The format of the
p
command is:Field | Data element | Description |
|---|---|---|
Command byte | Char | p for the process command. |
Command length | Byte | This is the length of the process command, which is normally 5 for the score command or 7 for the explain command. The length is longer when using fully specified class names or passing parameters with the command (for example, passwords for archives). |
Command | String | This is the string that contains the command (for example Score or Explain). The field was originally called ActivityClass but that has been deprecated. For more information, see Classless-based and activity-class-based scoring. |
File path length | UInt16 | This is the length of the file path in bytes. This is not the number of characters in the path but the number of UTF-8 encoded bytes. |
File path | String | This is the fully qualified path to the file to process. The file must reside on a path that is visible to the TCP service. Relative paths are relative to the TCP service and should not be used. |
The format of the response is:
Field | Data element | Description |
|---|---|---|
Routing tag length | Byte | This is the length of the routing tag. If the command is successful, the length is 0. If an error occurred, then the length is non-zero. |
Routing tag | String | This is the routing tag string. If the routing tag length field is 0, this field is empty. |
Feature count | Byte | This is the number of features being returned in this response. Up to 255 features can be returned although normally there is only one. |
Feature JSON length | UInt32 | This is the length of JSON returned for the feature. |
Feature JSON | String | This is the JSON object that contains the feature. |
The routing tag is a status string returned from the service for every process command. For commands that complete successfully, the routing tag is an empty string (that is, "") which means the first byte of the response is 0. Other routing tags provide additional information.
- "": Success. At least one feature is available in the response. Note that the included feature(s) may indicate an error but the service was able to at least attempt to process the file.
- "unknown": Invalid input or format not supported. This tag is returned when, for example, a file is provided that no loaded model can process. No features were returned as part of this response.
- "error": Unable to process the input. The command should not be repeated and would not succeed if retried (for example, if the file was not found or could not be read). No features were returned as part of this response.
- "fault": A temporary error occurred. The command can be repeated at a later time. Examples of this are file-sharing violations and similar errors. No features were returned as part of this response.
The routing tag only represents the status of the top-level operation and does not report issues during the processing of the file, for instance, once the file has been opened successfully. If an error occurs during the processing of a file, the service still produces a feature that contains more detailed information on the error.
Up to 255 features can be returned in a single process command. For most files, a single feature is returned that contains the score or a set of threat indicators. Due to the existence of archives, multiple features may be returned for a single file (for example, a .zip file contains multiple PE files). When the feature count field is greater than one, the feature JSON length and feature JSON fields are repeated for each feature. Applications must be prepared to examine all features because the order of the features is not guaranteed.
The feature name starts with SampleScoring for a score operation and TTMStatic for an explain operation. Because files may contain other files (for example, archives), a pseudo-path is appended to one of those strings to identify from where the file originated. Each level of nesting is separated by a vertical bar (|).
Due to the maximum length of the feature name (255 bytes), heavily nested feature names may be truncated to fit into the 255-byte limit. Two truncation steps that are applied in order until the length of the feature name fits into the limit:
- Any SHA256 hashes in the name are reduced from 64 characters to 8 characters followed by a tilde (~). SHA256 hashes are used when the name of the file cannot be determined.
- The feature name is the concatenation of "..." with the last 252 bytes of the UTF-8 encoded feature name.
Because the feature name may be truncated, it is recommended to track files by their SHA256 hash that is returned as part of the feature JSON.
For example, a resulting feature-name key for a single file looks like:
SampleScoring:example-file.exe
Resulting activity keys for an archive look like:
SampleScoring:test-file.zip|file1.exe SampleScoring:test-file.zip|file2.exe SampleScoring:test-file.zip|file3.pdf
Archives inside of archives are supported and each level of archive is separated with a vertical bar.