fix: quote the cloud image URL, raise when a node command cannot run (#43, #17) #45

Merged
christianmanivong merged 2 commits from fix/bugs-2026-11-02 into main 2026-11-02 08:23:52 +00:00
6 changed files with 192 additions and 69 deletions
Showing only changes of commit bfba804ec2 - Show all commits

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)