MS SQLServer Database Sensor User Guide

The MS SQL Server Database Sensor User Guide provides instructions for deploying and operating the MS SQL Server Database Sensor within the Keyfactor AgileSec Platform. This guide covers prerequisites, authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, data flows, incremental scanning, and auto-resolution.

Overview

The MS 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, this sensor 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 

Prerequisites

SQLServer Database Sensor Requirements

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

Remote Execution Requirements

If running the unified sensor remotely using CLI:

Authentication Methods

When executing scans through the Keyfactor AgileSec web UI, the Sensor utilizes SQL database username and password authentication.

Otherwise, the MS SQL Server Database Sensor utilizes an AgileSec Remote Sensor Token and EDR IDs to authenticate requests to the AgileSec Ingestion Service.

Generate a Remote Sensor Token

The Remote Sensor Token is required when running the Unified Sensor via the Unified Sensor CLI. This token is added 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 this token, 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 allowing 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 to limit blast radius and simplify 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:

1. Platform Scan Execution: Configure and execute scans directly though the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. CrowdStrike workflow:

   1. Deploy and Execute the sensor through a CrowdStrike workflow.

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

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

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

1.1 Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select MSSQL Sensor

2.1 Click the "Choose a Sensor" button.

2.2 Browse or search for “MSSQL”

2.3 Click on the MSSQL sensor card.

This will open the sensor configuration interface.

Step 3: Configure Sensor Parameters

3.1 Fill in the required configuration parameters:

Platform Scan Configuration Fields

CrowdStrike Workflow

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

1. Upload the Sensor Package to CrowdStrike.

2. Create Sensor Scripts

3. Create and Execute Run Sensor Workflow

4. Create and Execute Un-deploy Workflow

Upload the Sensor Package to CrowdStrike

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

Create Sensor Scripts

Create scripts to perform the follow tasks:

1. Check whether the Sensor Zip Exists

2. Run the Sensor

3. Un-deploy the Sensor

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

1.1 In CrowdStrike, on the Response scripts and files screen, select the Custom scripts tab, then click Create script.

1.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 2: Create a Script to Run the Sensor

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

2.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 3: Create a Script to Un-deploy the Sensor

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

Create and Execute the Run Sensor Workflow

Step 1: Create a Run SQL Server Database Sensor Workflow

1.1 Navigate to Fusion SOAR -> Workflows, then click Create workflow to open the CrowdStrike workflow builder interface. 

1.2 In the Create workflow dialog, select Create workflow from scratch.

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

1.4 On the workflow builder, click Action.

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

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

• Device status: all

• Host group: as defined in your environment

1.7 On the workflow builder, add a Loop after Device Query.

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

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

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

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

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

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

• Parameter: Platform

• Operator: is equal to

• Value: Windows

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

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

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

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

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

• Parameter: SensorZipExists

• Operator: is equal to

• Value: True

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

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

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

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

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

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

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

1.26 Configure the action kf-agilesec-run-mssql-sensor-windows using information from Step 1.21.

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

1.28 Click Publish, then in the Publish workflow dialog click Publish workflow. When you are ready to active the workflow, toggle Status to on.

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

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

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

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

• Users 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 remove the sensor 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 un-deploy workflow and configuration details.

Step 1: Create Un-deploy workflow

Follow the same instructions used to create the Run Sensor Workflow, but:

• Use Trigger On-demand only

• Use specific actions and script file kf-agilesec-undeploy-sensor-windows for the true branch of the check Windows platformcondition.

Step 2: Execute the 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 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 possessing 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:

Contact Support:

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