On-premises Scanner Configuration File

  • Updated on Oct 27, 2025
  • Published on Oct 23, 2025
  • 11 minute(s) read
Prev Next

1.0 Introduction

This article provides detailed information about configuring the Fortanix On-premises Scanner using a configuration file to enable secure and efficient scanning of cryptographic materials within your on-premises infrastructure types.

It also describes:

  • Using the configuration file types.

  • Configuring the configuration file parameters.

  • Using the TLS configuration help script for secure communication setup.

2.0 On-premises 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:

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.

2.1 Type 1 - Credentials Stored Directly in Configuration File

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

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

config
3.76 KB

For information on configuring the configuration file parameters, refer to Section 3.0: Configure the On-premises Scanner Parameters.

2.2 Type 2 - Credentials Loaded Using Environment Variables

In this type, 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 type 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.

config
3.74 KB

For information on configuring the configuration file parameters, refer to Section 3.0: Configure the On-premises Scanner Parameters.

3.0 Configure the On-premises Scanner Parameters

Configuring the scanner requires specifying the necessary parameters in the .yaml configuration file, as explained in Section 2.0: On-premises 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:

3.1 Armor URL

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

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

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

3.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 3.5: Scan Databases.

  • code_repos- List of source code repositories to be scanned. For more information on the source code parameters, refer to Section 3.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 3.7: Scan File System.

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

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

3.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 (Fortanix 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 Scanner Agent (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 Scanner Agents.

  2. The fortanix-fs-scanner (File System Scanner Agent) 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 Scanner Agent installation and configuration, refer to File System Scanner Agent Configuration.

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 4.0: 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 4.0: 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 4.0: 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 Scanner Agent is temporarily stored before being forwarded to Fortanix Key Insight. For example, /home/krish/onprem_test/fs-accumulator/database/.

4.0 TLS Configuration Help Script

To establish a secure trust relationship between the Fortanix On-premises Scanner (server) and its File System Scanner 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 Scanner Agent.

  • 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 Fortanix On-premises Scanner is running.

    • server-ip is the IP address of the Fortanix On-premises Scanner machine.

    • clients is the identifier or hostname of each File System Scanner Agent that will connect to the Fortanix 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 Scanner Agent, so they can authenticate with the Fortanix 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,...>

5.0 Troubleshooting

For guidance on troubleshooting steps for common issues encountered while configuring and running Fortanix Key Insight in on-premises environments, refer to On-premises Connection Troubleshooting.