umbermark-cli 1.0.0__py3-none-any.whl

umbermark/core/scoring.py

@@ -0,0 +1,105 @@
+"""Weighted scoring engine.
+
+Score starts at 100. FAIL deducts the check's full weight; WARN deducts
+half; PASS and SKIP deduct nothing. The result is clamped to [0, 100].
+
+`coverage` is the fraction of checks that actually produced a verdict
+(PASS / WARN / FAIL) — i.e. not SKIP. When coverage falls below
+COVERAGE_THRESHOLD the band is forced to "incomplete" regardless of
+the numeric score. This is the load-bearing fix for the dogfood-day
+finding that "100/100 gold with 3/5 checks skipped" misled the reader.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from umbermark.core.check import Finding, Verdict
+
+COVERAGE_THRESHOLD = 0.6
+
+
+@dataclass
+class Deduction:
+    check_id: str
+    title: str
+    severity: str
+    weight: int
+    verdict: str
+    points_lost: int
+
+
+@dataclass
+class ScoreResult:
+    score: int
+    band: str
+    coverage: float
+    deductions: list[Deduction]
+    pass_count: int
+    warn_count: int
+    fail_count: int
+    skip_count: int
+
+
+def _band(score: int, coverage: float = 1.0) -> str:
+    if coverage < COVERAGE_THRESHOLD:
+        return "incomplete"
+    if score >= 90:
+        return "gold"
+    if score >= 70:
+        return "green"
+    if score >= 40:
+        return "yellow"
+    return "red"
+
+
+def score(findings: Iterable[Finding]) -> ScoreResult:
+    deductions: list[Deduction] = []
+    total = 100
+    pc = wc = fc = sc = 0
+    for f in findings:
+        if f.verdict == Verdict.PASS:
+            pc += 1
+        elif f.verdict == Verdict.WARN:
+            wc += 1
+            lost = f.weight // 2
+            total -= lost
+            deductions.append(
+                Deduction(
+                    check_id=f.check_id,
+                    title=f.title,
+                    severity=f.severity.value,
+                    weight=f.weight,
+                    verdict=f.verdict.value,
+                    points_lost=lost,
+                )
+            )
+        elif f.verdict == Verdict.FAIL:
+            fc += 1
+            total -= f.weight
+            deductions.append(
+                Deduction(
+                    check_id=f.check_id,
+                    title=f.title,
+                    severity=f.severity.value,
+                    weight=f.weight,
+                    verdict=f.verdict.value,
+                    points_lost=f.weight,
+                )
+            )
+        else:
+            sc += 1
+    total = max(0, min(100, total))
+    total_checks = pc + wc + fc + sc
+    ran_checks = pc + wc + fc
+    coverage = (ran_checks / total_checks) if total_checks > 0 else 0.0
+    return ScoreResult(
+        score=total,
+        band=_band(total, coverage),
+        coverage=coverage,
+        deductions=deductions,
+        pass_count=pc,
+        warn_count=wc,
+        fail_count=fc,
+        skip_count=sc,
+    )

umbermark/core/settings.py

@@ -0,0 +1,238 @@
+"""Runtime settings loaded from environment.
+
+Required env vars (no defaults — caller must set):
+    SECRET_KEY        — used by itsdangerous for magic links + session signing
+    KEY_PEPPER        — used by keyenc for saved-server key encryption
+    IP_PEPPER         — used by crypto.hash_with_pepper for ip_hash
+    TARGET_PEPPER     — used by crypto.hash_with_pepper for target_host_hash
+    DATABASE_PATH     — sqlite file path
+    REDIS_URL         — redis://host:port/db or fakeredis://...
+    BASE_URL          — canonical https URL for the deployment
+
+Optional env vars (with defaults shown):
+    SESSION_TTL_SECONDS                — default 2_592_000 (30 days)
+    ANONYMOUS_REPORT_TTL_SECONDS       — default 2_592_000 (30 days)
+    POSTMARK_WIRED / TURNSTILE_WIRED   — default 0 (wired: false, C3). While 0 the Postmark and Turnstile
+                                         settings below are IGNORED: no email provider, no captcha, no
+                                         Cloudflare origin in the CSP. Polar is the only payment processor.
+    POSTMARK_TOKEN                     — only when POSTMARK_WIRED=1: real-mode email transport
+    POLAR_API_TOKEN                    — if set, real-mode Polar client
+    POLAR_WEBHOOK_SECRET               — HMAC-SHA256 secret for /billing/webhook
+    POLAR_PRODUCT_ONESHOT              — Polar product id for $5 one-shot
+    POLAR_PRODUCT_SOLO                 — Polar product id for $9/mo Solo tier
+    POLAR_PRODUCT_PRO                  — Polar product id for $19/mo Pro tier
+    POLAR_PRODUCT_AGENCY               — Polar product id for $49/mo Agency tier
+    POLAR_API_BASE                     — Polar API base URL; default https://api.polar.sh/v1
+                                         (sandbox: https://sandbox-api.polar.sh/v1)
+    UPLOAD_RATE_LIMIT_PER_HOUR         — max POST /scan/upload per IP per hour; default 20
+    FREE_PUSH_LIMIT_PER_DAY            — max POST /api/push per free-tier user per rolling 24h; default 20 (paid tiers uncapped)
+    PDF_STORAGE_DIR                    — on-disk PDF cache directory
+    TURNSTILE_SECRET                   — only when TURNSTILE_WIRED=1: Cloudflare Turnstile siteverify secret
+    TURNSTILE_SITE_KEY                 — only when TURNSTILE_WIRED=1: public site key embedded in widget
+    OPERATOR_EMAIL                     — recipient for operator daily abuse digest
+    EMAIL_FROM                         — outbound from-address; default noreply@<base_url host>
+    EMAIL_REPLY_TO                     — optional single address sent as Postmark ReplyTo on every message
+    SIGNIN_ENABLED                     — default 0. While 0 every sign-in / magic-link / CLI-login /
+                                         claim route answers 403, sessions and API tokens are not
+                                         honoured, and all existing sessions are revoked at boot.
+                                         The quad42 gate flips this once Starhold Account exists.
+    STARSHIP_ENABLED                   — default 0 (STAR-227). While 0 nothing from umbermark.starship is mounted and
+                                         behaviour is unchanged. See umbermark/starship/config.py for the STARSHIP_* settings.
+    MONTHLY_PLANS_ENABLED              — default 0. While 0 the Solo/Pro/Agency plans are hidden everywhere,
+                                         /billing/upgrade refuses, and subscription webhooks are ignored.
+
+  External-scan network path (UMBR-65; all unset = old behaviour):
+    SCAN_RESOLVERS                     — comma list of recursive DNS servers (UDP) used to resolve scan targets
+                                         and DNS-TXT proofs, so a name the host maps locally (its own hostname ->
+                                         127.0.1.1) resolves as the internet sees it. Unset = system resolver
+                                         for targets, 1.1.1.1/8.8.8.8 for TXT.
+    SCANNER_SELF_IPS                   — comma list of this server's own public IPs.
+    SCANNER_HAIRPIN_ADDR               — address that reaches this server from inside the container (rootless
+                                         podman/pasta: 169.254.1.2). With SCANNER_SELF_IPS set, probes of a self IP
+                                         go here, because pasta keeps the host's own IP inside the namespace.
+    SCANNER_SELF_PUBLIC_PORTS          — default 80,443: the only ports of this server reachable from the
+                                         internet. Other ports on a self IP read as filtered, as from outside.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+# Single source of truth for the anonymous report link lifetime (30 days).
+DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS = 2_592_000
+
+# Default sign-in session lifetime (30 days); the privacy page quotes it.
+DEFAULT_SESSION_TTL_SECONDS = 2_592_000
+
+_REQUIRED = (
+    "SECRET_KEY",
+    "KEY_PEPPER",
+    "IP_PEPPER",
+    "TARGET_PEPPER",
+    "DATABASE_PATH",
+    "REDIS_URL",
+    "BASE_URL",
+)
+
+
+_ADDR_RE = re.compile(r"^[^\s<>,;:\"()@]+@[^\s<>,;:\"()@]+\.[^\s<>,;:\"()@]+$")
+
+
+def _reply_to(value: str | None, name: str = "EMAIL_REPLY_TO") -> str | None:
+    """Optional Reply-To: one plain address (no display name, no list). Unset or blank = None."""
+    v = (value or "").strip()
+    if not v:
+        return None
+    if not _ADDR_RE.match(v):
+        raise ValueError(f"{name} must be a single plain email address")
+    return v
+
+
+def _flag(raw: str | None) -> bool:
+    """Parse a 0/1 style env switch. Unset or anything unrecognised is OFF."""
+    return (raw or "0").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _csv(raw: str | None) -> tuple[str, ...]:
+    """Comma list -> tuple of non-empty, stripped items."""
+    return tuple(p.strip() for p in (raw or "").split(",") if p.strip())
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    secret_key: str
+    key_pepper: str
+    ip_pepper: str
+    target_pepper: str
+    database_path: Path
+    redis_url: str
+    base_url: str
+    session_ttl_seconds: int = DEFAULT_SESSION_TTL_SECONDS
+    anonymous_report_ttl_seconds: int = DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS
+    upload_rate_limit_per_hour: int = 20
+    free_push_limit_per_day: int = 20
+    postmark_token: str | None = None
+    polar_api_token: str | None = None
+    polar_webhook_secret: str | None = None
+    polar_product_oneshot: str | None = None
+    polar_product_solo: str | None = None
+    polar_product_pro: str | None = None
+    polar_product_agency: str | None = None
+    polar_api_base: str = "https://api.polar.sh/v1"
+    pdf_storage_dir: Path | None = None
+    turnstile_secret: str | None = None
+    turnstile_site_key: str | None = None
+    operator_email: str | None = None
+    email_from: str | None = None
+    email_reply_to: str | None = None
+    # Pause switch: CHECKOUT_PAUSED=1 makes every Polar checkout route 503.
+    checkout_paused: bool = False
+    # Sign-in switch (STAR-147 / Q43). Closed by default: nobody can sign in
+    # until the Starhold Account launches and the gate flips SIGNIN_ENABLED=1.
+    signin_enabled: bool = False
+    # Monthly plans (Solo/Pro/Agency) are hidden and un-purchasable while 0
+    # (Q42/Q44). MONTHLY_PLANS_ENABLED=1 restores the old behaviour for the gate.
+    monthly_plans_enabled: bool = False
+    # C3: third-party providers that are NOT connected. Their credentials are
+    # ignored unless the matching *_WIRED switch is on.
+    postmark_wired: bool = False
+    turnstile_wired: bool = False
+    # STAR-227: Starhold Account integration. Off by default; `starship` is None unless enabled.
+    starship_enabled: bool = False
+    starship: object | None = None
+    # UMBR-65: how external scans reach targets (see module docstring).
+    scan_resolvers: tuple[str, ...] = ()
+    scanner_self_ips: tuple[str, ...] = ()
+    scanner_hairpin_addr: str = ""
+    scanner_self_public_ports: tuple[int, ...] = (80, 443)
+
+    def apply_scan_network(self) -> None:
+        """Install the external-scan network path in this process (web + worker)."""
+        from umbermark.core.external import ownership
+
+        ownership.configure_network(
+            resolvers=self.scan_resolvers,
+            self_ips=self.scanner_self_ips,
+            hairpin_addr=self.scanner_hairpin_addr,
+            self_public_ports=self.scanner_self_public_ports,
+        )
+
+    @property
+    def billing_enabled(self) -> bool:
+        """True only when a real Polar client can be built (token + one-shot product + webhook secret).
+
+        When False the app must not offer purchase/upgrade surfaces: main.py
+        falls back to FakePolarClient, which hands strangers a fake checkout.
+        """
+        # The webhook secret is required too: without it every paid webhook
+        # fails signature checks (401) and buyers pay but are never granted.
+        return bool(
+            self.polar_api_token
+            and self.polar_product_oneshot
+            and self.polar_webhook_secret
+        )
+
+    @property
+    def email_enabled(self) -> bool:
+        """True only when a real transactional email provider is configured.
+
+        Without it, magic-link sign-in mail goes to the console and never arrives.
+        """
+        return bool(self.postmark_token)
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "Settings":
+        e = env if env is not None else os.environ
+        missing = [name for name in _REQUIRED if not e.get(name)]
+        if missing:
+            raise ValueError(f"Missing required env vars: {', '.join(missing)}")
+        pdf_dir = e.get("PDF_STORAGE_DIR")
+        starship_on = _flag(e.get("STARSHIP_ENABLED"))
+        starship_cfg = None
+        if starship_on:
+            from umbermark.starship.config import StarshipConfig
+
+            starship_cfg = StarshipConfig.from_env(e, database_path=Path(e["DATABASE_PATH"]))
+        return cls(
+            secret_key=e["SECRET_KEY"],
+            key_pepper=e["KEY_PEPPER"],
+            ip_pepper=e["IP_PEPPER"],
+            target_pepper=e["TARGET_PEPPER"],
+            database_path=Path(e["DATABASE_PATH"]),
+            redis_url=e["REDIS_URL"],
+            base_url=e["BASE_URL"].rstrip("/"),
+            session_ttl_seconds=int(e.get("SESSION_TTL_SECONDS", DEFAULT_SESSION_TTL_SECONDS)),
+            anonymous_report_ttl_seconds=int(e.get("ANONYMOUS_REPORT_TTL_SECONDS", DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS)),
+            upload_rate_limit_per_hour=int(e.get("UPLOAD_RATE_LIMIT_PER_HOUR") or 20),
+            free_push_limit_per_day=int(e.get("FREE_PUSH_LIMIT_PER_DAY") or 20),
+            postmark_token=(e.get("POSTMARK_TOKEN") or None) if _flag(e.get("POSTMARK_WIRED")) else None,
+            postmark_wired=_flag(e.get("POSTMARK_WIRED")),
+            turnstile_wired=_flag(e.get("TURNSTILE_WIRED")),
+            polar_api_token=e.get("POLAR_API_TOKEN") or None,
+            polar_webhook_secret=e.get("POLAR_WEBHOOK_SECRET") or None,
+            polar_product_oneshot=e.get("POLAR_PRODUCT_ONESHOT") or None,
+            polar_product_solo=e.get("POLAR_PRODUCT_SOLO") or None,
+            polar_product_pro=e.get("POLAR_PRODUCT_PRO") or None,
+            polar_product_agency=e.get("POLAR_PRODUCT_AGENCY") or None,
+            polar_api_base=e.get("POLAR_API_BASE") or "https://api.polar.sh/v1",
+            pdf_storage_dir=Path(pdf_dir) if pdf_dir else None,
+            turnstile_secret=(e.get("TURNSTILE_SECRET") or None) if _flag(e.get("TURNSTILE_WIRED")) else None,
+            turnstile_site_key=(e.get("TURNSTILE_SITE_KEY") or None) if _flag(e.get("TURNSTILE_WIRED")) else None,
+            operator_email=e.get("OPERATOR_EMAIL") or None,
+            email_from=e.get("EMAIL_FROM") or None,
+            email_reply_to=_reply_to(e.get("EMAIL_REPLY_TO")),
+            checkout_paused=_flag(e.get("CHECKOUT_PAUSED")),
+            signin_enabled=_flag(e.get("SIGNIN_ENABLED")),
+            monthly_plans_enabled=_flag(e.get("MONTHLY_PLANS_ENABLED")),
+            starship_enabled=starship_on,
+            starship=starship_cfg,
+            scan_resolvers=_csv(e.get("SCAN_RESOLVERS")),
+            scanner_self_ips=_csv(e.get("SCANNER_SELF_IPS")),
+            scanner_hairpin_addr=(e.get("SCANNER_HAIRPIN_ADDR") or "").strip(),
+            scanner_self_public_ports=tuple(
+                int(p) for p in (_csv(e.get("SCANNER_SELF_PUBLIC_PORTS")) or ("80", "443"))
+            ),
+        )

umbermark/core/short_id.py

@@ -0,0 +1,27 @@
+"""Unguessable report identifiers.
+
+A report URL is a capability: anyone holding it can read the report (shareable
+by design). So the id must be impossible to guess. 16 random bytes = 128 bits,
+rendered as 26 lowercase base32 characters [a-z2-7]. Ids from before STAR-147
+were 8 characters (40 bits); migration 012 retires them.
+"""
+from __future__ import annotations
+
+import base64
+import re
+import secrets
+
+ID_BYTES = 16  # 128 bits
+ID_LENGTH = 26  # base32 of 16 bytes, unpadded
+
+_FORMAT = re.compile(r"^[a-z2-7]{26}$")
+
+
+def generate() -> str:
+    """Return a 26-char [a-z2-7] id carrying 128 random bits."""
+    raw = base64.b32encode(secrets.token_bytes(ID_BYTES)).decode("ascii").lower()
+    return raw.rstrip("=")
+
+
+def is_current_format(short_id: str) -> bool:
+    return bool(_FORMAT.match(short_id or ""))

umbermark/core/signing.py

@@ -0,0 +1,24 @@
+"""Thin wrapper over `itsdangerous.URLSafeTimedSerializer`.
+
+Used for magic-link tokens and any other time-limited signed payload.
+The wrapper takes a `salt` parameter so different token kinds (login link
+vs. report claim vs. CLI device token) can't be cross-redeemed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer
+
+__all__ = ["sign_token", "verify_token", "BadSignature", "SignatureExpired"]
+
+
+def sign_token(payload: Any, secret_key: str, salt: str) -> str:
+    return URLSafeTimedSerializer(secret_key, salt=salt).dumps(payload)
+
+
+def verify_token(token: str, secret_key: str, salt: str, max_age_seconds: int) -> Any:
+    """Returns the original payload. Raises SignatureExpired or BadSignature."""
+    return URLSafeTimedSerializer(secret_key, salt=salt).loads(
+        token, max_age=max_age_seconds
+    )

umbermark/core/ssh.py

@@ -0,0 +1,156 @@
+"""Command-runner protocol + paramiko (real SSH), WSL (dogfood), fake (tests)."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class CommandResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+class CommandRunner(Protocol):
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        ...
+
+
+@dataclass
+class FakeRunner:
+    """Test double — programmable command-string -> CommandResult mapping.
+
+    A response registered under the bare command matches whether or not
+    `sudo=True` was passed, so tests don't have to mirror the runner's
+    sudo-prefixing convention.
+    """
+
+    responses: dict[str, CommandResult] = field(default_factory=dict)
+    calls: list[str] = field(default_factory=list)
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        full_cmd = f"sudo -n {command}" if sudo else command
+        self.calls.append(full_cmd)
+        if command in self.responses:
+            return self.responses[command]
+        if full_cmd in self.responses:
+            return self.responses[full_cmd]
+        return CommandResult(
+            stdout="",
+            stderr=f"no fake response for: {command!r}",
+            exit_code=127,
+        )
+
+
+class ParamikoRunner:
+    """Real SSH runner via paramiko."""
+
+    def __init__(
+        self,
+        host: str,
+        user: str,
+        key_filename: str | None = None,
+        port: int = 22,
+        password: str | None = None,
+        connect_timeout: float = 10.0,
+    ) -> None:
+        import paramiko
+
+        self._client = paramiko.SSHClient()
+        self._client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+        connect_kwargs: dict = {
+            "hostname": host,
+            "username": user,
+            "port": port,
+            "timeout": connect_timeout,
+        }
+        if key_filename:
+            connect_kwargs["key_filename"] = key_filename
+        elif password:
+            connect_kwargs["password"] = password
+        self._client.connect(**connect_kwargs)
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        full = f"sudo -n {command}" if sudo else command
+        _, stdout, stderr = self._client.exec_command(full, timeout=timeout)
+        out = stdout.read().decode("utf-8", errors="replace")
+        err = stderr.read().decode("utf-8", errors="replace")
+        rc = stdout.channel.recv_exit_status()
+        return CommandResult(stdout=out, stderr=err, exit_code=rc)
+
+    def close(self) -> None:
+        try:
+            self._client.close()
+        except Exception:
+            pass
+
+
+class WSLRunner:
+    """Run commands inside a WSL distro via `wsl.exe`. Local dogfood only —
+    not a substitute for SSH against real targets."""
+
+    def __init__(
+        self,
+        distro: str | None = None,
+        user: str | None = None,
+        wsl_exe: str = "wsl.exe",
+    ) -> None:
+        self.distro = distro
+        self.user = user
+        self.wsl_exe = wsl_exe
+
+    def _build_cmd(self, command: str, sudo: bool) -> list[str]:
+        cmd: list[str] = [self.wsl_exe]
+        if self.distro:
+            cmd += ["-d", self.distro]
+        if sudo:
+            cmd += ["--user", "root"]
+        elif self.user:
+            cmd += ["--user", self.user]
+        cmd += ["--", "bash", "-c", command]
+        return cmd
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        try:
+            p = subprocess.run(
+                self._build_cmd(command, sudo),
+                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)
+
+    def close(self) -> None:  # parity with ParamikoRunner
+        return None

umbermark/core/ssh_fingerprint.py

@@ -0,0 +1,16 @@
+"""SHA-256 fingerprint of an SSH private key for audit logging.
+
+Per spec §17 — the audit log records a fingerprint so we can correlate
+repeat scan attempts by the same key without ever logging the private
+bytes themselves. The fingerprint is SHA-256 of the stripped UTF-8
+bytes of the PEM. Exact derivation does not need to match openssh's
+public-key fingerprint — only same-key→same-fingerprint and no leak.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def derive_key_fingerprint(private_key_pem: str) -> str:
+    payload = private_key_pem.strip().encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()