How to Sanitize Agents

About Agent Sanitization

Sanitizing an Agent clears the local state files it uses to track policies, tasks and scan progress, then restarts the endpoint service so those files are rebuilt from scratch.

It is the standard recovery step when a Spirion Windows Agent has become stuck in a bad local state — for example when policies stop arriving or a scan will not leave a failing state.

When to Sanitize an Agent

Sanitize an agent when it is running but behaving incorrectly. For example, you may want to sanitize Agents when:

• Policies are not arriving to the Agent
• When a scan is stuck in a failing state

Requirements

• Spirion Windows Agents only. The paths and services in this article are Windows-specific.
• Local administrator rights on the endpoint. The PowerShell script exits immediately if it is not run elevated.
• Local or remote access to the endpoint itself. This is not a Console-side operation — every step runs on the Agent machine itself.

Impact

• Any scan currently running on the endpoint is terminated and its progress is lost.
• The agent re-requests its policy from the Console after the service restarts, so allow a polling interval before judging whether the fix worked.
• Sanitizing does not uninstall the agent, unregister it from the Console, or remove its endpoint identity. The agent returns as the same endpoint.

Note: Sanitizing addresses local state corruption. If the Agent cannot reach the Console at all, the problem is communication-related rather than the state of the Agent itself — check the EPS logs first. See How to Read a Log File.

What Sanitizing Does

The procedure stops the Windows Agent processes, deletes a specific set of local working directories and databases, and restarts the service.

Every item removed is regenerated automatically on restart — nothing here holds configuration you need to preserve.

• Tasks and TasksMonitor — queued and in-flight task state.
• ScanProgress — per-scan progress tracking. This is what pins a scan in a failing state.
• MCData and AdminData — cached management and administrative data from the Console, including policy material.
• jobQueueLocal.db — the local job queue.
• DistributedSearchInfo.db — distributed search / discovery team assignment state.

Because the cached policy data in MCData and AdminData is discarded, the Agent is forced to pull fresh policy from the Console — which is precisely why sanitizing resolves the “policies not arriving” symptom.

How to Sanitize a Windows Agent using PowerShell

• The easiest way to sanitize an agent is via a PowerShell script
• Run this script from the Windows PowerShell ISE

The quickest method is the attached script, SanitizeAgent_13.6.1.ps1, which is available from the help.archtis.com article How to Sanitize Windows Agents (requires login). Run it from the PowerShell ISE, which is present on any Windows installation.

1. Copy SanitizeAgent_13.6.1.ps1 to the endpoint.
2. Open PowerShell ISE as Administrator. The script checks for elevation and exits if it is not running as an administrator.
3. Open the script and run it.
4. Confirm the services are running again—see How to Verify the Agent Recovered.

Caution: as written, the script calls Set-ExecutionPolicy -ExecutionPolicy Bypass without a -Scope parameter, which changes the execution policy persistently rather than only for the current session. If your environment manages execution policy centrally, run the script with -Scope Process instead, or remove that line and launch PowerShell with powershell.exe -ExecutionPolicy Bypass -File SanitizeAgent_13.6.1.ps1.

What the Script Does and Does Not Cover

The script is not a complete equivalent of the manual procedure. It covers the five working directories, but it does not remove the two database files.

The script does:

• Verify it is running elevated, and exit if it is not running.
• Stop the processes IdentityFinderCmd, IdentityFinder and idfEndpoint.
• Stop the service IdentityFinderService.
• Delete MCData, Tasks, TasksMonitor, ScanProgress and AdminData.
• Delete the directories %TEMP%\IDFTmpDir and C:\Windows\Temp\IDFTmpDir\IdentityFinderCmd.
• Start the services IdentityFinderService and IdentityFinderEndpointService.

The script does not:

• Delete the databases jobQueueLocal.db and DistributedSearchInfo.db.
• Stop the process idfServicesMonitor.

Therefore: If the symptom involves a stuck job queue or a distributed search / discovery team problem, run the script and then delete the two database files manually using the steps in "How to Manually Sanitize Agents," below — or perform the manual procedure in full.

Note also that the script removes the IDFTmpDir temporary directories, which the manual procedure explicitly says are not necessary to delete. This is harmless but means the two methods do not produce identical results.

How to Manually Sanitize Agents

When running a PowerShell script is not an option, manually sanitize a Windows Agent. Use the steps below:

Step 1: Stop the Agent processes

Procedure:

1. Navigate to the local agent machine.
2. Open the Task Manager.
3. Go the Processes tab.
4. KILL the following processes by selecting each process and then pressing the Delete key on the keyboard or selecting "End task":
5. • Identity Finder Endpoint Service (blue arrows in the screenshot below)
   • Identity Finder idfServicesMonitor (blue arrows in the screenshot below)
     
     
   • Conditional steps:
   • 1. If it is running, Identity Finder Command Line process
     2. If there were previous Shipper or RMQ connection issues, KILL the process IdentityFinderService (red arrow in the screenshot above) as well

Step 2: Clear the working directories

Proedure:

1. Open the Windows File Explorer.
2. Navigate to the following directory: C:\ProgramData\Identity Finder 
3. DELETE all files in the following directories:
4. • Tasks
   • TasksMonitor
   • ScanProgress
   • MCData
   • AdminData
     
     

Step 3: Delete the local job queue database

Procedure:

1. Navigate to the directory C:\ProgramData\Identity Finder\Application\LocalSearch 
2. Delete the database file jobQueueLocal.db.

Step 4: Delete the distributed search database

Procedure:

1. Navigate to C:\ProgramData\Identity Finder\Application\Console\DistributedSearchInfo 
2. Delete the database file DistributedSearchInfo.db.

Step 5: Restart the endpoint service

Procedure:

1. Go back to the Task Manager.
2. Select the "Services" tab.
3. START the service IdentityFinderEndpointService.
4. 1. Identity Finder idfServicesMonitor service will start automatically
      
      
   2. IF the IdentityFinderService was previously stopped, this service must be restarted manually
4. Any directories or deleted databases are automatically recreated/regenerated when the service IdentityFinderEndpointService restarts.

*** Unless there are issues shredding temp files, or the directory is full and consuming a lot of memory, there is no need to delete the the directory IDFTmpDir or anything in it, and there is no need to delete anything in the directory boost_interprocess***

How to Verify the Spirion Agent Recovered

1. In Task Manager's Services tab, confirm IdentityFinderEndpointService and IdentityFinderServicesMonitor are running and have PIDs assigned.
2. Confirm the deleted directories nested under C:\ProgramData\Identity Finder have been recreated.
3. Check the most recent EPS log for a fresh Endpoint service started entry with no errors following it. See How to Read a Log File.
4. Allow at least one polling interval, then confirm on the console (in SDP) that the endpoint's heartbeat has updated and that policy has been delivered.

Tip: If the Agent still does not receive the policy after sanitizing, the problem is not local state. Move to communication troubleshooting.

What Not to Delete

Unless you are specifically dealing with problems shredding temporary files or the directory has grown large enough to consume significant disk space, there is no need to delete:

• IDFTmpDir, or anything inside it
• Anything in the boost_interprocess directory

Likewise, leave Certificates, Logs, Profiles and ErrorReports in place.

Deleting Logs in particular destroys the diagnostic history you are likely to need if the sanitize does not resolve the issue.