Fortanix Key Insight - On-Premises Configuration for Scanning

1.0 Introduction

This article describes the minimum configuration requirements for Fortanix Key Insight to successfully scan keys and resources in an on-premises or Fortanix Data Security Manager (DSM) on-premises connection.

2.0 Terminology References

For On-Premises connection terminologies, refer to Fortanix Key Insight Concepts and Fortanix Key Insight for On-Premises Concepts.

3.0 Scanning Permissions

For detailed information on on-premises connection scanning permissions, refer to Fortanix Key Insight - 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

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

• Network

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

  • armor.fortanix.com on port 443

  • Databases on their configured ports

  NOTE

  The on-premises scanner does not expose any ports.

• Configuration File

  The on-premises scanner requires a configuration file that includes a list of databases 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

You must install the on-premises scanner package to manage your databases and Fortanix DSM on-premises keys and resources.

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 6.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 7.0: On-Premises Scanner Execution.

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

After installing the scanner package, you must configure it with the following information:

• For database scanning: Connection ID, API key, and database credentials. You can obtain the connection ID and API key from the On-Premises connection details page. For more information, refer to Fortanix Key Insight - Getting Started With On-Premises Connection.

• For Fortanix DSM on-premises environment scanning: Connection ID, API key, and Fortanix DSM credentials, such as the admin application (app) ID and certificates.

The fortanix-scanner is the on-premises scanner executable. The current version supports scanning databases and Fortanix DSM on-premises keys. It requires the path to .yaml configuration file as a command-line argument:

$ fortanix-scanner -c /path/to/config.yaml

NOTE

The configuration file is processed in the order they are provided.

The scanner configuration file includes:

• Credentials for authenticating with Fortanix Key Insight.

• A list of databases, including their Uniform Resource Identifiers (URIs) and query credentials (username and password).

• Credentials for authenticating with Fortanix DSM on-premises environment.

To facilitate integration with a secrets manager, the scanner can be configured to read all the credentials from either an environment variable or a separate credentials file.

1. Sample configuration file:

   armor:
     url: 'https://armor.fortanix.com'
   connections:
     - connection_id: 9d4c54e0-ba56-481b-8d19-36f70f71af87
       credential:
         type: apikey
         apikey:
           value: ...
       dsm:
         url: 'https://onprem.dsm.host'
         app_id: <Uuid>
         credential:
           type: certificate
           authentication_key:
             value: ...
           authentication_cert:
             value: ...
     - connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
       credential:
         type: apikey
         apikey:
           value: ...
       databases:
         - uri: 'oracle://host:port/db'
           username:
             value: ...
           password:
             value: ...
         - uri: 'mssql://host:port'
           username:
             value: ...
           password:
             file: ...
         - uri: 'mssql://host:port'
           username:
             value: ...
           password:
             value: ...

2. Sample configuration file where Fortanix credentials are read from environment variables:

   armor:
     url: 'https://armor.fortanix.com'
   connections:
     - connection_id: 9d4c54e0-ba56-481b-8d19-36f70f71af87
       credential:
         type: apikey
         apikey:
           env_var: ARMOR_API_KEY_1
       dsm:
         url: 'https://onprem.dsm.host'
         app_id: <Uuid>
         credential:
           type: certificate
           authentication_key:
             env_var: DSM_APP_AUTH_KEY
           authentication_cert:
             env_var: DSM_APP_AUTH_CERT
     - connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
       credential:
         type: apikey
           apikey:
           env_var: ARMOR_API_KEY_2
       databases:
         - uri: 'oracle://host:port/db'
           username:
             env_var: DB1_USERNAME
           password:
             env_var: DB1_PASSWORD
         - uri: 'mssql://host:port'
           username:
             env_var: DB2_USERNAME
           password:
             env_var: DB2_PASSWORD
         - uri: 'mssql://host:port'
           username:
             env_var: DB3_USERNAME
           password:
             env_var: DB3_PASSWORD

NOTE

• The paths specified in the configuration file are relative to /opt/fortanix/scanner/bin directory by default.

• If the configuration file has duplicate database URIs, the last specified URI and its associated credentials will override any previous entries.

• If you are using the older configuration file (prior to the KI 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 Fortanix Key Insight - On-Premises Scanner Integration with Hashicorp Vault for on-premises scanner configuration.

7.0 On-Premises Scanner Execution

Refer to the following sections to initiate the scanner for various databases:

NOTE

Any database information in the configuration file that is not relevant to the specified scan type (Oracle, MSSQL, or Fortanix DSM On-Premises Environment) will be ignored during the scanning process.

7.1 Scan Oracle Only

1. Perform the following steps to install the Oracle Instant Client package: This will help you to connect to the Oracle database from the scanner.

   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

2. Run the following command to start the scanner:

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

   Or

   The fortanix-oracle-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-oracle-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

   $ sudo systemctl enable fortanix-oracle-scanner
   $ sudo systemctl start fortanix-oracle-scanner

7.2 Scan MSSQL Only

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

Or

The fortanix-mssql-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-mssql-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

$ sudo systemctl enable fortanix-mssql-scanner 
$ sudo systemctl start fortanix-mssql-scanner 

7.3 Scan Fortanix DSM On-Premises Environment Only

Run the following command to start the scanner:

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

Or

The fortanix-dsm-scanner can be run as a systemd service. A sample unit file is provided at /opt/fortanix/scanner/conf/fortanix-dsm-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

$ sudo systemctl enable fortanix-dsm-scanner 
$ sudo systemctl start fortanix-dsm-scanner 

7.4 Scan All

Perform the following steps to scan Oracle, MSSQL, and/or Fortanix DSM on-premises environment keys and resources:

1. Refer to Step 1 from Section 7.1: Scan Oracle Only to install the Oracle client libraries.

2. Run the following command to start the scanner:

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

   Or

   The fortanix-scanner can be run as a systemd service. A sample unit file is provided at  /opt/fortanix/scanner/conf/fortanix-scanner.service.example. Create a systemd unit file based on the example in /usr/lib/systemd/system/.

   $ sudo systemctl enable fortanix-scanner
   $ sudo systemctl start fortanix-scanner

8.0 Troubleshooting

When running the Fortanix Key Insight or Fortanix DSM On-Premises scanners on different Linux environments, you may encounter missing library errors.

wget http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2_amd64.deb
dpkg -i libssl1.1_1.1.1f-1ubuntu2_amd64.deb
apt-get install -f

apt-get update
apt-get install libaio-dev -y
ln -s /lib/x86_64-linux-gnu/libaio.so.1t64 /lib/x86_64-linux-gnu/libaio.so.1

wget https://yum.oracle.com/repo/OracleLinux/OL9/appstream/x86_64/getPackage/compat-openssl11-1.1.1k-3.el9.x86_64.rpm
dnf install ./compat-openssl11-1.1.1k-3.el9.x86_64.rpm -y

9.0 Limitations

Here are the known limitations of Oracle and MSSQL databases in terms of their encryption key management:

10.0 Additional References

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

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

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