[ ~/netbox-openbao ]tty0

emerson@netdevops:~/netbox-openbao$ ./describe.sh netbox-openbao

netbox-openbao

NetBox plugin that keeps secret material in OpenBao while NetBox owns credential inventory, assignments, and audit.

netbox-openbao splits secret material from credential metadata. Private keys, passwords, and API tokens live only in OpenBao KV v2. Usernames, fingerprints, expiry dates, and device assignments stay in NetBox — searchable, filterable, and safe to export without a reveal permission.

Unlike browser-side vault plugins, every resolve path is server-side over the NetBox REST API, so automation and operators share one authorization model. Reveal is a separate permission, POST-only in the UI, JSON-only on the wire, and fully audited.

license=Apache-2.0netbox=4.6.x – 4.7.xpython=3.12+

›overview

emerson@netdevops:~/netbox-openbao$ cat OVERVIEW.md

netbox-openbao splits secret material from credential metadata. Private keys, passwords, and API tokens live only in OpenBao KV v2. Usernames, fingerprints, expiry dates, and device assignments stay in NetBox — searchable, filterable, and safe to export without a reveal permission.

Unlike browser-side vault plugins, every resolve path is server-side over the NetBox REST API, so automation and operators share one authorization model. Reveal is a separate permission, POST-only in the UI, JSON-only on the wire, and fully audited.

›features

emerson@netdevops:~/netbox-openbao$ ./features --list

  • ├─No model field can hold secret material — changelog, exports, and REST GET responses are safe by construction
  • ├─Inventory queries (expiry, fingerprint, assignment) need zero OpenBao reads
  • ├─Dedicated reveal permission with object-level constraints in standard NetBox RBAC
  • ├─Staged rotation: write candidate alongside live version, promote on decision
  • ├─Per-tier AppRoles bound blast radius; optional broker mode keeps vault credentials off the NetBox host
  • ├─HashiCorp Vault supported as an alternative backend on the same wire contract
  • ├─Quick-add SSH password flow; broker mode and netbox-rpc integrate without a proprietary credential mirror

›how it works

NetBox stores Credential rows, policy tiers, engine configuration, assignments to devices/VMs/services, and a complete access log. OpenBao stores the payload — private key, password, token, or certificate key — addressed by a path derived from the engine and policy tier.

Every operation that touches material flows through services.py inside the NetBox process. UI views, REST viewsets, forms, and background jobs never call OpenBao directly; they call the service layer, which picks the correct AppRole (or broker client certificate) and enforces NetBox permissions first.

Reading material requires the reveal_credential action. Writing creates or rotates a KV version with explicit compensation if PostgreSQL rolls back. Destroying a row schedules vault deletion after commit so a failed transaction never wipes working secrets.

Goes to OpenBaoStays in NetBox (indexed)
private keypublic key
passphraseSHA256 fingerprint
passwordusername
API tokenkey type and bit length
certificate private keyserial, issuer, subject, not_before, not_after

›security model

  • ├─secret_data is write-only in the REST API — DRF refuses to serialize it on GET, brief, or browsable API
  • ├─Reveal responses are Cache-Control: no-store and exclude the HTML browsable renderer
  • ├─Backend exceptions carry no vendor text — OpenBao policy hints never reach logs or clients
  • ├─AppRole SecretIDs load from environment or _FILE mounts, never from the database
  • ├─Broker mode removes vault credentials from NetBox configuration; NetBox holds an mTLS client cert and asks the broker to read
see also›Proxmox VM & container secrets — proxbox + openbao architecturesee also›netbox-rpc cross-plugin integrations — dispatch, reveal, companions

›ecosystem

  • netbox-openbao-broker

    Optional sidecar that holds the AppRole. NetBox authenticates with a client certificate; audit log sits outside NetBox's blast radius.

  • netbox-rpc

    OpenBao host operations and companion automation dispatch through audited RPC procedures — see the cross-plugin architecture page.

  • netbox-sdk / nbx

    Automation resolves credentials through the plugin REST API (/api/plugins/openbao/credentials/) with the same tokens and RBAC as any other NetBox endpoint.

›stack

emerson@netdevops:~/netbox-openbao$ cat stack.txt

  • › NetBox plugin (Django / Python 3.12+)
  • › OpenBao 2.6.x KV v2 (HashiCorp Vault optional)
  • › PostgreSQL 15+ with ltree
  • › Redis 6+ and NetBox RQ for background jobs

›install

emerson@netdevops:~/netbox-openbao$ install

install
emerson@netdevops:~$ pip install netbox-openbao

# Requires OpenBao (or Vault) with KV v2, AppRole auth, and per-engine SecretID in the NetBox process environment.

›api

Inventory endpoints never return material. Reveal requires netbox_openbao.reveal_credential and an optional reason query parameter.

inventory — no OpenBao read
curl -H "Authorization: Bearer $TOKEN" \
  'https://netbox.example.net/api/plugins/openbao/credentials/?expires_within_days=30'
reveal — separate permission
curl -X POST -H "Authorization: Bearer $TOKEN" \
  'https://netbox.example.net/api/plugins/openbao/credentials/142/reveal/?reason=CHG-1234'

›repo

emerson@netdevops:~/netbox-openbao$ repo:stats

$ gh repo view emersonfelipesp/netbox-openbao --json
stars
0
forks
0
lang
Python
release
—

static · from public/github-data

›links

emerson@netdevops:~/netbox-openbao$ links