umbermark-cli 1.0.0rc1__py3-none-any.whl

umbermark/checks/world_writable_suid_audit.py

@@ -0,0 +1,171 @@
+"""Audit world-writable files (outside /tmp) + non-standard SUID binaries.
+
+Both are well-known privilege-escalation vectors. World-writable files in
+unexpected places are usually misconfigurations; SUID binaries outside the
+distro's standard set deserve scrutiny because each one is a potential
+local exploit if it has bugs.
+
+Each find is wrapped in `timeout 20` (in the command string, so the Tier-2
+collector script inherits it); on timeout, partial output is kept and the
+evidence is marked "partial — timed out". On a busy server the whole-tree
+scan can take a while. Output is capped at 100 / 200 lines respectively.
+"""
+from __future__ import annotations
+
+from umbermark.core.check import Check, Finding, Severity, Verdict
+from umbermark.core.ssh import CommandRunner
+
+# Standard SUID binaries on Debian/Ubuntu + RHEL family. Anything outside this
+# set is flagged as "non-standard" and worth a manual look — it might be
+# legitimate (e.g. a custom tool), but the operator should know it's there.
+_EXPECTED_SUID_ALLOWLIST = {
+    # core identity / auth
+    "/usr/bin/sudo", "/usr/bin/su", "/usr/bin/passwd",
+    "/usr/bin/chsh", "/usr/bin/chfn", "/usr/bin/newgrp", "/usr/bin/gpasswd",
+    "/usr/bin/expiry",
+    # rootless-container helpers (the `uidmap` package; required by rootless podman)
+    "/usr/bin/newuidmap", "/usr/bin/newgidmap",
+    "/bin/newuidmap", "/bin/newgidmap",
+    # mount / unmount (often setuid for non-root)
+    "/usr/bin/mount", "/usr/bin/umount",
+    "/usr/bin/fusermount", "/usr/bin/fusermount3",
+    "/bin/mount", "/bin/umount", "/bin/fusermount",
+    # network utilities
+    "/usr/bin/ping", "/bin/ping",
+    # legacy utilities
+    "/usr/bin/wall", "/usr/bin/write", "/usr/bin/at", "/usr/bin/crontab",
+    # ssh keysign + dbus / polkit
+    "/usr/lib/openssh/ssh-keysign",
+    "/usr/lib/policykit-1/polkit-agent-helper-1",
+    "/usr/lib/polkit-1/polkit-agent-helper-1",
+    "/usr/lib/dbus-1.0/dbus-daemon-launch-helper",
+    "/usr/libexec/dbus-1/dbus-daemon-launch-helper",
+    "/usr/libexec/polkit-agent-helper-1",
+    # RHEL/Rocky-specific
+    "/usr/sbin/pam_timestamp_check", "/usr/sbin/unix_chkpwd",
+    "/usr/sbin/userhelper",
+    "/usr/sbin/mount.nfs",
+    # mail
+    "/usr/sbin/exim4",
+    "/usr/sbin/postdrop", "/usr/sbin/postqueue",
+    "/usr/sbin/sendmail.postfix",
+    # browsers / containers
+    "/opt/google/chrome/chrome-sandbox",
+    "/usr/lib/chromium/chrome-sandbox",
+    "/usr/lib/firefox/firefox",  # rare but shipped on some distros
+    # snap
+    "/snap/core/current/usr/lib/snapd/snap-confine",
+    "/usr/lib/snapd/snap-confine",
+    # vmware / parallels guest tools (common on cloud VMs)
+    "/usr/lib/vmware-tools/sbin/vmware-checkvm",
+}
+
+
+# SUID files inside rootless-container image layers are owned by sub-uids (not
+# host root) and live in a user namespace, so they give no host escalation.
+_ROOTLESS_CONTAINER_STORAGE = "/.local/share/containers/storage/"
+
+
+class WorldWritableSuidAuditCheck(Check):
+    id = "world_writable_suid_audit"
+    title = "World-writable files + non-standard SUID binaries audit"
+    category = "filesystem"
+    severity = Severity.HIGH
+    weight = 9
+    applicable_distros = ()
+    remediation = (
+        "Investigate each entry:\n"
+        "  World-writable outside /tmp + /var/tmp + /dev/shm is usually a\n"
+        "    misconfiguration — fix with: chmod o-w <path>\n"
+        "  SUID binaries not on the standard distro set are potential local\n"
+        "    privilege-escalation surface. If you didn't intentionally install\n"
+        "    them, strip the SUID bit: chmod u-s <path>\n"
+        "  If a non-standard SUID IS intentional (custom helper, third-party\n"
+        "    software), that's fine — the report is informational."
+    )
+
+    # Each find is bounded by coreutils `timeout` INSIDE the command string, so
+    # the Tier-2 collector script (generated from these strings) inherits the
+    # bound -- it has no other timeout. The pipeline's exit status is `head`'s,
+    # so a `find` killed by `timeout` (exit 124) would be invisible; the brace
+    # group therefore echoes a marker line when that happens. `sh -c` keeps the
+    # command a single simple command so the runner's `sudo -n ` prefix applies
+    # to the whole thing. Patterns use double quotes to nest in the outer '...'.
+    _FIND_TIMEOUT_SECS = 20
+    _TIMEOUT_MARKER = "__UMBERMARK_FIND_TIMEOUT__"
+    _FIND_WW = (
+        "sh -c '{ timeout 20 find / -xdev -type f -perm -2 "
+        '! -path "/tmp/*" ! -path "/var/tmp/*" ! -path "/dev/shm/*" '
+        '! -path "/proc/*" ! -path "/sys/*" 2>/dev/null; '
+        "[ $? -eq 124 ] && echo __UMBERMARK_FIND_TIMEOUT__; } | head -100'"
+    )
+    _FIND_SUID = (
+        "sh -c '{ timeout 20 find / -xdev -type f -perm -4000 "
+        '! -path "/proc/*" ! -path "/sys/*" 2>/dev/null; '
+        "[ $? -eq 124 ] && echo __UMBERMARK_FIND_TIMEOUT__; } | head -200'"
+    )
+
+    def _parse(self, res) -> tuple[list[str], bool, bool]:
+        """Return (lines, timed_out, usable) for one find result.
+
+        Timed out = marker line in stdout, or the runner itself reported exit
+        124. Usable = clean exit, or a timeout that still left partial output.
+        """
+        raw = [ln.strip() for ln in (res.stdout or "").splitlines() if ln.strip()]
+        lines = [ln for ln in raw if ln != self._TIMEOUT_MARKER]
+        timed_out = len(lines) != len(raw) or res.exit_code == 124
+        usable = res.ok or (res.exit_code == 124 and bool(lines))
+        return lines, timed_out, usable
+
+    def run(self, runner: CommandRunner) -> Finding:
+        rww = runner.run(self._FIND_WW, sudo=True, timeout=30)
+        rsu = runner.run(self._FIND_SUID, sudo=True, timeout=30)
+        # Pipeline exit is head's (0) even on permission denied or no matches,
+        # so "usable" = clean exit, or timeout (124) that left partial output.
+        ww_lines, ww_to, ww_ok = self._parse(rww)
+        suid_lines, suid_to, suid_ok = self._parse(rsu)
+        if not (ww_ok or suid_ok):
+            return self._finding(
+                Verdict.SKIP,
+                skip_reason="find produced no output (likely timeout — see --timeout flag)",
+            )
+        partial = ww_to or suid_to
+        if partial and not (ww_lines or suid_lines):
+            return self._finding(
+                Verdict.SKIP,
+                skip_reason="find timed out before producing any results",
+            )
+        note = " [partial — timed out]" if partial else ""
+        container_suid = [s for s in suid_lines if _ROOTLESS_CONTAINER_STORAGE in s]
+        unexpected_suid = [
+            s for s in suid_lines
+            if s not in _EXPECTED_SUID_ALLOWLIST and _ROOTLESS_CONTAINER_STORAGE not in s
+        ]
+        if container_suid:
+            note += f" [{len(container_suid)} SUID file(s) in rootless container storage ignored]"
+        problems = len(ww_lines) + len(unexpected_suid)
+
+        if problems == 0:
+            return self._finding(
+                Verdict.PASS,
+                evidence=(
+                    f"0 unexpected world-writable, 0 non-standard SUID "
+                    f"(of {len(suid_lines)} total SUID — all on allow-list or in rootless container storage)"
+                    f"{note}"
+                ),
+            )
+        parts: list[str] = []
+        if ww_lines:
+            parts.append(
+                f"{len(ww_lines)} world-writable: {', '.join(ww_lines[:3])}"
+                + (f" (+{len(ww_lines) - 3} more)" if len(ww_lines) > 3 else "")
+            )
+        if unexpected_suid:
+            parts.append(
+                f"{len(unexpected_suid)} non-standard SUID: {', '.join(unexpected_suid[:3])}"
+                + (f" (+{len(unexpected_suid) - 3} more)" if len(unexpected_suid) > 3 else "")
+            )
+        evidence = "; ".join(parts) + note
+        if problems <= 5:
+            return self._finding(Verdict.WARN, evidence=evidence)
+        return self._finding(Verdict.FAIL, evidence=evidence)

umbermark/cli/__init__.py

@@ -0,0 +1,4 @@
+"""Umbermark CLI package."""
+from umbermark.cli.app import app
+
+__all__ = ["app"]

umbermark/cli/app.py

@@ -0,0 +1,23 @@
+"""Umbermark CLI (Typer)."""
+from __future__ import annotations
+
+import typer
+
+from umbermark.cli.commands import doctor as doctor_cmd
+from umbermark.cli.commands import login as login_cmd
+from umbermark.cli.commands import push as push_cmd
+from umbermark.cli.commands import report as report_cmd
+from umbermark.cli.commands import scan as scan_cmd
+from umbermark.cli.commands import scan_local as scan_local_cmd
+from umbermark.cli.commands import scan_wsl as scan_wsl_cmd
+from umbermark.cli.commands import version as version_cmd
+
+app = typer.Typer(name="umbermark", help="Linux server hardening scanner.")
+app.command(name="version")(version_cmd.version)
+app.command(name="doctor")(doctor_cmd.doctor)
+app.command(name="login")(login_cmd.login)
+app.command(name="push")(push_cmd.push)
+app.command(name="scan")(scan_cmd.scan)
+app.command(name="scan-wsl")(scan_wsl_cmd.scan_wsl)
+app.command(name="scan-local")(scan_local_cmd.scan_local)
+app.command(name="report")(report_cmd.report)

umbermark/cli/auth.py

@@ -0,0 +1,44 @@
+"""CLI token storage.
+
+Token is the API bearer token issued by /cli/login/callback. Stored
+at ~/.config/umbermark/token on POSIX, %APPDATA%\\umbermark\\token on
+Windows. File is created with 0o600 perms on POSIX.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def default_token_path() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA")
+        if base:
+            return Path(base) / "umbermark" / "token"
+        return Path.home() / "AppData" / "Roaming" / "umbermark" / "token"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "umbermark" / "token"
+
+
+def save_token(token: str, *, token_path: Path | None = None) -> Path:
+    p = token_path or default_token_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(token, encoding="utf-8")
+    if sys.platform != "win32":
+        p.chmod(0o600)
+    return p
+
+
+def load_token(*, token_path: Path | None = None) -> str | None:
+    p = token_path or default_token_path()
+    if not p.exists():
+        return None
+    return p.read_text(encoding="utf-8").strip() or None
+
+
+def clear_token(*, token_path: Path | None = None) -> None:
+    p = token_path or default_token_path()
+    if p.exists():
+        p.unlink()

umbermark/cli/commands/doctor.py

@@ -0,0 +1,16 @@
+"""`umbermark doctor` — environment + token sanity check."""
+from __future__ import annotations
+
+import typer
+
+from umbermark.cli.auth import default_token_path, load_token
+from umbermark.cli.config import resolve_api_url
+
+
+def doctor() -> None:
+    """Print CLI environment state (api URL, token presence)."""
+    api = resolve_api_url(flag=None)
+    typer.echo(f"api_url: {api}")
+    token_path = default_token_path()
+    typer.echo(f"token_path: {token_path}")
+    typer.echo(f"token_present: {load_token() is not None}")

umbermark/cli/commands/login.py

@@ -0,0 +1,80 @@
+"""`umbermark login` — browser-based token exchange.
+
+Binds 127.0.0.1:<random port>, opens browser to /cli/login/start, blocks
+until the browser hits the loopback callback with a token, saves it.
+"""
+from __future__ import annotations
+
+import secrets
+import threading
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+import typer
+
+from umbermark.cli.auth import save_token
+from umbermark.cli.config import resolve_api_url
+
+
+def run_login_flow(
+    *,
+    api_url: str,
+    token_path: Path | None = None,
+    timeout_seconds: int = 120,
+) -> None:
+    state = secrets.token_urlsafe(16)
+    captured: dict = {}
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *args, **kwargs):  # silence stderr
+            return
+
+        def do_GET(self):
+            parsed = urllib.parse.urlparse(self.path)
+            qs = urllib.parse.parse_qs(parsed.query)
+            captured["token"] = (qs.get("token") or [""])[0]
+            captured["state"] = (qs.get("state") or [""])[0]
+            done = (qs.get("done_url") or [""])[0]
+            if done:
+                self.send_response(302)
+                self.send_header("Location", done)
+                self.end_headers()
+            else:
+                self.send_response(200)
+                self.send_header("Content-Type", "text/plain; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(b"You can close this tab.")
+
+    server = HTTPServer(("127.0.0.1", 0), Handler)
+    port = server.server_address[1]
+    server_thread = threading.Thread(target=server.handle_request, daemon=True)
+    server_thread.start()
+
+    cb = f"http://127.0.0.1:{port}/cb"
+    url = f"{api_url}/cli/login/start?" + urllib.parse.urlencode(
+        {"cb": cb, "state": state}
+    )
+    webbrowser.open(url)
+
+    server_thread.join(timeout=timeout_seconds)
+    server.server_close()
+
+    if not captured.get("token"):
+        raise RuntimeError("Login timed out before browser callback completed.")
+    if captured.get("state") != state:
+        raise RuntimeError("CLI login state mismatch — possible CSRF.")
+    save_token(captured["token"], token_path=token_path)
+
+
+def login(
+    api_url: str = typer.Option(
+        None, "--api-url", help="Override umbermark API base URL"
+    ),
+) -> None:
+    """Open a browser and store the issued API token."""
+    resolved = resolve_api_url(flag=api_url)
+    typer.echo(f"Opening {resolved} in your browser...")
+    run_login_flow(api_url=resolved)
+    typer.echo("Saved API token. You can now run `umbermark push`.")

umbermark/cli/commands/push.py

@@ -0,0 +1,54 @@
+"""`umbermark push REPORT.json` — upload a local report to the SaaS."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import httpx
+import typer
+
+from umbermark.cli.auth import load_token
+from umbermark.cli.config import resolve_api_url
+
+
+def _make_client(*, base_url: str) -> httpx.Client:
+    return httpx.Client(base_url=base_url, timeout=30.0)
+
+
+def push(
+    report: str = typer.Argument(
+        ..., help="Path to a Report-v1.0 JSON file (or - for stdin)"
+    ),
+    api_url: str = typer.Option(None, "--api-url"),
+    token_path: str | None = typer.Option(None, "--token-file", hidden=True),
+) -> None:
+    """Upload a local scan report to the SaaS."""
+    api = resolve_api_url(flag=api_url)
+    tok = load_token(token_path=Path(token_path) if token_path else None)
+    if not tok:
+        typer.secho(
+            "Not logged in. Run `umbermark login` first.", err=True, fg="red"
+        )
+        raise typer.Exit(code=2)
+
+    if report == "-":
+        payload = json.load(sys.stdin)
+    else:
+        payload = json.loads(Path(report).read_text(encoding="utf-8"))
+
+    with _make_client(base_url=api) as c:
+        r = c.post(
+            "/api/push",
+            json=payload,
+            headers={"Authorization": f"Bearer {tok}"},
+        )
+        if r.status_code >= 400:
+            typer.secho(
+                f"Push failed: HTTP {r.status_code} - {r.text}",
+                err=True,
+                fg="red",
+            )
+            raise typer.Exit(code=1)
+        body = r.json()
+        typer.echo(f"Pushed. {body['url']}")

umbermark/cli/commands/report.py

@@ -0,0 +1,26 @@
+"""`umbermark report REPORT.json` — render a local Report-v1.0 JSON as HTML."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import typer
+
+from umbermark.core.html_report import render_owner_html_from_payload
+
+
+def report(
+    report_path: str = typer.Argument(..., help="Path to a Report-v1.0 JSON file"),
+    output: str | None = typer.Option(
+        None, "-o", "--output", help="Write HTML to file (default: stdout)"
+    ),
+) -> None:
+    """Render a Report-v1.0 JSON to HTML."""
+    payload = json.loads(Path(report_path).read_text(encoding="utf-8"))
+    target = payload.get("target", "<unknown>")
+    html = render_owner_html_from_payload(payload, target=target)
+    if output:
+        Path(output).write_text(html, encoding="utf-8")
+    else:
+        sys.stdout.write(html)

umbermark/cli/commands/scan.py

@@ -0,0 +1,77 @@
+"""`umbermark scan HOST --user U --key PATH` — SSH scan emitting Report-v1.0 JSON."""
+from __future__ import annotations
+
+import dataclasses
+import json
+from pathlib import Path
+
+import typer
+
+import umbermark
+from umbermark.checks import ALL_CHECKS
+from umbermark.core.engine import run_scan
+
+
+def _build_runner(host: str, user: str, key_path: str):
+    """Construct a ParamikoRunner. Test-injectable via monkeypatch."""
+    from umbermark.core.ssh import ParamikoRunner
+
+    return ParamikoRunner(host=host, user=user, key_filename=key_path)
+
+
+def _enum_value(v):
+    return getattr(v, "value", v)
+
+
+def _report_to_payload(report) -> dict:
+    return {
+        "schema_version": "1.0",
+        "target": report.target,
+        "started_at": report.started_at,
+        "finished_at": report.finished_at,
+        "umbermark_version": umbermark.__version__,
+        "findings": [
+            {
+                "check_id": f.check_id,
+                "title": f.title,
+                "category": f.category,
+                "severity": _enum_value(f.severity),
+                "weight": f.weight,
+                "verdict": _enum_value(f.verdict),
+                "evidence": f.evidence,
+                "remediation": f.remediation,
+                "skip_reason": f.skip_reason,
+            }
+            for f in report.findings
+        ],
+        "result": _deductions_to_dict(report.result),
+    }
+
+
+def _deductions_to_dict(result) -> dict:
+    d = dataclasses.asdict(result)
+    # Normalize Enum-bearing deduction fields to strings
+    for ded in d.get("deductions", []):
+        for k in ("severity", "verdict"):
+            if k in ded:
+                ded[k] = _enum_value(ded[k])
+    return d
+
+
+def scan(
+    target: str = typer.Argument(..., help="Host or IP to scan via SSH"),
+    user: str = typer.Option(..., "--user", "-u"),
+    key: str = typer.Option(..., "--key", "-k"),
+    output: str | None = typer.Option(
+        None, "-o", "--output", help="Write JSON to file (default: stdout)"
+    ),
+) -> None:
+    """Scan a target server via SSH and emit a Report-v1.0 JSON."""
+    runner = _build_runner(target, user, key)
+    report = run_scan(target=target, runner=runner, checks=ALL_CHECKS)
+    payload = _report_to_payload(report)
+    text = json.dumps(payload, indent=2)
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    else:
+        typer.echo(text)

umbermark/cli/commands/scan_local.py

@@ -0,0 +1,72 @@
+"""`umbermark scan-local` — scan the local machine via subprocess.
+
+Used in the spec §6.4 "agent mode" flow: a Linux box runs the CLI on
+itself, then `umbermark push` uploads the JSON to the SaaS without ever
+exposing SSH credentials.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+import typer
+
+from umbermark.checks import ALL_CHECKS
+from umbermark.cli.commands.scan import _report_to_payload
+from umbermark.core.engine import run_scan
+from umbermark.core.ssh import CommandResult
+
+
+class LocalRunner:
+    """Run commands in the local shell via subprocess.
+
+    Mirrors the CommandRunner Protocol so the core scan engine can use
+    it interchangeably with ParamikoRunner / WSLRunner / FakeRunner.
+    """
+
+    def __init__(self, shell: str = "/bin/sh") -> None:
+        self.shell = shell
+
+    def run(
+        self, command: str, sudo: bool = False, timeout: float = 30.0
+    ) -> CommandResult:
+        full = f"sudo -n {command}" if sudo else command
+        try:
+            p = subprocess.run(
+                [self.shell, "-c", full],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                encoding="utf-8",
+                errors="replace",
+            )
+            return CommandResult(stdout=p.stdout, stderr=p.stderr, exit_code=p.returncode)
+        except subprocess.TimeoutExpired:
+            return CommandResult(stdout="", stderr="timeout", exit_code=124)
+        except FileNotFoundError:
+            return CommandResult(stdout="", stderr="shell not found", exit_code=127)
+
+    def close(self) -> None:
+        return None
+
+
+def _build_runner():
+    return LocalRunner()
+
+
+def scan_local(
+    output: str | None = typer.Option(None, "-o", "--output"),
+) -> None:
+    """Scan the local machine and emit a Report-v1.0 JSON."""
+    import socket
+
+    runner = _build_runner()
+    target = socket.gethostname() or "localhost"
+    report = run_scan(target=target, runner=runner, checks=ALL_CHECKS)
+    payload = _report_to_payload(report)
+    text = json.dumps(payload, indent=2)
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    else:
+        typer.echo(text)

umbermark/cli/commands/scan_wsl.py

@@ -0,0 +1,35 @@
+"""`umbermark scan-wsl [DISTRO]` — scan a WSL distro on this Windows box."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from umbermark.checks import ALL_CHECKS
+from umbermark.cli.commands.scan import _report_to_payload
+from umbermark.core.engine import run_scan
+
+
+def _build_runner(distro: str | None):
+    from umbermark.core.ssh import WSLRunner
+
+    return WSLRunner(distro=distro)
+
+
+def scan_wsl(
+    distro: str | None = typer.Argument(
+        None, help="WSL distro name (omit for default)"
+    ),
+    output: str | None = typer.Option(None, "-o", "--output"),
+) -> None:
+    """Scan a WSL distro and emit a Report-v1.0 JSON."""
+    runner = _build_runner(distro)
+    target = f"wsl://{distro or 'default'}"
+    report = run_scan(target=target, runner=runner, checks=ALL_CHECKS)
+    payload = _report_to_payload(report)
+    text = json.dumps(payload, indent=2)
+    if output:
+        Path(output).write_text(text, encoding="utf-8")
+    else:
+        typer.echo(text)

umbermark/cli/commands/version.py

@@ -0,0 +1,11 @@
+"""`umbermark version` — print installed version."""
+from __future__ import annotations
+
+import typer
+
+import umbermark
+
+
+def version() -> None:
+    """Print the installed umbermark version."""
+    typer.echo(f"umbermark {umbermark.__version__}")

umbermark/cli/config.py

@@ -0,0 +1,13 @@
+"""CLI configuration resolver."""
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+DEFAULT_API_URL = "https://umbermark.starhold.app"
+
+
+def resolve_api_url(*, flag: str | None, env: Mapping[str, str] | None = None) -> str:
+    e = env if env is not None else os.environ
+    val = flag or e.get("UMBERMARK_API_URL") or DEFAULT_API_URL
+    return val.rstrip("/")