vitals-vps 0.2.1

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

🩺 vitals-vps

Read-only SSH server diagnostics with plain-English root-cause analysis.

---

Connect to any Linux VPS with your root credentials and get an instant, full-colour report on what's going wrong. vitals-vps acts as an automated system administrator, identifying CPU spikes, active brute-force attacks, memory pressure, disk exhaustion, and zombie processes—and gives you the exact commands to fix them.

✅ 100% Safe & Read-Only: Every command is strictly filtered through a safety blocklist. No files are created, modified, or deleted. No services are restarted.

---

🚀 Installation

Install globally via pip:

pip install vitals-vps

(Requires Python 3.8+, paramiko, and rich)

---

💻 Usage

You can use vitals-vps straight from your terminal or programmatically via Python.

Terminal CLI

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

# Use an SSH key instead of a password
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

# Verbose mode: Also show raw process lists, log excerpts, and port tables
vitals 192.168.1.10 --ask-pass --verbose

Python API (Jupyter / Scripts / Google Colab)

Perfect for integrating into automated monitoring dashboards or running from Jupyter Notebooks.

import vitals

# Print the full styled report to your screen
vitals.info("192.168.1.10", password="mypassword")

# Use key-based authentication
vitals.info("192.168.1.10", user="ubuntu", key="~/.ssh/id_rsa")

# Silent execution: Returns a list of Finding objects for automation
findings = vitals.scan("192.168.1.10", password="mypassword")

critical_issues = [f for f in findings if f.severity.value == "critical"]
for issue in critical_issues:
    print(f"Alert: {issue.title}")

---

🔍 What It Checks

Category	Diagnostic Targets
⚡ CPU	Load average vs core count, CPU utilization %, I/O wait (iowait), runaway background processes.
🧠 Memory	RAM allocation, available memory, swap usage, and recent OOM (Out-of-Memory) killer events.
💽 Disk	Partitions > 80% full, inode exhaustion, largest hidden directories, disk I/O bottlenecks.
🌐 Network	Connection floods, top remote IPs, TIME_WAIT socket buildup, and open listening ports.
🛡️ Security	SSH brute-force attacks, top attacking IPs, fail2ban status, firewall presence, active sessions, and unauthorized UID-0 accounts.
⚙️ Processes	Zombie processes, D-state (I/O-blocked) processes, and failed systemd services.
📜 Logs	dmesg kernel errors, systemd journal errors, and web server / database error logs.

---

📊 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

• Hardware Level Guard: Every SSH command runs through a rigorous blocklist filter. If a command string contains anything resembling a write, delete, kill, or install operation, it immediately raises a ValueError before sending it to your server.
• No Artifacts Left Behind: No temporary data is written to disk. The tool runs entirely in memory, prints the results, and cleanly closes the SSH connection.
• Secure Key Management: The SSH client leverages AutoAddPolicy for seamless connections, but strictly logs host keys to prevent man-in-the-middle attacks.

---

🗺️ Roadmap

• --output json flag for piping directly into CI/CD or alerting pipelines
• --watch mode: re-scan every N seconds for live monitoring
• HTML report export for client delivery
• Docker container support (scan via docker exec)
• Baseline comparison mode: diff current findings against a historical baseline

---

⚖️ License

This project is licensed under the MIT License.

You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software in both private and commercial environments, provided that the original copyright notice and permission notice are included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.