Monitoring SSHPortal with Vigilmon

SSHPortal is a lightweight open-source SSH bastion host written in Go that acts as a transparent SSH proxy — intercepting all SSH sessions for auditing, access control, and routing without requiring a heavy web UI. DevOps teams use it to enforce SSH ACLs, manage host groups, and record session logs through a minimal-footprint bastion that exposes a REST API and an admin shell for management. When SSHPortal's SSH proxy port goes silent, every developer and operator connecting through it is immediately blocked. Vigilmon monitors SSHPortal's TCP ports, REST API health endpoint, and session audit log integrity so you catch failures before your team does.

What You'll Set Up

• TCP port monitor for the SSHPortal SSH proxy service (port 2222)
• HTTP uptime monitor for the /healthz REST API health endpoint (if enabled)
• TCP port monitor for the admin REST API (port 8080, if enabled)
• SSL certificate expiry alerts for any HTTPS reverse proxy fronting the management API
• Heartbeat monitor for SSHPortal session audit log writing

Prerequisites

• SSHPortal running with its SSH proxy on port 2222
• REST API enabled on port 8080 (optional but recommended)
• A free Vigilmon account

Step 1: Monitor the SSH Proxy Port (TCP 2222)

The SSH proxy port is SSHPortal's core service. Every SSH connection from clients passes through this port. Monitoring it with a TCP connection probe is the most direct way to confirm SSHPortal is alive and accepting connections.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to TCP Port.
3. Enter your SSHPortal hostname and set Port to 2222.
4. Set Check interval to 1 minute.
5. Click Save.

To verify SSHPortal is listening on port 2222:

# On the SSHPortal host
ss -tlnp | grep 2222
# Expected: LISTEN ... *:2222

# From a remote machine
nc -zv sshportal.yourdomain.com 2222
# Expected output ends with: succeeded!

# Confirm it's actually SSHPortal (not another SSH daemon)
ssh -p 2222 sshportal.yourdomain.com
# Expected: SSHPortal banner or connection refused with no matching host

If SSHPortal is configured on a non-default port, update the Vigilmon monitor accordingly.

Step 2: Monitor the /healthz Endpoint

SSHPortal exposes a /healthz HTTP endpoint on its REST API port (default 8080) when the API is enabled. This endpoint provides a simple liveness check for the SSHPortal process beyond a raw TCP connection.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the health check URL: http://sshportal.yourdomain.com:8080/healthz
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 200.
5. Optionally set Expected response body to contain "ok" or "healthy".
6. Click Save.

Enable the REST API if it is not already running. In your SSHPortal startup command or service configuration:

# Start SSHPortal with REST API enabled
sshportal server \
  --db-conn "sshportal.db" \
  --bind-addr "0.0.0.0:2222" \
  --api-addr "0.0.0.0:8080"

Or in a systemd unit file:

[Service]
ExecStart=/usr/local/bin/sshportal server \
  --db-conn /var/lib/sshportal/sshportal.db \
  --bind-addr 0.0.0.0:2222 \
  --api-addr 0.0.0.0:8080

Restrict port 8080 to your internal network or monitoring infrastructure — the admin API should not be publicly reachable.

Step 3: Monitor the Admin REST API Port (TCP 8080)

A TCP probe on port 8080 complements the HTTP /healthz check and is useful when SSHPortal is bound to localhost or a private network interface where HTTP probing from Vigilmon's external IPs is not possible.

1. Click Add Monitor → TCP Port.
2. Enter your SSHPortal hostname and set Port to 8080.
3. Set Check interval to 2 minutes.
4. Click Save.

If the admin API is only accessible from localhost (recommended for security), run the TCP probe from a local monitoring script instead and report results via a heartbeat URL — see Step 5 below.

Step 4: SSL Certificate Alerts for the Management API Proxy

If SSHPortal's REST API is fronted by an HTTPS reverse proxy (nginx, Caddy, or Traefik) to expose management endpoints securely, monitor the SSL certificate on that proxy. An expired certificate blocks API access and any tooling that integrates with SSHPortal's REST API.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter your HTTPS management API URL: https://sshportal-api.yourdomain.com/healthz
3. Set Expected HTTP status to 200.
4. Enable Monitor SSL certificate under the SSL section.
5. Set Alert when certificate expires in less than 21 days.
6. Click Save.

For nginx-proxied deployments:

server {
    listen 443 ssl;
    server_name sshportal-api.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/sshportal-api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sshportal-api.yourdomain.com/privkey.pem;

    location /healthz {
        proxy_pass http://127.0.0.1:8080/healthz;
    }
}

Step 5: Heartbeat Monitoring for Session Audit Log Writing

SSHPortal records session audit logs to its database. If the database becomes unwritable, fills up, or SSHPortal loses write access, session recordings silently stop — your audit trail becomes incomplete without any visible error. Use a scheduled connectivity probe through the SSH proxy to verify end-to-end session recording is working.

1. Click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 10 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add a monitoring script that makes a test SSH connection through the proxy and pings Vigilmon if the TCP handshake succeeds:

#!/bin/bash
# /usr/local/bin/sshportal-heartbeat.sh
SSHPORTAL_HOST="sshportal.yourdomain.com"
SSHPORTAL_PORT="2222"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

# TCP probe — confirms SSH proxy is accepting connections
if nc -z -w 5 "$SSHPORTAL_HOST" "$SSHPORTAL_PORT" 2>/dev/null; then
  curl -sf "$HEARTBEAT_URL"
fi

For a deeper audit log verification, check the SSHPortal database for recent session records:

#!/bin/bash
# /usr/local/bin/sshportal-auditlog-heartbeat.sh
DB_PATH="/var/lib/sshportal/sshportal.db"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"

# Check that the database file is writable and recently modified
if [ -w "$DB_PATH" ]; then
  LAST_MODIFIED=$(date -r "$DB_PATH" +%s)
  NOW=$(date +%s)
  AGE=$(( NOW - LAST_MODIFIED ))

  # Alert if DB hasn't been written in more than 30 minutes
  if [ "$AGE" -lt "1800" ]; then
    curl -sf "$HEARTBEAT_URL"
  fi
fi

5. Schedule the script with cron:

crontab -e
# Add:
*/10 * * * * /usr/local/bin/sshportal-heartbeat.sh

Make executable: chmod +x /usr/local/bin/sshportal-heartbeat.sh

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 1 on the SSH proxy TCP monitor — a closed port 2222 means SSHPortal is definitively down and blocking all SSH access.
3. Set Consecutive failures before alert to 2 on the API monitors — brief Go runtime GC pauses can occasionally delay a response.

Summary

| Monitor | Target | What It Catches | |---|---|---| | TCP Port | :2222 | SSH proxy down, process crashed | | HTTP / HTTPS | :8080/healthz | REST API failure, process unhealthy | | TCP Port | :8080 | Admin API not listening | | SSL Certificate | Management API domain | Reverse proxy certificate expiry | | Cron Heartbeat | SSH TCP probe + DB write check | Proxy degraded, audit log writes stopped |

SSHPortal's minimal footprint is its biggest advantage — but minimal also means no built-in alerting. Vigilmon provides the external observability layer that SSHPortal intentionally omits, ensuring your lightweight bastion is always doing its job of securely routing and recording every SSH session.