veltro-cli 0.15.7__py3-none-any.whl

veltro_cli/lib/upgrade.py

@@ -0,0 +1,379 @@
+"""Fetch and apply one immutable Veltro suite release."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from veltro_cli.lib.compose import ComposeClient
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.install import materialise_from_checkout, materialise_from_tarball
+from veltro_cli.lib.paths import resolve_dir
+from veltro_cli.lib.products import read_env_file, resolve_selection
+from veltro_cli.lib.release import (
+    RELEASE_BASE,
+    RELEASE_REPO,
+    parse_release_version,
+    release_tag,
+    release_version,
+)
+from veltro_cli.lib.toml_config import VELTRO_TOML, read_config, write_config
+
+VERSION_VARS = {
+    "vectorflow": "VF_VERSION",
+    "chad": "CHAD_VERSION",
+    "warden": "WARDEN_VERSION",
+    "veltro": "VELTRO_VERSION",
+}
+
+
+def normalise_target(target: str) -> tuple[str, str]:
+    """``(tag, X.Y.Z)`` for a release named by its version or either tag spelling."""
+    version = release_version(target)
+    return release_tag(version), version
+
+
+def refuse_downgrade(current: str, target: str) -> None:
+    cur = parse_release_version(current)
+    tgt = parse_release_version(target)
+    if tgt < cur:
+        raise VeltroCliError(
+            f"refusing downgrade: installed {current} → target {target}",
+            remedy="restore from backup if you need an older suite; upgrade never rolls backward",
+        )
+    if tgt == cur:
+        raise VeltroCliError(
+            f"already at {current}",
+            remedy="pass a newer --to X.Y.Z",
+        )
+
+
+def fetch_release_notes(body: str) -> list[str]:
+    warnings: list[str] = []
+    for heading in ("BREAKING", "MIGRATION"):
+        if re.search(rf"^#+ .*{heading}", body, re.I | re.M):
+            warnings.append(heading)
+    return warnings
+
+
+def release_urls(target: str) -> tuple[str, str]:
+    tag, version = normalise_target(target)
+    return (
+        f"{RELEASE_BASE}/releases/download/{tag}/veltro-suite-{version}.json",
+        f"{RELEASE_BASE}/archive/refs/tags/{tag}.tar.gz",
+    )
+
+
+def load_release_manifest(
+    target: str,
+    *,
+    opener: Callable[..., Any] = urllib.request.urlopen,
+) -> dict[str, Any]:
+    manifest_url, _ = release_urls(target)
+    try:
+        with opener(manifest_url, timeout=30) as response:
+            raw = response.read()
+    except Exception as exc:
+        raise VeltroCliError(
+            f"could not fetch suite manifest for {target}: {exc}",
+            remedy=f"verify the release exists at {manifest_url} and retry",
+        ) from exc
+    try:
+        manifest = json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise VeltroCliError(
+            "published suite manifest is not valid JSON",
+            remedy="do not upgrade; report the immutable release asset",
+        ) from exc
+    _, version = normalise_target(target)
+    if not isinstance(manifest, dict) or manifest.get("schema") not in {
+        "veltro-suite-manifest/v4",
+        "veltro-suite-manifest/v5",
+    }:
+        raise VeltroCliError("published suite manifest has an unsupported schema")
+    if manifest.get("suite_version") != version:
+        raise VeltroCliError(
+            f"manifest suite_version {manifest.get('suite_version')!r} does not match {version!r}",
+            remedy="do not upgrade; the release asset is inconsistent with its tag",
+        )
+    verification = manifest.get("verification")
+    if not isinstance(verification, dict) or verification.get("status") not in {
+        "smoke-passed",
+        "config-rendered",
+    }:
+        raise VeltroCliError(
+            "suite manifest is not release-gate attested",
+            remedy="choose a published suite release with verification evidence",
+        )
+    return manifest
+
+
+def manifest_versions(manifest: Mapping[str, Any]) -> dict[str, str]:
+    modules = manifest.get("modules")
+    if not isinstance(modules, dict):
+        raise VeltroCliError("suite manifest has no module versions")
+    versions: dict[str, str] = {}
+    for name, env_var in VERSION_VARS.items():
+        module = modules.get(name)
+        if not isinstance(module, dict) or not isinstance(module.get("version"), str):
+            raise VeltroCliError(f"suite manifest has no {name} version")
+        versions[env_var] = module["version"]
+    return versions
+
+
+def verify_staged_pins(root: Path, manifest: Mapping[str, Any]) -> None:
+    actual = read_env_file(root / "versions.env")
+    expected = manifest_versions(manifest)
+    mismatches = [
+        f"{key}={actual.get(key)!r} (manifest {value!r})"
+        for key, value in expected.items()
+        if actual.get(key) != value
+    ]
+    if mismatches:
+        raise VeltroCliError(
+            "release tarball pins disagree with its manifest: " + ", ".join(mismatches),
+            remedy="do not upgrade; report the immutable release artifacts",
+        )
+
+
+def verify_staged_release(root: Path, manifest: Mapping[str, Any]) -> None:
+    """Bind extracted release bytes to the release-gated manifest."""
+    verify_staged_pins(root, manifest)
+    contract = manifest.get("config_contract")
+    files = contract.get("files") if isinstance(contract, dict) else None
+    if not isinstance(files, dict) or not files:
+        raise VeltroCliError(
+            "suite manifest has no config artifact digests",
+            remedy="do not install or upgrade from an unattested release",
+        )
+    for relative, expected in files.items():
+        if not isinstance(relative, str) or not isinstance(expected, str):
+            raise VeltroCliError("suite manifest has a malformed config artifact digest")
+        path = root / relative
+        actual = "sha256:" + hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None
+        if actual != expected:
+            raise VeltroCliError(
+                f"release artifact {relative} digest {actual!r} does not match {expected!r}",
+                remedy="do not install or upgrade; report the immutable release artifacts",
+            )
+
+def _run_backup(root: Path, products: tuple[str, ...], staged: Path) -> Path:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    archive = root / "backups" / f"veltro-backup-auto-{stamp}.tar"
+    archive.parent.mkdir(parents=True, exist_ok=True)
+    command = [
+        sys.executable,
+        str(staged / "scripts" / "veltro_backup.py"),
+        "backup",
+        "--dir",
+        str(root),
+        "--products",
+        ",".join(products),
+        "--to",
+        str(archive),
+    ]
+    # The old checkout still has legacy backup code and profile names. Run the
+    # staged backup against old pins/.env, but render the staged Compose services
+    # under the existing project name so exec finds the running containers.
+    env = dict(os.environ)
+    env["COMPOSE_FILE"] = str(staged / "docker-compose.yml")
+    env["COMPOSE_PROJECT_NAME"] = (
+        env.get("COMPOSE_PROJECT_NAME")
+        or read_env_file(root / ".env").get("COMPOSE_PROJECT_NAME")
+        or root.name
+    )
+    completed = subprocess.run(command, text=True, capture_output=True, check=False, env=env)
+    if completed.returncode != 0:
+        raise VeltroCliError(
+            completed.stderr.strip() or "automatic pre-upgrade backup failed",
+            remedy="fix backup prerequisites; upgrade has not changed the install",
+        )
+    if not archive.is_file():
+        raise VeltroCliError(
+            f"automatic backup reported success but did not create {archive}",
+            remedy="upgrade has not changed the install; inspect the backup command output",
+        )
+    return archive
+
+
+def expected_image_digests(manifest: Mapping[str, Any]) -> dict[str, str]:
+    expected: dict[str, str] = {}
+    modules = manifest.get("modules")
+    if isinstance(modules, dict):
+        for module in modules.values():
+            if not isinstance(module, dict):
+                continue
+            images = module.get("images")
+            if isinstance(images, dict):
+                expected.update(
+                    {
+                        ref: digest
+                        for ref, digest in images.items()
+                        if isinstance(ref, str)
+                        and isinstance(digest, str)
+                        and digest.startswith("sha256:")
+                    }
+                )
+    return expected
+
+
+def verify_local_image_digests(
+    manifest: Mapping[str, Any],
+    *,
+    runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+) -> None:
+    for ref, digest in expected_image_digests(manifest).items():
+        completed = runner(
+            ["docker", "image", "inspect", "--format", "{{json .RepoDigests}}", ref],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if completed.returncode != 0 or f"@{digest}" not in completed.stdout:
+            raise VeltroCliError(
+                f"running image {ref} is not the manifest digest {digest}",
+                remedy="run `veltro down`, restore the automatic backup, and inspect registry access",
+            )
+
+
+def module_version_deltas(root: Path, manifest: Mapping[str, Any]) -> list[dict[str, str]]:
+    current = read_env_file(root / "versions.env")
+    target = manifest_versions(manifest)
+    return [
+        {"module": name, "from": current.get(env_var, "unknown"), "to": target[env_var]}
+        for name, env_var in VERSION_VARS.items()
+        if current.get(env_var) != target[env_var]
+    ]
+
+
+def load_release_warnings(
+    target: str,
+    manifest: Mapping[str, Any],
+    *,
+    opener: Callable[..., Any] = urllib.request.urlopen,
+) -> list[str]:
+    tag, _ = normalise_target(target)
+    releases: list[tuple[str, str, str]] = [("suite", RELEASE_REPO, tag)]
+    modules = manifest.get("modules")
+    if isinstance(modules, dict):
+        for name, module in modules.items():
+            if isinstance(module, dict) and isinstance(module.get("repo"), str) and isinstance(module.get("tag"), str):
+                releases.append((name, module["repo"], module["tag"]))
+    warnings: list[str] = []
+    for name, repo, notes_tag in releases:
+        request = urllib.request.Request(
+            f"https://api.github.com/repos/{repo}/releases/tags/{notes_tag}",
+            headers={"Accept": "application/vnd.github+json"},
+        )
+        try:
+            with opener(request, timeout=15) as response:
+                payload = json.load(response)
+        except Exception as exc:
+            warnings.append(f"{name} release notes unavailable: {exc}")
+            continue
+        body = payload.get("body") if isinstance(payload, dict) else ""
+        for heading in fetch_release_notes(body if isinstance(body, str) else ""):
+            warnings.append(f"{name}: {heading} section present in release notes")
+    return warnings
+
+def plan_upgrade(
+    *,
+    directory: str | Path | None,
+    target: str,
+    current: str | None = None,
+    manifest_opener: Callable[..., Any] = urllib.request.urlopen,
+    notes_opener: Callable[..., Any] = urllib.request.urlopen,
+) -> dict[str, Any]:
+    root = resolve_dir(directory)
+    cfg = read_config(root / VELTRO_TOML)
+    installed = current or (cfg.installed_suite_version if cfg else "") or "0.0.0"
+    refuse_downgrade(installed, target)
+    manifest = load_release_manifest(target, opener=manifest_opener)
+    return {
+        "directory": str(root),
+        "from": installed,
+        "to": normalise_target(target)[0],
+        "dry_run": True,
+        "module_deltas": module_version_deltas(root, manifest),
+        "warnings": load_release_warnings(target, manifest, opener=notes_opener),
+        "steps": [
+            "fetch and verify immutable suite manifest",
+            "veltro backup --auto",
+            "replace compose/nginx/versions.env from release",
+            "veltro up --wait",
+            "verify local image digests against suite manifest",
+            "record installed_version in veltro.toml",
+        ],
+    }
+
+
+def execute_upgrade(
+    *,
+    directory: str | Path | None,
+    target: str,
+    current: str | None = None,
+    manifest_opener: Callable[..., Any] = urllib.request.urlopen,
+    tarball_opener: Callable[..., Any] = urllib.request.urlopen,
+    backup_runner: Callable[[Path, tuple[str, ...], Path], Path] = _run_backup,
+    client_factory: Callable[..., ComposeClient] = ComposeClient,
+    digest_verifier: Callable[[Mapping[str, Any]], None] = verify_local_image_digests,
+) -> dict[str, Any]:
+    root = resolve_dir(directory)
+    cfg = read_config(root / VELTRO_TOML)
+    if cfg is None:
+        raise VeltroCliError("veltro.toml is missing", remedy="run `veltro install` first")
+    installed = current or cfg.installed_suite_version or "0.0.0"
+    refuse_downgrade(installed, target)
+    manifest = load_release_manifest(target, opener=manifest_opener)
+    _, tarball_url = release_urls(target)
+    products = resolve_selection(root)
+    with tempfile.TemporaryDirectory(prefix="veltro-upgrade-") as tmp:
+        staged = Path(tmp) / "release"
+        materialise_from_tarball(tarball_url, staged, opener=tarball_opener)
+        verify_staged_release(staged, manifest)
+        backup_path = backup_runner(root, products, staged)
+        materialise_from_checkout(staged, root)
+    if cfg.tls_mode != "off":
+        from veltro_cli.lib.tls import write_caddyfile
+
+        write_caddyfile(
+            root,
+            tls_mode=cfg.tls_mode,
+            public_url=cfg.public_url,
+            products=products,
+        )
+    client = client_factory(
+        root,
+        products=products,
+        tls_mode=cfg.tls_mode,
+        monitoring=cfg.monitoring,
+    )
+    result = client.up()
+    if result.returncode != 0:
+        raise VeltroCliError(
+            result.stderr.strip() or "upgraded services did not become healthy",
+            remedy=f"run `veltro restore {backup_path} --yes`",
+        )
+    digest_verifier(manifest)
+    tag, _ = normalise_target(target)
+    write_config(
+        root / VELTRO_TOML,
+        type(cfg)(
+            products=",".join(products),
+            public_url=cfg.public_url,
+            tls_mode=cfg.tls_mode,
+            dir=cfg.dir,
+            installed_suite_version=tag,
+            monitoring=cfg.monitoring,
+        ),
+    )
+    return {"from": installed, "to": tag, "backup": str(backup_path)}

veltro_cli-0.15.7.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: veltro-cli
+Version: 0.15.7
+Summary: Operator CLI for the Veltro security operations suite (Compose + Helm).
+Author: Veltro Security
+License: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/veltrosecurity/veltro
+Project-URL: Documentation, https://github.com/veltrosecurity/veltro#readme
+Project-URL: Repository, https://github.com/veltrosecurity/veltro
+Project-URL: Issues, https://github.com/veltrosecurity/veltro/issues
+Keywords: veltro,security,soc,compose,helm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# veltro-cli
+
+Stdlib-only operator CLI for the Veltro suite. Every Veltro release publishes
+it at the release's version. Install a release with:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/veltrosecurity/veltro/vX.Y.Z/install.sh \
+  | VELTRO_RELEASE=X.Y.Z sh
+```
+
+or `pip install veltro-cli==X.Y.Z` and `veltro install --suite-version X.Y.Z`.
+Leave the version out to take the newest release.
+
+Requires Python ≥ 3.10 and Docker Compose ≥ 2.20 on the host.

veltro_cli-0.15.7.dist-info/RECORD

@@ -0,0 +1,31 @@
+veltro_cli/__init__.py,sha256=VnqEClGNNd-QoD4KB-KKrdl4MiGH7UE79FDD29io9aY,162
+veltro_cli/__main__.py,sha256=3TsZ7P9l58oD0WSz5Bs123zv4awf_A7F_zFLhjYktZ4,122
+veltro_cli/cli.py,sha256=h4ktX-TGiUpnDfGIEJV1yizmtqw1IKm_jfh1c2Vq8Xk,18999
+veltro_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+veltro_cli/lib/__init__.py,sha256=AfQgBH4JgPETDMOLmeY2mueXU8EPL-M9O76lpf0d0lE,98
+veltro_cli/lib/agent.py,sha256=7U8c5x8e50jgU_BBlCpcuUNn_9RcZKzDUC6peRK65y4,1358
+veltro_cli/lib/backup.py,sha256=Xu6XjaFxiwHKald_WyUvY5ZLA72bAegCqfkFGdtES7U,4789
+veltro_cli/lib/compose.py,sha256=-m9xsqRF7Dn4dryk-dkBwtaLvpVpZ4dndyAyo0mHC78,9316
+veltro_cli/lib/datasets.py,sha256=BLGZYXnQ7HBbjl4KKO6b6SyWyBa9r6IMcsvmFLbB-Kc,23622
+veltro_cli/lib/demo.py,sha256=gipzWJc9R-Na4h75rL6QIZpxQeAQn-6_wUsYaaPCf4g,16076
+veltro_cli/lib/demo_replay.py,sha256=i6PLEKFPCobcE_-PEYKSVcqr5ipUdnD_q8Mab1Drd20,32353
+veltro_cli/lib/doctor.py,sha256=KvOJlvGkg2MN4gy7nf1ODuMuEMZNuetB7LZI2sJC4bM,3097
+veltro_cli/lib/env_init.py,sha256=27J8NfiLLasSRGQ79dtskRb3Dum6xjvI21YqdwcwJqg,3416
+veltro_cli/lib/errors.py,sha256=uUEtGpdMLSM5_A8S_u-Gg2zGZ1uaZVluMHUNzJZrvsw,1083
+veltro_cli/lib/host.py,sha256=GQdnNppsYqaI26yFDIE0E_2mpeyjGbBTdeZa3QlrgwY,11267
+veltro_cli/lib/install.py,sha256=2CghrBRB7t8SlBm4P9YC5UbcIATTanwbvu0TyjEklJs,15287
+veltro_cli/lib/k8s.py,sha256=WzpsrMjqgUIRzI19Ywy2xs4FcH45PPq30CLdCT8IamI,2026
+veltro_cli/lib/paths.py,sha256=n2SzPs-0-vJant86WIpnHbg44j3Dhtt0YKBoTbWvqXM,1489
+veltro_cli/lib/products.py,sha256=XtyJHSA_tXLLMtyTO72qmeOsX_8yoM_Qris6-gcUrqE,2037
+veltro_cli/lib/release.py,sha256=uj4ltZfSFkI0A8VtWrKFBCEE-DaWYX4uJXS0Rcb0wsQ,3303
+veltro_cli/lib/status.py,sha256=W4Z7ONM46XXdswVNOuTqY8b56fnAvexyzMxI8_eg-68,6434
+veltro_cli/lib/suite_http.py,sha256=x8nVimYw9OcG1MfnYEFOrPGWkdvdgbW41kTeDFFuRsA,9354
+veltro_cli/lib/support.py,sha256=rqLZAiAaps-JiJx4CWttMnzlnKEnA9aAHRbDHGL9zdA,1169
+veltro_cli/lib/tls.py,sha256=-h4M3SUH_7_ZL8xnvXYCZQ5QXgC7PXhtSqi2u4BUjzU,3675
+veltro_cli/lib/toml_config.py,sha256=pWqlJnaOEno5fVivVTtkbsvLW13IYy9PjvCSvKc1LXc,3822
+veltro_cli/lib/upgrade.py,sha256=LtPumvD6DrxQid6TfHKUpmW12LjGBLweCEcQKHXlgek,14519
+veltro_cli-0.15.7.dist-info/METADATA,sha256=fsjKbb8oGyNgsgVdwP0XI2Z1eD2ylCDdvHVlCiLC--w,1622
+veltro_cli-0.15.7.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+veltro_cli-0.15.7.dist-info/entry_points.txt,sha256=YAiC7EzAE1y2ekqMrqzKXjTzfC61Dre003Lq_UFKH5Y,47
+veltro_cli-0.15.7.dist-info/top_level.txt,sha256=WhGjLaHoeUKxcuWg-8GxmhXJc61uPYz3l4OCWU_nGBE,11
+veltro_cli-0.15.7.dist-info/RECORD,,

veltro_cli-0.15.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

veltro_cli-0.15.7.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+veltro = veltro_cli.cli:main

veltro_cli-0.15.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+veltro_cli