Troubleshooting

import { Aside } from ‘@astrojs/starlight/components’;

Agent issues

Agent not appearing in Endpoints after installation

Check 1 — service is running:

# Linux
systemctl status bastion-agent

# macOS
launchctl list com.bastionedr.agent

# Windows (PowerShell)
Get-Service BastionAgent

Check 2 — backend URL is correct: Verify agent.toml has the correct url. The backend must be reachable from the endpoint on port 50051.

# Test gRPC reachability from the endpoint
nc -zv YOUR_BACKEND_IP 50051

Check 3 — firewall: Port 50051 (outbound TCP from endpoint to backend) must be open. Port 50051 must be open inbound on the backend server.

High CPU usage on endpoint

By default the agent uses <0.5% CPU at idle. If you see spikes:

Check if a YARA scan is running (expected during initial deployment or after policy update)
Check detection.memory_scan_enabled — disable on resource-constrained devices
Check if the exclude_paths list is missing large directories (e.g., /var/log on a busy server)

Backend issues

Backend fails to start — “Failed to connect to SurrealDB”

SurrealDB must be running before the backend starts. With Docker Compose, the depends_on directive handles this, but if SurrealDB is still initializing:

docker compose logs surrealdb
# Wait for: "SurrealDB initialized"
docker compose restart bastion-backend

“Missing field `customer_name`” in license tests

This error occurs in development if the database schema was created before the customer_name field was added. Fix:

# Drop and recreate the database (dev only — this deletes all data)
docker compose down -v
docker compose up -d

Console shows “401 Unauthorized” after a password change

JWT tokens issued before the password change remain valid until expiry. To force re-login for all sessions, rotate tokens:

POST /api/v1/admin/security/revoke/{user_id}
Authorization: Bearer <admin-token>

Compliance

HIPAA compliance score is lower than expected

Check the control checklist in Compliance → HIPAA → Controls. Each control shows its current status and a remediation note. Common reasons for low scores:

PHI encryption is disabled (enable in config/backend.toml under [encryption])
Audit log integrity has not been verified recently (click Verify in Audit Logs)
No active SMTP configuration (email notifications are a control indicator)

FERPA PII timeline shows no events

The agent must be running on the endpoints where student records are accessed. Verify:

Agents are deployed to the endpoints where your SIS/LMS runs
The detection.behavioral_enabled flag is true in agent.toml
Allow 5–15 minutes for initial baseline collection

Console

Console fails to connect to backend

Verify the backend URL in Settings → Connection matches your backend IP and port
Check that port 8080 is open from your console workstation to the backend server
If using HTTPS, verify the TLS certificate is trusted or add it to your system trust store

”flutter_secure_storage” error on Linux

On some Linux distributions, flutter_secure_storage requires libsecret:

sudo apt-get install -y libsecret-1-dev

Getting help

When reporting a bug, include:

Bastion version (curl http://localhost:8080/health | jq .version)
OS and version of the affected component
Relevant log output (journalctl -u bastion-agent --since "10 minutes ago" or backend Docker logs)
Steps to reproduce