emerson@netdevops:~/netbox-rpc$ ./describe.sh netbox-rpc
netbox-rpc
NetBox plugin that catalogs audited remote procedures, dispatches them through netbox-rpc-backend, and records every execution in NetBox.
netbox-rpc is the Remote Command Policy bounded context inside NetBox. It owns the procedure catalog, approval and destructive gates, execution audit ledger, and backend dispatch — not SSH drivers or device protocol implementations. Those live in netbox-rpc-backend and other executor services.
Every host operation that would otherwise become an ad-hoc shell script becomes a seeded RPCProcedure with a params schema, Linux-service allowlist entry when applicable, and a visible execution history. Operators and automation share one NetBox RBAC model for execute, approve, and cancel.
›overview
emerson@netdevops:~/netbox-rpc$ cat OVERVIEW.md
netbox-rpc is the Remote Command Policy bounded context inside NetBox. It owns the procedure catalog, approval and destructive gates, execution audit ledger, and backend dispatch — not SSH drivers or device protocol implementations. Those live in netbox-rpc-backend and other executor services.
Every host operation that would otherwise become an ad-hoc shell script becomes a seeded RPCProcedure with a params schema, Linux-service allowlist entry when applicable, and a visible execution history. Operators and automation share one NetBox RBAC model for execute, approve, and cancel.
›features
emerson@netdevops:~/netbox-rpc$ ./features --list
- ├─RPCProcedure catalog with versioned commands, effect classes, and optional approval/destructive gating
- ├─Append-only RPCExecutionEvent ledger with projection fold — terminal states never transition backward
- ├─RPCBackend registry selects netbox-rpc-backend (or other executors) without embedding drivers in the plugin
- ├─Credential material resolved through netbox-openbao reveal when a procedure needs SSH keys or passwords
- ├─Companion integrations: netbox-proxbox service monitoring, netbox-packer template verify, netbox-fileserver Samba, netbox-proxy NGINX deploy
- ├─OpenBao host operations (health, seal status, policy reload) as audited procedures — never raw shell from other plugins
- ├─nms rpc / nbx automation dispatch through the same REST API and permission checks as the UI
›how it works
An operator or API client creates an RPCExecution against an enabled RPCProcedure and target NetBox object (device, VM, service, or plugin-specific endpoint). The command handler checks execute permission, normalizes params against the schema, and enqueues an RQ job.
The job selects an RPCBackend row, forwards the normalized command to netbox-rpc-backend over HTTPS, and appends typed domain events as progress arrives. Success, failure, and cancellation each land in the execution projection and in NetBox ObjectChange where applicable.
When SSH material is required, the backend asks NetBox to reveal assigned credentials through netbox-openbao (direct AppRole or broker mTLS). Inventory metadata stays in NetBox; secrets never enter procedure params or GET responses.
| Owned by netbox-rpc | Owned by executor backend |
|---|---|
| procedure policy and params schema | SSH/CLI driver selection |
| approval / destructive gates | fixed-argv command assembly |
| RPCExecution audit ledger | host connectivity and timeouts |
| NetBox RBAC for execute/cancel | credential reveal callback to openbao |
| RPCBackend routing metadata | stdout/stderr capture and redaction |
›security model
- ├─Caller input never reaches a shell — handlers use structured params mapped to fixed argv templates
- ├─Destructive procedures require explicit approval and never run autonomously from companion plugins
- ├─Execution events are append-only with payload hashing; ORM deletes on the ledger are rejected
- ├─Backend exceptions are bounded and redacted before they reach clients or ObjectChange snapshots
- ├─Reveal permissions stay on netbox-openbao; RPC only references credential assignments by ID
›ecosystem
- netbox-rpc-backend
FastAPI executor that runs audited procedures over SSH/CLI. netbox-rpc selects a backend row; drivers never ship inside the NetBox plugin.
- netbox-openbao
Stores SSH and API material in OpenBao KV v2. RPC backends reveal assigned credentials at execution time with the same POST-only audit trail.
- netbox-openbao-broker
Optional sidecar so vault AppRoles never sit on the NetBox host. RPC and openbao share the broker path for host operations and guest SSH.
- netbox-proxbox
Queues read-only systemd service monitoring and Proxmox endpoint SSH procedures through netbox-rpc when the companion integration is enabled.
- netbox-packer · netbox-fileserver · netbox-proxy
Template verification, Samba share checks, and NGINX config deploy each declare companion RPC procedures — see the cross-plugin architecture page.
›stack
emerson@netdevops:~/netbox-rpc$ cat stack.txt
- › NetBox plugin (Django / Python 3.12+)
- › PostgreSQL 15+ for procedure catalog and execution ledger
- › Redis 6+ and NetBox RQ for async dispatch
- › netbox-rpc-backend executor (FastAPI, multi-driver SSH layer)
›install
emerson@netdevops:~/netbox-rpc$ install
# Requires netbox-rpc-backend reachable from NetBox and RPCBackend rows seeded for your estate. Companion plugins add optional procedure families.
›api
List procedures, create executions, and poll status through /api/plugins/rpc/. Approval-gated runs expose a separate approve action.
curl -H "Authorization: Bearer $TOKEN" \ 'https://netbox.example.net/api/plugins/rpc/procedures/?enabled=true'
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"procedure":"os.linux.ubuntu.24.restart_service","target":44,"params":{"service_slug":"netbox"}}' \
'https://netbox.example.net/api/plugins/rpc/executions/'›repo
emerson@netdevops:~/netbox-rpc$ repo:stats
- stars
- 0
- forks
- 0
- lang
- Python
- release
- —
static · from public/github-data
›links
emerson@netdevops:~/netbox-rpc$ links