kevward 0.2.0__py3-none-any.whl

kevward/__init__.py

@@ -0,0 +1,11 @@
+"""kevward - defensive server hardening & patch automation for Ubuntu.
+
+A plugin-based CLI that inspects running services, reports known
+vulnerabilities and available security updates, optionally applies
+security patches / minor version upgrades, and schedules reboots.
+
+This is a *defensive* tool. It never touches remote hosts and contains
+no offensive capability.
+"""
+
+__version__ = "0.2.0"

kevward/cli.py

@@ -0,0 +1,212 @@
+"""kevward command-line interface.
+
+Subcommands:
+  check            Report findings (no changes). Default if none given.
+  plan             Alias for check, framed as "what apply would do".
+  apply            Apply security updates (and minor upgrades if policy allows).
+  report           Write an HTML posture report (+ attacker IPs, + trends).
+  trends           Show actively-exploited CVEs (CISA KEV) relevant to this host.
+  schedule-reboot  Schedule a reboot in the maintenance window.
+  list-plugins     Show discovered service plugins.
+
+Safety: `apply` changes the system and is never implied. Everything else is
+read-only. Reboots require both --reboot/`schedule-reboot` AND policy opt-in.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import Config
+from .engine import run as run_engine
+from .integrations import fail2ban, logwatch
+from .model import Severity
+from .plugin import detected_kev_terms, discover
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("-c", "--config", help="path to config.toml")
+    p.add_argument("-s", "--service", action="append", dest="services",
+                   help="limit to this service (repeatable)")
+    p.add_argument("--json", action="store_true", help="emit JSON")
+
+
+def _mkconfig(args) -> Config:
+    cfg = Config.load(getattr(args, "config", None))
+    if getattr(args, "services", None):
+        cfg.policy.services = args.services
+    return cfg
+
+
+def _collect_attackers(include_trends: bool, host_terms=None) -> dict:
+    data = {
+        "fail2ban": fail2ban.collect(),
+        "logwatch": logwatch.collect(),
+    }
+    if include_trends:
+        from .integrations import trends as trends_mod
+        data["trends"] = trends_mod.matching_trends(host_terms)
+    return data
+
+
+def _print_findings(result, use_json: bool) -> int:
+    if use_json:
+        print(result.to_json())
+    else:
+        worst = Severity.INFO
+        for svc in result.services:
+            if not svc.present:
+                continue
+            head = f"[{svc.service}]"
+            if svc.version:
+                head += f" {svc.version}"
+            print(head)
+            if svc.error:
+                print(f"  ! error: {svc.error}")
+            for f in svc.findings:
+                sev = f.severity if isinstance(f.severity, str) else f.severity.value
+                print(f"  - {sev.upper():8} {f.title}")
+                if f.severity.rank > worst.rank:
+                    worst = f.severity
+            if not svc.findings:
+                print("  ok")
+        if result.reboot_required:
+            print("\n** reboot required **")
+    # exit code reflects worst severity for CI/cron use
+    return 0
+
+
+def cmd_check(args) -> int:
+    cfg = _mkconfig(args)
+    result = run_engine(cfg, do_apply=False, dry_run=True)
+    return _print_findings(result, args.json)
+
+
+def cmd_apply(args) -> int:
+    cfg = _mkconfig(args)
+    if args.minor:
+        cfg.policy.apply_minor = True
+    dry = not args.yes
+    if dry:
+        print("DRY RUN (pass --yes to actually apply)\n")
+    result = run_engine(cfg, do_apply=True, dry_run=dry)
+    for svc in result.services:
+        for a in svc.actions:
+            tag = "would" if a.dry_run else ("ok" if a.ok else "FAIL")
+            print(f"[{svc.service}] {tag}: {a.description}")
+    if result.reboot_required:
+        if cfg.policy.allow_reboot and args.reboot and not dry:
+            from .scheduler import schedule_reboot
+            print(schedule_reboot(cfg.policy.reboot_window_start))
+        else:
+            print("\nreboot required (not scheduled; use schedule-reboot or --reboot "
+                  "with allow_reboot=true)")
+    return 0
+
+
+def cmd_report(args) -> int:
+    cfg = _mkconfig(args)
+    result = run_engine(cfg, do_apply=False, dry_run=True)
+    host_terms = detected_kev_terms(cfg.policy.services or None)
+    result.attackers = _collect_attackers(args.trends, host_terms)
+    from .reporting.html import render
+    out = Path(args.output) if args.output else cfg.report_dir / "report.html"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render(result), encoding="utf-8")
+    print(f"wrote {out}")
+    if args.json:
+        print(result.to_json())
+    return 0
+
+
+def cmd_trends(args) -> int:
+    cfg = _mkconfig(args)
+    from .integrations import trends as trends_mod
+    host_terms = detected_kev_terms(cfg.policy.services or None)
+    data = trends_mod.matching_trends(host_terms)
+    if args.json:
+        import json
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+        return 0
+    print(f"CISA KEV catalog: {data['catalog_size']} CVEs "
+          f"({'fresh' if data['cache_fresh'] else 'cached'})")
+    print(f"matched to detected software ({', '.join(host_terms)}): "
+          f"{data['match_count']} ({data['ransomware_linked']} ransomware-linked)")
+    print("note: name-level match — confirm version applicability per CVE.\n")
+    for m in data["matches"][:25]:
+        rw = " [ransomware]" if m["ransomware"] else ""
+        print(f"  {m['cve']:18} {m['vendor']}/{m['product']}  (added {m['date_added']}){rw}")
+    return 0
+
+
+def cmd_schedule_reboot(args) -> int:
+    cfg = _mkconfig(args)
+    if not cfg.policy.allow_reboot:
+        print("refused: policy.allow_reboot is false. Set it to true to permit reboots.")
+        return 2
+    from .scheduler import schedule_reboot
+    print(schedule_reboot(args.window or cfg.policy.reboot_window_start))
+    return 0
+
+
+def cmd_list_plugins(args) -> int:
+    for name, cls in sorted(discover().items()):
+        mode = "report-only" if not cls.supports_apply else "apply-capable"
+        print(f"  {name:12} {mode}  ({cls.__module__})")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="kevward", description=__doc__.split("\n")[0])
+    p.add_argument("--version", action="version", version=f"kevward {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    c = sub.add_parser("check", help="report findings (no changes)")
+    _add_common(c)
+    c.set_defaults(func=cmd_check)
+
+    pl = sub.add_parser("plan", help="alias of check")
+    _add_common(pl)
+    pl.set_defaults(func=cmd_check)
+
+    a = sub.add_parser("apply", help="apply security updates")
+    _add_common(a)
+    a.add_argument("--yes", action="store_true", help="actually apply (else dry-run)")
+    a.add_argument("--minor", action="store_true", help="also apply minor upgrades")
+    a.add_argument("--reboot", action="store_true", help="schedule reboot if required")
+    a.set_defaults(func=cmd_apply)
+
+    r = sub.add_parser("report", help="write HTML posture report")
+    _add_common(r)
+    r.add_argument("-o", "--output", help="output HTML path")
+    r.add_argument("--trends", action="store_true", help="include CISA KEV trends (network)")
+    r.set_defaults(func=cmd_report)
+
+    t = sub.add_parser("trends", help="actively-exploited CVEs relevant to host")
+    _add_common(t)
+    t.set_defaults(func=cmd_trends)
+
+    sr = sub.add_parser("schedule-reboot", help="schedule a maintenance-window reboot")
+    _add_common(sr)
+    sr.add_argument("--window", help="HH:MM local time")
+    sr.set_defaults(func=cmd_schedule_reboot)
+
+    lp = sub.add_parser("list-plugins", help="list discovered plugins")
+    _add_common(lp)
+    lp.set_defaults(func=cmd_list_plugins)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "cmd", None):
+        args = parser.parse_args((argv or []) + ["check"])
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kevward/config.py

@@ -0,0 +1,72 @@
+"""Configuration loading and the safety policy.
+
+Config is optional; sane, *safe* defaults apply when no file is present.
+Format is TOML (stdlib ``tomllib`` on 3.11+, ``tomli`` backport on 3.10).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+try:
+    import tomllib  # Python 3.11+
+except ModuleNotFoundError:  # Python 3.10: pip install tomli
+    import tomli as tomllib
+
+DEFAULT_PATHS = [
+    Path("/etc/kevward/config.toml"),
+    Path.home() / ".config" / "kevward" / "config.toml",
+    Path("kevward.toml"),
+]
+
+
+@dataclass
+class Policy:
+    """What kevward is permitted to do. Defaults are conservative."""
+
+    # Apply security updates when running `apply`.
+    apply_security: bool = True
+    # Apply non-security minor version upgrades. Off by default.
+    apply_minor: bool = False
+    # Allow kevward to reboot the host itself. Off by default: by default it
+    # only *reports* that a reboot is required, or schedules one in a window.
+    allow_reboot: bool = False
+    # Maintenance window for scheduled reboots, local time "HH:MM".
+    reboot_window_start: str = "04:00"
+    # Services to manage. Empty = all discovered plugins.
+    services: list[str] = field(default_factory=list)
+    # Per-service overrides, e.g. {"nginx": {"apply_minor": true}}.
+    overrides: dict[str, dict] = field(default_factory=dict)
+
+    def for_service(self, name: str) -> Policy:
+        ov = self.overrides.get(name)
+        if not ov:
+            return self
+        merged = {**self.__dict__, **ov}
+        merged.pop("overrides", None)
+        return Policy(**{k: v for k, v in merged.items() if k in Policy.__annotations__})
+
+
+@dataclass
+class Config:
+    policy: Policy = field(default_factory=Policy)
+    report_dir: Path = Path("/var/log/kevward")
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> Config:
+        candidates = [Path(path)] if path else DEFAULT_PATHS
+        for p in candidates:
+            if p.is_file():
+                return cls._from_file(p)
+        return cls()
+
+    @classmethod
+    def _from_file(cls, p: Path) -> Config:
+        data = tomllib.loads(p.read_text())
+        pol = data.get("policy", {})
+        policy = Policy(**{k: v for k, v in pol.items() if k in Policy.__annotations__})
+        cfg = cls(policy=policy)
+        if "report_dir" in data:
+            cfg.report_dir = Path(data["report_dir"])
+        return cfg

kevward/engine.py

@@ -0,0 +1,56 @@
+"""Runs plugins according to policy and produces an aggregate run result."""
+
+from __future__ import annotations
+
+import json
+import platform
+import socket
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from .config import Config
+from .model import ServiceReport
+from .plugin import load
+
+
+@dataclass
+class RunResult:
+    host: str
+    generated_at: str
+    os: str
+    services: list[ServiceReport] = field(default_factory=list)
+    attackers: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def reboot_required(self) -> bool:
+        return any(s.reboot_required for s in self.services)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "host": self.host,
+            "generated_at": self.generated_at,
+            "os": self.os,
+            "reboot_required": self.reboot_required,
+            "services": [s.to_dict() for s in self.services],
+            "attackers": self.attackers,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+
+def run(cfg: Config, do_apply: bool = False, dry_run: bool = True) -> RunResult:
+    only = cfg.policy.services or None
+    plugins = load(only)
+    result = RunResult(
+        host=socket.gethostname(),
+        generated_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        os=f"{platform.system()} {platform.release()}",
+    )
+    for p in plugins:
+        sp = cfg.policy.for_service(p.name)
+        # Respect per-service apply gating by temporarily narrowing intent.
+        apply_this = do_apply and (sp.apply_security or sp.apply_minor)
+        result.services.append(p.report(do_apply=apply_this, dry_run=dry_run))
+    return result

kevward/integrations/__init__.py

@@ -0,0 +1 @@
+"""External signal integrations: attacker telemetry and threat-trend feeds."""

kevward/integrations/fail2ban.py

@@ -0,0 +1,77 @@
+"""Collect banned-IP telemetry from fail2ban.
+
+Prefers `fail2ban-client` (authoritative current state); falls back to parsing
+the fail2ban log for a historical view of bans over time.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+
+from ..util import have, is_root, run
+
+_BAN_LINE = re.compile(
+    r"(?P<ts>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}).*?\bBan\b\s+(?P<ip>\d{1,3}(?:\.\d{1,3}){3}|[0-9a-fA-F:]+)"  # noqa: E501
+)
+
+
+def _jails() -> list[str]:
+    res = run(["fail2ban-client", "status"], timeout=20)
+    if not res.ok:
+        return []
+    m = re.search(r"Jail list:\s*(.+)", res.out)
+    if not m:
+        return []
+    return [j.strip() for j in m.group(1).split(",") if j.strip()]
+
+
+def currently_banned() -> dict[str, list[str]]:
+    """{jail: [ip, ...]} of IPs banned right now. Needs fail2ban-client + root."""
+    out: dict[str, list[str]] = {}
+    if not (have("fail2ban-client") and is_root()):
+        return out
+    for jail in _jails():
+        res = run(["fail2ban-client", "status", jail], timeout=20)
+        if not res.ok:
+            continue
+        m = re.search(r"Banned IP list:\s*(.*)", res.out)
+        ips = m.group(1).split() if m else []
+        out[jail] = ips
+    return out
+
+
+def historical_bans(log_glob: str = "/var/log/fail2ban.log*") -> Counter:
+    """Count Ban events per IP across (possibly rotated) fail2ban logs."""
+    counts: Counter = Counter()
+    import gzip
+    from glob import glob
+
+    for path in sorted(glob(log_glob)):
+        p = Path(path)
+        try:
+            opener = gzip.open if p.suffix == ".gz" else open
+            with opener(p, "rt", errors="ignore") as fh:  # type: ignore[operator]
+                for line in fh:
+                    m = _BAN_LINE.search(line)
+                    if m:
+                        counts[m.group("ip")] += 1
+        except OSError:
+            continue
+    return counts
+
+
+def collect() -> dict:
+    """Aggregate fail2ban telemetry for the report layer."""
+    live = currently_banned()
+    hist = historical_bans()
+    live_total = sum(len(v) for v in live.values())
+    return {
+        "available": have("fail2ban-client"),
+        "live_by_jail": live,
+        "live_total": live_total,
+        "top_offenders": hist.most_common(50),
+        "unique_ips": len(hist),
+        "total_ban_events": sum(hist.values()),
+    }

kevward/integrations/logwatch.py

@@ -0,0 +1,55 @@
+"""Lightweight attacker signal from auth logs (logwatch-style, no dependency).
+
+If `logwatch` is installed we capture its summary; independently we parse
+sshd auth failures directly so the report works even without logwatch.
+"""
+
+from __future__ import annotations
+
+import gzip
+import re
+from collections import Counter
+from glob import glob
+from pathlib import Path
+
+from ..util import have, run
+
+_IP = r"(\d{1,3}(?:\.\d{1,3}){3}|[0-9a-fA-F:]{3,})"
+_FAILED = re.compile(rf"Failed password for .*? from {_IP}")
+_INVALID = re.compile(rf"Invalid user \S+ from {_IP}")
+
+
+def ssh_auth_failures(log_glob: str = "/var/log/auth.log*") -> Counter:
+    counts: Counter = Counter()
+    for path in sorted(glob(log_glob)):
+        p = Path(path)
+        try:
+            opener = gzip.open if p.suffix == ".gz" else open
+            with opener(p, "rt", errors="ignore") as fh:  # type: ignore[operator]
+                for line in fh:
+                    m = _FAILED.search(line) or _INVALID.search(line)
+                    if m:
+                        counts[m.group(1)] += 1
+        except OSError:
+            continue
+    return counts
+
+
+def logwatch_summary() -> str | None:
+    if not have("logwatch"):
+        return None
+    res = run(
+        ["logwatch", "--range", "yesterday", "--service", "sshd", "--output", "stdout"],
+        timeout=120,
+    )
+    return res.out if res.ok else None
+
+
+def collect() -> dict:
+    fails = ssh_auth_failures()
+    return {
+        "logwatch_available": have("logwatch"),
+        "ssh_failed_logins": fails.most_common(50),
+        "ssh_unique_sources": len(fails),
+        "ssh_total_attempts": sum(fails.values()),
+    }

kevward/integrations/trends.py

@@ -0,0 +1,118 @@
+"""Recent attack-trend awareness.
+
+Pulls CISA's Known Exploited Vulnerabilities (KEV) catalog — the authoritative
+list of CVEs *observed being exploited in the wild* — and cross-references it
+against software detected on this host. The point is to answer the operator's
+real question: "of everything being actively attacked right now, does any of it
+apply to me?"
+
+Network access is required and entirely opt-in (``kevward trends`` or
+``report --trends``). The feed URL is configurable; results are cached so an
+offline/locked-down host can still use the last snapshot.
+
+No credentials, no outbound host data: this only downloads a public catalog.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+KEV_URL = (
+    "https://www.cisa.gov/sites/default/files/feeds/"
+    "known_exploited_vulnerabilities.json"
+)
+CACHE = Path("/var/cache/kevward/kev.json")
+CACHE_TTL = 6 * 3600  # seconds
+
+
+@dataclass
+class KevEntry:
+    cve: str
+    vendor: str
+    product: str
+    name: str
+    date_added: str
+    due_date: str
+    ransomware: bool
+
+    @classmethod
+    def from_raw(cls, d: dict) -> KevEntry:
+        return cls(
+            cve=d.get("cveID", ""),
+            vendor=(d.get("vendorProject") or "").lower(),
+            product=(d.get("product") or "").lower(),
+            name=d.get("vulnerabilityName", ""),
+            date_added=d.get("dateAdded", ""),
+            due_date=d.get("dueDate", ""),
+            ransomware=(d.get("knownRansomwareCampaignUse", "") or "").lower() == "known",
+        )
+
+
+def _load_catalog(url: str = KEV_URL, timeout: int = 30) -> list[KevEntry]:
+    """Fetch the KEV catalog, falling back to cache on any network error."""
+    raw: dict | None = None
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "kevward"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw = json.loads(resp.read().decode("utf-8"))
+        try:
+            CACHE.parent.mkdir(parents=True, exist_ok=True)
+            CACHE.write_text(json.dumps(raw))
+        except OSError:
+            pass
+    except Exception:
+        if CACHE.is_file():
+            raw = json.loads(CACHE.read_text())
+    if not raw:
+        return []
+    return [KevEntry.from_raw(v) for v in raw.get("vulnerabilities", [])]
+
+
+def _cache_fresh() -> bool:
+    try:
+        return CACHE.is_file() and (time.time() - CACHE.stat().st_mtime) < CACHE_TTL
+    except OSError:
+        return False
+
+
+# Keywords describing software this host may run, mapped to KEV vendor/product
+# substrings. Extend freely — matching is deliberately broad, then surfaced for
+# a human to judge rather than acted on automatically.
+_HOST_KEYWORDS = [
+    "nginx", "apache", "php", "openssh", "openssl", "wordpress", "node",
+    "nodejs", "laravel", "linux", "ubuntu", "mysql", "mariadb", "postgres",
+    "redis", "docker", "fortinet", "cisco", "citrix", "vmware",
+]
+
+
+def matching_trends(
+    host_terms: list[str] | None = None,
+    url: str = KEV_URL,
+) -> dict:
+    """Return KEV entries plausibly relevant to this host, plus summary stats.
+
+    ``host_terms`` lets callers pass detected product names (e.g. from the
+    service plugins). When omitted, a broad built-in keyword list is used.
+    """
+    catalog = _load_catalog(url)
+    terms = [t.lower() for t in (host_terms or _HOST_KEYWORDS)]
+    hits: list[KevEntry] = []
+    for e in catalog:
+        # Match only on vendor/product, never the free-text vulnerability name:
+        # a name like "...PHP Remote File Inclusion" for a Zimbra/Juniper CVE
+        # would otherwise false-match a host that merely runs PHP.
+        hay = f"{e.vendor} {e.product}".lower()
+        if any(t in hay for t in terms):
+            hits.append(e)
+    hits.sort(key=lambda e: e.date_added, reverse=True)
+    return {
+        "catalog_size": len(catalog),
+        "cache_fresh": _cache_fresh(),
+        "match_count": len(hits),
+        "ransomware_linked": sum(1 for e in hits if e.ransomware),
+        "matches": [e.__dict__ for e in hits[:100]],
+    }