Metadata-Version: 2.4
Name: vitals-vps
Version: 0.2.4
Summary: 🩺 VPS Vital Signs Monitor — read-only SSH diagnostics with root-cause analysis
Author: Suriya
Author-email: suriyakumar.vijayanayagam@gmail.com
Keywords: vps,ssh,diagnostics,devops,server,monitoring,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: paramiko>=3.0.0
Requires-Dist: rich>=13.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">
  <h1>🩺 vitals-vps</h1>
  <p><strong>Read-only SSH server diagnostics with plain-English root-cause analysis.</strong></p>

  [![PyPI Version](https://img.shields.io/pypi/v/vitals-vps.svg)](https://pypi.org/project/vitals-vps/)
  [![Python Support](https://img.shields.io/pypi/pyversions/vitals-vps.svg)](https://pypi.org/project/vitals-vps/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#-license)
</div>

---

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`:

```bash
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

```bash
# 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.

```python
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

```text
╭─────────────────────────────────────────────╮
│             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.*
