Configuration file for the Cylance Engine
Cylance Engine
The configuration file is a standard UTF-8 encoded text file that is broken into multiple sections.
- Each section name must be enclosed in square brackets ([]).
- Each section contains zero or more key/value pairs with the format key=value.
- Whitespace around the = sign is ignored, as are blank lines and trailing whitespace.
- You can add comments by starting a line with a # sign. The comment extends to the end of that line.
You can update certain entries in the .ini configuration file while the
Cylance Engine
is running. The DataFileUpdateInterval setting determines how often the service checks for these changes. For most settings, you must restart the service for the updated setting to take effect. Settings that you can update while the service is running are indicated in their respective sections.For settings that do not have a default value, a — symbol appears in default-value column in the tables.
The Service section controls general features and configuration controlling the service. You must restart the service for updates to any of the settings in this section to take effect.
Key | Default value | Description |
|---|---|---|
DataFileUpdateInterval | 0 | This key specifies the interval, in seconds, between checks to see whether the .ini configuration file contains any updated settings.
|
ExternalClientEnable | false | When this value is false, the service restricts connections to the local host only. When this value is true, the service listens on all network interfaces, allowing clients from other machines to connect to the service. |
IP | 127.0.0.1 | This key specifies the TCP port the Cylance Engine should listen on when multiple ports are available. Setting the value to 0.0.0.0 listens on all interfaces, which is the same as setting the ExternalClientEnable key to true. |
MaxConcurrency | 0 | This key specifies the maximum number of files that the Cylance Engine can process simultaneously. The default value of 0 indicates that the concurrency should be set to the number of detected CPU cores. Setting this value higher than the number of CPU cores could lead to poor system performance. |
MaxPendingConnections | 100 | This key specifies the maximum number of connections that can be pending (that is, not yet being processed) before new connections are rejected. |
Port | — | This key specifies the port on which the TCP Service should listen. |
Protocol | IDP for Mono ;REST for Microsoft
.NET 8.0 | This key specifies the protocol to run on the listening port. The valid values are:
|
Proxy | — | This key specifies a proxy server to use when making any outgoing connections. The format of the proxy specification is “http://proxy.com:port”, or “http://username:password@proxy.com:port” if a username and password are required. The HTTPS protocol can be used as well. When using a username and password, you must escape any special characters used in the URL notation (for example, /, :, @, and so on), according to the HTTP specification. |
ScoringTimeout | 0 | This key specifies the amount of time, in seconds, to allow for scoring a single file. The default (0) indicates 300 seconds (5 minutes). A non-zero value indicates the time in seconds. Setting this value too low may result in abort errors when scoring files, especially archives. |
ShutdownCommand | false | This key specifies whether the Cylance Engine should honor the shutdown command (s ) or not. The default value of false ignores the shutdown command. |
When Protocol=REST, you can configure additional settings in the Service section to control secure connections.
Key | Default value | Description |
|---|---|---|
HttpsEnable | false | When this value is false, the service does not enable HTTPS connections. When this value is true, the service enables HTTPS connections. When they are enabled, you must configure the TlsPort, TlsCertPath, and TlsCertPassword settings. |
TlsPort | — | This key specifies the port for secure connections, that is, for clients that connect to the REST API via HTTPS. The Port setting is for insecure connections via HTTP only. |
TlsCertPath | — | This key specifies the path to a file containing the TLS certificate in Persona Information Exchange (.pfx) format. This is a standard X.509 certificate that contains both the public and private key. |
TlsCertPassword | — | This key specifies the password to use for the PFX TLS certificate. |
ClientCertRequired | false | When this value is false, client certificates are not validated. When this value is true, client certificates are validated that they are signed by the certificate specified by TlsCertPath. Clients that cannot present a correctly signed certificate are denied access. |
CacheSize | 1024 | This key specifies the maximum number of validated certificates to cache. |
CacheEntryExpiration | 1 | This key specifies the expiration time, in hours, for validated certificates in the cache. Once this time has elapsed, the client certificate must be revalidated on connection. |
The AllowedRestrictedHashList section indicates where the allowed and restricted SHA256 list can be located. The file path is checked for changes according to the DataFileUpdateInterval setting in the Service section.
Key | Default value | Description |
|---|---|---|
FilePath | — | This key specifies the path to a file containing the allowed and restricted hash list JSON entries. For the format of this file, see Infinity Public Data API. |
The ConsoleLog section controls the logging of the
Cylance Engine
to the console. You must restart the service for updates to any of the settings in this section to take effect.Key | Default value | Description |
|---|---|---|
LogLevel | — | This key specifies the verbosity of the console log. The valid values are
|
LogTag | false | This key specifies whether tagging information should be included with each message. When false, specifies that no tagging information should be included; when true, indicates that the module name space and message hash will be included with each message. The tag represents the particular subsystem that produced the message. For most messages, this information is not important and you can disable the setting to reduce the size of the log file. |
TimeStamp | off | This key specifies the format of the time stamp included with each message. The default value of off indicates that no time stamp should be included. Other valid values are:
|
The FileLog section controls the logging of the
Cylance Engine
to a file. The FileLog section supports the same settings as the ConsoleLog section, and the following additional setting. You must restart the service for updates to any of the settings in this section to take effect.Because the console logging and file logging are separate sections within the configuration file, you can configure the settings for each section with different values.
Key | Default value | Description |
|---|---|---|
FilePath | — | This key specifies the path to the file in which to log the messages. Relative paths are relative to the location of the .ini configuration file. |
The Syslog section controls the syslog configuration. You must restart the service for updates to any of the settings in this section to take effect.
Key | Default value | Description |
|---|---|---|
Host | — | When specified, logging to a system logger (syslog) is enabled and this setting specifies the host name of the service. The default is to leave this setting blank and not log to a syslog server. |
Port | 514 | This key specifies the port on which the syslog service is running. For most systems, the default is 514, but you can specify a different port for non-standard configurations. |
Protocol | RFC5424 | This key specifies the protocol to use when communicating with the syslog service. The default protocol is RFC5424, but for older services, RFC3164 is supported as well. |
Facility | Security | This key specifies the syslog facility that you log any messages under. The valid values are:
|
MalwareSeverity | Alert | This key controls the syslog level at which malware notifications are sent. The valid values are:
|
SeverityFilter | Warning | This key controls which messages get logged with the syslog service. Any message with a lower priority is logged. The valid values are:
|
ScoreThreshold | 0.0 | This key specifies the threshold at which the score is considered malware. Everything equal to or less than this value results in a syslog malware notification. The range of valid values is +1.0 to -1.0. |
The CloudScoring section controls whether scores for files should be retrieved from the
Cylance
Infinity Cloud or only calculated locally. You must restart the service for updates to any of the settings in this section to take effect.Key | Default value | Description |
|---|---|---|
Enabled | false | When this value is false, the service disables the retrieval of cloud scores. When this value is true, the service enables the retrieval of cloud scores. If you enable setting, you must also specify an API key via the ApiKey setting. |
ApiKey | This is the Cylance Infinity Cloud API key to use for cloud-scoring requests. This must be a 32-character, all upper-case, hexadecimal number. API keys are assigned per customer. Contact your BlackBerry representative if you need an API key | |
RequestTimeoutMs | — | This key specifies the time, in milliseconds, to wait for a response from the cloud. Normally, responses are very quick (within hundreds of milliseconds) but they can take longer depending on network conditions. |
The ManifestCentroidUpdate section controls the retrieval and loading of the new manifest-based centroids, which allows the service to fetch only the centroids that it does not already have. You must restart the service for updates to any of the settings in this section to take effect.
Key | Default value | Description |
|---|---|---|
Enabled | false | When this value is false, the service disables the retrieval of new centroids. When this value is true, the service enables the retrieval of new centroids. |
CentroidUpdateIntervalHours | 48 | This key specifies the interval, in hours, between checks for new centroids. |
DirectoryPath | — | This key specifies the directory in which to store the downloaded centroids. The default is to store them under an appropriate local application data folder on the system. |
The Cache section controls the internal caching of scores to avoid rescoring commonly seen files. You must restart the service for updates to any of the settings in this section to take effect.
Key | Default value | Description |
|---|---|---|
CacheSizeMB | — | This key specifies the amount of memory, in MB, to use for the cache. When score caching is enabled, the minimum value is 1MB. While there is no upper limit to the size, large caches are not recommended because this memory is exclusively reserved for the cache. |
Enabled | false | When this value is false, the service disables score caching. When this value is true, the service enables score caching. |
RedisHost | — | This key specifies the URL of the Redis server to use for caching, instead of the in-memory score cache. When this setting is a valid URL (using the format redis://host:port/), the internal cache is disabled and the CacheSizeMB key is ignored.Scores that are stored in the Redis cache still honor the TimeToLive key, which is enforced by the Redis server and not the Cylance Engine . You should configure multiple instances of the Cylance Engine to use the same Redis server to share the score caching among them. |
TimeToLive | — | This key specifies the length of time, in hours, for which any cache entry is kept in the cache. The minimum is 1 hour but this value can be increased to allow entries to live longer. For the local cache (not Redis ), cache entries are not automatically expunged when they exceed their time to live, but they may be evicted any time after this period, depending on the need for space in the cache.This setting does not have an inherent maximum value, but we recommend that the TimeToLive value not be set too high when cloud scoring is enabled to get updated values from the cloud. |
The activity sections control which activity classes are loaded. Each section must have a unique name and start with "Activity:". Although the name does not matter, it is recommended that scoring activities start with "Score-" and explaining activities start with "Explain-" (for example, "Score-PE" and "Explain-PE"). Apart from the amount of available memory, there is no limit for the number of configured activities. Multiple generations of a single model (for example, PE) can be specified if the activity name is unique, such as Score-PE4 and Score-PE6.
The activities support a number of settings but not all are valid for each type of activity. Note that, in the activity sections, only the Centroids setting is checked for changes according to the DataFileUpdateInterval setting in the Service section.
Key | Description |
|---|---|
AssemblyPath | This key applies to scoring, explaining, and archive activities. This is the path, relative to the .ini configuration file, to the assembly for the activity. |
EnsemblePath | This key applies to scoring and archive activities only. This is the path, relative to the .ini configuration file, to the ensemble for the activity. |
Centroids | This key applies to scoring activities only. This is an optional path to a file containing centroids to load into the model. Centroids do not have to be separated by model; each scoring activity loads only the appropriate centroids from the specified file. Therefore, all centroid settings can point to the same file; this is the recommended setup. In the activity sections, only the Centroids setting is checked for changes according to the DataFileUpdateInterval setting in the Service section. |
MaxNestedFileDepth | This key applies to the archive activity only. When the service is processing archives, this value controls how many levels of nesting of archives to examine before giving up. A value of 1 examines the top-level archive entries but no archives inside. Setting this value too high may result in the scoring operation aborting due to a timeout, or the process hanging if the archive is malformed. |
Passwords | This key applies to the archive activity only. This is an optional, comma-separated list of default passwords to try on password-protected archives. These are tried after any passwords that are passed via the Score or Explain commands. |
TempArchiveDirectory | This key applies to the archive activity only. When processing archives, if this setting is present, the value is a temporary disk location in which you can extract the contents of the archive for processing. By default, archives are processed entirely in memory. Using this setting can reduce the amount of memory used for archive processing at the expense of additional disk space usage and processing time. |
The following is an example of each activity:
... [Activity:Score-PE] AssemblyPath=Cylance.Model.SS3PE6.dll EnsemblePath=Ensemble-20180813-S3V8-PE6.cym Centroids=Centroids.cyb [Activity:Explain-PE] AssemblyPath=SampleExplainPE.dll [Activity:Score-ARC] AssemblyPath=Cylance.Model.ARC.dll EnsemblePath=Ensemble-20190319-S0V5-ARC.cym MaxNestedFileDepth=3 Passwords=abc123,clean,dirty ...
The Activity:Score-ARC name is not special. The Cylance.Model.ARC.dll assembly defines this as being an archive activity. Only Cylance.Model.ARC.dll understands the MaxNestedFileDepth and Passwords settings. If these settings are present in any other section, the service ignores them.
The Archive section is no longer supported and has been replaced with Activity:Score-ARC.
The
Prometheus
section allows you to enable whether you want to use a Prometheus
server to scrape metrics data from the Cylance Engine
periodically, and the port to listen on for scrape requests. For more information about how Prometheus
works with the Cylance Engine
, see Appendix: Prometheus monitoring support.Key | Default | Description |
|---|---|---|
Enabled | false | This key specifies whether to use a Prometheus server to scrape metrics data. When enabled, the service listens on the TCP port that you specify using the Port key, or the port specified using the --prometheus-port command-line option (see Command-line options for the Cylance Engine). |
Port | 9009 | This key specifies the port to listen on for scrape requests. |