Fortanix Key Insight - On-Premises Scanner Integration With HashiCorp Vault

  • Updated on Apr 25, 2025
  • Published on Oct 8, 2024
  • 6 minute(s) read
Prev Next

1.0 Introduction

This article describes the steps needed to effectively integrate Fortanix Key Insight’s on-premises scanning capabilities with HashiCorp Vault.

HashiCorp Vault provides a centralized system for managing secrets and encrypting keys. By integrating it with Fortanix Key Insight, you can leverage Vault’s secure storage and management capabilities while benefiting from Key Insight’s advanced scanning and monitoring features.

2.0 Prerequisites

Before starting the integration, ensure you have:

  • Fortanix Key Insight Account: Access to Fortanix Key Insight with appropriate permissions.

  • HashiCorp Vault Installation: An operational instance of HashiCorp Vault, either installed on-premises or managed by HashiCorp.

  • Administrative Privileges: Access to administrative interfaces for both Fortanix Key Insight and HashiCorp Vault.

For information on configuring the on-premises scanner and getting started with Fortanix Key Insight, please refer to the Fortanix Key Insight - Getting Started with On-Premises Connection.

3.0 Install On-Premises Scanner

For details on how to install an on-premises scanner, refer to the Fortanix Key Insight-Getting Started with On-Premises Connection.

4.0 Configure On-Premises Scanner

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 or Fortanix DSM On-Premises connection details page. For more details, refer to the 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 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) (URLs and query credentials.

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

Refer to the following sample configuration file:


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

Here,

  • The fortanix-scanner is set up to scan three databases, with their credentials stored in the environment variables DB1_USERNAME, DB1_PASSWORD, DB2_USERNAME, DB2_PASSWORD, DB3_USERNAME, and DB3_PASSWORD.

  • The API key required for authenticating with Fortanix Key Insight is available in the environment variable ARMOR_API_KEY_1 .

  • The API key and certificate required for authenticating with Fortanix DSM on-prem environment are available in the environment variables DSM_APP_AUTH_KEY and DSM_APP_AUTH_CERT , respectively.

NOTE

  • Paths specified in the configuration file are relative /opt/fortanix/scanner/bin 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.

5.0 Integrate On-Premises Scanner with HashiCorp Vault

If you utilize HashiCorp Vault for managing credentials, you should use the vault-agent to retrieve credentials from the Vault and inject them as environment variables into the fortanix-scanner.

In this integration, the vault-agent must be configured to execute the fortanix-scanner, as outlined in the Vault Agent's Process Supervisor Mode.

Refer to the sample configuration file in the Section 4.0: Configure On-Premises Scanner.

Refer to the following code sample to configure the vault-agent:

auto_auth {
  method {
  ...
  }
}
template_config {
  static_secret_render_interval = "..."
  exit_on_retry_failure         = true
  max_connections_per_host      = 10
}
vault {
  address = "https://<vault uri>"
}
env_template "ARMOR_API_KEY_1" {
  contents             = "{{ with secret \"path/to/secret1\" }}{{ 
.Data.data.apikey }}{{ end }}"
   error_on_missing_key = true
}
env_template "ARMOR_API_KEY_2" {
  contents             = "{{ with secret \"path/to/secret2\" }}{{ 
.Data.data.apikey }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB1_USERNAME" {
  contents             = "{{ with secret \"path/to/db1/cred\" }}{{ .Data.username }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB1_PASSWORD" {
  contents             = "{{ with secret \"path/to/db1/cred\" }}{{ .Data.password }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB2_USERNAME" {
  contents             = "{{ with secret \"path/to/db2/cred\" }}{{ .Data.username }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB2_PASSWORD" {
  contents             = "{{ with secret \"path/to/db2/cred\" }}{{ .Data.password }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB3_USERNAME" {
  contents             = "{{ with secret \"path/to/db3/cred\" }}{{ .Data.username }}{{ end }}"
   error_on_missing_key = true
}
env_template "DB3_PASSWORD" {
  contents             = "{{ with secret \"path/to/db3/cred\" }}{{ .Data.password }}{{ end }}"
   error_on_missing_key = true
}
exec {
  command                   = ["/path/to/fortanix-scanner", "start", "-c", "/path/to/fortanix-scanner-config.yaml"]
  restart_on_secret_changes = "always"
  restart_stop_signal       = "SIGTERM"
}

  • During the integration, the vault-agent will read and inject secrets specified in the env_template blocks as environment variables into the child process defined in the exec block, with the name fortanix-scanner. These environment variables will be accessible only to the fortanix-scanner.

  • The vault-agent will wait until all environment templates are rendered before starting the child process.

  • The vault-agent will refresh the environment variables whenever it detects an update to the injected secrets. The fortanix-scanner should ensure it reads all configured environment variables before initiating a scan to obtain the latest credentials.

  • The vault-agent will terminate when the fortanix-scanner stops running. It is your responsibility to detect this and restart the vault-agent if needed.

6.0 Verify Scanner Operation

After the integration, perform the following steps to verify the scanner operation:

  1. Ensure the scanner is configured to fetch and use environment variables before starting a scan.

  2. Run a test scan on the command line to verify that the fortanix-scanner correctly picks up the environment variables set by the vault-agent.

  3. Add an on-premises scanner on the Fortanix Key Insight user interface (UI). For more details, refer to the Fortanix Key Insight - Getting Started with On-Premises Connection.

After the scanner is added and the resources have been successfully scanned, the new on-premises connection will be added to the ON-PREMISES tab on the Fortanix Key Insight user interface (UI) Connections page.

After you complete the configuration and scan your on-premises resources, you can view the discovery and assessment results in the Fortanix Key Insight dashboard. For more information on the Key Insight on-premises Overview page and its features, refer to the Fortanix Key Insight- On-Premises User Interface Components.