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
This commit is contained in:
Christian Manivong committed 2026-11-02 08:46:44 +01:00
1 parent 6a8132e234
commit bfba804ec2
6 files changed
+192 -69

No files matched your search

+7
View File
@@ -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
+70
View File
@@ -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
# "<algo>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]:
"""``"<algo>:<hex>"`` 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}"
+29 -64
View File
@@ -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]:
"""``"<algo>:<hex>"`` 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<i>": "virtio[=<mac>],bridge=<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
-1
View File
@@ -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
+2 -4
View File
@@ -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"
+84
View File
@@ -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 <file>" 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)