Assess Proxmox VE with cnspec

Rely on cnspec to query and assess your Proxmox VE clusters, including nodes, virtual machines, storage pools, networks, firewall rules, users, API tokens, and pending package updates.

Prerequisites

To analyze your Proxmox VE environment with cnspec, you must have:

cnspec installed on your workstation
A Proxmox VE 7.x or 8.x cluster
A Proxmox API token with at least the PVEAuditor role
Network access from your workstation to the Proxmox API on port 8006
The QEMU Guest Agent installed inside any VM whose pending updates you want to query

Configure access to Proxmox VE

To create an API token:

Log in to the Proxmox VE web UI as a user with permission to manage tokens.
Navigate to Datacenter > Permissions > API Tokens.
Add a new token for a user that has at least the PVEAuditor role on /.
Copy the resulting token value. cnspec expects the full token string in this form:
```
PVEAPIToken=user@realm!tokenid=secret
```
For example: PVEAPIToken=root@pam!cnspec=00000000-1111-2222-3333-444444444444

Connect to Proxmox VE

To launch an interactive shell against a Proxmox VE cluster:

cnspec shell proxmox \
  --host https://192.168.1.10:8006 \
  --token 'PVEAPIToken=user@realm!tokenid=secret'

If your Proxmox host uses a self-signed certificate, add the --insecure (or -k) flag to skip TLS verification:

cnspec shell proxmox \
  --host https://pve.example.com:8006 \
  --token 'PVEAPIToken=user@realm!tokenid=secret' \
  --insecure

Scan Proxmox VE

To scan your Proxmox VE cluster:

cnspec scan proxmox \
  --host https://192.168.1.10:8006 \
  --token 'PVEAPIToken=user@realm!tokenid=secret'

You can also create your own policies to meet your specific requirements.

Example queries

Cluster overview

cnspec> proxmox.cluster { name quorate nodeCount version }

List nodes with hardware information

cnspec> proxmox.nodes { name cpuModel cpuCores memTotal kernelVersion pveVersion }

Inspect running services on each node

cnspec> proxmox.nodes { name services.where(state == "running") { name } }

List virtual machines

cnspec> proxmox.vms { id name status bios agent tags networks { model bridge } }

Find VMs with pending security updates

cnspec> proxmox.vms.where(status == "running") {
  name
  updates.where(severity == "security" && upgradable == true) { name newVersion }
}

Storage capacity overview

cnspec> proxmox.storages { id type usagePercent total }

Audit users and their API tokens

cnspec> proxmox.users { id tokens { id expire privsep } }

Inspect VM firewall rules

cnspec> proxmox.vms { name firewallRules { pos action proto dest dport } }

Learn more

To learn more about how the MQL query language works, read Write Effective MQL.
For a list of all the Proxmox resources and fields you can query, read the Proxmox Resource Pack Reference.

Assess Proxmox VE with cnspec

On this page