On-premises Connection Scanning Configuration for File System

  • Updated on Oct 17, 2025
  • Published on Sep 24, 2025
  • 12 minute(s) read
Prev Next

1.0 Introduction

This article describes the minimum configuration requirements for Fortanix Key Insight to successfully scan file system resources in an on-premises connection using the File System Agent scanner.

It also describes:

  • How to install the File System Agent scanner.

  • How to configure the scanner through the configuration file parameters.

  • How to execute the File System Agent 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 a File System Agent scanner in an on-premises connection:

  • Fortanix On-premises Scanner: Ensure that the fortanix-scanner package, which acts as the central service, is installed, configured, and running. It communicates with Fortanix Key Insight and with the File System Agent scanners. When the file system scanning service (fs_accumulator) is enabled, this package starts a local HTTPS server to receive data from the agents.

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

  • 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, 22.04, 24.04, and RHEL 8/9 (alternatively, Rocky Linux 9). The necessary packages are available in .deb or .rpm formats.

    • Windows: Supported operating systems include Windows Server 2016, 2019, and 2022.

  • Network Requirements

    • Outbound (File System Agent → On-premises Scanner):

      File System Agent must be able to establish Transmission Control Protocol (TCP) connections to the on-premises scanner’s host and port, as defined in the configuration file

    NOTE

    The File System Agent scanner does not expose any ports. It only initiates outbound connections to the fortanix-scanner service.

5.0 File System Scanning

Organizations often store cryptographic material in local files, including private keys, public keys, symmetric keys, certificates, and application-specific files (for example, SSH and PGP). To reduce security risks, these assets need to be scanned, their metadata extracted, and the results integrated into a managed state.

The File System Scanning feature enables this scanning process by capturing inventory information and integrating it into Fortanix Key Insight, providing visibility, analysis, and seamless integration.

5.1 File System Scanning Components

The feature consists of two main components:

  • File System Agent scanner (fortanix-fs-scanner): Installed on servers that need to be scanned. It traverses file systems and extracts metadata about cryptographic materials. For more information, refer to Section 5.1.1: File System Agent Scanner.

  • Fortanix On-premises scanner (fortanix-scanner): Installed once per organization. It receives metadata from multiple File System Agents using HTTPS and forwards the collected information to Fortanix Key Insight. For detailed information on on-premises scanner installation and configuration, refer to On-premises Connection Scanning Configuration.

NOTE

No cryptographic material ever leaves the server. The File System Agent scanner transmits only metadata, such as file paths, cryptographic asset type, algorithms, and key sizes. The information sent outside the server is at the same security level as the data shown in Fortanix Key Insight reports and asset listings.

5.1.1 File System Agent Scanner

The File System Agent scanner is the primary component responsible for scanning and extracting metadata. It is available for:

  • Linux: Provided as .deb and .rpm packages.

  • Windows: Provided as an .exe executable.

The following are the key properties of the File System Agent scanner:

  • Extracts only metadata (never raw cryptographic materials such as private keys).

  • Ensures that no file uploads occur, keeping all data strictly on-premises.

  • Runs as a lightweight process without requiring long-running services or external dependencies such as OpenSSL.

  • Supports file system and network throttling to control CPU, I/O, and network usage without disrupting normal operations.

5.2 Supported Key and Certificate Formats

The file system scanning process supports detection and analysis of the following key and certificate formats:

  • SSH Keys

    • RSA private and public keys (OpenSSH, PEM)

    • DSA keys

    • ECDSA private and public keys (PEM)

    • Ed25519 private and public keys

    • PuTTY RSA private key (PPK)

  • TLS/SSL Certificates and Keys

    • Certificate chains (PEM)

    • Root CA, Intermediate CA, and Leaf certificates

    • Certificate Signing Requests (CSR)

    • Certificate Revocation Lists (CRL)

    • RSA private and public keys

    • Elliptic Curve (EC) parameters and keys

    • Diffie–Hellman (DH) parameters

    • JSON Web Keys (JWK)

    • Symmetric keys (encrypted formats)

      NOTE

      Raw symmetric keys in AES or HMAC format (binary data without headers) may be detected based on file size and file naming patterns. Any keys found this way should be manually verified, as they are not fully supported formats.

NOTE

  • Partially supported PKCS cryptographic container formats (detection and limited metadata extraction):

    • PKCS#12 / PFX bundles (encrypted and unencrypted)

    • PKCS#7 signed and enveloped messages

  • Supported PGP cryptographic materials (detection only):

    • PGP public keys

    • PGP private keys

    • PGP messages (encrypted and signed)

    • PGP signatures

5.3 File-Type Independent Scanning and Data Parsing

To maximize the accuracy of metadata detection, file extensions are generally not used to determine file type or scanning eligibility.

For now, all files that are 4 GiB or smaller are scanned, regardless of extension. The File System Agent scanner works directly on the binary data, attempting to extract metadata where possible.

If a file contains multiple PEM blocks, each block is evaluated separately for metadata in formats that support PEM encapsulation. File names are not a factor: as long as the file is readable, its contents are processed and checked for compatible metadata.

6.0 File System Agent Scanner Installation - Linux

You must install the File System Agent scanner package to manage your file system 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-fs-scanner_<version>-focal_amd64.deb

    • Ubuntu 22.04

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

    • Ubuntu 24.04

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

    • RHEL9

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

  3. Generate the scanner configuration file as detailed in Section 7.0: File System Agent Scanner Configuration.

    NOTE

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

  4. Initiate the scanning process as detailed in Section 8.0: Run the File System Agent Scanner on Linux.

NOTE

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

  • fortanix-fs-scanner.yaml.example

  • fortanix-fs-scanner.service.example

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

TIP

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

7.0 File System Agent Scanner Configuration

This section describes how to configure the File System Agent scanner, including the following:

  • Paths to include or exclude during scanning.

  • Connection details for communicating with the fortanix-scanner (HTTPS endpoint).

  • Throttling options to control local and outbound resource usage.

7.1 The File System Agent Scanner Configuration File

The File System Agent scanner requires a configuration file in YAML format to define which file paths to scan, what metadata to extract, throttling options, and how to connect back to the central on-premises scanner (fortanix-scanner).

The scanner supports the following:

  • File System scanning (extracting metadata for keys, certificates, and related cryptographic files).

  • Secure metadata transfer to the fortanix-scanner over HTTPS.

The following is the sample configuration file in .yaml format:

config
1.06 KB

To configure the scanner, you need to define the required parameters in the .yaml configuration file.

  • included_root_paths: Specifies one or more starting directories for scanning; for example, using / instructs the scanner to process the entire file system, and multiple paths can be listed if necessary.

  • excluded_path_regexes: Defines regular expression patterns for files or directories that should be skipped; leaving it as an empty list ([]) means nothing is excluded.

  • ca_file: Points to the Certificate Authority (CA) certificate file to authenticate clients during the mutual TLS (mTLS) handshake, and it must be the same CA that issued the client certificate. This is located at pki/ca/ca-cert.pem and is generated by the script explained in Section 7.2: TLS Configuration Help Script.

  • identity_file: Specifies the location of the client’s identity file in PEM format, created during provisioning for this specific scanner. This file proves that it serves as proof that the scanner is a trusted client. This is located at pki/clients/<client-name-given-by-you>/identity.pem and is also generated by the script explained in Section 7.2: TLS Configuration Help Script.

  • host: Determines the IP address where the scanner service listens, commonly set to 127.0.0.1 for local-only access, but adjustable if remote connections are required.

  • port: Specifies the HTTPS port for the scanner service. The fs-accumulator service connects to this port. Ensure it does not conflict with other services running on the machine.

NOTE

If the configuration file has duplicate details, the last specified value will override any previous entries.

The scanner executable is fortanix-fs-scanner.  For information on running the File System Agent Scanner on Linux and Windows, refer to Section 8.0 Run the File System Agent Scanner on Linux and Section: 10.0: Run the File System Agent Scanner on Windows.

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

8.0 Run the File System Agent Scanner on Linux

After the scanner is configured, the File System Agent scanner must be run with root privileges (for example, using sudo).

NOTE

  • You must start the fortanix-scanner package first before executing the File System Agent scanner (fortanix-fs-scanner). If the fortanix-scanner service is not running, the File System Agent scanner fails with a connection refused error when attempting to register a new scan.

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

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

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

8.1 Run the Scanner Manually

Run the following command to start the scanner:

sudo -u fortanix -H /opt/fortanix/fs-scanner/bin/fortanix-fs-scanner -c /opt/fortanix/fs-scanner/conf/config.yaml

8.2 Run the Scanner using a Scheduled Timer

To ensure the File System Agent scanner runs automatically, it can be configured as a systemd timer. This allows the agent to run on a defined schedule without manual intervention. Using a systemd timer is the recommended approach for running the File System Agent scanner on Linux.

This method uses the example unit files provided in /opt/fortanix/fs-scanner/conf/.

The systemd timer automatically triggers the scanner at the specified intervals. While manual execution of the agent is still possible (for example, during debugging), scheduling with a systemd timer ensures consistent and reliable operation.

In the downloaded package, you will find the following example files:

  • Service file: fortanix-fs-scanner.service.example - Ensures the File System Agent scanner runs as a low-priority background task, minimizing impact on normal system operations.

  • Timer unit: fortanix-fs-scanner.timer.example - Defines the schedule for running the service.

Here is the sample timer file:

[Unit]

Description = Fortanix File System Scanner (scheduled)

[Timer]

OnCalendar=Sun 03:45

Persistent=false

[Install]

WantedBy=timers.target

This configuration runs the scanner every Sunday at 03:45 AM,  as specified in the OnCalendar parameter.

Perform the following steps to schedule the scanner:

  1. Run the following command to copy the example service and timer unit files into the systemd directory:

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

  2. Run the following commands to enable and start the timer so it starts automatically on boot:

    sudo systemctl enable fortanix-fs-scanner.timer
sudo systemctl start fortanix-fs-scanner.timer

9.0 File System Agent Scanner Installation - Windows

You must install the File System Agent scanner package on a Windows machine to manage your File System resources on Windows.

NOTE

You must start the fortanix-scanner service before executing the File System Agent scanner. If the fortanix-scanner service is not running, the File System Agent scanner will fail with an error when attempting to register a new scan.

Perform the following steps:

  1. Download and open the Microsoft Installer File (msi) file.

  2. On the Fortanix KI Filesystem Scanner Setup dialog box, read through the scanner license agreement and select the check box to accept the terms.

    Figure 1: Install the Scanner Package

  3. Click Install to proceed with the installation.

  4. After the installation completes, click Finish to close the installer. The scanner is installed in the default directory, C:\Program Files\Fortanix\KI\.

  5. Generate the scanner configuration file as described in Section 7.0: File System Agent Scanner Configuration with the details specific to Windows.

  6. Start the scanning process as described in Section 10.0: Run the File System Agent Scanner on Windows.

NOTE

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.

10.0 Run the File System Agent Scanner on Windows

After the scanner is configured, the File System Agent must be run from an elevated Command Prompt or PowerShell session as Administrator.

Perform the following steps to execute the scanner:

  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:

    FortanixFSScanner.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:\Program Files\Fortanix\KI\conf\config.yaml.

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.

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

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

11.0 Troubleshooting

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