Troubleshooting

Common issues and solutions for Aquilon DLP.

Installation Issues

“osquery not found” during installation

Aquilon DLP requires osquery 5.0.1 or later. Install osquery first:

macOS:

# Using Homebrew
brew install --cask osquery

# Or download PKG from https://github.com/osquery/osquery/releases

Ubuntu/Debian:

wget https://pkg.osquery.io/deb/osquery_5.10.2-1.linux_amd64.deb
sudo apt install ./osquery_5.10.2-1.linux_amd64.deb

CentOS/RHEL:

wget https://pkg.osquery.io/rpm/osquery-5.10.2-1.linux.x86_64.rpm
sudo dnf install ./osquery-5.10.2-1.linux.x86_64.rpm

Verify installation:

osqueryd --version
# Expected: osqueryd version 5.0.1 or later

“Unsupported osquery version”

Upgrade osquery to 5.0.1 or later from osquery releases.

“Signature verification failed” (macOS)

The PKG may be corrupted. Re-download from the official source and verify:

spctl -a -v aquilon-dlp-enterprise.pkg

“Installation already in progress” (macOS)

Another installation is running. If a previous installation crashed:

sudo rm -rf /var/run/aquilon-install.lock

macOS Issues

Full Disk Access Not Granted

Aquilon DLP requires Full Disk Access for file monitoring.

Diagnosis:

# Check TCC database
sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT auth_value FROM access
   WHERE service = 'kTCCServiceSystemPolicyAllFiles'
   AND client = 'dev.aquilon.dlp-plugin';"
# Expected: 2 (granted)

Solution:

Open System Settings > Privacy & Security > Full Disk Access
Click the lock icon and authenticate
Click + and navigate to /opt/aquilon/aquilon-dlp.app
Ensure the toggle is enabled
Restart the service

For MDM deployments: Deploy a PPPC (Privacy Preferences Policy Control) profile. See MDM Deployment.

Extension Not Loading in osquery

Diagnosis:

# Check extension registered
cat /var/osquery/extensions.load

# Check osquery sees extension
osqueryi --connect /var/osquery/osquery.sock 'SELECT * FROM osquery_extensions;'

Solutions:

Verify Full Disk Access (see above)

Restart osqueryd:

sudo launchctl unload /Library/LaunchDaemons/io.osquery.agent.plist
sudo launchctl load /Library/LaunchDaemons/io.osquery.agent.plist

Note: OSQuery 5.0.1+ uses io.osquery.agent.plist. Older versions use com.facebook.osqueryd.plist.

Check logs:

tail -f /var/log/aquilon/aquilon-dlp.log

“Unsupported macOS version”

Aquilon DLP requires macOS 11.0 (Big Sur) or later:

sw_vers -productVersion

Linux Issues

Extension Not Loading

Diagnosis:

# Check extension registered
cat /etc/osquery/extensions.load

# Check osquery status
sudo systemctl status osqueryd

# Check logs
journalctl -u osqueryd -f

Solutions:

Restart osqueryd:
```
sudo systemctl restart osqueryd
```

Check extension permissions:

ls -la /usr/lib/osquery/extensions/aquilon-dlp-*.ext
# Should be: -rwxr-xr-x root root

SELinux Blocking Access (RHEL/CentOS)

Diagnosis:

# Check for SELinux denials
sudo ausearch -m avc -ts recent

# Check SELinux status
getenforce

Solution:

# Restore security contexts
sudo restorecon -Rv /usr/lib/osquery/extensions/
sudo restorecon -Rv /etc/aquilon/

Permission Denied Errors

Diagnosis:

ls -la /usr/lib/osquery/extensions/aquilon-dlp-*.ext

Solution:

sudo chmod 755 /usr/lib/osquery/extensions/aquilon-dlp-*.ext
sudo chown root:root /usr/lib/osquery/extensions/aquilon-dlp-*.ext

OSQuery Integration Issues

Table Not Found

If aquilon_dlp_alerts table is not available:

# Verify extension is loaded
osqueryi --connect /var/osquery/osquery.sock 'SELECT * FROM osquery_extensions WHERE name LIKE "%aquilon%";'

# Check table exists
osqueryi 'PRAGMA table_info(aquilon_dlp_alerts);'

If empty, the extension isn’t loaded. See platform-specific extension loading issues above.

SQL Query Errors

Common column name mistakes:

Wrong	Correct
`created_at`	`timestamp`
`policy_name`	`policy`
`pattern_matched`	`pattern`
`confidence_score`	`confidence`
`hash`	`JSON_EXTRACT(context, ‘$.file.hash’)`

Correct query example:

SELECT path, scanner, severity, timestamp
FROM aquilon_dlp_alerts
ORDER BY timestamp DESC
LIMIT 10;

Configuration Issues

Configuration Not Loading

Diagnosis:

# Validate configuration
aquilon-dlp --validate-config /etc/aquilon/config.toml

Common errors:

Unknown field: Check field names match exactly (e.g., max_scan_size_mb not max_file_size_mb)
Unknown section: Use correct section names ([scan] not [scanner], [resource_limits] not [resources])
Invalid TOML: Check syntax with a TOML validator

watch_paths Not Working

Ensure watch_paths is at the top level of your config, not under a section:

# CORRECT - at top level
watch_paths = ["/home/%%", "/var/data/%%"]
[policies]
enabled_policies = ["gdpr", "ccpa"]

# WRONG - under [policies] section
[policies]
enabled_policies = ["gdpr", "ccpa"]
watch_paths = ["/home/%%"]  # This won't work!

Performance Issues

High CPU Usage

Diagnosis:

# Check process
top -pid $(pgrep -f aquilon)

# Check alert volume
osqueryi "SELECT COUNT(*) FROM aquilon_dlp_alerts;"

Solutions:

Add exclusions for high-churn directories:

exclude_paths = [
    "/home/*/.cache/%%",
    "/home/*/.npm/%%",
    "/var/log/%%",
    "**/*.iso",
    "**/*.dmg"
]

Limit file size:
```
[scan]
max_scan_size_mb = 40
```
Reduce workers:
```
[worker]
num_workers = 2
```

Enable resource limits:

[resource_limits]
enabled = true
max_cpu_percent = 50.0
max_memory_mb = 512

High Memory Usage

Solutions:

Reduce cache size:

[cache]
ttl_secs = 1800  # 30 minutes instead of longer

Limit memory:

[resource_limits]
enabled = true
max_memory_mb = 256

No Alerts Generated

Diagnosis

-- Check for any alerts
SELECT COUNT(*) FROM aquilon_dlp_alerts;

-- Check recent alerts
SELECT * FROM aquilon_dlp_alerts
ORDER BY timestamp DESC
LIMIT 5;

Common Causes

No sensitive data: Test with known sensitive data:

echo "SSN: 122-15-6289" > /tmp/test-sensitive.txt

Policies not enabled: Check configuration:

[policies]
enabled_policies = ["gdpr", "ccpa", "hipaa"]

Wrong watch paths: Ensure paths are monitored:
```
watch_paths = ["/home/%%", "/var/data/%%"]
```
Exclusions too broad: Review exclude_paths
Cache returning old results: Clear cache or wait for TTL expiry

Debugging Enrichment

When investigating false positives (legitimate data flagged as sensitive) or false negatives (sensitive data not detected), use context trace mode to understand enrichment decisions.

Enable Context Trace

Add to your configuration:

[context_trace]
enabled = true

Understanding Trace Output

With tracing enabled, the logs show each enrichment decision in JSON format:

{
  "event": "context_enrichment",
  "scanner": "ssn",
  "original_confidence": 0.75,
  "context_profiles_matched": ["personal_data", "employment"],
  "adjustments": [
    {"profile": "personal_data", "boost": 0.15, "reason": "SSN keyword in context"},
    {"profile": "employment", "boost": 0.10, "reason": "W-2 form indicator"}
  ],
  "final_confidence": 0.95
}

Key fields:

Field	Description
`original_confidence`	Scanner’s base confidence before context analysis
`context_profiles_matched`	Which context profiles found relevant keywords
`adjustments`	Individual confidence boosts with reasoning
`final_confidence`	Result after all adjustments applied

Common Debugging Scenarios

False Positive Investigation:

Enable context trace
Scan the file generating false positives
Check which context profiles are boosting confidence
Consider adjusting enabled_profiles in [context] config

False Negative Investigation:

Enable context trace
Scan the file that should generate alerts
Look for low original_confidence (scanner issue) vs no adjustments (context issue)
Consider enabling additional context profiles

Disable After Debugging

Context tracing generates significant log volume. Disable when done:

[context_trace]
enabled = false

Getting Help

Collecting Diagnostic Information

macOS:

# Collect logs
tail -n 500 /var/log/aquilon/aquilon-dlp.log > dlp-diagnostics.txt

# System info
sw_vers >> dlp-diagnostics.txt

# FDA status
sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db \
  "SELECT * FROM access WHERE client LIKE '%aquilon%';" >> dlp-diagnostics.txt

Linux:

# Collect logs
sudo journalctl -u osqueryd -n 500 > dlp-diagnostics.txt

# System info
uname -a >> dlp-diagnostics.txt
cat /etc/os-release >> dlp-diagnostics.txt

# Service status
systemctl status aquilon-dlp >> dlp-diagnostics.txt

Support Channels

Basic Edition: GitHub Issues
Enterprise Edition: support@aquilonsecurity.com
- Critical (P1): 4-hour response
- High (P2): 8-hour response
- Normal (P3): 24-hour response

Keyboard shortcuts

Aquilon DLP Documentation