On-premises Connection Scanning Configuration

1.0 Introduction

This article describes the minimum configuration requirements for Fortanix Key Insight to successfully scanning keys and resources in on-premises and external key source (Fortanix Fortanix-Data-Security-Manager (DSM) on-premises) connections.

It also describes:

• Installing the on-premises scanner on Linux and Windows.

• Configuring the scanner through the configuration file parameters.

• Executing the on-premises scanner on Linux and Windows.

2.0 Terminology References

For On-premises connection features and supported features, refer to All Connections Concepts and On-premises Connection Concepts.

3.0 Scanning Permissions

For detailed information on on-premises connection scanning permissions, refer to On-premises Connection Permissions.

4.0 Prerequisites

The following are the prerequisites to configure an on-premises connection on Fortanix Key Insight:

• Server Specifications

  • The server hosting the scanner must have at least 2 virtual Central Processing Units (vCPUs) allocated.

  • The server must have a minimum of 8 GB of Random Access Memory (RAM) to support the scanner.

  • The server should have at least 20 GB of storage capacity for temporarily storing scanned data.

• Operating System and Libraries

  • Linux: Supported operating systems include Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, and RHEL 9 (or Rocky Linux 9). The necessary packages are available in .deb or .rpm formats.

  • Windows: Supported operating systems include Windows Server 2016, 2019, 2022, and 2025. The necessary packages are available in .msi format.

• Network Requirements

  • Outbound (On-premises Scanner → External Services)

    The on-premises scanner must be allowed to make outgoing connections to:

    • armor.fortanix.com on port 443

    • Databases on their configured ports

    • The following Internet Protocol (IP) range to communicate back to Fortanix Key Insight:

      • 216.180.120.0/24

      IP whitelisting is not mandatory. It is required only if your on-premises  environment enforces outbound firewall restrictions.

  • Inbound (File System Agent scanner → On-premises scanner)

    The on-premises scanner must be reachable from the File System Agent:

    • Must accept inbound connections from the File System Agent’s IP on the configured port. For example, 8080 or 1443.

    • Firewall or security group rules must allow this traffic.

    • The service must bind to 0.0.0.0 or its external or private IP, not just 127.0.0.1.

  NOTE

  Although inbound connectivity is required, the on-premises scanner itself does not expose any ports externally.

• Configuration File

  The on-premises scanner requires a configuration file that includes a list of databases, source code, and file systems with their corresponding credentials, as well as the Fortanix DSM on-premises credentials. This configuration file is in plain text, and it is your responsibility to secure the file and its credentials.

• Mixed Mode Authentication: Ensure that Mixed Mode authentication is enabled in MSSQL if you are using Windows Authentication before starting the scan.

  Perform the following steps to enable the Mixed Mode:

  1. Open Microsoft SQL Server Management Studio (SSMS).

  2. Right click the server’s name and select Properties.

  3. Navigate to the Security page.

  4. Set Server authentication to SQL Server and Windows Authentication mode.

  5. Click OK.

  

5.0 On-premises Scanner Installation - Linux

You must install the on-premises scanner package to manage your databases, source code, file system, and Fortanix DSM on-premises keys and resources on a Linux host.

1. Download the scanner package to your local machine. The deb or rpm package is provided with the downloaded package for the supported operating systems.

2. Run the following command to install the scanner package:

   • Ubuntu 20.04

     sudo apt install ./fortanix-scanner_<version>-focal_amd64.deb

   • Ubuntu 22.04

     sudo apt install ./fortanix-scanner_<version>-jammy_amd64.deb

     NOTE

     You can ignore the message N: Download is performed unsandboxed as root as file '..../fortanix-scanner_<version>-jammy_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) during the installation of the scanner package.

   • Ubuntu 24.04

     sudo apt install ./fortanix-scanner_<version>-noble_amd64.deb

   • RHEL9

     sudo dnf install ./fortanix-scanner-<version>-1.x86_64.rpm

3. Generate the scanner configuration file as detailed in Section 9.0: On-premises Scanner Configuration.

   NOTE

   • You must create the configuration file in the /opt/fortanix/scanner/conf directory.

   • A sample configuration file is present in /opt/fortanix/scanner/conf/fortanix-scanner.yaml.example.

4. Initiate the scanning process as detailed in Section 6.0: On-premises Scanner Execution - Linux.

NOTE

• After you start the scanner, any changes made to the scanner configuration file require a restart of the scanner to apply the latest updates.

• Installing a new version of the on‑premises scanner package for Linux will overwrite the following default files in the /opt/fortanix/scanner/conf/ directory:

  • fortanix-scanner.yaml.example

  • fortanix-scanner.service.example

  However, any custom files (for example, user-created configurations) in the same directory will not be removed during the upgrade.

  To avoid potential loss of important settings, it is recommended to back up your configuration files before proceeding with the installation.

6.0 On-premises Scanner Execution - Linux

After the scanner is configured, refer to the following sections to initiate the scanner for on-premises infrastructures on a Linux host.

NOTE

The scanner commands require the configuration file to be named config.yaml. If you are using the provided example file (fortanix-scanner.yaml.example), ensure to copy or rename it to config.yaml before running any of the scanner commands in the following sections.

6.1 Prerequisites for Oracle Scan

To enable the scanner to connect to an Oracle database, install the Oracle Instant Client package by performing the following steps:

1. Open the Oracle Instant Client version 23.5.0.

2. Download the instantclient-basic-linux.x64-23.5.0.24.07.zip file.

3. Run the following command to create folders for installing Oracle Instant Client:

   mkdir -p /opt/oracle

4. Run the following commands to extract the files: This would create a directory instantclient_23_5 in /opt/oracle:

   sudo cp instantclient-basic-linux.x64-23.5.0.24.07.zip /opt/oracle
   cd /opt/oracle
   sudo unzip instantclient-basic-linux.x64-23.5.0.24.07.zip

5. Run the following command to modify or create /etc/ld.so.conf.d/oracle.conf file and add it to the directory  instantclient_23_5:

   echo /opt/oracle/instantclient_23_5 | sudo tee /etc/ld.so.conf.d/oracle.conf

6. Run the following command to update the dynamic link:

   This allows the Oracle Cloud Infrastructure (OCI) libraries to be accessible to other applications on the host, ensuring that they can find and use these shared libraries when needed.

   sudo ldconfig

6.2 Run the On-premises Scanner

You must run the on-premises scanner to start scanning Oracle, MSSQL, Fortanix DSM (on-premises), source code, and file system environment resources.

NOTE

• If you are scanning an Oracle database, ensure the Oracle client libraries are installed as described in Section 6.1: Prerequisites for Oracle Scan.

• If the scan is interrupted or closed before completion, then the next scan will start from the beginning.

6.2.1 Run the Scanner Manually

Run the following command to start the scanner:

sudo -u fortanix -E -H /opt/fortanix/scanner/bin/fortanix-mssql-scanner start -c /opt/fortanix/scanner/conf/config.yaml

6.2.2 Run the Scanner as a Systemd Service

To ensure the Fortanix on-premises scanner runs automatically at startup and restarts if it stops unexpectedly, configure it as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-scanner.service.example.

Perform the following steps to configure the systemd service:

1. Run the following command to copy the example unit file into the systemd directory:

   sudo cp /opt/fortanix/scanner/conf/fortanix-scanner.service.example /usr/lib/systemd/system/fortanix-scanner.service

2. Run the following command to enable the service to start automatically on boot:

   sudo systemctl enable fortanix-scanner

3. Run the following command to start the service:

   sudo systemctl start fortanix-scanner

4. Run the following command to confirm the status of the service:

   sudo systemctl status fortanix-scanner

7.0 On-premises Scanner Installation - Windows

You must install the on-premises scanner package on a Windows machine to manage your databases, source code, file systems, and Fortanix DSM on-premises keys and resources.

Perform the following steps to install the scanner:

1. Download and open the Fortanix Key Insight scanner Microsoft installer file (msi) file.

2. Review the Fortanix Key Insight Scanner license agreement and select the check box to accept the terms.

   

3. Click Install to begin the installation.

4. After the installation is complete, click Finish to exit the setup wizard. The installer installs the scanner at the default directory, C:\Program Files\Fortanix\KI\.

   

5. Generate the scanner configuration file as detailed in Section 9.0: On-Premises Scanner Configuration.

6. Initiate the scanning process as detailed in Section 8.0: On-Premises Scanner Execution - Windows.

NOTE

• A sample configuration file is available at C:\ProgramData\Fortanix\KI\Conf\Config.yaml.example.

• To upgrade the package on Windows, download the latest installer (.msi) and run it. The installer automatically replaces the previous version and no manual uninstallation is required.

8.0 On-premises Scanner Execution - Windows

NOTE

The scanner command in this section requires the configuration file to be named config.yaml. If you are using the provided example file (config.yaml.example), ensure to copy or rename it to config.yamlbefore running the scanner command.

After configuring the scanner, perform the following steps to execute it:

1. Open the command prompt and run the following command to navigate to the scanner installation directory:

   cd "C:\Program Files\Fortanix\KI"

2. Run the following command to execute the scanner:

   NOTE

   Recommended guidelines:

   • Run the FortanixScanner.exe file from the C:\Program Files\Fortanix\KI directory.

   • Keep the config.yaml file in the C:\ProgramData\Fortanix\KI\Conf directory.

   FortanixScanner.exe start --config-file < path-to-config.yaml>

   Where, < path-to-config.yaml> is the full path to your scanner configuration file. For example: C:\ProgramData\Fortanix\KI\Conf\config.yaml.

NOTE

• After you start the scanner, any changes made to the scanner configuration file require restarting of the scanner to apply the latest updates.

• If a scan is interrupted or closed before completion, then the next scan will restart from the beginning.

• To stop the scanner running in Command Prompt, press Ctrl + C in the same console window.

9.0 On-premises Scanner Configuration

This section describes how to configure the on-premises scanner for both Linux and Windows platforms, including authentication methods, database, source code, and file system infrastructures, and secure credential management using environment variables or configuration files.

9.1 The Scanner Configuration File

The Fortanix on-premises scanner requires a configuration file in YAML format to define on-premises infrastructure parameters.

The Fortanix on-premises scanner can securely retrieve credentials from environment variables or a separate secrets file instead of storing them directly in the main configuration file, helping protect sensitive information and simplifying integration with secrets managers.

Two types of configuration files can be used, depending on the context:

• Credentials stored directly in the configuration file. For more information, refer to Section 9.1.1: Credentials Stored Directly in Configuration File.

• Credentials loaded using environment variables. For more information, refer to Section 9.1.2: Credentials Loaded Using Environment Variables.

NOTE

• Contact Fortanix Support to include and use any fields or sections marked as Optional in the configuration file.

• The scanner processes configuration files in the order they are specified. If multiple configuration files are provided, the settings in later files override those in earlier ones.

• If you are using the older configuration file (prior to the Fortanix Key Insight 25.04 release), you can continue with it. However, to scan the Fortanix DSM on-premises environment, or both the Fortanix DSM on-premises environment and databases, you must use the new configuration file mentioned above.

If you use secret manager tools (for example, Hashicorp Vault) to manage credentials, refer to On-premises Scanner Integration with Hashicorp Vault for on-premises scanner configuration.

9.1.1 Credentials Stored Directly in Configuration File

In this method, the API key (or other credentials) is written directly inside the configuration file.

This method is:

• Very simple to set up.

• Less secure, since sensitive values are stored in plain text and could be exposed if the file is shared.

In the following config.yaml file,

• Include only the required sections (Databases, Source Code, File Systems, or Fortanix DSM) with the appropriate connection details (ID and API Key). To enable a section, remove the comment symbol (#) at the beginning of the lines.

• Replace placeholders (YOUR_XXX_XX) with actual credentials or valid file paths before use.

For information on configuring the configuration file parameters, refer to Section 9.2: Configure the Scanner Parameters.

9.1.2 Credentials Loaded Using Environment Variables

In this method, sensitive data (credentials) are not stored directly in the configuration file. Instead, the configuration file references the name of an environment variable (for example, ARMOR_API_KEY_1), and the actual secret is set in the system environment. The application automatically reads the value from the environment variable at runtime.

• Only credential fields can use env_var (API keys, usernames, passwords, certificate keys/certs).

• All other fields (connection_id, app_id, branch, subfolder, and so on) are plain strings.

This method helps to:

• Keep sensitive data out of configuration files.

• Enable secure separation between code and secrets.

Before running the application, you must set or export the environment variables in your system. Once set, the application will automatically read the value from the environment variable referenced in the configuration file.

For example, in Linux, run the following command to set the environment variable for the API Key: Here, replace "your-secret-api-key" with your actual API key value.

export ARMOR_API_KEY_1="your-secret-api-key"

In the following config.yaml file, include only the required sections (Databases, Source Code, File Systems, or Fortanix DSM) with the appropriate connection details (ID and API Key). To enable a section, remove the comment symbol (#) at the beginning of the lines.

For information on configuring the configuration file parameters, refer to Section 9.2: Configure the Scanner Parameters.

9.2 Configure the Scanner Parameters

Configuring the scanner requires specifying the necessary parameters in the .yaml configuration file, as explained in Section 9.1: The Scanner Configuration File. This file specifies how the scanner connects to Fortanix Key Insight, Fortanix DSM, source code repositories, file systems, and target databases.

The following sections describe each section of the configuration file along with its corresponding fields:

9.2.1 Armor URL

The URL of the Fortanix Key Insight Armor platform used for communication with the scanner. For example, https://armor.fortanix.com.

9.2.2 Logging

The configuration file allows you to configure the log file path, maximum log file size, and number of archived log files to retain.

• folder – Directory path where log files are stored. The file name is always audit.log.

  The default values are:

  • Linux: /var/log/fortanix/scanner

  • Windows: C:\ProgramData\Fortanix\KI\Logs

• file_size_mb – Maximum size (in megabytes) of the log file before it is rotated. The default value is 50.

• max_files – Number of rotated or archived log files to retain. The default value is 5.

9.2.3 External Key Source (Fortanix DSM On-premises) Connection

Each connection entry defines the authentication details for either an external key source connection (Fortanix DSM on-premises instance) or an on-premises environment to be scanned.

• connection_id – Unique identifier for the Fortanix DSM on-premises connection in Fortanix Key Insight.

• type – Specifies the authentication method for Fortanix Key Insight; use apikey. For example, the API key can be stored in the environment variable ARMOR_API_KEY_2.

  You can obtain the connection ID and API key from the Fortanix DSM on-premises connection details page. For more information, refer to Getting Started With External Key Source Connection.

• dsm – Defines the Fortanix DSM on-premises environment details:

  • url – URL of the Fortanix DSM on-premises instance.

  • app_id – Fortanix DSM administrator (admin) application (app) ID used for scanning. For more information on obtaining the app ID, refer to the User’s Guide: Authentication.

  • credential – Specifies the certificate-based authentication for Fortanix DSM access. For more information on obtaining the certificate credentials, refer to the User’s Guide: Authentication.

    • authentication_key – Specifies the value of the Fortanix DSM application’s private key.

    • authentication_cert – Specifies the value of the Fortanix DSM application’s certificate.

      Both parameters can be provided either as a file path to the corresponding key or certificate, or as an environment variable.

      NOTE

      When using environment variables, the value must contain the complete contents of the key or certificate file, not just the file path.

9.2.4 On-premises Connections

Each connection entry defines the authentication details for either an external key source connection (Fortanix DSM on-premises instance) or an on-premises environment to be scanned.

• connection_id – Unique identifier for the on-premises connection in Fortanix Key Insight.

• type – Specifies the authentication method. It is apikey for Fortanix Key Insight access. For example, the API key required for authenticating with Fortanix Key Insight is available in the environment variable ARMOR_API_KEY_1.

You can obtain the connection ID and API key from the on-premises connection details page. For more information, refer to Getting Started With On-premises Connection.

• databases – List of databases to be scanned, with URI and credentials. For more information on the database parameters, refer to Section 9.2.5: Scan Databases.

• code_repos- List of source code repositories to be scanned. For more information on the source code parameters, refer to Section 9.2.6: Scan Source Code.

• fs_accumulator- Configuration for the file systems, including server settings, queues, and the datastore path for scanned file system data. For more information on the file system parameters, refer to Section 9.2.7: Scan File System.

9.2.5 Scan Databases

To scan databases in an on-premises connection, configure the following parameters:

• databases – List of databases to be scanned, with URI and credentials.

  • uri: Database connection string in the following formats:

    • Oracle:oracle://<host>:<port>/<db name>

      For example, oracle://host:port/db

    • MSSQL: mssql://<host>:<port>/

      For example, mssql://host:port

  • credential- Specifies the authentication methods based on the type.

    • password- Uses basic username or password authentication. Both MSSQL and Oracle databases use the password authentication method to scan databases. The username or password values can be provided as:

      • value – Directly in the config file.

      • file – Path to a file containing the credential.

      • env_var – Environment variable storing the credential. For example, DB1_USERNAME and DB1_PASSWORD.

    • windows_authentication: Uses Windows integrated authentication. It is supported only for Windows hosts.

    • You can also configure Microsoft Entra (formerly Azure AD) authentication for scanning MSSQL databases in Fortanix Key Insight. Before using any of the following methods, ensure that your MSSQL server is configured to support Entra authentication.

      For more information on enabling and configuring Microsoft Entra authentication in SQL Server, refer to Enable Microsoft Entra authentication for SQL Server on Azure VMs.

      • azure_client_secret: Uses Microsoft Entra ID service principal authentication with Azure client_id, client_secret, and tenant_id. These values can also be provided using the environment variables DB_CLIENT_ID, DB_CLIENT_SECRET, and DB_TENANT_ID,respectively.

        For more information on obtaining these values, refer to Register an application in Microsoft Entra ID.

      • azure_cli: Uses Azure CLI-based authentication.

      • azure_managed_identity: Uses Azure Managed Identity authentication.

        For more information on the above Microsoft Entra authentication types, refer to Microsoft Entra authentication for SQL Server.

9.2.6 Scan Source Code

To scan source code repositories in an on-premises connection, configure the following parameters:

• code_repos – List of source code repositories to be scanned.

  • url- HTTPs URL of the repository (repo). For example, https://github.com/fortanix/rust-sgx.

  • branch (Optional)- Specific branch to scan. If omitted, the default branch is scanned.

  • subfolder (Optional)- Restrict scanning to a specific folder within the repo. For example, app.

  • auth (Optional)- Defines authentication type and credentials for private repositories.

    • type- Supports basic authentication (username, password, or personal access token).

    • The username or password values can be provided as:

      • value – Directly in the config file.

      • file – Path to a file containing the credential.

      • env_var – Environment variable storing the credential. For example, REPO1_USERNAME and REPO1_PASSWORD.

For example, refer to the following on how to obtain the authentication credentials for different repositories:

• GitHub

• Bitbucket

9.2.7 Scan File System

To perform file system scans in an on-premises environment, the two components must run in the following order:

1. The fortanix-scanner (On-premises scanner) package: This is the on-premises scanner (server) package and acts as the central service. It communicates with Fortanix Key Insight and with the File System Agent scanner (client). When the file system scanning service (fs_accumulator) is enabled, this package starts a local HTTPS server to receive data from the File System Agent scanners.

2. The fortanix-fs-scanner (File System Agent scanner) package: This is installed on a server that has access to the file systems you want to scan. You can deploy multiple agents, and each must be configured to connect to the IP address and port of the HTTPS server started by the fortanix-scanner.

For detailed information on File System Agent scanner installation and configuration, refer to On-premises Connection Scanning Configuration for File System.

To enable and configure the fs_accumulator service in the fortanix-scanner configuration file, specify the following parameters:

• fs_accumulator – Configuration for the File System Accumulator service, including server settings, queues, and datastore path for scanned file system data.

  • enabled- Enables or disables the fs_accumulator service. Here, true indicates that the service is running, whereas false indicates that the service is disabled.

  • server_configs- This section defines how the accumulator server listens for incoming connections and how it handles TLS.

    • binding_ips_and_ports- Defines one or more IP:PORT combinations where the fs_accumulator service should listen. For example,

      • 127.0.0.1:1234 binds the service locally and only accepts connections from the same machine.

      • 0.0.0.0:1234 exposes the service on all network interfaces, allowing external connections.

      NOTE

      Ensure the on-premises service (fs_accumulator) is bound either to 0.0.0.0 or the machine’s external or private IP address. Using only 127.0.0.1 will prevent remote File Sytem Agents from connecting.

    • tls- This section enables HTTPS with mutual TLS authentication.

      • ca_file- Points to the CA certificate that issued the client certificates, which the on-premises scanner uses to authenticate agents; typically, this is pki/ca/ca-cert.pem generated by the script explained in Section 9.3: TLS Configuration Help Script.

      • certificate_chain_file- Specifies the PEM file containing the server’s certificate chain, starting with the server’s leaf certificate and followed by any intermediates but excluding the root CA; this is  pki/server/server-chain.pem from the script explained in Section 9.3: TLS Configuration Help Script.

      • certificate_key_file- Defines the server’s private key in unencrypted PKCS#8 format. This is pki/server/server-key.pem from the script explained in Section 9.3: TLS Configuration Help Script. The permissions on this file should be restricted for security.

  • datastore_configs- Settings related to local storage of scanned data.

    • datastore_path- Specifies the local storage path where metadata received from the File System Agent scanners is temporarily stored before being forwarded to Fortanix Key Insight. For example, /home/krish/onprem_test/fs-accumulator/database/.

9.3 TLS Configuration Help Script

To establish a secure trust relationship between the Fortanix on-premises scanner (server) and its File System Agents (clients), certificate, identity, and private key files must be created and managed. Generating these files manually can be error-prone, so the help script automates the process and ensures a consistent setup.

This helper script:

• Creates or reuses a private Certificate Authority (CA) using ECDSA P-256.

• Issues a single server certificate (with DNS name and optional IP SAN).

• Issue one or more client certificates, each unique to an individual File System Agent scanner.

• Produces all output in a structured pki/ directory, ready for use.

Perform the following steps to use the help script:

1. Download the following script (.sh) file:

   fortanix_key_insight_fs_accumulator_tls_configuration

   5.57 KB

2. Run the following command to make the script executable:

   chmod +x fortanix_key_insight_fs_accumulator_tls_configuration.sh

3. Run the following command for the first-time setup to generate CA, server certificate, and client identities:

   ./ fortanix_key_insight_fs_accumulator_tls_configuration.sh\
       --server-dns <SERVER_DNS> \
       --server-ip <SERVER_IP> \
       --clients <CLIENT_NAME_1,CLIENT_NAME_2,...>

   Example:

   ./ fortanix_key_insight_fs_accumulator_tls_configuration.sh\
       --server-dns scanner.internal \
       --server-ip 10.0.0.5 \
       --clients clientA,clientB

   Here,

   • server-dns is the DNS hostname of the machine where the on-premises server will run.

   • server-ip is the IP address of the on-premises server.

   • clients is the identifier or hostname of each File System Agent scanner that will connect to the on-premises scanner. Multiple client names can be provided as a comma-separated list.

4. After running the command, the following files will be generated: Copy these files securely to each server that will run the Fortanix File System Agent scanner, so they can authenticate with the on-premises scanner.

   • CA files:

     • pki/ca/ca-key.pem – Private key

     • pki/ca/ca-cert.pem - CA certificate

   • Server files

     • pki/server/server-key.pem - Server private key

     • pki/server/server-cert.pem - Server certificate

     • pki/server/server-chain.pem - Server chain

   • Client identity files:

     • pki/clients/<CLIENT_NAME>/identity.pem - Combined client key and certificate

   NOTE

   • The CA certificate is created only once and reused.

   • Server certificates are created when you provide --server-dns.

   • Client certificates are created when you provide --clients.

5. Run the following command to add more clients later, if required, reusing the same CA and server certificates:

   ./ fortanix_key_insight_fs_accumulator_tls_configuration.sh\
       --clients <NEW_CLIENT_NAME_1,NEW_CLIENT_NAME_2,...>

10.0 Limitations

The following table summarizes the known limitations of Oracle and MSSQL databases regarding their encryption key management:

11.0 Frequently Asked Questions (FAQs)

12.0 Additional References

After configuring the on-premises scanner, refer to the following:

• Getting Started With On-Premises Connection for guidance on onboarding an on-premises connection in Fortanix Key Insight.

• Getting Started With External Key Source Connection for guidance on onboarding a Fortanix DSM on-premises connection in Fortanix Key Insight.

• On-Premises Connection Troubleshooting for guidance on troubleshooting steps for common issues encountered while configuring and running Fortanix Key Insight in on-premises environments.