This document describes the security controls implemented in proxmox-sdk, including what is protected, how each control works, and how to verify it.
All user-supplied URLs passed to the codegen pipeline are validated by validate_source_url() in proxmox_codegen/security.py before any outbound request is made.
| Category | Examples | Error |
|---|---|---|
| Non-HTTPS schemes | file://, gopher://, http:// (default) |
Invalid URL scheme |
| Private IPv4 ranges | 10.x.x.x, 192.168.x.x, 172.16–31.x.x, 127.x.x.x, 169.254.x.x |
SSRF attempt blocked: private IP range |
| Private IPv6 ranges | ::1, fe80::, fc00:: |
SSRF attempt blocked: private IPv6 range |
| IPv4-mapped IPv6 | ::ffff:127.0.0.1, ::ffff:10.0.0.1 |
SSRF attempt blocked: IPv6-mapped address |
| 6to4 addresses | 2002:7f00::1 (encodes 127.0.0.1) |
SSRF attempt blocked: IPv6-mapped address |
| Localhost strings | localhost, 127. prefix patterns |
SSRF attempt blocked: localhost |
| Non-Proxmox domains | Any hostname not under *.proxmox.com |
not in the allowed domains list |
By default only official Proxmox documentation domains are permitted:
pve.proxmox.com
pmg.proxmox.com
pbs.proxmox.com
pdm.proxmox.com
proxmox.com
To allow other domains (e.g. a self-hosted API viewer), pass allow_any_domain=True explicitly in code. The API endpoint does not expose this flag to callers.
Plain HTTP is blocked by default. Pass allow_http=True to validate_source_url() in trusted internal tooling only.
Browser crawling validates every ordinary HTTP request against the source origin. Allowed routes are fetched with zero redirects and zero retries; a redirect is rejected before any followed-hop network I/O or browser fulfillment. Ordinary same-origin resources remain available.
All WebSockets are refused without connecting upstream, including same-origin sockets. Their route callbacks queue refusals for the owning synchronous caller to close after navigation, selector processing, and during cleanup. Each drain processes only the queue snapshot present on entry, so reentrant callbacks cannot keep a drain running indefinitely. Browser closure disposes final unconnected routes and clears remaining handles. Both synchronous and asynchronous crawler entry points preserve this policy.
The original Chromium security regressions retain their assertions and deadlines. Public browser CI runs every complete schema row on Ubuntu 24.04 and installs the exact locked Chromium revision with the official ephemeral-host dependency installer before testing. An empty browser cache must not substitute skips for these regressions.
Read-only CI validates lint, syntax/imports, distributions and installed wheels, every complete browser-enabled schema row, documentation generation, and strict documentation build. Its always-run summary rejects failed, cancelled, missing, or unexpectedly skipped quality jobs and unexpected Docker dispositions.
The optional non-secret repository variable CI_QUALIFICATION_ONLY, set to the
canonical literal true, suppresses only CI Docker publication and the legacy
documentation writer while preserving all read-only quality. An absent value
preserves ordinary future publication. A normal feature pull request must pass
complete CI before protected main integration. A controlled protected squash
may then use the temporary variable for its main event; both writers must be
terminal and skipped before restoring the previous absent setting. A later
rerun requires a fresh guarded qualification window.
Version tags used in codegen URLs and file paths are validated by validate_version_tag():
- Only
[a-zA-Z0-9._-]characters are permitted ..,/, and\are rejected (prevents path traversal)- Empty strings are rejected
When you call Files.download_file_to_storage(url) without an explicit
checksum=, the SDK tries to auto-discover one by requesting sibling URLs
({url}.sha256, {base}/SHA256SUMS, …) from the SDK host. Because that
outbound request is driven by a caller-supplied URL, _is_safe_probe_url() in
sdk/tools/files.py gates it:
- Only
httpandhttpsschemes are probed. - Hosts that are loopback, private, link-local, or reserved IP literals — incl.
IPv4-mapped IPv6 (
::ffff:…) andlocalhost— are refused, so a download URL pointing at a cloud-metadata endpoint (169.254.169.254) or an internal service never triggers an SDK-side probe. - Public hostnames pass; DNS-rebinding is out of scope (matching the codegen guard, which also inspects only IP literals).
If the URL is refused the SDK logs a warning and skips discovery (the download
itself still proceeds — Proxmox performs it). Pass an explicit checksum= to
verify the artifact and bypass discovery entirely.
POST /codegen/generate and related endpoints require a Bearer token set via the CODEGEN_API_KEY environment variable.
export CODEGEN_API_KEY=your-secret-key
curl -H "Authorization: Bearer your-secret-key" \
-X POST "http://localhost:8000/codegen/generate?..."Missing or wrong credentials return 401 Unauthorized. The endpoint is also rate-limited to 1 request per hour per IP to prevent abuse.
SlowAPI rate limits are applied to resource-intensive endpoints:
| Endpoint | Limit |
|---|---|
POST /codegen/generate |
1 / hour |
GET /codegen/openapi |
5 / hour |
GET /codegen/pydantic |
5 / hour |
Rate limiting uses the direct client IP. Behind a trusted reverse proxy, configure X-Forwarded-For forwarding at the proxy layer.
CORS is disabled by default (no origins allowed). Enable it by setting CORS_ORIGINS:
export CORS_ORIGINS=https://your-app.example.com,https://staging.example.comWhen set, allowed headers are restricted to:
Content-Type, Authorization, X-Requested-With
Wildcards (*) are never used for headers or origins.
GET /health returns 404 Not Found for any client not connecting from localhost. This prevents the endpoint from being used as a service-discovery probe.
Allowed hosts: 127.0.0.1, ::1, localhost.
testclient (Starlette test helper) is only added when TESTING=1 is set.
Unhandled exceptions are caught by a global handler and returned as a generic 500 response:
{"detail": "An internal server error occurred."}Stack traces, file paths, and internal state are never sent to clients. Full exception details are logged server-side at ERROR level.
Proxmox credentials (PROXMOX_API_TOKEN_SECRET, PROXMOX_API_PASSWORD, PROXMOX_API_OTP) are read once at startup and then overwritten with "********" in os.environ. Subsequent code cannot accidentally read the raw values from the environment.
The CLI stores credentials in ~/.proxmox-cli/config.json. On write:
- The config directory is set to
0700 - The config file is set to
0600 - Writing is refused if the file or its parent directory is a symbolic link
On load, a warning is emitted if the file has group or other read/write permissions.
A SensitiveDataFilter is applied to all log output. It redacts values following these patterns before anything reaches stdout:
password=… token_value=… token_secret=…
PVEAuthCookie=… PMGAuthCookie=… PBSAuthCookie=…
CSRFPreventionToken=… Authorization=…
The Paramiko SSH backend uses WarningPolicy (logs unknown host keys) instead of AutoAddPolicy (silently accepts any key). System known_hosts is loaded automatically.
To enforce strict verification, pass a custom policy at construction:
from paramiko import RejectPolicy
from proxmox_sdk.sdk.backends.ssh_paramiko import SshParamikoBackend
backend = SshParamikoBackend(
host="pve.example.com",
user="root",
service_config=...,
host_key_policy=RejectPolicy(),
)SSH command execution uses shlex.join() to properly quote all arguments. Remote temp file cleanup uses shlex.quote() on each path. The OpenSSH backend uses shlex.join() natively.
Uploaded temp files on the remote host use secrets.token_hex(8) (64-bit random) instead of id(object) (predictable memory address).
Both SSH backends clean up temp files uploaded to the remote host in a finally block, preventing data leakage from failed transfers.
SSL certificate verification is enabled by default (PROXMOX_API_VERIFY_SSL=true). Disable only in trusted internal networks:
export PROXMOX_API_VERIFY_SSL=falseThe TicketAuth handler uses the same SSL context configured for the backend when making the /access/ticket POST. This ensures that verify_ssl=False applies consistently across both auth and API requests rather than silently defaulting to system CAs for the auth step.
# Verify SSRF protection rejects private IPs
curl "http://localhost:8000/codegen/generate?source_url=http://169.254.169.254/"
# → 400 Bad Request
# Verify codegen requires auth
curl -X POST "http://localhost:8000/codegen/generate"
# → 401 Unauthorized
# Verify health endpoint is hidden
curl "http://external-host:8000/health"
# → 404 Not Found
# Verify error responses don't leak internals
curl "http://localhost:8000/nonexistent-path-xyz"
# → 404 with {"detail": "Not Found"} — no stack trace| Variable | Purpose | Default |
|---|---|---|
CODEGEN_API_KEY |
Bearer token for /codegen/* endpoints |
— (required for codegen) |
CORS_ORIGINS |
Comma-separated list of allowed origins | "" (disabled) |
PROXMOX_API_VERIFY_SSL |
Enable SSL certificate verification | true |
PROXMOX_API_TOKEN_SECRET |
API token secret (cleared from env after read) | — |
PROXMOX_API_PASSWORD |
Password auth (cleared from env after read) | — |
TESTING |
Add testclient to health endpoint allow-list |
"" (disabled) |