vitals-vps 0.2.0

🩺 VPS Vital Signs Monitor — read-only SSH diagnostics with root-cause analysis

vitals-vps

Read-only SSH server diagnostics with plain-English guidance.

Connect to any Linux VPS with your root credentials, get a full colourised report on what's wrong — CPU spikes, brute-force attacks, memory pressure, disk full, zombie processes — and exact commands to fix each issue.

✅ 100% read-only. No files are created, modified, or deleted. No services are restarted. You can share root credentials safely knowing the tool cannot cause harm.

---

Install

pip install vitals-vps

Requirements: Python 3.8+, paramiko, rich

---

Usage

CLI

# Prompt for password (recommended)
vitals 192.168.1.10 --ask-pass

# Use SSH key
vitals 192.168.1.10 --key ~/.ssh/id_rsa

# Non-standard port or user
vitals 192.168.1.10 --port 2222 --user ubuntu --ask-pass

# Also show raw process lists, log excerpts, port table
vitals 192.168.1.10 --ask-pass --verbose

Python API (works in scripts, Jupyter, and Google Colab)

import vitals

# Full styled report printed to screen
vitals.info("your.server.ip", password="mypass")

# Key-based auth
vitals.info("your.server.ip", user="ubuntu", key="~/.ssh/id_rsa")

# Silent — returns Finding objects for scripting
findings = vitals.scan("your.server.ip", password="mypass")
critical = [f for f in findings if f.severity.value == "critical"]
for f in critical:
    print(f.title)

Google Colab

!pip install vitals-vps

import vitals
vitals.info("your.server.ip", password="mypass")

---

What It Checks

Category	What it looks for
CPU	Load average vs core count, CPU %, I/O wait (iowait), runaway processes
Memory	RAM %, available memory, swap usage, OOM killer events
Disk	Partitions > 80% full, inode exhaustion, largest directories, I/O stats
Network	Connection floods, top remote IPs, TIME_WAIT buildup, open ports
Security	SSH brute-force attack count, top attacking IPs, fail2ban status, firewall presence, extra UID-0 accounts, active sessions
Processes	Zombie processes, D-state (I/O-blocked) processes, failed systemd services
Logs	dmesg kernel errors, systemd journal errors, web server errors, MySQL errors

---

Sample Output

╭─────────────────────────────────────────────╮
│             System Identity                 │
│  Host     my-server.example.com            │
│  OS       Ubuntu 22.04.3 LTS               │
│  Kernel   5.15.0-89-generic                │
│  Uptime   up 12 days, 4 hours              │
│  CPU      Intel Xeon E5-2670 v2            │
│  Cores    4                                │
╰─────────────────────────────────────────────╯

┌──────────────────────────────────────────────┐
│         Diagnostic Scorecard                 │
│  Category   Status       Findings            │
│  CPU        ● CRITICAL   1 issue(s)          │
│  Memory     ● CRITICAL   2 issue(s)          │
│  Disk       ✅ OK         All clear           │
│  Network    ⚠ WARNING    1 issue(s)          │
│  Security   ● CRITICAL   2 issue(s)          │
└──────────────────────────────────────────────┘

── CPU ──────────────────────────────────────────
🔴 Extreme load average: 8.4 on 4 core(s)
  📋 1-min load=8.4, 5-min=6.2, 15-min=4.1. With 4 cores,
     the system has ~2x more runnable work than it can handle.
  💡 What to do: Identify the runaway process(es)…
  📌 Commands:
     ps aux --sort=-%cpu | head -15
     top -b -n1 | head -20

── Security ─────────────────────────────────────
🔴 Active brute-force attack: 47,312 SSH login failures
  📋 47,312 failed SSH login attempts found in auth log.
  💡 What to do:
     1. Install fail2ban immediately to auto-ban attackers.
     2. Change SSH to a non-standard port (e.g. 2222).
     3. Disable password login — use SSH keys only.
  📌 Commands:
     apt install fail2ban -y
     systemctl enable --now fail2ban

---

Safety Guarantees

• Every SSH command runs through a blocklist filter. If the command string contains anything resembling a write, delete, kill, or install operation, it raises a ValueError before sending it.
• The SSH client uses AutoAddPolicy for convenience but logs the host key. In a production hardened setup, you can supply known_hosts.
• No data is stored. The tool runs, prints, and exits.

---

Roadmap

• --output json flag for piping into alerting pipelines
• --watch mode: re-scan every N seconds
• HTML report export
• Docker container support (scan via docker exec)
• Comparison mode: scan baseline vs current and diff the findings

---

License

MIT