Nex Healthcheck

Multi-service health and uptime monitoring dashboard for websites, APIs, infrastructure, and applications across multiple systems. Monitor website availabili...

Security Scan

The package is a coherent local health-check tool that mostly matches its description, but there are notable inconsistencies and cautious behaviors (declared required Telegram env vars that are actually optional, remote SSH arbitrary-command capability, and an optional systemd timer), plus some code-quality bugs — review before installing in production.

Purpose & Capability

The code implements the advertised health checks (HTTP, TCP, DNS, SSL, Docker, systemd, SSH commands, disk, ping) and the required binaries (python3, dig, ssh) are relevant. However the registry claims Telegram creds are required; in the code Telegram is optional (defaults to empty) which is an inconsistency between metadata and implementation.

Instruction Scope

SKILL.md and CLI instruct only the expected monitoring actions. It also documents running arbitrary commands remotely via the ssh_cmd check and supports running docker/systemctl on remote hosts via SSH — this is within the tool's purpose but increases risk because SSH checks execute arbitrary remote commands. There are also small implementation bugs (e.g., check_ssl_cert accesses ssock after the socket context, which is a code-quality/functional issue).

Install Mechanism

There is no remote download install; setup.sh is included and idempotently creates a data directory, initializes a local SQLite DB, installs a wrapper in ~/.local/bin, and optionally installs a user systemd timer. All files are local and transparent; no external archives or downloads are fetched during install.

Credentials

Registry metadata lists HEALTHCHECK_TELEGRAM_TOKEN and HEALTHCHECK_TELEGRAM_CHAT as required env vars, but the code treats these as optional (defaults to empty) and will simply skip alerts if not provided. Marking them required in the registry is disproportionate/confusing. Other requested env vars (HEALTHCHECK_DATA) are reasonable. No unrelated cloud secrets or extra credentials are requested.

Persistence & Privilege

The skill does not force persistent inclusion or elevate privileges. setup.sh creates a CLI wrapper in ~/.local/bin and can (with explicit user consent) install a per-user systemd timer to run checks periodically — this is persistent but user-controlled. The skill does not alter other skills or system-wide credentials.

What to consider before installing

This package appears to be what it claims (a local health-check tool), but review and cautious deployment are advised: - Metadata mismatch: the registry marks Telegram env vars as required, but the code treats them as optional. Do not put production secrets into environments unless you intend to enable Telegram alerts. - SSH remote checks: the tool supports executing arbitrary commands on remote machines via SSH (ssh_cmd, remote docker/systemd). Only use that feature with hosts you control and with properly restricted SSH keys; untrusted targets can run unexpected commands. - Systemd timer: setup.sh can optionally install a user systemd timer to run checks periodically. Accept that only if you want a persistent background job; the installer prompts before enabling it. - Inspect and test before production: run setup.sh in a non-production or containerized environment first, inspect the created files (~/.nex-healthcheck, ~/.local/bin/nex-healthcheck), and verify behavior. - Code quality issues: there are minor bugs (e.g., SSL certificate check references the socket object after the with block) — consider reviewing/fixing or running tests before relying on expiry alerts. If you plan to use this skill: review the source (already included), avoid setting global/privileged tokens unnecessarily, restrict SSH access, and run the installer interactively so you can decline the systemd timer if undesired.

Multi-service health dashboard and monitoring tool. Monitor websites, APIs, SSL certificates, Docker containers, systemd services, infrastructure health, and more. All checks run locally. Optional Telegram notifications.

When to Use

Use this skill when the user asks about:

• Service uptime, health status, or monitoring
• Website or API availability checks
• SSL certificate expiry dates or renewal
• Docker container status or health
• Systemd service status
• Server or infrastructure health checks
• Disk usage or space monitoring
• Ping or network connectivity
• Incident history or downtime events
• Uptime statistics and SLA tracking
• Health dashboards or status pages

Trigger phrases: "is everything healthy?", "what went down this week?", "when does my SSL cert expire?", "check if ollama is running", "monitor my services", "uptime stats", "disk usage", "service health", "infrastructure status"

Quick Setup

If the database does not exist yet, run the setup script:

bash setup.sh

This creates the data directory, installs the CLI tool, and initializes the database.

Available Commands

The CLI tool is nex-healthcheck. All commands output plain text.

Check Services

Run health checks on monitored services:

nex-healthcheck check              # Run all enabled checks
nex-healthcheck check --service "nex-ai.be"
nex-healthcheck check --group "production"
nex-healthcheck check --tag "pi"

Add Service

Add a service to monitor:

nex-healthcheck add --name "nex-ai.be" --type http --target "https://nex-ai.be" --expected 200
nex-healthcheck add --name "HAL-9000" --type tcp --target "192.168.1.100" --port 2222
nex-healthcheck add --name "SSL nex-ai.be" --type ssl_cert --target "nex-ai.be"
nex-healthcheck add --name "Pi Docker Ollama" --type docker --target "ollama" --ssh-host "pi@192.168.1.100"
nex-healthcheck add --name "Pi Disk" --type disk --target "/" --ssh-host "pi@192.168.1.100" --group "pi-infra"
nex-healthcheck add --name "Cloudflare DNS" --type dns --target "nex-ai.be"
nex-healthcheck add --name "Life Logger" --type systemd --target "nex-life-logger" --ssh-host "pi@192.168.1.100"
nex-healthcheck add --name "Health API" --type ssh_cmd --ssh-host "user@server" --target "curl http://localhost:8000/health" --expected "ok"

Check types:

• http: HTTP GET request, check status code
• tcp: TCP socket connection test
• dns: DNS resolution check (requires dig/nslookup)
• ssl_cert: SSL certificate expiry check
• docker: Docker container status (requires docker CLI or SSH)
• systemd: Systemd service status (requires systemctl or SSH)
• ssh_cmd: Run arbitrary command via SSH
• ping: ICMP ping check
• disk: Disk usage check

List Services

nex-healthcheck list              # Show all monitored services

Remove Service

nex-healthcheck remove --name "service-name"

Status

nex-healthcheck status            # Quick status from last checks

History

nex-healthcheck history --name "service-name" --days 7
nex-healthcheck history --name "service-name" --days 30

Incidents

nex-healthcheck incidents          # Show active incidents
nex-healthcheck incidents --all    # Show all incidents (active + resolved)

Uptime Statistics

nex-healthcheck uptime --days 30
nex-healthcheck uptime --days 7

Dashboard

nex-healthcheck dashboard         # Full dashboard view

Send Dashboard via Telegram

nex-healthcheck notify            # Send current status to Telegram

Requires HEALTHCHECK_TELEGRAM_TOKEN and HEALTHCHECK_TELEGRAM_CHAT environment variables.

Configuration

nex-healthcheck config --set-token "YOUR_BOT_TOKEN"
nex-healthcheck config --set-chat "YOUR_CHAT_ID"

Example Interactions

User: "Is everything healthy?" Agent runs: nex-healthcheck dashboard Agent: Shows full health dashboard with all services grouped by category.

User: "When does my SSL cert expire?" Agent runs: nex-healthcheck check --tag "ssl" Agent: Shows SSL certificate expiry dates for all monitored certificates.

User: "What went down this week?" Agent runs: nex-healthcheck incidents --all Agent: Shows all incidents from the past week with start/end times.

User: "Check if Ollama is running on the Pi" Agent runs: nex-healthcheck check --name "Pi Docker Ollama" Agent: Reports the container status.

User: "Show me uptime for the last month" Agent runs: nex-healthcheck uptime --days 30 Agent: Displays uptime percentage, check success rate, and average response time.

User: "Monitor my nex-ai.be website" Agent runs: nex-healthcheck add --name "nex-ai.be" --type http --target "https://nex-ai.be" --expected 200 --group "production" Agent: Confirms service added. Then nex-healthcheck check --service "nex-ai.be" to verify.

User: "Check disk usage on my server" Agent runs: nex-healthcheck add --name "Server Disk" --type disk --target "/" --ssh-host "user@192.168.1.50" then nex-healthcheck check --name "Server Disk" Agent: Reports disk usage percentage and free space.

User: "Show me an incident history" Agent runs: nex-healthcheck incidents --all Agent: Lists all past incidents with duration and status.

Output Parsing

All CLI output is plain text, structured for easy parsing:

• Traffic light emojis: 🟢 OK, 🟡 WARNING, 🔴 CRITICAL, ⚪ UNKNOWN
• Grouped by category/service group
• Timestamps in ISO-8601 format
• Every command output ends with [Nex HealthCheck by Nex AI | nex-ai.be]

When presenting output to the user, strip the footer line and present the information naturally.

Important Notes

• All check data is stored locally at ~/.nex-healthcheck/. No data is sent externally.
• Remote checks (Docker, systemd, disk on remote hosts) require SSH access. Configure with --ssh-host user@host.
• SSL cert checks warn at 30 days, critical at 7 days before expiry.
• Disk checks warn at 80% usage, critical at 90%.
• Default check interval is 5 minutes. Customize with --interval when adding a service.
• Telegram notifications require environment variables: HEALTHCHECK_TELEGRAM_TOKEN and HEALTHCHECK_TELEGRAM_CHAT.
• For periodic automated checks, use systemd timer (see setup.sh for optional service files).

Troubleshooting

• "dig and nslookup not found": Install bind-utils (RHEL/CentOS) or dnsutils (Debian/Ubuntu) for DNS checks.
• "docker: command not found": Install Docker or use SSH to a remote Docker host with --ssh-host.
• SSH failures: Ensure passwordless SSH is configured, or use SSH key authentication.
• Database not found: Run bash setup.sh to initialize.

Credits

Built by Nex AI (https://nex-ai.be) - Digital transformation for Belgian SMEs. Author: Kevin Blancaflor