Skip to main content
Version: File Inspection Engine 1.0.0

Docker

Docker image​

The File Inspection Engine Docker image can either be obtained from the ReversingLabs container registry or provided as a .tar file.

Pulling the Docker image​

To pull the Docker image from the ReversingLabs container registry:

  1. Log in to the Docker Registry

    Log in using your cloud username and password:

    docker login registry.reversinglabs.com

  2. Pull the Docker image

    Pull the file-inspection-engine Docker image with the specified tag:

    docker pull registry.reversinglabs.com/fie/file-inspection-engine:v1.0.0

  3. Verify the download

    Verify that the image has been successfully pulled:

    docker image ls | grep inspection

    Example output

    file-inspection-engine                                  v1.0.0

Loading the Docker image from a .tar file​

If you have received the Docker image as a .tar archive:

  1. Load the Docker image Load the image using the following command:

    docker image load -i file-inspection-engine-v1.0.0.tar.gz

  2. Verify the loaded image

    To verify that the image has been loaded, you can list Docker images and filter for the product:

    docker image ls | grep inspection

    Example output

    file-inspection-engine                                  v1.0.0

Running the application​

The File Inspection Engine (FIE) reads its license from an environment variable called RL_LICENSE. This license, provided by ReversingLabs, must be passed to the application at startup.

To start the application, use one of the following commands. If the image has been pulled from the registry, the full image name should include the registry.

docker run --rm -it -e RL_LICENSE="contents of the license file" --net host file-inspection-engine:v1.0.0

In this example, the container runs on the host network, so no port mapping is needed.

If you’re not using the host network, you’ll need to map the container’s port to the host.

The HTTP server uses port 8000 by default, but you can change it:

  • To map the port to a different host port:

    docker run --rm -it -p 127.0.0.1:80:8000 file-inspection-engine:v1.0.0

  • To change the HTTP port used by the container:

    docker run --rm -it -p 127.0.0.1:80:9000 file-inspection-engine:v1.0.0 --http-address :9000

Help / Main Options​

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

docker run --rm -it file-inspection-engine:v1.0.0 --help

Note that these 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.

--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.

--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-threat-data / RL_CLOUD_THREAT_DATA​

  • Description: Path to the directory for local threat data to avoid contacting the cloud API during file inspection.

  • Default: /rl/threat-data

  • Notes: Requires ~20 GB for malicious data and 1 GB for suspicious data, with additional space needed during updates (files are downloaded fully before replacement).

    Threat data synchronization starts shortly after the application is up and running and continues at regular intervals, configurable via the --cloud-update-interval parameter.

    Initial synchronization involves larger files, while subsequent updates use incremental changes (typically < 100 KB per segment). Data is divided into 256 segments per classification, and each segment may require multiple updates, which can increase the total download size to several megabytes, especially with less frequent updates.

--cloud-update-interval / RL_CLOUD_UPDATE_INTERVAL​

  • Description: Sets how frequently the application checks for cloud threat data updates.
  • Default: 5m
  • Possible Values: Time format (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

--tmp-dir / RL_TMP_DIR​

  • Description: Path to the temporary directory for uploaded files, unpacked files, and reports.
  • Default: /rl/tmp

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

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

--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.

--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: The maximum analysis time, for example 10s (seconds) or 1m (minute). Timeouts apply to all processing after the file is uploaded.
  • Default: 0 (unlimited)
note

You do not need to change the default paths for --cloud-threat-data and --tmp-dir. However, it is important to mount the appropriate directories to these paths when starting the container.

Do not configure more than one container to use the same directories concurrently.

Examples​

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:v1.0.0

Manual threat data synchronization​

The File Inspection engine retrieves updates automatically.

If you want to pre-download threat data so your customers can start using it immediately, or if you prefer to manually sync the data, use the threat-data command included in the image. This command is also used to download threat data in air-gapped environments.

Supported Options​

The threat-data command supports the following options in addition to username and password:

  • RL_PARANOID_MODE Download data collection for suspicious files.
  • RL_PROXY_ADDRESS Specify a proxy server address if you need to connect to the cloud via a proxy.

Sync Command​

To manually sync the threat data, use the sync sub-command, which requires specifying the threat data directory:

./threat-data sync /threat/data/dir

To execute this via Docker, run:

docker run --rm -it \
  -e RL_CLOUD_USERNAME=username \
  -e RL_CLOUD_PASSWORD=password \
  -e RL_PARANOID_MODE=true \
  -v ./external/dir:/rl/threat-data:z \
  --entrypoint ./threat-data \
  registry.reversinglabs.com/fie/file-inspection-engine:v1.0.0 \
  sync /rl/threat-data

If you need to treat suspicious files as malicious, make sure to set the RL_PARANOID_MODE option to true in the command.

Important:

  • The threat-data command only supports configuration via environment variables.
  • We recommend pre-downloading the threat data once and including it in your distribution for multiple users, as a full threat data download is more resource-intensive compared to incremental updates.
  • Do not run the threat-data command concurrently with the application if both are accessing the same directory.

Air-gapped manual threat data synchronization​

For air-gapped environments, follow the process below to synchronize threat data. First, download the threat data on a machine with internet access, then transfer the data to the air-gapped instance.

  1. Start a File Inspection Engine (FIE) instance on a machine with internet access. Once the data sync is complete, stop the FIE instance that was used for downloading, and then proceed to step 2.

    Alternatively, run the following command to manually sync the threat data:

    docker run --rm -it \
    -e RL_CLOUD_USERNAME=username \
    -e RL_CLOUD_PASSWORD=password \
    -v /external/dir:/rl/threat-data \
    --entrypoint ./threat-data \
    file-inspection-engine:v1.0.0 \
    sync /rl/threat-data

    /external/dir represents the path on the host system where the threat data is stored. If the directory contains older threat data, it will be incrementally updated.

    note

    If using paranoid mode, set the environment variable RL_PARANOID_MODE=true.

    Upon successful synchronization, the log should show Threat data fully updated. In case of errors, rerun the command to retry. Proceed to step 2.

  2. Stop a production FIE instance (or create a new one) in the air-gapped environment.

  3. Copy the threat data from /external/dir on the internet-connected machine to the corresponding threat data directory used by the air-gapped FIE instance. Ensure that the transferred data is placed in the directory where the application would normally download it if it were online. For further assistance, contact ReversingLabs Support.

  4. Restart or deploy the air-gapped FIE instance with the updated threat intelligence data.