Skip to main content
Version: File Inspection Engine 2.0.0

Configuration

The --help flag output lists all available command-line options along with their default values.

docker run registry.reversinglabs.com/fie/file-inspection-engine:2.0.0 --help

Note that default values may be overridden by environment variables.

  • Boolean flags must include an equals sign (=) when explicitly set to true/1 or false/0 (e.g., --cloud-updates=true, --cloud-updates=false). Alternatively, to enable a boolean flag, use the shortcut by specifying the flag name alone (e.g., --cloud-updates for true). Non-boolean flags don't need an equals sign. Both --timeout 10s and --timeout=10s are fine.

  • Time Duration Options: For configuration options containing time durations, the supported suffixes are ms, s, m, and h (e.g., --timeout 10s or --cloud-update-interval 1m).

info

Environment variables: Command line flags can also be passed as environment variables, by using RL_ as the prefix and replacing the dashes in between the words with underscores. For example, --http-address becomes the environment variable RL_HTTP_ADDRESS.

When a default value is not mentioned in the help output, it is empty (either an empty string or false for boolean options).

Configuration options​

RL_LICENSE​

  • Description: Set the contents of your license file.
  • Default: N/A
  • Notes: This option is only available as an environment variable.

RL_RETRY_COUNT​

  • Description: Configures the maximum number of retries for failed threat data segment downloads when using the threat-data command.
  • Default: 3
  • Possible Values: 0 to 100

--add-file-type / RL_ADD_FILE_TYPE​

  • Description: Controls whether file_type information is returned in the /scan API response.
  • Default: disabled
  • Possible Values: disabled, enabled, force
  • Notes:
    • When enabled, the correct file_type will only be returned if static analysis was performed.
    • When force is set, static analysis is always performed.

--concurrency-limit / RL_CONCURRENCY_LIMIT​

  • Description: Maximum concurrent requests when performing file analysis, across all HTTP endpoints.
  • Default: 20
  • Possible Values: From 0 (unlimited) to 100
  • Notes: Even if the limit is set to 0 (unlimited), the system will still track the number of active concurrent requests. The active_concurrency field will always reflect the actual number of concurrent requests, regardless of the limit setting. The active_concurrency field is logged in the format: active_concurrency={value}/{limit}.

--cpu-request / RL_CPU_REQUEST​

  • Description: Informs the application how many CPUs were requested for the container. This value does not control how many Spectra Core instances are created. Those are configured explicitly with --number-of-regular-cores and --number-of-large-cores. Instead, it is used only for reporting in the /status endpoint.
  • Default: Not set (FIE will use the total number of CPUs detected on the node).
  • Notes:
    • When set, the percentage_* fields in the /status endpoint are calculated relative to this value.
    • The available_* fields show counts of available instances and are not affected by this value.
    • This option is most useful in Kubernetes, where you typically specify resources.requests.cpu. Docker does not have a concept of CPU requests.
  • You can provide the value in three ways:
    1. Command-line flag: 
      args: ["--cpu-request=8"]
    2. Environment variable: 
      env:
        - name: RL_CPU_REQUEST
          value: "8"
    3. Kubernetes Downward API (avoids duplicating the number): 
      env:
        - name: RL_CPU_REQUEST
          valueFrom:
            resourceFieldRef:
              containerName: fie
              resource: requests.cpu

--proxy-address / RL_PROXY_ADDRESS​

  • Description: Specifies the address of a proxy server for contacting the cloud API.
  • Default: N/A
  • Possible Values:
    • https://host:port
    • http://host:port
    • socks5://host:port
  • Notes: You can include credentials in the proxy URL, for example:
    • http://user:password@localhost:8080

--cloud-update-interval / RL_CLOUD_UPDATE_INTERVAL​

  • Description: Sets how frequently the application checks for cloud threat data updates.
  • Default: 5m
  • Possible Values: From 1m to 24h (e.g., 45m, 6h)

--cloud-updates / RL_CLOUD_UPDATES​

  • Description: Enables or disables automatic updates for threat data.
  • Default: true
  • Possible Values: true, false

--http-address / RL_HTTP_ADDRESS​

  • Description: Defines the host and port for the HTTP server.
  • Default: :8000
  • Possible Values:
    • Port only. Example: :9000
    • Host and port. Example: 127.0.0.1:8080

--log-json / RL_LOG_JSON​

  • Description: Defines the log output format as either JSON or colored plain text.
  • Default: true
  • Possible Values: true, false

--max-decompression-factor / RL_MAX_DECOMPRESSION_FACTOR​

  • Description: Spectra Core has a set of mechanisms that protect the user from intentional or unintentional archive bombs, ranging from checks that prevent a file from making identical copies of itself during unpacking, to the maximum allowed decompression ratio for any given file.

    These protection measures enable the engine to terminate the archive decompression if the size of unpacked content exceeds a set quota. The maximum decompression ratio is calculated as

    MaximumDecompressionFactor * (1000 / ln(1 + InputFileSize * pow(10, -5)))

    where InputFileSize must be in bytes. To calculate the maximum decompressed file size, multiply this ratio by the InputFileSize. In practice, this means that the unpacking will stop once the size of all extracted content exceeds the theoretical maximum of the best performing compression algorithm.

  • Default: 1.0

  • Notes: When a file exceeds the decompression ratio, the unpacking will stop and the partially unpacked content will be sent for analysis.

    If set to a negative value, a warning is printed, and the value defaults to 1.0. Setting this to 0 disables decompression management, but this is strongly discouraged as it leaves the system vulnerable to resource exhaustion attacks.

--max-upload-file-size / RL_MAX_UPLOAD_FILE_SIZE​

  • Description: Maximum file size (in MiB) the application will accept.
  • Default: 100
  • Minimum: 1
  • Maximum: 10240

--number-of-regular-cores / RL_NUMBER_OF_REGULAR_CORES​

  • Description: Configures how many Spectra Core instances are allocated to handle files up to the size threshold (--large-file-threshold).
  • Default: 4
  • Possible Values: 1-100

--number-of-large-cores / RL_NUMBER_OF_LARGE_CORES​

  • Description: Configures how many Spectra Core instances are reserved for files larger than the size threshold (--large-file-threshold).
  • Default: 2
  • Possible Values: 0-100
  • Notes: If set to 0, no instances are reserved for large files, and all files are processed by the pool of "regular" instances.

--large-file-threshold / RL_LARGE_FILE_THRESHOLD​

  • Description: File size threshold (in MiB) that determines when a file is routed to the reserved large-file instances.
  • Default: 10
  • Possible Values: 0-10240
  • Routing rules:
    • Files larger than the threshold go to the large-file instances.
    • Files equal to or smaller than the threshold stay in the regular pool.
  • Notes:
    • When set to 0, size-based routing is disabled and all files are distributed across available instances. In this case, the system routes files to the instance with the fewest active analyses, rather than using file size.
    • File size is only an approximation of processing cost. Real resource usage depends on file complexity (number of unpacked children, nesting depth). Choosing an optimal threshold and timeout may require experimentation based on your workload.

--paranoid-mode / RL_PARANOID_MODE​

  • Description: Enables an additional classification for suspicious files, allowing them to be flagged as suspicious instead of OK. With this option, the possible response classifications are OK, malicious, and suspicious.
  • Default: false
  • Possible Values: true, false
  • Notes: Requires an additional 1 GB of cloud threat data.

--processing-unavailable-at-memory-percent / RL_PROCESSING_UNAVAILABLE_AT_MEMORY_PERCENT​

  • Description: Defines the memory usage threshold (in percentage) at which the application will reject new file uploads and return an error on the /readyz endpoint. This helps prevent overloading the system when memory usage is high. For example, to reject uploads once memory usage reaches 80%, use: --processing-unavailable-at-memory-percent=80.
  • Default: 0 (disabled)
  • Possible Values: 0–100
  • Notes: The threshold is based on cgroup v2 memory usage within the container. If your system doesn't support cgroup v2, you can disable this feature by setting the parameter to 0.

--with-threat-details / RL_WITH_THREAT_DETAILS​

  • Description: Determines whether detailed threat information is included in the JSON HTTP response for malware classification.
  • Default: false
  • Possible Values: true, false
  • Notes: Slows down the response as it contacts the cloud API. If no additional threat information is available, the threat_details property won't be present.

--unpacking-depth / RL_UNPACKING_DEPTH​

  • Description: The maximum number of file layers to unpack when performing static analysis.
  • Default: 17
  • Possible values: From 0 (unlimited) to MaxInt32.

--timeout / RL_TIMEOUT​

  • Description: Configures the timeout limit for file analysis, in seconds. The countdown starts when a Spectra Core instance begins processing a file.
  • Default: 0 (unlimited)
  • Examples: --timeout=30s, --timeout=5m, --timeout=1h
  • Notes:
    • When the timeout is reached, the Spectra Core instance is terminated and restarted.
    • If the instance was processing multiple files, all analyses are aborted.
    • Logs contain information about which files were impacted.
    • Before restart, the instance cleans up its temporary files. Restart time depends on the number of files and disk performance, but typically takes a few seconds.
    • Because restart takes time, very short timeout values are not recommended.

Example - Running with proxy and additional settings

docker run --rm -it \
-e RL_LICENSE="the content of the license file" \
-e RL_PROXY_ADDRESS=http://proxy.server.lan \
-e RL_MAX_UPLOAD_FILE_SIZE=200 \
-e RL_PARANOID_MODE=true \
-e RL_WITH_THREAT_DETAILS=true \
-p 127.0.0.1:8000:8000 \
-v /external/threat-data:/rl/threat-data \
-v /external/tmp:/rl/tmp \
file-inspection-engine:2.0.0