File System Scanner Agent Configuration File

1.0 Introduction

This article provides detailed information about configuring the File System Scanner Agent using a configuration file to enable secure and efficient scanning of cryptographic keys and resources within your file system infrastructure.

It also describes:

• Configuring the configuration file parameters.

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

2.0 File System Scanner Agent Configuration

This section describes how to configure the File System Scanner Agent, 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.

2.1 The File System Scanner Agent Configuration File

The File System Scanner Agent (fortanix-fs-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 Fortanix On-premises scanner (fortanix-scanner).

The File System Scanner Agent 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:

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 3.0: 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 3.0: TLS Configuration Help Script.

• host: Specifies the IP address of the Fortanix On-premises Scanner.

• port: Specifies the port used for communication with the Fortanix On-premises Scanner. Ensure this is the same port specified in the Fortanix On-premises Scanner Configuration File.

NOTE

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

For information on running the File System Scanner Agent on Linux and Windows, refer to File System Scanner Agent Configuration.

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

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