Sentinel: Troubleshooting

Common issues and solutions for Sentinel Agent deployments across Windows, macOS, and Linux.

Installation Issues

Installation Fails or Hangs

Windows:

# Check Windows Installer logs
Get-EventLog -LogName "Application" -Source "MsiInstaller" -Newest 10

# Try repair install
msiexec /f sentinel-installer.msi /quiet /norestart

macOS:

# Check installer logs
log stream --predicate 'process == "Installer"' --level debug

# Try manual installation
sudo cp -r Sentinel.app /Applications/

Linux:

# Check apt/yum logs
sudo tail -100 /var/log/apt/history.log  # Ubuntu/Debian
sudo tail -100 /var/log/yum.log           # RHEL/CentOS

Insufficient Disk Space

# Check available disk space
df -h

# Windows
Get-Volume

# Required space
# Installation: 100MB
# Database + logs: 100MB minimum
# Total: 200MB minimum

Permission Denied

Windows:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
msiexec /i sentinel-installer.msi /quiet

macOS/Linux:

# Add user to required groups
sudo usermod -a -G adm,sudo sentinel
sudo chown -R sentinel:sentinel /var/lib/truthvouch/

Connectivity Issues

Cannot Connect to Cloud API

1. Test DNS resolution:

# Windows
nslookup api.truthvouch.io

# macOS/Linux
nslookup api.truthvouch.io

2. Test HTTPS connectivity:

# All platforms
curl -I https://api.truthvouch.io

# Windows PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest -Uri https://api.truthvouch.io

3. Check firewall:

# Windows
netstat -an | findstr 443

# macOS/Linux
netstat -an | grep 443
ss -tulpn | grep :443

4. Check proxy settings:

# config.yaml (if using proxy)
cloud:
  proxy_url: http://proxy.company.local:8080
  proxy_username: user
  proxy_password: pass

API Key Invalid or Expired

Verify API key:

# Windows PowerShell
$key = (Get-Content "C:\ProgramData\TruthVouch\Sentinel\config.yaml" | Select-String "api_key").Line
Write-Host $key

Regenerate API key:

1. Log into TruthVouch dashboard
2. Settings → API Keys
3. Revoke old key
4. Create new key
5. Update in config.yaml
6. Restart Sentinel

Timeout Errors

Increase timeout values:

cloud:
  request_timeout_sec: 60  # Default: 30

Policy Sync Issues

Policies Not Updating

Check last sync time:

# Windows PowerShell
$sync = (Get-Content "C:\ProgramData\TruthVouch\Sentinel\config.yaml").LastSync
Write-Host $sync

# macOS/Linux
grep "last_sync" ~/.truthvouch/sentinel/sentinel.db

Force immediate sync:

# Windows
sentinel.exe --sync-policy --force

# macOS/Linux
sentinel --sync-policy --force

Clear cache and resync:

# Windows
Remove-Item C:\ProgramData\TruthVouch\Sentinel\policies\* -Recurse

# macOS
rm -rf ~/.truthvouch/sentinel/cache/

# Linux
sudo rm -rf /var/lib/truthvouch/sentinel/policies/

Then restart Sentinel.

Policy Signature Verification Failed

Symptoms: Policies rejected, old policies continue in use

Causes:

• Corrupt policy file
• Man-in-the-middle attack
• Clock skew (system time incorrect)

Solutions:

# 1. Check system time
# Windows: Settings → Time & Language → Date & time
# macOS/Linux: date

# 2. Sync system time
# Windows (PowerShell as Admin)
W32tm /resync

# macOS
sudo sntp -sS time.nist.gov

# Linux
sudo ntpdate -s time.nist.gov

Performance Issues

High CPU Usage

Identify cause:

# Windows Task Manager
tasklist /v | findstr sentinel

# macOS Activity Monitor
top -o %CPU | grep sentinel

# Linux
top -p $(pidof sentinel)

Reduce monitoring scope:

monitoring:
  # Disable expensive features
  clipboard_monitoring: false
  network_monitoring: false

  # Monitor only specific tools
  tools:
    - name: "ChatGPT"
      enabled: true
    - name: "Unused Tool"
      enabled: false

Increase sync interval:

policy:
  sync_interval: 120  # 2 hours instead of 1

High Memory Usage

Check process memory:

# Windows
Get-Process sentinel | Select-Object WorkingSet64

# macOS/Linux
ps aux | grep sentinel

Reduce database size:

database:
  max_size_mb: 50  # Reduce from 100

advanced:
  offline_grace_period_days: 7  # Shorter retention

Check for memory leaks:

# Monitor over time
# Windows: Performance Monitor
# macOS/Linux: watch -n 1 'ps aux | grep sentinel'

If memory grows continuously, report to support with logs.

Slow Policy Evaluation

Increase timeout:

advanced:
  policy_check_timeout_ms: 500  # Default: 100

Check for regex issues: View config.yaml for complex DLP patterns. Simplify regex if needed.

Logging and Diagnostics

Enable Debug Logging

Windows:

# Edit config
(Get-Content "C:\ProgramData\TruthVouch\Sentinel\config.yaml") |
  ForEach-Object { $_ -replace 'level: INFO', 'level: DEBUG' } |
  Set-Content "C:\ProgramData\TruthVouch\Sentinel\config.yaml"

Restart-Service TruthVouchSentinel

macOS/Linux:

# Edit config
sudo sed -i 's/level: INFO/level: DEBUG/' /etc/truthvouch/sentinel/config.yaml

# Restart
sudo systemctl restart sentinel  # Linux
launchctl reload ~/Library/LaunchAgents/io.truthvouch.sentinel.plist  # macOS

View Logs

Windows:

# Event Viewer
eventvwr.msc

# PowerShell
Get-EventLog -LogName "Application" -Source "TruthVouch" -Newest 100

# Or file
Get-Content "C:\ProgramData\TruthVouch\Sentinel\logs\sentinel.log" -Tail 50

macOS:

log stream --predicate 'process == "sentinel"' --level debug

# File
tail -50 ~/.truthvouch/sentinel/logs/sentinel.log

Linux:

# Real-time
sudo journalctl -u sentinel -f

# Historical
sudo journalctl -u sentinel | tail -50

# File
sudo tail -50 /var/log/truthvouch/sentinel.log

Collect Diagnostics

Create diagnostic bundle:

# Windows (PowerShell as Admin)
$diag = @{
  "config" = Get-Content "C:\ProgramData\TruthVouch\Sentinel\config.yaml"
  "service" = Get-Service TruthVouchSentinel
  "logs" = Get-EventLog -LogName "Application" -Source "TruthVouch" -Newest 100
}
$diag | ConvertTo-Json | Out-File diagnostics.json

# macOS/Linux
tar -czf sentinel-diagnostics.tar.gz \
  /etc/truthvouch/sentinel/config.yaml \
  ~/.truthvouch/sentinel/logs/ \
  /var/log/truthvouch/sentinel.log

Service Not Running

Windows Service Won’t Start

# Check service status
Get-Service TruthVouchSentinel

# View error logs
Get-EventLog -LogName "System" -Source "Service Control Manager" -Newest 10

# Try to start service
Start-Service TruthVouchSentinel -ErrorAction SilentlyContinue

# Check dependencies
Get-Service TruthVouchSentinel | Format-List DependentServices, ServicesDependedOn

macOS Daemon Issues

# Check if loaded
launchctl list | grep truthvouch

# Try to load
launchctl load ~/Library/LaunchAgents/io.truthvouch.sentinel.plist

# Check permissions
ls -la ~/Library/LaunchAgents/io.truthvouch.sentinel.plist

# Fix ownership
sudo chown root ~/Library/LaunchAgents/io.truthvouch.sentinel.plist

Linux Systemd Issues

# Check service status
sudo systemctl status sentinel

# View unit file
sudo systemctl cat sentinel

# Check permissions
ls -la /etc/systemd/system/sentinel.service
sudo systemctl daemon-reload

# Try to start
sudo systemctl start sentinel

# View detailed error
sudo systemctl status sentinel -n 50

AI Tool Detection Issues

Tool Not Being Detected

1. Verify tool is configured:

monitoring:
  tools:
    - name: "ChatGPT"
      enabled: true
      executables:
        - "chrome.exe"
        - "firefox.exe"

2. Check if tool is installed and running:

• Windows: Check Task Manager for process
• macOS: Activity Monitor
• Linux: ps aux | grep chrome

3. Enable debug logging and check logs for process detection

False Positives/Negatives

Report issue:

1. Enable debug logging
2. Collect diagnostics (see above)
3. Include specific examples
4. Contact support with bundle

DLP Issues

PII Not Being Detected

Check pattern configuration:

dlp:
  pii:
    patterns:
      ssn: true
      credit_card: true

Test pattern:

# Test SSN regex
"123-45-6789" should match pattern "^\d{3}-\d{2}-\d{4}$"

Legitimate Content Blocked

Add to exceptions:

allowlists:
  pii_exceptions:
    patterns:
      - "[email protected]"  # Test email
      - "555-0100"              # Test phone

Database Issues

Database Corruption

Symptoms: Sentinel won’t start, database errors in logs

Fix:

# Windows
Remove-Item "C:\ProgramData\TruthVouch\Sentinel\data\sentinel.db"

# macOS
rm ~/.truthvouch/sentinel/sentinel.db

# Linux
sudo rm /var/lib/truthvouch/sentinel/sentinel.db

Restart Sentinel to rebuild database.

Database Size Growing

database:
  retention_days: 30  # Reduce from default 90
  max_size_mb: 50    # Limit database size

Sentinel automatically cleans old logs.

Updating Issues

Update Fails

Windows:

# Remove old installation
msiexec /x sentinel-installer.msi /quiet

# Reinstall
msiexec /i sentinel-installer.msi /quiet

macOS:

# Remove old version
sudo rm -rf /Applications/Sentinel.app

# Reinstall via Homebrew
brew upgrade sentinel

Linux:

sudo apt update
sudo apt upgrade sentinel
# or
sudo yum update sentinel

Getting Help

Collect before contacting support:

1. Version: sentinel --version
2. Config (without API keys): sentinel --show-config
3. Recent logs (50 lines)
4. System info (OS, architecture)
5. Error messages (exact text)

Support channels:

• Email: [email protected]
• Chat: TruthVouch dashboard
• Docs: https://docs.truthvouch.io

See Configuration Reference and Policy Sync for configuration help.