vault-plugin-secrets-netbox/README.md

vault-plugin-secrets-netbox

A Vault / OpenBao secrets engine that mints NetBox API tokens through NetBox's REST API (/api/users/tokens/).

Why

Long-lived NetBox tokens handed to CI and to Puppet fact collectors are hard to rotate and easy to leak. This engine issues short-lived, per-user tokens on demand, each bound to a Vault lease: the token's NetBox expires is aligned to the lease, the lease renewal pushes expires forward, and revoking the lease deletes the token from NetBox.

A single seeded admin token authenticates the engine. NetBox lets an admin token create tokens for other users (with add_token + grant_token), so one credential is enough — a role just names a pre-existing NetBox service user.

NetBox token model (4.6+)

NetBox 4.6 issues v2 tokens by default: only an HMAC digest is stored, and the plaintext is returned once, at creation. A v2 credential authenticates as Authorization: Bearer nbt_<key>.<secret>. Legacy v1 tokens (bare 40-char value) authenticate as Authorization: Token <value>.

• The engine returns both the raw token credential and a ready-to-use authorization header value on each mint.
• v2 tokens require API_TOKEN_PEPPERS to be configured on the NetBox server. If yours is not, set token_version=1 on config to mint v1 tokens (drop-in for older NetBox API clients that only send the Token scheme).

Paths

Path	Description
config	NetBox URL, TLS settings, seeded admin token, token_version, optional admin_user_id/admin_token_id.
config/rotate	Reissue the seeded admin token (mint a replacement for the admin user, delete the old).
roles/<name>	Mint policy: netbox_user_id (or netbox_username), write_enabled (default false), ttl, max_ttl, description.
creds/<role>	Read to mint a short-lived, lease-bound token.

Usage

vault secrets enable -path=netbox vault-plugin-secrets-netbox

vault write netbox/config \
  netbox_url=https://netbox.example.com \
  token="nbt_ab12cd34ef56.XXXXXXXX" \
  ca_cert=@netbox-ca.pem

# A read-only role for a NetBox service user (write_enabled defaults to false).
vault write netbox/roles/puppet-facts netbox_username=svc-puppet-facts ttl=1h max_ttl=8h

# A write-enabled role.
vault write netbox/roles/terraform-ipam netbox_username=svc-terraform-ipam \
  write_enabled=true ttl=30m max_ttl=4h

# Mint one.
vault read netbox/creds/puppet-facts
# -> token, authorization ("Bearer nbt_<key>.<secret>"), expires, ...

Each role points at its own pre-existing NetBox service user (e.g. svc-terraform-ipam, svc-puppet-facts), so a minted token carries exactly that user's NetBox permissions. write_enabled=false additionally forbids create/update/delete regardless of the user's rights.

Development

make build      # build the plugin binary into ./dist
make test       # unit tests (httptest mock NetBox)
make e2e        # full lifecycle vs mock NetBox on Vault + OpenBao (Docker)
make rpm        # build Vault + OpenBao RPMs via nfpm

Releases are tag-driven (make patch|minor|major): a Woodpecker pipeline builds the RPMs and uploads them to the internal artifactapi yum repo.