Metadata-Version: 2.4
Name: vitals-vps
Version: 0.2.0
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

# 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

```bash
pip install vitals-vps
```


**Requirements:** Python 3.8+, `paramiko`, `rich`

---

## Usage

### CLI

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

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

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