[ ~/netbox-rpc/integrations ]tty0

emerson@netdevops:~/netbox-rpc$ diagram netbox-rpc --integrations --cross-plugin

Cross-plugin RPC architecture

How netbox-rpc catalogs audited procedures, dispatches through netbox-rpc-backend, and meets companion plugins on shared NetBox objects — without ad-hoc shell or inter-plugin imports.

netbox-rpc never embeds SSH drivers or OpenBao clients for guest credentials. It owns procedure policy, execution audit, and backend selection inside NetBox. netbox-rpc-backend performs host connectivity; netbox-openbao reveals material when a procedure needs login secrets.

Companion plugins — netbox-proxbox, netbox-packer, netbox-fileserver, netbox-proxy, and netbox-openbao itself — integrate by declaring RPCProcedure seeds and calling the same execution API operators use. They do not import each other's Python modules at runtime.

Every integration lane is visible in NetBox: procedure catalog rows, RPCExecution history, and ObjectChange on configuration entities. If a capability is not listed under procedures and executions, it has not been added to the audited surface.

›overview

design principles

  • ├─Policy in NetBox, execution in backend services — netbox-rpc is the contract boundary, not the driver layer.
  • ├─Structured params only — caller input maps to fixed argv; nothing passes through eval, shell interpolation, or ad-hoc one-liners.
  • ├─Credentials via netbox-openbao reveal at execution time — assignments live on devices, VMs, and services; material never appears on GET.
  • ├─Companion plugins queue procedures they need; they never SSH to Proxmox or OpenBao directly when netbox-rpc is installed.
  • ├─Destructive and approval-gated procedures require human intent — automation cannot bypass the gate silently.

›dispatch lane

Lane 1 — procedure dispatch — hover any node for details

operator / companionOperator, nms rpc, nbx, or companion plugin — creates RPCExecution with procedure slug and target object ID.
POST /api/plugins/rpc/executions/
[netbox-rpcplugin]netbox-rpcnetbox-rpc validates RBAC, normalizes params, enqueues RQ job, appends ExecutionQueued and lifecycle events.
RQ worker + event append
netbox-rpc-backendnetbox-rpc-backend receives normalized command over HTTPS, selects driver, connects to target host.
RPCBackend HTTPS
target hostManaged device, VM, Proxmox endpoint, or service — must exist in NetBox before dispatch.

SSH / CLI driver

›credential lane

Lane 2 — credential resolution — reveal at execution time only

RPCExecutionRunning RPCExecution — backend knows credential assignment ID from target object, not secret bytes.
procedure requires SSH
[netbox-openbaoPOST reveal]netbox-openbaonetbox-openbao services.py — POST reveal with reveal_credential permission and optional reason.
POST reveal
broker / OpenBaonetbox-openbao-broker (optional) — holds AppRole; NetBox uses mTLS client cert.
KV v2 read
OpenBao KV v2OpenBao KV v2 — password, private key, or token material returned once to backend over TLS.
SSH auth
SSH targetSSH session to guest or host — material never stored in RPCExecution params or GET responses.

›plugin map

Lane 3 — cross-plugin map — shared NetBox objects, no direct plugin imports

[netbox-rpccatalog + ledger]netbox-rpcnetbox-rpc — single procedure catalog and execution history for all lanes.
[netbox-proxbox]netbox-proxboxnetbox-proxbox — inventory + optional service monitoring RPC triggers on ProxmoxEndpoint.[netbox-openbao]netbox-openbaonetbox-openbao — credential assignments on VMs/devices; vault host ops as RPC procedures.netbox-packernetbox-packer — template verify procedures after bake completes.netbox-fileservernetbox-fileserver — Samba share validation procedures.netbox-proxynetbox-proxy — NGINX test/reload deploy procedures.

creates target objects · CredentialAssignment · queue RPCExecution · append-only ledger

PluginIntegrationTypical procedures
netbox-proxboxEndpoint service monitoring, Proxmox SSH readssystemd status refresh, read-only host probes
netbox-openbaoVault host operationshealth, seal status, policy reload via audited RPC
netbox-packerTemplate bake verificationpost-build SSH checks on baked templates
netbox-fileserverSamba share validationshare list and permission probes
netbox-proxyNGINX config deployconfig test and reload through netbox-rpc
netbox-openbao-brokerVault access pathmTLS broker sits between NetBox and OpenBao for reveal and host ops

›what stays outside netbox-rpc

Inventory sync — proxbox discovery, OpenBao KV writes, Packer image builds — runs in its own lane. RPC executes only after the target object exists in NetBox and a procedure is enabled for that object type.

netbox-rpc-backend is not a second NetBox plugin. It is a separate FastAPI service registered as an RPCBackend row. Rotating backend URLs or credentials is configuration, not a code deploy inside the NetBox venv.

Guest SSH for automation should flow: assign credential in netbox-openbao → queue RPC execution with target VM → backend reveals → SSH. Skipping reveal and embedding passwords in procedure params violates the split boundary.

# netbox-rpc docs/cross-plugin-integrations.md

# netbox-openbao docs/architecture/openbao-broker-rpc.md

# netbox-proxbox docs/companion-plugins/netbox-rpc.md

›typical operator sequence

  1. Confirm RPCBackend points at netbox-rpc-backend and required RPCProcedure rows are enabled (seed migrations or admin UI).
  2. Assign SSH credentials on the target device or VM through netbox-openbao when the procedure family needs login material.
  3. Create an RPCExecution from the UI, nms rpc, or a companion plugin trigger (e.g. proxbox service refresh).
  4. Approve if the procedure requires it; watch execution events until status is succeeded or failed.
  5. Inspect stdout/stderr and ObjectChange — the ledger is the audit record for compliance and postmortems.
see also›netbox-rpc showcasesee also›Proxmox VM secrets — proxbox + openbao