From bfba804ec261ac04ff46f5347c5ee6e69a76d0fc Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Mon, 2 Nov 2026 08:46:44 +0100 Subject: [PATCH] fix(vm-provision): quote the image URL in the node's root commands The cloud-image download put image_url, hand-wrapped in single quotes, and the cache path built from its basename unquoted into commands that run as root on the node: a quote, $(...), ; or space in a URL from a release feed was acted on by the shell. The URL and every path built from it now go through shlex.quote (exists check, wget, mv, checksum, rm, unpack, qm importdisk), and the cache file name keeps only the characters Proxmox keeps in a content file name, as the import volume name already did. The checksum algorithm is checked against the ones Proxmox knows, since it is part of the command name. The file-name helpers move to image_names.py; vm_provision_mixin.py would otherwise cross the 1000-line limit. _download_cloud_image drops below 50 lines, so its baseline entry goes. Closes #43 --- CHANGELOG.md | 7 +++ napalm_proxmox/image_names.py | 70 +++++++++++++++++++++ napalm_proxmox/vm_provision_mixin.py | 93 +++++++++------------------- tests/quality_baseline.json | 1 - tests/test_vm_import_download.py | 6 +- tests/test_vm_provision_mixin.py | 84 +++++++++++++++++++++++++ 6 files changed, 192 insertions(+), 69 deletions(-) create mode 100644 napalm_proxmox/image_names.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 31f8a18..7ff8e4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -113,6 +113,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 its cause, so the caller can remove it with `destroy_vm()`. Failures there that were a `ValueError` (no snippet storage, a NIC without a bridge) are its cause now. Needs `VMProvisionIncomplete` from napalm-device-types (#28). +- `create_vm_from_cloud_init()` quotes the image URL and every path built from it in + the commands it runs as root on the node (download, checksum, unpack, disk + import). A URL with a quote, `$(…)`, `;` or a space no longer reaches the shell: + the node's cache file name keeps only the characters Proxmox keeps in a file + name, the others become `_`. A checksum algorithm other than md5, sha1, sha224, + sha256, sha384 or sha512 is refused with a `ValueError` before anything runs on + the node (#43). ## [0.8.0] - 2026-10-23 diff --git a/napalm_proxmox/image_names.py b/napalm_proxmox/image_names.py new file mode 100644 index 0000000..5441937 --- /dev/null +++ b/napalm_proxmox/image_names.py @@ -0,0 +1,70 @@ +"""File names and checksums of the cloud images a VM is provisioned from. + +The image URL comes from whoever publishes the image (a release feed), so +nothing taken from it reaches a file name on the node unless Proxmox would keep +it in a content file name too. +""" + +from __future__ import annotations + +import hashlib +import re + +# Proxmox reads an import volume's format off its extension and accepts only +# these. Ubuntu ships its qcow2 cloud images as ".img", so that is stored as +# qcow2: if an .img is really raw, the import fails loudly, whereas guessing +# raw for a qcow2 would attach the qcow2 container as a raw disk silently. +_IMPORT_EXTENSIONS = {"qcow2": "qcow2", "raw": "raw", "vmdk": "vmdk", "img": "qcow2"} + +# Characters Proxmox keeps in a content file name (PVE::Storage's +# SAFE_CHAR_CLASS_RE); anything else it would rewrite behind our back. +_UNSAFE_FILENAME_CHARS = re.compile(r"[^A-Za-z0-9\-.+=_]") + +# The checksum algorithms Proxmox's download-url accepts; each has a coreutils +# "sum" on the node. +_CHECKSUM_ALGORITHMS = frozenset({"md5", "sha1", "sha224", "sha256", "sha384", "sha512"}) + + +def url_key(image_url: str) -> str: + """Short hash of the full URL — Ubuntu and others publish a new build + under the same basename every day, so the basename alone is no cache key.""" + return hashlib.sha256(image_url.encode()).hexdigest()[:12] + + +def _basename(image_url: str) -> str: + return image_url.rstrip("/").rsplit("/", 1)[-1] + + +def split_checksum(image_checksum: str) -> tuple[str, str]: + """``":"`` as ``(algo, hex)``; the algorithm defaults to sha256. + + :raises ValueError: for an algorithm Proxmox does not know. + """ + algo, _, expected = image_checksum.partition(":") + algo = (algo or "sha256").lower() + if algo not in _CHECKSUM_ALGORITHMS: + raise ValueError(f"unknown checksum algorithm {algo!r}") + return algo, expected + + +def cache_name(image_url: str) -> str: + """The file name *image_url* gets in the node's image cache. + + The URL's hash, then its basename with every character Proxmox would not + keep replaced by ``_``. + """ + return f"{url_key(image_url)}-{_UNSAFE_FILENAME_CHARS.sub('_', _basename(image_url))}" + + +def import_volume_name(image_url: str) -> str | None: + """The file name *image_url* gets in an import storage. + + None when Proxmox cannot import the image's type at all (compressed, + ISO, no extension) — provisioning then downloads it over SSH as before. + """ + stem, dot, ext = _basename(image_url).rpartition(".") + extension = _IMPORT_EXTENSIONS.get(ext.lower()) if dot and stem else None + if extension is None: + return None + safe_stem = _UNSAFE_FILENAME_CHARS.sub("_", stem) + return f"netork-{url_key(image_url)}-{safe_stem}.{extension}" diff --git a/napalm_proxmox/vm_provision_mixin.py b/napalm_proxmox/vm_provision_mixin.py index 87beb7c..9d1d3e8 100644 --- a/napalm_proxmox/vm_provision_mixin.py +++ b/napalm_proxmox/vm_provision_mixin.py @@ -3,10 +3,10 @@ from __future__ import annotations import base64 -import hashlib import ipaddress import logging import re +import shlex import time from typing import TYPE_CHECKING, Any from urllib.parse import quote @@ -26,6 +26,7 @@ from napalm_device_types.provisioning import ( split_compression, ) +from napalm_proxmox.image_names import cache_name, import_volume_name, split_checksum from napalm_proxmox.network_targets import bridge_targets, vnet_target from napalm_proxmox.utils import cpu_flags @@ -81,12 +82,6 @@ _HOST_CPU_DESCRIPTION = ( # download cost once. _IMAGE_CACHE_DIR = "/var/lib/vz/template/netork-images" -# Proxmox reads an import volume's format off its extension and accepts only -# these. Ubuntu ships its qcow2 cloud images as ".img", so that is stored as -# qcow2: if an .img is really raw, the import fails loudly, whereas guessing -# raw for a qcow2 would attach the qcow2 container as a raw disk silently. -_IMPORT_EXTENSIONS = {"qcow2": "qcow2", "raw": "raw", "vmdk": "vmdk", "img": "qcow2"} - # The VM shell each guest needs. OpenBSD's qemu-ga cannot use virtio-serial, # and over ISA serial it answers only as the second port (cua01): the OpenBSD # cloud image keeps its console on com0, which serial0 takes (netork#793). @@ -99,37 +94,6 @@ _GUEST_VM_SETTINGS: dict[str, dict[str, str]] = { # A NIC as Proxmox reports it: "virtio=BC:24:11:AA:BB:02,bridge=vmbr0". _NIC_MAC = re.compile(r"^[a-z0-9]+=([0-9A-Fa-f:]{17})") -# Characters Proxmox keeps in a content file name (PVE::Storage's -# SAFE_CHAR_CLASS_RE); anything else it would rewrite behind our back. -_UNSAFE_FILENAME_CHARS = re.compile(r"[^A-Za-z0-9\-.+=_]") - - -def _url_key(image_url: str) -> str: - """Short hash of the full URL — Ubuntu and others publish a new build - under the same basename every day, so the basename alone is no cache key.""" - return hashlib.sha256(image_url.encode()).hexdigest()[:12] - - -def _split_checksum(image_checksum: str) -> tuple[str, str]: - """``":"`` as ``(algo, hex)``; the algorithm defaults to sha256.""" - algo, _, expected = image_checksum.partition(":") - return (algo or "sha256").lower(), expected - - -def _import_volume_name(image_url: str) -> str | None: - """The file name *image_url* gets in an import storage. - - None when Proxmox cannot import the image's type at all (compressed, - ISO, no extension) — provisioning then downloads it over SSH as before. - """ - basename = image_url.rstrip("/").rsplit("/", 1)[-1] - stem, dot, ext = basename.rpartition(".") - extension = _IMPORT_EXTENSIONS.get(ext.lower()) if dot and stem else None - if extension is None: - return None - safe_stem = _UNSAFE_FILENAME_CHARS.sub("_", stem) - return f"netork-{_url_key(image_url)}-{safe_stem}.{extension}" - def _nic_config_args(nics: list[dict[str, Any]]) -> dict[str, str]: """``{"net": "virtio[=],bridge=[,tag=|,trunks=]"}`` per NIC.""" @@ -197,33 +161,26 @@ class ProxmoxVMProvisionMixin: once (covers a corrupted/partial transfer or a stale same-keyed file) before raising. """ - filename = image_url.rstrip("/").rsplit("/", 1)[-1] - local_path = f"{_IMAGE_CACHE_DIR}/{_url_key(image_url)}-{filename}" - - algo, expected = _split_checksum(image_checksum or "") + local_path = f"{_IMAGE_CACHE_DIR}/{cache_name(image_url)}" + algo, expected = split_checksum(image_checksum or "") max_attempts = 2 for attempt in range(1, max_attempts + 1): - exists = self._run_node_command( - f"mkdir -p {_IMAGE_CACHE_DIR} && test -f {local_path} " - f"&& echo EXISTS || echo MISSING", - timeout=30, - ) - if "EXISTS" not in exists: + if not self._cached_on_node(local_path): self._fetch_image(image_url, local_path, timeout) if not image_checksum: return local_path actual = self._run_node_command( - f"{algo}sum {local_path} | awk '{{print $1}}'", timeout=60 + f"{algo}sum {shlex.quote(local_path)} | awk '{{print $1}}'", timeout=60 ) if actual.lower() == expected.lower(): return local_path # Remove the bad file so the next attempt re-downloads instead of # reusing it. - self._run_node_command(f"rm -f {local_path}", timeout=30) + self._run_node_command(f"rm -f {shlex.quote(local_path)}", timeout=30) if attempt == max_attempts: raise RuntimeError( f"Checksum mismatch for {image_url}: expected {expected}, got {actual}" @@ -235,6 +192,15 @@ class ProxmoxVMProvisionMixin: raise AssertionError("unreachable") # loop always returns or raises above + def _cached_on_node(self, path: str) -> bool: + """Whether *path* is already in the node's image cache (made if missing).""" + found = self._run_node_command( + f"mkdir -p {shlex.quote(_IMAGE_CACHE_DIR)} && test -f {shlex.quote(path)} " + "&& echo EXISTS || echo MISSING", + timeout=30, + ) + return "EXISTS" in found + def _fetch_image(self, image_url: str, local_path: str, timeout: int) -> None: """Download *image_url* to *local_path* on the node, through a ``.tmp``. @@ -242,9 +208,10 @@ class ProxmoxVMProvisionMixin: reaches the error, and a failed download leaves no partial ``.tmp``. """ _logger.info(f"Downloading cloud image {image_url} -> {local_path}") - tmp = f"{local_path}.tmp" + tmp = shlex.quote(f"{local_path}.tmp") + path = shlex.quote(local_path) self._run_node_command( - f"wget -nv -O {tmp} '{image_url}' && mv {tmp} {local_path} " + f"wget -nv -O {tmp} {shlex.quote(image_url)} && mv {tmp} {path} " f"|| {{ s=$?; rm -f {tmp}; exit $s; }}", timeout=timeout, ) @@ -257,22 +224,19 @@ class ProxmoxVMProvisionMixin: the unpacked file is kept. Proxmox's download-url unpacks ISOs only, so a packed image always comes this way. """ - filename = image_url.rstrip("/").rsplit("/", 1)[-1] - unpacked_name, unpack = split_compression(filename) + unpacked_name, unpack = split_compression(cache_name(image_url)) if unpack is None: return self._download_cloud_image(image_url, image_checksum, timeout=timeout) - unpacked = f"{_IMAGE_CACHE_DIR}/{_url_key(image_url)}-{unpacked_name}" - cached = self._run_node_command( - f"mkdir -p {_IMAGE_CACHE_DIR} && test -f {unpacked} && echo EXISTS || echo MISSING", - timeout=30, - ) - if "EXISTS" in cached: + unpacked = f"{_IMAGE_CACHE_DIR}/{unpacked_name}" + if self._cached_on_node(unpacked): return unpacked packed = self._download_cloud_image(image_url, image_checksum, timeout=timeout) _logger.info(f"Unpacking {packed} -> {unpacked}") + tmp = shlex.quote(f"{unpacked}.tmp") self._run_node_command( - f"{unpack} {packed} > {unpacked}.tmp && mv {unpacked}.tmp {unpacked} && rm -f {packed}", + f"{unpack} {shlex.quote(packed)} > {tmp} && mv {tmp} {shlex.quote(unpacked)} " + f"&& rm -f {shlex.quote(packed)}", timeout=timeout, ) return unpacked @@ -344,7 +308,7 @@ class ProxmoxVMProvisionMixin: params: dict[str, Any] = {"url": image_url, "content": "import", "filename": filename} if image_checksum: - algo, expected = _split_checksum(image_checksum) + algo, expected = split_checksum(image_checksum) params["checksum"] = expected params["checksum-algorithm"] = algo _logger.info(f"Downloading cloud image {image_url} into {volid}") @@ -369,7 +333,8 @@ class ProxmoxVMProvisionMixin: local_path = self._cloud_image_on_node(image_url, image_checksum, download_timeout) _logger.info(f"Importing {local_path} into VM {vmid} on storage {image_storage}") self._run_node_command( - f"qm importdisk {vmid} {local_path} {image_storage} --format qcow2", + f"qm importdisk {int(vmid)} {shlex.quote(local_path)} {shlex.quote(image_storage)} " + "--format qcow2", timeout=timeout, ) @@ -401,7 +366,7 @@ class ProxmoxVMProvisionMixin: verifies and copies the image itself — and over SSH otherwise. """ import_storage = self._find_import_storage() - filename = _import_volume_name(image_url) if import_storage else None + filename = import_volume_name(image_url) if import_storage else None if not import_storage or not filename: self._import_over_ssh( vmid, image_storage, image_url, image_checksum, download_timeout, timeout diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 97dd17c..52e528b 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -37,7 +37,6 @@ "napalm_proxmox/system_mixin.py::ProxmoxSystemMixin.set_hostname": 114, "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vm_interfaces": 179, "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vms": 114, - "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin._download_cloud_image": 56, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.create_vm_from_cloud_init": 220, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.destroy_vm": 56, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.get_vm_status": 92 diff --git a/tests/test_vm_import_download.py b/tests/test_vm_import_download.py index 1167bff..3479912 100644 --- a/tests/test_vm_import_download.py +++ b/tests/test_vm_import_download.py @@ -10,10 +10,8 @@ from __future__ import annotations from unittest.mock import MagicMock, patch -from napalm_proxmox.vm_provision_mixin import ( - ProxmoxVMProvisionMixin, - _import_volume_name, -) +from napalm_proxmox.image_names import import_volume_name as _import_volume_name +from napalm_proxmox.vm_provision_mixin import ProxmoxVMProvisionMixin _UBUNTU = ( "https://cloud-images.ubuntu.com/releases/26.04/release/ubuntu-26.04-server-cloudimg-amd64.img" diff --git a/tests/test_vm_provision_mixin.py b/tests/test_vm_provision_mixin.py index 98df5e0..ec5c56c 100644 --- a/tests/test_vm_provision_mixin.py +++ b/tests/test_vm_provision_mixin.py @@ -1417,3 +1417,87 @@ def test_download_cloud_image_does_not_silence_wget(): download = mixin._run_node_command.call_args_list[1][0][0] assert download.startswith("wget -nv ") + + +# --------------------------------------------------------------------------- +# The image URL in root shell commands (#43) +# --------------------------------------------------------------------------- + +# A URL a tampered release feed could publish: a quote that ends hand-written +# quoting, a command substitution and a space, each of which the node's shell +# would act on if the URL or the file name built from it went in unquoted. +_HOSTILE_URL = "https://example.org/$(reboot)/a b/x';reboot;'.img" + +# reboot() records that the shell ran it; wget() saves the URL it was given as +# the "image", so the file's content shows whether the URL arrived as one argument. +_HOSTILE_PRELUDE = ( + 'reboot() { echo injected >> "$MARK"; }; ' + "wget() { " + "while [ $# -gt 0 ]; do " + '[ "$1" = -O ] && o=$2; [ $# -eq 1 ] && u=$1; shift; done; ' + 'printf \'%s\' "$u" > "$o"; }; ' + # The unpack step of a packed image: "xz -dc " as a plain copy. + 'xz() { cat "$2"; }; ' +) + + +def _hostile_shell(tmp_path, monkeypatch) -> ProxmoxVMProvisionMixin: + import napalm_proxmox.vm_provision_mixin as module + + cache = tmp_path / "cache" + monkeypatch.setattr(module, "_IMAGE_CACHE_DIR", str(cache)) + monkeypatch.setenv("MARK", str(tmp_path / "injected")) + mixin = ProxmoxVMProvisionMixin() + mixin._node_ssh = MagicMock(return_value=_LocalShell(_HOSTILE_PRELUDE)) + return mixin + + +def test_a_hostile_image_url_stays_one_argument_in_every_command(tmp_path, monkeypatch): + import hashlib + from pathlib import Path + + mixin = _hostile_shell(tmp_path, monkeypatch) + checksum = "sha256:" + hashlib.sha256(_HOSTILE_URL.encode()).hexdigest() + + path = mixin._download_cloud_image(_HOSTILE_URL, checksum, timeout=10) + + assert not (tmp_path / "injected").exists() + assert Path(path).read_text() == _HOSTILE_URL # wget got the whole URL + assert Path(path).parent == tmp_path / "cache" + + +def test_the_cache_file_name_keeps_only_safe_characters(tmp_path, monkeypatch): + import re + from pathlib import Path + + mixin = _hostile_shell(tmp_path, monkeypatch) + + path = mixin._download_cloud_image(_HOSTILE_URL, None, timeout=10) + + assert re.fullmatch(r"[A-Za-z0-9._+=-]+", Path(path).name) + assert Path(path).name.endswith("-x__reboot__.img") + + +def test_a_packed_hostile_image_is_unpacked_without_running_anything(tmp_path, monkeypatch): + from pathlib import Path + + mixin = _hostile_shell(tmp_path, monkeypatch) + url = _HOSTILE_URL + ".xz" + + path = mixin._cloud_image_on_node(url, None, timeout=10) + + assert not (tmp_path / "injected").exists() + assert Path(path).read_text() == url + assert not path.endswith(".xz") + + +def test_a_checksum_algorithm_outside_the_known_ones_is_refused(): + mixin = ProxmoxVMProvisionMixin() + mixin._run_node_command = MagicMock(return_value="EXISTS") + + with pytest.raises(ValueError, match="checksum algorithm"): + mixin._download_cloud_image( + "https://example.org/img/debian.qcow2", "sha256;reboot;:abc", timeout=10 + ) + + assert not any("reboot" in c.args[0] for c in mixin._run_node_command.call_args_list)