File Based Discovery on Agent (ACC-V): Configuration and Troubleshooting GuideIssue This article explains how File Based Discovery operates on Agent Client Collector for Visibility (ACC-V), focusing on execution context, permission requirements, and common configuration issues. It provides a troubleshooting flowchart to diagnose why File Information is not collected despite policy execution Release Zurich and later versions. Resolution ## How File Based Discovery on Agent Works ### Policy Execution Flow 1. **Policy creation/publication** — File Based Discovery policy is defined in ACC-V (e.g., "Scan C:\Program Files\ for *.exe") 2. **Policy distribution** — Policy is sent to connected agents via MID Server or direct communication 3. **Agent-side execution** — ACC Agent receives policy, runs as its configured service account, and scans local directories 4. **File detection** — Agent finds files matching policy criteria and reports File Information (file path, version, size, etc.) back to instance 5. **CI reconciliation** — ServiceNow IRE reconciles reported files with installed software CIs ### Key Difference: Local vs Network - **Agentless:** MID Server has network permissions; scan succeeds or fails based on network share availability - **Agent:** ACC service has local OS permissions; scan succeeds or fails based on **the agent user's rights on the target host** --- ## Execution Context: Who Runs File Based Discovery? File Based Discovery is executed by the **ACC Agent service account**, which is one of: 1. **Local System** (recommended) 2. **servicenow** (custom domain or local user) 3. **Other service account** ### Why This Matters The agent's service account must have sufficient OS permissions on the target directories. If the account lacks permissions, the policy runs without error but produces no results. **Verification:** On the target Windows host: ``` Services > ACC Agent > Log On tab > This account: [Local System | servicenow | other] ``` If using **Local System**, permissions are typically not an issue (full OS access). If using a custom account, the account must have explicit **"List Folder Contents"** permission on scanned directories. --- ## Permission Requirements ### Windows File System Permissions For File Based Discovery to scan a directory, the **agent's execution user must have "List Folder Contents" (read + execute) permission** on the target directory. ### Verification Steps 1. **On the target host**, navigate to the directory to be scanned (e.g., `D:\Tools`) 2. **Right-click** → **Properties** → **Security** tab 3. **Select the agent user** (e.g., Local System, servicenow account) 4. **Click Edit** → **Advanced** 5. **Verify "List Folder Contents" is allowed** (enabled in the "Allow" column) ### Special Note: Everyone vs. Specific User - If the agent runs as **Local System** → Local System must have explicit permission - If **Everyone has read permission**, Local System inherits it (as part of "Everyone") - Best practice: Explicitly grant the agent user or Local System the needed permission ### Common Issue: Read-only is Not Enough "Read" permission alone is insufficient. The agent must be able to **list directory contents**, which requires: - **Read** + **Execute** on the directory - Or the combined "List Folder Contents" permission --- ## Policy Distribution Verification File Based Discovery runs as a **Background Policy** within ACC-V. Before troubleshooting file detection, verify the policy was distributed to the agent. ### Checking Agent Logs On the **target host** where ACC Agent is installed, check the agent-side logs: **Log locations:** - `C:\Program Files\ServiceNow\ACC\logs\agent.log` - `C:\Program Files\ServiceNow\ACC\logs\acc.log` **What to look for:** In these logs, search for File Based Discovery background policy execution: ``` [FileBasedDiscovery | Background Policy] [Policy received from instance] [Background check started] [Background check finished with status: 0] ``` - **Status 0** = execution succeeded (but does not guarantee files were found) - **Status non-zero** = execution failed (check for error messages) - **No log entries** = policy was not received by agent (distribution failure) ### If No Policy Log Entries 1. Check MID Server Sync status (ensure MID Server is connected) 2. Verify the policy is published in ACC-V console 3. Check network connectivity between MID Server and agent --- ## Configuration: Folders To Scan ### The Folders To Scan Setting The File Based Discovery policy includes a **"Folders To Scan"** setting, which lists the directories the agent will scan. **Location in UI:** - ACC-V console → Policies → File Based Discovery Policy → Edit → Folders To Scan **Example:** ``` C:\Program Files\ D:\ptc\ E:\Software\ ``` ### Common Pitfall: Empty or Wrong Paths File Based Discovery **executes successfully (status 0)** even if: - **No files are found** (returns empty results) - **Configured paths don't exist** on the target host - **Configured paths contain no matching files** If the policy runs but reports **no File Information**, the agent likely scanned paths where no software exists. ### Diagnosis: Checking What Was Scanned Look at the agent log output: ``` [Output: [ ]] <- Empty output ``` Empty output after successful execution (status 0) suggests: - Scanned directories had no matching files - Scanned directories don't exist - Agent lacked read permission (but logs may not always reflect this) --- ## Solutions: Getting File Based Discovery to Collect ### Option A: Add Actual Software Installation Paths **Best for:** Environments with predictable, known software install locations. **Steps:** 1. Identify where software is actually installed on the target host (e.g., `C:\Program Files\`, `D:\ptc\`) 2. In ACC-V File Based Discovery policy, add these paths to **Folders To Scan** 3. Republish the policy 4. Verify in agent logs that new paths appear in the background policy execution **Example:** ``` Folders To Scan: C:\Program Files\ C:\Program Files (x86)\ D:\ptc\ E:\Custom Apps\ ``` ### Option B: Enable Add SPATH Folders To Scan List (Recommended) **Best for:** Dynamic environments or when you want automatic standard-path coverage. **What SPATH does:** - Automatically scans standard software installation paths known to ServiceNow - Reduces need for manual path configuration - Covers common directories (Program Files, Program Files (x86), etc.) **Steps:** 1. In ACC-V File Based Discovery policy, locate **"Add SPATH Folders To Scan List"** 2. **Enable** the setting 3. Republish the policy 4. SPATH will automatically include standard Windows software paths **Benefit:** One-time configuration; scales to new software automatically. **Trade-off:** Slightly longer scan time (more directories checked), but provides broader coverage. --- ## Troubleshooting Flowchart ``` File Based Discovery not collecting File Information? ┌─ Agent service account correct (Local System or servicenow)? │ ├─ NO → Reconfigure service startup account │ └─ YES → Continue │ ├─ Target directories have "List Folder Contents" permission? │ ├─ NO → Grant permission to agent user on target directories │ └─ YES → Continue │ ├─ File Based Discovery Background Policy in agent logs? │ ├─ NO → Check MID Server sync, policy publication, republish policy │ └─ YES → Continue │ ├─ Policy execution status = 0 (success)? │ ├─ NO (error status) → Review error messages in agent log │ └─ YES → Continue │ ├─ Output is empty [ ]? │ ├─ YES → Check Folders To Scan paths (likely wrong or empty) │ │ │ ├─ Add actual software install paths, OR │ │ │ └─ Enable Add SPATH Folders To Scan List │ │ └─ Republish policy │ └─ NO → Files detected; verify file information in CMDB ``` --- ## Step-by-Step Troubleshooting Example **Scenario:** File Based Discovery policy runs (status 0) but no File Information collected. **Step 1: Verify execution context** ``` C:\Program Files\ServiceNow\ACC\logs\agent.log Search: Local System or servicenow user name in service startup context Expected: Local System or servicenow user running the policy ``` **Step 2: Check permissions** ``` On target host: - Right-click C:\Program Files\ → Properties → Security → Advanced - Verify Local System (or servicenow user) has "List Folder Contents" allowed ``` **Step 3: Verify policy distribution** ``` C:\Program Files\ServiceNow\ACC\logs\agent.log Search: "File Based Discovery Background Policy" Expected: "Policy received from instance", "Background check finished with status: 0" ``` **Step 4: Check scanning paths** ``` C:\Program Files\ServiceNow\ACC\logs\agent.log Search: "Folders To Scan:" or output section Expected: Paths listed and scanned (e.g., C:\Program Files\, D:\ptc\) Actual: D:\tools\WinShot, D:\tools\BGInfo (wrong paths) Action: Update Folders To Scan in policy and republish ``` **Step 5: Republish and verify** ``` ACC-V console: 1. Policies → File Based Discovery Policy 2. Edit Folders To Scan (add actual install paths or enable SPATH) 3. Save → Republish button 4. Wait for policy distribution to agent 5. Re-run background policy on agent 6. Check agent log for successful detection ``` --- ## Performance Considerations ### Scan Time vs Coverage - **Narrow scope (few paths)** — fast scans, may miss software - **Broad scope (many paths)** — slower scans, better coverage - **SPATH enabled** — automatic standard paths, moderate performance impact **Recommendation:** Balance coverage and performance based on your environment: - Small environments: Explicit paths (faster) - Large environments: SPATH enabled (maintenance-free) ### Running Background Policy Manually To test immediately without waiting for the scheduled interval: 1. ACC-V console → Policies → File Based Discovery Policy 2. **Check instance** related list → File Based Discovery 3. Click on File Based Discovery script 4. **Run** button (or equivalent, depending on UI version) 5. Check agent logs for execution result --- ## When File Based Discovery Succeeds (Expected Behavior) File Information collection is working correctly when: - ✅ Agent service account is Local System (or servicenow with proper permissions) - ✅ Policy is received and executed in agent logs (status 0) - ✅ Folders To Scan includes directories where software is actually installed - ✅ File Information appears in ServiceNow CMDB as discovered software CIs Example successful log: ``` [FileBasedDiscovery | Background Policy] [Background check started] [Scan path: C:\Program Files\] [Scan path: D:\ptc\] [Files found: 47] [Output: [C:\Program Files\app.exe, D:\ptc\library.dll, ...]] [Background check finished with status: 0] ``` Related Links - **KB1994337** — File Based Discovery through Agent (general reference)