On-premises Scanner Configuration File

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:

Credentials stored directly in the configuration file. For more information, refer to Section 2.1: Type 1 - Credentials Stored Directly in Configuration File.
Credentials loaded using environment variables. For more information, refer to Section 2.2: Type 2 - Credentials Loaded Using Environment Variables.

NOTE
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 a configuration file created prior to the Fortanix Key Insight 25.09 release, it will remain compatible. However, to scan Fortanix DSM on-premises environments, source code repositories, containers, and file systems, you must use the updated configuration file described 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, Containers, 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

4.94 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, Containers, 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

4.90 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, containers, file systems, and target databases.

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

3.1 Armor URL and Region

This section explains the Fortanix Armor platform endpoint and region used by the Fortanix On-premises Scanner for secure communication.

url: Specifies the Fortanix Armor URL used by the Fortanix On-premises Scanner. The URL value must be https://api.armor.fortanix.com.
region: Specifies the Fortanix Armor geographical region used by the Fortanix On-premises Scanner. Supported values are north_america and european_union.
If this field is not specified, the region defaults to european_union.

3.2 Proxy

The configuration file allows you to specify an HTTP or HTTPS proxy with optional authentication for outbound connections made by the Fortanix On-premises Scanner. Proxy settings can be applied for communication with the Fortanix Armor platform or other configurable sections (such as Source Code repositories) in the configuration file.

NOTE
Proxy configuration applies only to http(s) URLs and is optional.

proxy: Indicates that proxy configuration is enabled.
- url: Specifies the HTTP or HTTPS proxy endpoint. For example, http://localhost:8888.
- credential: Defines the basic authentication method. Include credential details in the configuration file only if basic authentication is enabled in your proxy settings.
  - type – Specifies the authentication type. Currently, only basic is supported.
  - username and password – Specify the proxy credentials. The username or password values can be provided as:
    - value – Directly in the configuration file.
    - file – Path to a file containing the credential.
    - env_var – Environment variable storing the credential. For example, PROXY_USER and PROXY_PASSWORD.

NOTE
If the same proxy must be used for all code repositories and the Fortanix Armor platform, the configuration file supports YAML anchors and aliases to reuse the proxy configuration block. For more information, refer to Section 4.0: Reusing Configuration Fille Components.

3.3 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.4 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:
NOTE
The parameters in this section are used by the Fortanix On-premises Scanner to authenticate directly to the Fortanix DSM on-prem instance. These credentials are created and managed in Fortanix DSM, and are independent of the API key generated in the Fortanix Key Insight UI, which is used only for Fortanix On-premises Scanner to Fortanix Key Insight authentication.
- 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 Fortanix DSM admin app ID, refer to the User’s Guide: Authentication.
  NOTE
  For Fortanix DSM on-premises scanning, the Fortanix On-premises Scanner authenticates to Fortanix DSM using TLS client certificate authentication. The associated admin app must have Certificate authentication enabled before the scanner is run. The admin app may be initially created using API Key authentication to obtain the Admin App ID (APP_UUID); after the TLS client certificate is generated with the APP_UUID as the Common Name (CN), the admin app authentication method must be changed to Certificate.
- credential – Specifies the certificate-based (TLS client certificate) authentication used by the Fortanix On-premises Scanner to access the Fortanix DSM on-prem instance. For more information on obtaining the certificate credentials, refer to the User’s Guide: Authentication.
  - authentication_key – Path to, or environment variable containing, the externally generated TLS client private key associated with the Fortanix DSM admin app.
  - authentication_cert – Path to, or environment variable containing, the externally generated TLS client certificate associated with the Fortanix DSM admin app.
    Important
    Fortanix DSM does not automatically generate the TLS client private key or certificate. The TLS client certificate must be generated externally, and the Common Name (CN) of the certificate must match the Admin App ID (APP_UUID).
    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.5 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 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.1: Scan Databases.
code_repos- List of source code repositories to be scanned. For more information on the source code parameters, refer to Section 3.5.2: 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.5.3: Scan File System.
container_images – Configuration for scanning container images, including definitions of image artifacts, pull requirements, and the container engine used for retrieval. Each artifact entry specifies the repository image, tag, and daemon settings used during the scan process. For more information on container image parameters, refer to Section 3.5.4: Scan Containers.

3.5.1 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. You can reuse credentials in the configuration file using YAML anchors and aliases. For more information, refer to Section 4.0: Reusing Configuration File Components.
  - 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.

For more information on the Database infrastructure type, refer to Database.

3.5.2 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.
- proxy: For information on proxy settings and related parameters, refer to Section 3.2: Proxy.
- 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:

For more information on the Source Code infrastructure type, refer to Source Code.

3.5.3 Scan File System

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

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.
For more information on how the Fortanix On-premises Scanner interacts with the File System Scanner Agent, refer to File System.
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.

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

3.5.4 Scan Containers

To scan container images in an on-premises environment, configure the following parameters:

container_images - Defines the configuration for scanning the container images.
- daemons - A list of container runtime daemons that the scanner can connect to.
  Each daemon includes the following parameters:
  - name – A unique identifier for the daemon. For example, docker.
  - socket – The connection endpoint for the container runtime.
    Default Docker sockets:
    - Linux: unix:///var/run/docker.sock
    - Windows: npipe:////./pipe/docker_engine
- artifacts - A list of container image definitions to be processed by the scanner.
  Each artifact includes the following parameters:
  - type - Specifies the container image source type. For on-premises scanning, the supported value is daemon_repository_image, which indicates that the image is retrieved from the local Docker (or similar container runtime).
  - image – Specifies the name of the container image to scan. For example, vault or ghcr.io/linuxserver/nginx.
  - image_tag - Specifies the tag of the container image. For example, 1.13.3.
  - daemon - Defines the container runtime daemon from which the image is retrieved.
    NOTE
    The daemon specified under artifacts must match with one of the daemon name defined in the daemons section.

For more information on the container infrastructure type, refer to Containers.

4.0 Reusing Configuration File Components

The configuration file supports YAML Anchors (&) and Aliases (*) for reusing the same configuration across multiple sections. This is useful when the same credentials, proxy settings, or other configurations need to be applied to multiple servers, databases, or services.

Using anchors and aliases ensures that updating a single section automatically propagates the changes wherever it is referenced.

Example:

NOTE
The following code block is only a sample example and not an actual configuration file. For the complete and accurate configuration details, refer to Section 2.0: On-premises Scanner Configuration File.

# MSSQL Credentials Anchor
# Use this anchor to provide default MSSQL credentials across multiple connections.
mssql_default_creds: &mssql_creds
  credential:
    type: password
    username:
      value: <MSSQL_USERNAME>   
    password:
      value: <MSSQL_PASSWORD>   

# Oracle Credentials Anchor
# Use this anchor to provide default Oracle credentials across multiple connections.
oracle_default_creds: &oracle_creds
  credential:
    type: password
    username:
      value: <ORACLE_USERNAME>  
    password:
      value: <ORACLE_PASSWORD>  

# Proxy Configuration Anchor
# Use this anchor to provide default proxy settings across multiple places.
proxy_ref: &proxy_ref
  proxy:
    url: "http(s)://<host>:<port>"
    credential:
      type: basic
      username:
        value: user
      password:
        value: password

armor:
  url: "<ARMOR_SERVICE_URL>"  
  <<: *proxy_ref

connections:
  - connection_id: <CONNECTION_ID>  
    credential:
      type: apikey
      apikey:
        value: <API_KEY>  

    databases:
      - uri: "mssql://<MSSQL_HOST_1>:<PORT>"  
        <<: *mssql_creds

      - uri: "mssql://<MSSQL_HOST_2>:<PORT>" 
        <<: *mssql_creds

      - uri: "oracle://<ORACLE_HOST>/<DB_NAME>"  
        <<: *oracle_creds

Here, for example,

&mssql_creds– Specifies the anchor (defines reusable credentials)
*mssql_creds – Specifies the alias (references the anchor)
<<: – Merges the anchor content into each server block.

NOTE
Changing credentials in one place automatically updates all servers.

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

Download the following script (.sh) file:
fortanix_key_insight_fs_accumulator_tls_configuration
5.57 KB

Run the following command to make the script executable:

chmod +x fortanix_key_insight_fs_accumulator_tls_configuration.sh

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

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

6.0 Troubleshooting

For information about common issues and troubleshooting steps when configuring and running Fortanix Key Insight in on-premises environments, refer to On-premises Connection Troubleshooting.