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)