Monitoring Velociraptor with Vigilmon

Velociraptor lets security teams collect forensic artifacts and hunt for threats across thousands of endpoints simultaneously. When the Velociraptor server goes down, investigators lose visibility, agents stop uploading telemetry, and hunts stall silently. Vigilmon closes that blind spot — monitoring your Velociraptor admin UI, client frontend, API, and disk health so your DFIR platform stays operational when you need it most.

What You'll Set Up

• Admin GUI uptime monitor (port 8889 — investigator access)
• Client frontend monitor (port 8000 — agent connectivity)
• API server monitor (port 8001 — automation integrations)
• File store disk usage alert (>80% triggers data loss risk)
• TLS certificate expiry alert (<30 days remaining)
• Cron heartbeat for Velociraptor server process health

Prerequisites

• Velociraptor server running on a Linux or Windows host
• Ports 8000, 8889, and 8001 accessible from your monitoring vantage point (or Vigilmon agent installed on the host)
• A free Vigilmon account

Step 1: Monitor the Admin GUI (Port 8889)

The Velociraptor admin GUI is the primary investigator interface. If it goes down, your entire DFIR team is locked out of active investigations.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the admin GUI URL: https://your-velociraptor-host:8889/app/index.html
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Add keyword check: Velociraptor (the page title appears in the HTML on a healthy server).
7. Click Save.

Note: Velociraptor uses self-signed TLS by default. In Vigilmon, enable Ignore SSL errors or upload your CA certificate so the check doesn't fail on certificate verification.

Step 2: Monitor the Client Frontend (Port 8000)

Port 8000 is where Velociraptor agents connect to upload forensic data and receive collection tasks. If this endpoint goes down, all agents become unreachable — no new telemetry, no hunt results.

1. Click Add Monitor and set Type to TCP Port.
2. Enter your Velociraptor server hostname and port 8000.
3. Set Check interval to 1 minute.
4. Click Save.

A TCP monitor is appropriate here because the frontend speaks the Velociraptor binary protocol over TLS — not plain HTTP. A successful TCP handshake confirms the service is accepting connections.

If you want an HTTP-level check, Velociraptor's frontend returns a 200 on /server.pem (its public certificate endpoint):

https://your-velociraptor-host:8000/server.pem

Add an HTTP monitor for this URL as a secondary signal.

Step 3: Monitor the gRPC API (Port 8001)

Port 8001 is the Velociraptor gRPC API used by automation scripts, SOAR integrations, and the velociraptor CLI. Downtime here silently breaks all API-driven workflows.

1. Click Add Monitor and set Type to TCP Port.
2. Enter your Velociraptor server hostname and port 8001.
3. Set Check interval to 2 minutes.
4. Click Save.

For deeper API health validation, if you expose a REST-wrapped health endpoint via Velociraptor's notebook or a sidecar proxy, add an HTTP monitor pointing to it.

Step 4: Alert on File Store Disk Usage

Velociraptor writes all forensic artifacts, hunt results, and client uploads to its file store directory (typically /opt/velociraptor/ or C:\Program Files\Velociraptor\). At >80% disk utilization, Velociraptor cannot write new artifacts — causing silent data loss during active hunts.

Option A: Use a Vigilmon Agent (Recommended)

Install the Vigilmon agent on your Velociraptor host for in-process disk monitoring:

# Install the Vigilmon agent (see your Vigilmon dashboard for the install command)
curl -fsSL https://vigilmon.online/agent/install.sh | sudo bash

In the Vigilmon dashboard, add a Disk Usage check for the file store mount point and set the alert threshold to 80%.

Option B: Expose Disk Metrics via a Health Endpoint

Create a lightweight script that writes disk usage to a file Velociraptor's notebook can serve, or run a small HTTP server alongside:

#!/bin/bash
# /usr/local/bin/disk-health.sh
USAGE=$(df /opt/velociraptor | awk 'NR==2 {print $5}' | tr -d '%')
if [ "$USAGE" -gt 80 ]; then
  echo '{"status":"critical","disk_usage_pct":'$USAGE'}'
  exit 1
fi
echo '{"status":"ok","disk_usage_pct":'$USAGE'}'

Serve it with a simple HTTP listener and add a Vigilmon HTTP monitor with keyword "status":"ok".

Step 5: Monitor TLS Certificate Expiry

Velociraptor's self-signed or CA-signed certificates secure all agent-to-server communication. If a certificate expires, agents cannot reconnect and the admin GUI becomes inaccessible.

1. Click Add Monitor and set Type to SSL Certificate.
2. Enter your Velociraptor admin GUI domain and port 8889.
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

Add a second SSL monitor for port 8000 (client frontend certificate) — agents will reject expired server certificates and stop uploading data.

Step 6: Set Up a Cron Heartbeat for the Velociraptor Process

Velociraptor runs as a single binary. If the process crashes silently, none of the port monitors above will fire until the OS starts refusing connections. A heartbeat from the Velociraptor host catches process-level failures faster.

In the Vigilmon dashboard, create a Cron Heartbeat monitor:

1. Click Add Monitor and set Type to Cron Heartbeat.
2. Set Expected interval to 2 minutes.
3. Copy the heartbeat ping URL.

Add a systemd timer or cron job on the Velociraptor host to ping the heartbeat URL:

# /etc/cron.d/velociraptor-heartbeat
* * * * * root systemctl is-active --quiet velociraptor && curl -fsS YOUR_HEARTBEAT_URL > /dev/null
* * * * * root sleep 60; systemctl is-active --quiet velociraptor && curl -fsS YOUR_HEARTBEAT_URL > /dev/null

This pings every minute. If the Velociraptor service stops, the curl never runs and Vigilmon fires a downtime alert within two minutes.

Step 7: Configure Alerting

Alert Channels

In Vigilmon, go to Alert Channels and connect your preferred destinations:

• Email — immediate downtime notifications
• Slack / Discord — team-wide visibility for DFIR team channels
• PagerDuty / Opsgenie — on-call escalation for production DFIR environments
• Webhook — push alerts into your SOAR or ticketing system

Recommended Alert Rules

| Monitor | Condition | Severity | |---|---|---| | Admin GUI (8889) | Down > 1 min | Critical | | Client Frontend (8000) | Down > 1 min | Critical | | API Server (8001) | Down > 2 min | High | | File Store Disk | > 80% | High | | TLS Certificate | < 30 days | Medium | | Process Heartbeat | Missing > 2 min | Critical |

Status Page

Create a Vigilmon status page to give your DFIR team a shared view of platform health:

1. Go to Status Pages → Create Status Page.
2. Add your Velociraptor monitors.
3. Share the status page URL with the incident response team.

What to Watch Beyond Uptime

Once basic uptime is covered, instrument these operational signals from Velociraptor's internal metrics or logs:

Connected client count — Velociraptor exposes client statistics via its API. A >10% drop in connected clients indicates agent connectivity issues or network disruption affecting endpoint coverage during active investigations.

Collection job success rate — Velociraptor dispatches VQL collection tasks to agents. High collection failure rates indicate client-side issues (agent crash, AV interference) or resource exhaustion on endpoints.

Hunt completion rate — Scheduled hunts across all endpoints should complete within their configured timeout. Stalled hunts often indicate the file store is full or the Velociraptor server is CPU-constrained.

Data ingestion throughput — A drop in bytes-per-second ingested from clients signals agent connectivity degradation before client count visibly drops.

To collect these metrics, query the Velociraptor API periodically with a script and push the results to Vigilmon via its metrics API or to your existing APM stack.

Conclusion

Velociraptor gives your security team unparalleled endpoint visibility — but that visibility disappears the moment the server fails. With Vigilmon, you get:

• Sub-minute detection when the admin GUI or client frontend goes down
• Disk alerts before the file store fills and starts dropping forensic artifacts
• Certificate monitoring before expired certs cut agents off from the server
• Process heartbeat catching silent crashes the port monitors miss

Set this up once and your DFIR team can focus on hunting threats instead of wondering whether Velociraptor is healthy.

Get started free at vigilmon.online.