Metadata-Version: 2.4
Name: netbox-secrets-manager
Version: 0.2.2
Summary: Attach secrets to NetBox objects, backed by AWS Secrets Manager
Author: SF Compute
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/sfcompute/netbox-secrets-manager
Project-URL: Source, https://github.com/sfcompute/netbox-secrets-manager
Keywords: netbox,netbox-plugin,secrets,aws,secrets-manager
Classifier: Framework :: Django
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34
Provides-Extra: dev
Requires-Dist: moto[secretsmanager,sts]>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# 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](https://github.com/Onemind-Services-LLC/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](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

```bash
pip install netbox-secrets-manager
```

Add to `configuration.py`:

```python
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](docs/configuration.md).

## Development

Tasks run through [just](https://github.com/casey/just); `just` on its own lists
everything.

```bash
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
