Sentinel Troubleshooting

Agent Not Running

Problem: Sentinel Agent icon not in system tray / not monitoring

Solution:

1. Check if installed: Programs → Sentinel Agent listed
2. Restart service:
   • Windows: Services → Restart “Sentinel Agent”
   • macOS: Killall Sentinel Agent, relaunch
   • Linux: sudo systemctl restart sentinel-agent
3. Check logs for errors (see Logs section below)
4. Reinstall if needed: Uninstall → Download → Reinstall

Not Connecting to Cloud

Problem: Agent shows “Not Connected” or “Offline”

Solution:

1. Check Internet: Open browser, confirm internet works
2. Check Firewall: Sentinel needs outbound HTTPS (443)
   • Windows: Firewall → Allow Sentinel through
   • macOS: Check System Preferences → Security
3. Check Proxy: If behind proxy, configure:
   • Windows: Settings → Proxy settings
   • Linux: Edit /etc/truthvouch/sentinel/config.yaml

   network:
     proxy:
       host: "proxy.company.com"
       port: 8080

4. Test Connectivity:

   curl -I https://api.truthvouch.io
   # Should respond with HTTP 200

Not Monitoring Tools

Problem: ChatGPT/Claude usage not appearing in dashboard

Solution:

1. Verify monitoring enabled:
   • Windows: Settings → Monitoring → ChatGPT ✓
   • Edit config: "monitor_chatgpt": true
2. Confirm tool running: Open ChatGPT in browser
3. Check if blocked by other software:
   • Antivirus might block monitoring
   • Browser extension might interfere
4. Clear browser cache: Settings → Clear browsing data
5. Restart Sentinel Agent

High CPU or Memory Usage

Problem: Sentinel using >30% CPU or >500MB RAM

Solution:

1. Disable Screenshots: Reduce to RAM usage

   monitoring:
     capture:
       screenshots: false

2. Reduce Log Verbosity:

   logging:
     level: "warn"  # Instead of "debug"

3. Disable Unused Features:

   monitoring:
     file_access: false  # If not needed
     browser_history: false

4. Restart: sudo systemctl restart sentinel-agent

Permissions/Access Denied

Problem: “Administrator access required” or “Permission denied”

Solution:

1. Windows: Run as Administrator
   • Right-click executable → Run as Administrator
   • Or: Settings → Run as administrator
2. macOS: Grant Full Disk Access
   • System Preferences → Security & Privacy
   • Add Sentinel to Full Disk Access list
3. Linux: Use sudo for installation

   sudo apt install sentinel-agent  # Not apt install

DLP Not Blocking

Problem: Sensitive data not being blocked

Solution:

1. Verify DLP Enabled:

   dlp:
     enabled: true

2. Check Patterns:

   dlp:
     patterns:
       credit_card: true
       ssn: true
       api_key: true

3. Test Pattern: Try exact pattern from config

   • If pattern uses \d{3}-\d{2}-\d{4}, test with 123-45-6789

4. Check Exemptions: Pattern may be exempted

   • Review DLP Exceptions in dashboard

5. Refresh Policy: Force sync

   • Windows: sentinel-agent --sync-policies
   • Linux: sentinel-agent --sync-policies

Policy Not Applying

Problem: Tool whitelist/blacklist not enforced

Solution:

1. Check Deployment: Dashboard → Sentinel → Policies
   • Status should show “Deployed”
2. Check Scope: Policy applies to your user/department
   • Go to Policy → Edit → Scope
3. Force Policy Sync:
   • Windows: C:\Program Files\TruthVouch\sentinel.exe --sync-policies
   • Linux: sentinel-agent --sync-policies
4. Restart Agent:
   • Windows: net stop truthvouch-sentinel && net start truthvouch-sentinel
   • Linux: sudo systemctl restart sentinel-agent

Logs Won’t Upload

Problem: Logs stuck in queue, not reaching dashboard

Solution:

1. Check Connection: Ensure connected to internet
2. Check Endpoint: Verify API endpoint reachable

   curl -I https://api.truthvouch.io/health
   # Should return HTTP 200

3. Force Upload:
   • Windows: sentinel-agent --upload-now
   • Linux: sentinel-agent --upload-now
4. Clear Queue (if stuck):

   # Windows
   del "%ProgramData%\TruthVouch\Sentinel\queue\*"
   
   # Linux
   sudo rm -f /var/lib/truthvouch/sentinel/queue/*

5. Restart: Agent will resume normal operation

Installation Failed

Problem: “Installation failed” or installer won’t run

Solution:

1. Windows:

   • Run as Administrator
   • Disable antivirus temporarily
   • Restart computer, try again
   • Download fresh copy (no corrupt file)

2. macOS:

   • Check quarantine: xattr ~/Downloads/Sentinel*.dmg
   • Remove quarantine: xattr -d com.apple.quarantine ~/Downloads/Sentinel*.dmg
   • Try manual install:

     sudo installer -pkg Sentinel*.pkg -target /

3. Linux:

   • Check dependencies: dpkg --audit
   • Install missing: sudo apt --fix-broken install
   • Try manual: sudo dpkg -i sentinel-agent*.deb --force-all

Agent Crash/Hanging

Problem: Sentinel process crashed or unresponsive

Solution:

1. Force Kill:

   • Windows: taskkill /IM sentinel-agent.exe /F
   • macOS: killall -9 Sentinel\ Agent
   • Linux: sudo killall -9 sentinel-agent

2. Check Crash Logs:

   • Windows: C:\ProgramData\TruthVouch\Sentinel\logs\crash.log
   • macOS: ~/Library/Logs/TruthVouch/crash.log
   • Linux: /var/log/truthvouch/crash.log

3. Restart Cleanly:

   • Windows: net start truthvouch-sentinel
   • Linux: sudo systemctl start sentinel-agent

4. If Still Crashing:

   • Reinstall agent
   • Contact support with crash logs

Logs & Debugging

View Logs

Windows:

# Real-time logs
Get-Content C:\ProgramData\TruthVouch\Sentinel\logs\agent.log -Tail 100 -Wait

# Or open in notepad
notepad C:\ProgramData\TruthVouch\Sentinel\logs\agent.log

macOS/Linux:

# Real-time logs
tail -f ~/.truthvouch/sentinel/agent.log

# Or system logs
journalctl -u sentinel-agent -f

Enable Debug Logging

# /etc/truthvouch/sentinel/config.yaml or config.json
logging:
  level: "debug"

# Restart
sudo systemctl restart sentinel-agent  # Linux
net stop truthvouch-sentinel && net start truthvouch-sentinel  # Windows

Collect Diagnostics

Create support bundle:

# Windows
C:\Program Files\TruthVouch\sentinel.exe --diagnostics --output=diagnostic-bundle.zip

# Linux
sentinel-agent --diagnostics --output=diagnostic-bundle.zip

Upload to support team.

Common Error Messages

Error	Cause	Fix
”Certificate verification failed”	SSL issue	Update CA certificates, check date/time
”Failed to connect to API”	Network blocked	Check firewall, proxy settings
”Policy sync failed”	Connection issue	Check internet, retry manually
”DLP pattern invalid”	Regex error	Fix regex syntax in config
”Permission denied”	Admin rights	Run as admin or use sudo

Still Having Issues?

1. Collect Info:

   • OS and version
   • Sentinel version: sentinel-agent --version
   • Logs (last 100 lines)
   • Diagnostic bundle (see above)

2. Contact Support:

   • Email: support@truthvouch.io
   • Dashboard: Help → Contact Support
   • Provide diagnostic bundle

Related Topics

• Sentinel Overview
• Installation
• Configuration