PVE Builder

Proxmox VE VM builder with cloud-init automation, config-driven hardware defaults, validation, and static IP support

Security Scan

The skill's behavior matches its stated purpose (generating Proxmox qm commands and storing local keys), but the shipped implementation has unsafe use of shell execution with user-controlled inputs and other risky code patterns that merit review before use.

Purpose & Capability

Name/description match what the files do: generate Proxmox QM commands, build cloud-init user-data, manage local SSH keys, and ask the user to run/verify things on the Proxmox node. No unrelated cloud credentials, remote APIs, or unexpected network endpoints are requested.

Instruction Scope

SKILL.md and agent.js stick to generating commands and asking the user to run validation on the Proxmox node (they explicitly forbid remote Proxmox access). The agent reads pve-env.md and writes local files (cache and SSH keys) as described. However, the implementation runs shell commands (ssh-keygen, mkdir, chmod) via child_process.exec wrappers and interpolates user-supplied values (vmName, keyDir, imagePath) into shell strings — this introduces a command-injection risk if untrusted input is provided. Also the fallback behavior writes a 'placeholder' private key file if ssh-keygen fails; that may produce a non-functional private key stored on-disk and should be reviewed.

Install Mechanism

No install spec or third-party downloads are present (instruction-only with an included agent.js). Nothing is downloaded from external URLs or extracted; risk from install mechanism is low. The runtime will perform local file operations and spawn a few common binaries (ssh-keygen, chmod).

Credentials

The skill requests no environment variables or external credentials. It stores private SSH keys locally (default: ~/.ssh/pve-builder/) and a validation cache (~/.pve-builder/validation.json). That storage is proportional to its purpose, but private keys are generated without passphrases and the code attempts to chmod them — you should verify file locations, permissions, and retention policies. No secrets are sent to remote endpoints in the code provided.

Persistence & Privilege

No elevated platform privileges requested (always:false). The skill writes a small cache (~/.pve-builder) and stores keys in the user's SSH directory; this is expected. The combination of autonomous invocation being allowed by default is not, by itself, a problem — but if the skill were allowed to run automatically, the command-injection vulnerability could be triggered without careful prompts/validation.

What to consider before installing

This skill appears to do what it says (generate Proxmox qm commands and help build cloud-init), but review and harden the implementation before trusting it with real inputs or running it autonomously. Specific suggestions: - Review agent.js for shell-injection risks: functions call child_process.exec with string interpolation of user-controlled values (vm name, key directory, image path). If you use the skill, avoid passing untrusted characters in those prompts or prefer a version that uses execFile/spawn with argument arrays or sanitizes inputs. - Inspect any pve-env.md you create for sensitive content and ensure it has strict permissions (chmod 600) as the SKILL.md recommends. - The skill generates private SSH keys without passphrases and writes them to disk; confirm the directory, permissions, and retention policy meet your security requirements. If ssh-keygen fails, the code writes placeholder 'private key' text — verify and delete placeholders if present. - Because the skill asks you to run validation commands on the Proxmox node and paste outputs, do not paste untrusted outputs into the agent; treat pasted data as potentially adversarial input for the agent's parser. - Prefer to run this tool interactively (not in an autonomous mode) until you (or someone you trust) have audited/mitigated the command-injection issues and are comfortable with its local file writes. If you want, I can point out the exact lines in agent.js that are risky and suggest safe code replacements (use spawn/execFile, escape/sanitize inputs, avoid writing placeholder private keys, etc.).

CRITICAL: Agent Access Limitations

YOU DO NOT HAVE ACCESS TO PROXMOX

Agent runs on your local machine - NOT on Proxmox

Forbidden:

• Try to run qm commands
• Try to run pvesh commands
• Check storage availability
• Verify VM creation
• Access Proxmox API

Must Do:

• Output commands as text for user to copy/paste
• Tell user which node to SSH to
• Store keys locally in a configurable directory (default: ~/.ssh/pve-builder/)
• Never claim to create VMs
• Use web search for specs validation

---

PVE Builder Skill

Overview

Generates Proxmox VM creation commands with cloud-init configuration, SSH key management, and optional data disks. All hardware defaults are config-driven via pve-env.md.

IMPORTANT: Commands are output as text for you to copy/paste into Proxmox shell. The agent does NOT execute any Proxmox commands.

---

Environment Setup

• Config file: pve-env.md in the skill directory
• Ignored from git: .gitignore excludes pve-env.md

Critical Configuration Keys (pve-env.md)

Section	Keys	Purpose
Proxy	Proxy Required, HTTP Proxy, HTTPS Proxy, Proxy CA Certificate	Network proxy for apt inside VMs
SSH	Default User, Key Path, Key Type	Default SSH user, key storage location, key type
Network	Default Bridge, Default VLAN, DNS Server, Use DHCP Default, Network Interface	Default network settings and interface type
Storage	Default Storage, Template Path, Default OS Disk Size, Auto-Format Data Disks, Data Disk Interface, Default Cloud Image	Storage defaults and cloud image path
Node	Default Node, BIOS Type, Machine Type, CPU Type, OS Type, SCSI Controller, Onboot	Hardware defaults for VM creation
Workload Presets	Preset table (RAM/CPU/Disk)	Recommended specs per workload type
Package Defaults	Package Update, Base Packages	Always-installed package list

Agent Workflow

The workflow uses section-based numbered prompts with continuous numbering across sections:

=== VM Specs ===
1. CPU cores  2. CPU sockets  3. RAM in GB  4. OS disk size

=== Network ===
5. Bridge  6. VLAN  7. DHCP?
  [if static:] 8. IP  9. Gateway  10. DNS

=== User & Disks ===
11. SSH user  12. Add data disks?  13. Format?  14. Count  15.x: Disk sizes
15. Proxy?  16. Extra packages  17. SSH key directory

Steps:

1. Load pve-env.md (error if missing)
2. Ask cloud image path (default from config: Template Path + Default Cloud Image)
3. Ask Proxmox node (default from config)
4. Validate storage/bridge/image (see Validation section below)
5. Ask VM name
6. Software lookup (name or URL) → web search for RAM/CPU recommendations (or manual)
7. Prompt specs (numbered prompts: cores, sockets, RAM, OS disk)
8. Prompt network (bridge, VLAN, DHCP vs static)
9. Static IP details (only if no DHCP)
10. Prompt SSH username
11. Prompt data disks (count, sizes, formatting option)
12. Proxy configuration (yes/no/change)
13. Extra apt packages
14. SSH key directory (default from config)
15. Generate SSH key (unique ed25519 per VM)
16. Show summary & confirm
17. VMID (direct input / auto helper / manual)
18. Build cloud-init user-data YAML (packages, proxy, data disk formatting)
19. Generate and display commands
20. Optional: save commands to file
21. Show SSH key path and chmod reminder

Validation

Before generating commands, the agent validates that the target storage, bridge, and cloud image exist on the Proxmox node.

Cache System

• Cache file: ~/.pve-builder/validation.json
• Valid for: 24 hours
• Cache invalidated if: node, storage, or bridge values change
• On cache hit: validation is skipped if all checks passed

Validation Process

If no valid cache exists, the agent shows these commands for the user to run on the Proxmox node:

echo "=== Storage ==="; pvesm status
echo "=== Bridge ==="; ip -br link show
echo "=== Image ==="; ls -la <image-path>
echo "=== END ==="

Results are parsed:

• Storage: Checks if configured storage name exists in pvesm status
• Bridge: Verifies bridge interface is present and UP
• Image: Confirms cloud image file exists at path

On failure: Agent aborts and reports which check(s) failed. On success: Results are cached with node/storage/bridge/timestamp.

Notes

• Cloud-init user-data is written to /var/lib/vz/template/cloud-init/<VMNAME>-user-data.yaml on the Proxmox node
• The command to get the next VMID is provided as a hint; the agent does not run Proxmox commands
• SSH keys are stored locally in the configured directory (default: ~/.ssh/pve-builder/)
• Generated commands include cleanup steps at the end: lists cloud-init YAML files for review, then removes the current VM's file

Networking

DHCP (default)

Simple network config: qm set --ipconfig0 ip=dhcp

Static IP

When DHCP is declined, the agent prompts for:

• IP address with CIDR (e.g., 10.0.12.50/24)
• Gateway (e.g., 10.0.12.1)
• DNS servers (comma-separated, default from config)

Generated commands:

• qm set --ipconfig0 ip=10.0.12.50/24,gw=10.0.12.1
• qm set --nameserver 8.8.8.8

Package Installation

All VMs get base packages from pve-env.md (deduplicated with any extra packages).

If proxy is configured, apt proxy is automatically enabled in cloud-init.

Security

• SSH keys: Unique per VM, ed25519, no passphrase
• Passwords: Never used, SSH keys only
• pve-env.md: chmod 600, excluded from git
• Private keys: chmod 600, never in commands
• Public keys: Safe to embed in commands
• SSH key directory: configurable via Key Path in pve-env.md (default ~/.ssh/pve-builder); permissions 700 on base dir

Version History

• 1.0.3: Full config decoupling (all hardware defaults from pve-env.md), storage/bridge validation with 24h cache, static IP support, continuous numbered prompts with section headers, SSH key path not echoed in summary, duplicate package removal, direct VMID input, cloud-init cleanup commands
• 1.0.2: Added URL analysis, web search validation, simplified proxy flow
• 1.0.1: Added explicit access limitation warnings
• 1.0.0: Initial release

---

This file is yours to evolve. As you learn who you are, update it.