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

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 -Section 4.2.2: On-premises Scanner Installation.

4.0 Configure On-Premises Scanner

After the scanner package installation, you must configure the package with the connection ID, API key, and database (DB) credentials.

The fortanix-scanner is the on-premises scanner executable. The current version supports scanning databases and takes the path to a .yaml configuration file as a command-line argument, as shown below:

$ 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. To facilitate integration with a secrets manager, the scanner can be configured to read database credentials from either an environment variable or a separate credentials file.

Refer to the following sample configuration file:

# Config file
fortanix:
  url: 'https://armor.fortanix.com'
  connection_id: 2b6427fb-f19a-46e9-aa56-3293a218d917
  credential:
    type: apikey
    apikey:
      env_var: FORTANIX_API_KEY
databases:
  - uri: "mssql://host1:port"
    username:
      env_var: "DB1_USERNAME"
    password:
      env_var: "DB1_PASSWORD"
  - uri: "mssql://host2:port"
    username:
      env_var: "DB2_USERNAME"
    password:
      env_var: "DB2_PASSWORD"      
  - uri: "mssql://host3: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 FORTANIX_API_KEY.

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.

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 "FORTANIX_API_KEY" {
  contents             = "{{ with secret \"path/to/secret\" }}{{ 
.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 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.

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

   

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