netbox-secrets-manager

Attach secrets to NetBox objects — BMC credentials on a device, a private certificate on a virtual machine — while keeping AWS Secrets Manager as the system of record. NetBox stores only metadata: the ARN, which object the secret belongs to, and which shape it has.

No field on any model in this plugin ever holds plaintext or ciphertext.

Why not netbox-secrets?

netbox-secrets encrypts secrets inside NetBox: a per-user RSA keypair wraps a per-install master key, which wraps a session key, which encrypts each value. Decryption is a cryptographic capability, held by whoever has the private key.

That makes one common arrangement impossible to express: an operator who may rotate a BMC password but may not read it. This plugin moves storage to AWS and makes decryption a permission instead, so view (list without revealing), decrypt (reveal), add/change (write) and delete are granted separately.

The trade-off is explicit and you should read docs/security.md before deploying: the application's IAM role holds GetSecretValue at all times, so decrypt is an application-layer control, not an IAM one.

What it does

• Typed secrets. A SecretType carries a JSON Schema, so "BMC Credentials" (username, password) and "Private Cert" (one large certificate field) are data an admin edits, not code.
• Four separable permissions, including a custom decrypt action with object-level constraints — scope reveal to one secret type, or one app.
• Partial writes without reading. An operator with change but not decrypt can rotate one field; the server merges server-side and returns nothing.
• REST and GraphQL, with plaintext reachable only through explicit, separately-permissioned endpoints.
• Lifecycle management. The plugin names, creates and deletes the AWS secret, and nbsm_reconcile reports drift in both directions.

Requirements

• NetBox 4.7.x
• Python 3.12+
• An AWS account, and credentials reachable by the default boto3 chain

Installation

pip install netbox-secrets-manager

Add to configuration.py:

PLUGINS = ['netbox_secrets_manager']

PLUGINS_CONFIG = {
    'netbox_secrets_manager': {
        'apps': ['dcim.device', 'virtualization.virtualmachine'],
        'aws_region': 'us-east-1',
        'instance_id': 'prod-netbox',
    },
}

Then run migrations and collect static files. Full options are documented in docs/configuration.md.

Development

Tasks run through just; just on its own lists everything.

just up             # NetBox + Postgres + Redis + LocalStack
just test           # the suite
just check          # lint, migration drift and tests, as CI runs them

NetBox comes up on http://localhost:8000 as admin / admin, with LocalStack standing in for AWS.

The suite runs inside the stack rather than a local virtualenv, because it is built on NetBox's own test utilities and needs NetBox's settings, database and app registry.

just test-integration additionally runs the backend contract against LocalStack. It is worth running before a release: moto is not faithful on two behaviours this plugin depends on, so those tests are the only coverage of the adopt and restore-previous paths against a real Secrets Manager implementation.

License

Apache-2.0