MS SQLServer Database Sensor User Guide

The MS SQL Server Database Sensor User Guide provides instructions for installing, configuring, and running the SQL Server Database Sensor within the Keyfactor AgileSec Platform. It details sensor architecture, scan behavior, prerequisites, authentication requirements, and data processing workflows to support centralized discovery and analysis of database encryption and cryptographic assets.

Overview

The SQL Server Database Sensor queries SQL Server system views to determine the encryption state for all databases on the target SQL Server instance. For encrypted databases, it captures the encryption method and algorithm, along with Data Encryption Key (DEK) details. When Transparent Data Encryption (TDE) is enabled and protected by a certificate, the sensor also collects associated X.509 certificate metadata and other relevant cryptographic attributes. The sensor then sends these findings to Keyfactor’s AgileSec platform.

Key Features

• Instance-Wide Coverage: Scans all databases on the target SQL Server instance to determine encryption state and configuration.

• Encryption Discovery: Identifies whether databases are encrypted and captures the encryption method and algorithm (for example, TDE with AES-256).

• DEK Visibility: Collects Data Encryption Key (DEK) details, including key/protector attributes and related fingerprints where available.

• Certificate & X.509 Metadata (TDE): When TDE is certificate-protected, captures associated certificate metadata (subject/issuer, validity dates, and certificate fingerprints).

• Unified Sensor Integration: Runs as a Unified Sensor plugin and exports findings to Keyfactor’s AgileSec platform for centralized analysis and reporting.

• Read-Only Operation: Retrieves metadata via SQL Server system views and does not modify database configuration.

What Gets Scanned

The sensor queries the target SQL Server instance and evaluates all databases to identify encryption posture and related cryptographic assets, including:

• Database Encryption State: Whether each database is encrypted and its current encryption status.

• Encryption Method & Algorithm: Encryption type (for example, TDE) and configured algorithm (for example, AES-256).

• Data Encryption Key (DEK) Metadata: DEK creation details and protector information/fingerprints where available.

• TDE Protector Certificates: When TDE is certificate-protected, associated X.509 certificate metadata (subject/issuer, validity period, certificate fingerprints).

• Database Context: Key instance/database attributes used to contextualize findings 

Architecture and Data Flow

High-Level Architecture

The SQL Server Database Sensor runs as a Unified Sensor plugin and can be deployed on the same host as SQL Server or on a separate remote host with network connectivity to the target SQL Server instance. During execution, it authenticates to SQL Server using a group Managed Service Account (gMSA).

This section describes the end-to-end data flow, including the scan workflow executed by the Unified Sensor and the post-scan processing performed in the AgileSec platform.

Scan Flow

Scan Flow Description

• Authentication: Authenticates to SQL Server using Windows integrated authentication via a group Managed Service Account (gMSA). The sensor process must run under the gMSA security context (for example, as a Scheduled Task or service configured to run as the gMSA). 

• Query: Queries SQL Server system views to retrieve encryption configuration and related metadata, including DEK details and (when applicable) certificate information used for TDE protection.

• Enrich: The Unified Sensor Core processes raw results by: - Transformation: Normalizing scan output into a consistent schema for downstream processing. - Enrichment: Adding contextual metadata (for example, labels and source identifiers).

• Transmit: Sends the enriched results to the AgileSec Ingestion Service for centralized inventory, policy evaluation, and reporting.

Post-Scan Flow

Post-Scan Flow Description

• Scan: The Unified Sensor performs the scan as described in the previous sections.

• Send Findings: After the scan completes, the sensor transmits all discovered cryptographic findings to the AgileSec Platform, where they are stored in OpenSearch. New findings are initially marked with a Pending status.

• Execute Policies: The platform evaluates configured policies against the data in OpenSearch. Policies calculate a risk score for each finding and persist the score with the finding. Findings are then removed from pending status and assigned a score classification (for example, Compliant, High risk, Medium risk, or Low risk).

• Execute Processes: After policy evaluation, backend processes run to read findings from OpenSearch and perform post-processing activities such as de-duplication and auto-resolution.

Prerequisites

SQLServer Database Sensor Requirements

Before configuring the sensor to connect to the SQL Server instance, ensure the following requirements are met:

• SQL Server Version:

  • SQL Server 2016 - 13.x

  • SQL Server 2017 - 14.x

  • SQL Server 2019 - 15.x

  • SQL Server 2022 - 16.x

• Operating System: Windows Server 2016 or later.

• Sensor Deployment: The sensor must be installed on the same server where the SQL Server instance is running (for CrowdStrike-based deployments).

• SQL Server Network Configuration: SQL Server must be configured to accept TCP/IP connections on port 1433 (default). If SQL Server is listening on a custom port, specify it in the CrowdStrike workflow.

• Group Managed Service Account (gMSA): A gMSA must be created in Active Directory and configured with the necessary permissions to access the target SQL Server instance.

• SQL Server Permissions: The gMSA account must be granted the following server-level permissions:

GRANT VIEW SERVER STATE TO [<DOMAIN>\<gMSA_Account>$];

GRANT VIEW ANY DEFINITION TO [<DOMAIN>\<gMSA_Accoun>t$];

GRANT VIEW ANY DATABASE TO [<DOMAIN>\<gMSA_Account>$];

• Active Directory Domain: The server hosting the SQL Server instance must be joined to the same Active Directory domain where the gMSA is configured, or have a trust relationship with that domain.

• gMSA Retrieval Rights: The server’s machine account must be authorized to retrieve the gMSA password from Active Directory (configured via the gMSA’s PrincipalsAllowedToRetrieveManagedPassword attribute).

• AgileSec Platform TLS Trust (if using self-signed certificates): f the AgileSec Platform external URL uses a self-signed certificate (or a private CA), import the issuing root CA certificate into the Windows Local Computer trusted root certificate store on the host where the sensor runs. This ensures the sensor can establish TLS connections to the AgileSec Platform external endpoint.

Generate a Remote Sensor Token

The Remote Sensor Token is required when running the Unified Sensor via the CLI. This token is configured in the sensor YAML file (the token field) and is used to authenticate requests to the AgileSec Ingestion Service. A valid Remote Sensor Token is mandatory for the Unified Sensor to export findings and communicate with the AgileSec platform.

Generating a Remote Sensor Token

Step 1: Log in to the AgileSec Platform UI, navigate to Settings -> Access Tokens Settings, select the Remote Sensor Token tab, then click Generate Token.

Step 2: In the Generate Token dialog, enter the following information, then click Generate.

• Token Name: Any name you want to assign to the token

• Description: Optional description for the token

• Expiration Time: Token expiration timeframe

Step 3: Copy the newly generated token by clicking on the copy icon next to the token value. 

Caution: The token value is only available at the time of generation. After you close the dialog, the token cannot be copied or retrieved again. If you lose it, you must generate a new token.

Generate an EDR ID

An EDR ID is used by the Unified Sensor to obtain an access token for communicating with the AgileSec platform. This process is automatic: when the Unified Sensor runs, it presents the configured EDR ID to the Ingestion Service, which returns a Remote Sensor Token. The Unified Sensor stores this token locally and uses it for subsequent authenticated communication with the Ingestion Service.

EDR IDs provide an implicit trust mechanism that allows approved endpoints to obtain a Remote Sensor Token without embedding long-lived credentials on the host. EDR IDs can be revoked at any time to immediately block token issuance for endpoints using that ID.

You can generate multiple EDR IDs and assign them to specific deployments (for example, by environment, business unit, or endpoint group) rather than using a single EDR ID across all endpoints. This segmented approach is recommended because it limits blast radius and simplifies revocation and rotation when access needs to be restricted.

Generating an EDR ID

Step 1: Log in to the AgileSec Platform UI, navigate to EDR Management, then click Create EDR ID.

Step 2: In the Create EDR ID dialog, select your organization and click Generate.

Step 3: Copy the newly generated EDR ID by clicking the copy icon before the EDR ID.

Running the Sensor

The SQL Server Database Sensor can be executed using the following methods:

• CrowdStrike workflow:

  • Deploy and Execute the sensor through a CrowdStrike workflow.

  • Un-deploy the sensor: Run this workflow whenever a new version of the sensor package is released.

• Unified Sensor CLI: Run the Unified Sensor CLI using a SQL Server Database Sensor configuration. 

Running the Sensor using Crowdstrike workflow

Deploy and Execute the sensor

Follow these steps to deploy and execute the SQL Server Data Sensor using a CrowdStrike workflow.

Step 1: Download the Sensor Package

1.1 Download isg_sensor_windows_3.4.0_crowdstrike.zip from the Keyfactor download portal.

1.2 Extract the ZIP file. It contains a Crowdstrike directory with the scripts required to create the CrowdStrike workflow.

Step 2: Upload the Sensor ZIP to Crowdstrike

2.1 Log in to CrowdStrike and navigate to Host setup and management → Response scripts and files.

2.2 Select the "put" files tab and click Upload file. In the dialog, choose isg_sensor_windows_3.4.0_crowdstrike.zip, then click Upload

Step 3: Create a Script to Check Whether the Sensor Zip Exists

3.1 On the Response scripts and files screen, select the Custom scripts tab, then click Create script.

3.2 In the Create script dialog, complete the following fields:

• Name: kf-agilesec-check-sensor-zip-windows

• Shell type: PowerShell

• Script access: Users with the role of RTR Administrator

• Share script with workflows: Enabled

• Script: Copy the contents of crowdstrike\scripts\kf-agilesec-check-sensor-zip-windows.ps1 from the extracted ZIP

• Input schema: Copy the contents of crowdstrike\scripts\kf-agilesec-check-sensor-input-windows.json from the extracted ZIP

• Output schema: Copy the contents of crowdstrike\scripts\kf-agilesec-check-sensor-output.json from the extracted ZIP

Step 4: Create a Script to Run the Sensor

4.1 On the Response scripts and files screen, select the Custom scripts tab, then click Create script.

4.2 In the Create script dialog, complete the following fields:

• Name: kf-agilesec-run-mssql-sensor-windows

• Shell type: PowerShell

• Script access: Users with the role of RTR Administrator

• Share script with workflows: Enabled

• Script: Copy the contents of  isg_agilescan_windows_sensor\crowdstrike\scripts\kf-agilesec-run-mssql-windows.ps1 from the extracted ZIP.

• Input schema: Copy the contents of  isg_agilescan_windows_sensor\crowdstrike\scripts\kf-agilesec-run-mssql-sensor-input.json from the extracted ZIP.

Step 5: Create a Script to Undeploy the Sensor

5.1 On the Response scripts and files screen, select the Custom scripts tab, then click Create script.

5.2 In the Create script dialog, complete the following fields:

• Name: kf-agilesec-undeploy-sensor-windows

• Shell type: PowerShell

• Script access: Users with the role of RTR Administrator

• Share script with workflows: Selected

• Script: Copy the contents of  isg_agilescan_windows_sensor\crowdstrike\scripts\kf-agilesec-undeploy-sensor-windows.ps1 from the extracted ZIP.

• Input schema: Copy the contents of  isg_agilescan_windows_sensor\crowdstrike\scripts\kf-agilesec-undeploy-sensor-input-windows.json from the extracted ZIP.

Step 6: Create a Run SQL Server database Sensor Workflow to Run the Sensor

6.1 Navigate to Fusion SOAR -> Workflows, then click Create workflow to open then Crowdstrike workflow builder interface. 

6.2 In the Create workflow dialog, select Create workflow from scatch.

6.3 In the Add trigger dialog, select Scheduled workflow and configure the execution schedule.

6.4 On the workflow builder, click Action.

6.5 In the Add action dialog, search for and select Device Query.

6.6 In the Device Query dialog, configure fields specific to your environment to select. the devices where teh SQL Server Database Sensor should run. At a minimum, the following are recommended:

• Device status: all

• Host group: 

6.7 On the workflow builder, add a Loop after Device query.

6.8 In the Start loop dialog, enter the following and click Next:

• Loop type: For each

• Loop source: Sensor IDs

• Processing order: At the same time/concurrently

• Continue workflow on loop iteration failure: Enabled

6.9 On the workflow builder, add an action inside the loop.

6.10 In the Add action dialog, search for and select Get device details.

6.11 In the Device details dialog, set Device ID to Sensor IDs instance, then click Next.

6.12 On the workflow builder, add a Condition after Get device details.

6.13 In the Condition dialog, enter the following and click Next:

• Parameter: Platform

• Operator: is equal to

• Value: Windows

6.14 On the workflow builder, add an action under the TRUE branch.

6.15 In the Add action dialog, search for and select the script kf-agilesec-check-sensor-zip-windows.

6.16 In the action configuration for kf-agilesec-check-sensor-zip-windows, enter the following recommended values and click Next:

• Device ID: Sensor IDs instance

• sensorDirectory: C:\Program Files\Keyfactor

• sensorZipFilename: isg_sensor_windows_3.4.0_crowdstrike.zip

6.17 On the workflow builder, add a Condition after kf-agilesec-check-sensor-zip-windows.

6.18 In the Condition dialog, enter the following and click Next:

• Parameter: SensorZipExists

• Operator: is equal to

• Value: True

6.19 On the workflow build, add an action under the TRUE branch.

6.20 In the Add action dialog, search for and select the script kf-agilesec-run-mssql-sensor-windows.

6.21 In the action configuration for kf-agilesec-run-mssql-sensor-windows, enter the following recommended values for your environment:

6.22 On the workflow builder, add an action under the ELSE branch for sensorZipExists.

6.23 In the Add action dialog, search for and select Put file.

6.24 In the Put file dialog, enter the following values and click Next:

• Device Id: Sensor IDs instance

• File name: isg_sensor_windows_3.4.0_crowdstrike.zip

• Destination directory path: ${data['KfAgilesecCheckSensorZipWindows.sensorDirectory']}

• Queue offline: true

6.25 On the workflow builder, add action kf-agilesec-run-mssql-sensor-windows (same as Step 6.20) under the Put file.

6.26 Configure the action kf-agilesec-run-mssql-sensor-windows using Step 6.21.

6.27 The workflow is now complete and should resemble the following:

6.28 Click Publish, then in the Publish workflow dialog click Publish workflow. Toggle Status to on now or later to activate the workflow.

Step 7: Execute the Run SQL Server database Sensor workflow and check the scan results

7.1. If your workflow trigger is on-demand, execute the workflow to test the sensor.

7.2. If your trigger is scheduled, wait for the configured interval for the sensor to run.

7.3. Check the scan output data

• A SQL server database scan is initiated on all machines included in “Device Query” action.

• Found findings are exported to the ingestion service.

• User can view scan history and results within the Keyfactor web application.

Un-deploying the Sensor

You may need to un-deploy the sensor to upgrade to a newer version or to remove it from an endpoint. The un-deployment workflow cleanly removes the deployed sensor components and associated execution artifacts so the sensor can be reinstalled or upgraded as needed.

Refer to the CrowdStrike Workflow Guide for Sensor Deployment, which includes the supported undeploy workflow and configuration details.

Step 1: Create Un-deploy workflow

Follow the same instruction used to create the "Run host sensor" workflow, but:

• Use Trigger On-demand only

• Use specific actions and script file “kf-agilesec-undeploy-sensor-windows” for true branch of check Windows platform condition

Step 2: Execute the created Un-deploy workflow

This step will remove the old package version on all machines included in “Device Query” action.

Running the Sensor using the Unified Sensor CLI

Use this method to configure and run the SQL Server Database Sensor via Windows Task Scheduler (or an equivalent mechanism) instead of deploying and executing it through a CrowdStrike workflow. This approach is intended for environments where you manage execution directly on the Windows host.

Authentication (gMSA only): The SQL Server Database Sensor supports Windows integrated authentication via a group Managed Service Account (gMSA). The Unified Sensor CLI must run under the gMSA security context. 

Execution options:
- Recommended: Run the sensor as a Scheduled Task configured to run as the gMSA.
- Interactive shell (only if permitted): If your SQL Server configuration allows the sensor host to authenticate locally using the currently logged-in Windows identity, you may run the CLI from a shell as a user identity that has the required SQL Server permissions.

Step 1: Create a Configuration File

Create a file named mssql.yml and populate it with the following example (update values to match your environment):

scan_config: plugins: - mssql - export
config:
  mssql:
    name: mssql
    plugin_config:
      app: "AgileSecSensor"
      log_level: "info"
      server: "127.0.0.1"
      port: 1433
      spn: ""          # Not currently supported. Leave empty
      trust: true      # Trust SQL Server TLS certificate (if applicable).
  export:
    name: export
    plugin_config:
      sensor_name: "SQL Server Database Sensor (admin)"
      sensor_type: "SQL Server Database Sensor"
      ran_by: "admin"
      url: "https://agilesec.kf-agilesec.com:8443"
      token: "${env:SENSOR_TOKEN}"
  settings: 
    log_level: "info" 
    allow_push: true 
    async_send: true

Configuration attributes descriptions:

Step 2: Run the Sensor

Run the Unified Sensor binary with your configuration file:

./unified_sensor_linux -c ./mssql.yml

Notes:

• Run context: Execute the CLI under a Windows identity that can authenticate to SQL Server and has the required permissions (gMSA via Task Scheduler is recommended for production).

• SQL Server target: Set server and port to the SQL Server instance you want to scan. If the sensor runs on the same host as SQL Server, 127.0.0.1:1433 is typically sufficient.

• AgileSec Platform TLS trust: If the External facing AgileSec platform url uses a self-signed certificate or private CA, import the issuing CA into the Windows Local Computer trusted root certificate store on the host where the sensor runs.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• Unified sensor version

Contact Support:

• Email: support@keyfactor.com

• Portal: https://support.keyfactor.com