vitals-vps 0.2.0__tar.gz

vitals_vps-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suriya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be 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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vitals_vps-0.2.0/PKG-INFO

@@ -0,0 +1,191 @@
+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

vitals_vps-0.2.0/README.md

@@ -0,0 +1,153 @@
+# 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

vitals_vps-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vitals_vps-0.2.0/setup.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+from setuptools import setup, find_packages
+
+long_description = (Path(__file__).parent / "README.md").read_text(encoding="utf-8")
+
+setup(
+    name="vitals-vps",                  # <-- change if you prefer another name
+    version="0.2.0",
+    description="🩺 VPS Vital Signs Monitor — read-only SSH diagnostics with root-cause analysis",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+
+    author="Suriya",
+    author_email="suriyakumar.vijayanayagam@gmail.com",
+    python_requires=">=3.8",
+    packages=find_packages(exclude=["tests*"]),
+    install_requires=[
+        "paramiko>=3.0.0",
+        "rich>=13.0.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "vitals=vitals.cli:main",
+        ],
+    },
+
+    keywords=["vps", "ssh", "diagnostics", "devops", "server", "monitoring", "cli"],
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Environment :: Console",
+        "Intended Audience :: Developers",
+        "Intended Audience :: System Administrators",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Operating System :: OS Independent",
+        "Topic :: System :: Systems Administration",
+        "Topic :: System :: Monitoring",
+        "Topic :: Utilities",
+    ],
+)

vitals_vps-0.2.0/tests/test_analyzers.py

@@ -0,0 +1,111 @@
+"""Tests for analyzers using mock data — no real SSH connection needed."""
+
+import pytest
+from vitals.analyzers.cpu import analyze_cpu
+from vitals.analyzers.memory import analyze_memory
+from vitals.analyzers.disk import analyze_disk
+from vitals.analyzers.security import analyze_security
+from vitals.models import Severity
+
+
+# ── CPU ──────────────────────────────────────────────────────────────────────
+
+def test_cpu_ok():
+    findings = analyze_cpu({"load_1": 0.5, "load_5": 0.4, "load_15": 0.3, "cores": 4}, {})
+    assert any(f.severity == Severity.OK for f in findings)
+
+
+def test_cpu_critical_load():
+    findings = analyze_cpu({"load_1": 16.0, "load_5": 14.0, "load_15": 10.0, "cores": 4}, {})
+    assert any(f.severity == Severity.CRITICAL for f in findings)
+
+
+def test_cpu_high_iowait():
+    findings = analyze_cpu({
+        "load_1": 1.0, "load_5": 1.0, "load_15": 1.0, "cores": 4,
+        "vmstat": "0 0 0 100000 1000 200000 0 0 0 0 100 200 5 2 57 36 0",
+    }, {})
+    assert any("I/O wait" in f.title for f in findings)
+
+
+# ── Memory ───────────────────────────────────────────────────────────────────
+
+def test_memory_ok():
+    findings = analyze_memory({
+        "ram_pct": 40, "ram_total_mb": 4096, "ram_avail_mb": 2400,
+        "swap_pct": 0, "swap_used_mb": 0, "swap_total_mb": 2048,
+        "oom_events": "",
+    })
+    assert any(f.severity == Severity.OK for f in findings)
+
+
+def test_memory_critical():
+    findings = analyze_memory({
+        "ram_pct": 95, "ram_total_mb": 1024, "ram_avail_mb": 50,
+        "swap_pct": 90, "swap_used_mb": 1800, "swap_total_mb": 2048,
+        "oom_events": "oom-killer invoked",
+    })
+    severities = [f.severity for f in findings]
+    assert Severity.CRITICAL in severities
+
+
+def test_no_swap_warning():
+    findings = analyze_memory({
+        "ram_pct": 40, "ram_total_mb": 4096, "ram_avail_mb": 2400,
+        "swap_pct": 0, "swap_used_mb": 0, "swap_total_mb": 0,
+        "oom_events": "",
+    })
+    assert any("swap" in f.title.lower() or "swap" in f.recommendation.lower() for f in findings)
+
+
+# ── Disk ─────────────────────────────────────────────────────────────────────
+
+def test_disk_ok():
+    findings = analyze_disk({"critical_mounts": [], "df_inodes": ""})
+    assert any(f.severity == Severity.OK for f in findings)
+
+
+def test_disk_critical():
+    findings = analyze_disk({
+        "critical_mounts": [{"mount": "/", "pct": 97, "avail": "500M"}],
+        "df_inodes": "",
+    })
+    assert any(f.severity == Severity.CRITICAL for f in findings)
+
+
+# ── Security ─────────────────────────────────────────────────────────────────
+
+def test_security_brute_force():
+    findings = analyze_security({
+        "total_auth_failures": 50000,
+        "top_attacking_ips": "  500 1.2.3.4\n  300 5.6.7.8",
+        "uid0_users": "root",
+        "fail2ban_status": "active",
+        "firewall_rules": "Chain INPUT (policy DROP)",
+        "logged_in_users": "root pts/0",
+    })
+    assert any(f.severity == Severity.CRITICAL and "brute" in f.title.lower() for f in findings)
+
+
+def test_security_extra_uid0():
+    findings = analyze_security({
+        "total_auth_failures": 0,
+        "top_attacking_ips": "",
+        "uid0_users": "root\nhacker",
+        "fail2ban_status": "active",
+        "firewall_rules": "iptables rules here",
+        "logged_in_users": "",
+    })
+    assert any("UID 0" in f.title for f in findings)
+
+
+def test_no_fail2ban():
+    findings = analyze_security({
+        "total_auth_failures": 0,
+        "top_attacking_ips": "",
+        "uid0_users": "root",
+        "fail2ban_status": "not found",
+        "firewall_rules": "iptables rules here",
+        "logged_in_users": "",
+    })
+    assert any("fail2ban" in f.title.lower() for f in findings)