netbox-secrets-manager 0.1.0__tar.gz

netbox_secrets_manager-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: netbox-secrets-manager
+Version: 0.1.0
+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.6.0** or later (4.7 supported)
+- 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

netbox_secrets_manager-0.1.0/README.md

@@ -0,0 +1,96 @@
+# 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.6.0** or later (4.7 supported)
+- 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

netbox_secrets_manager-0.1.0/netbox_secrets_manager/__init__.py

@@ -0,0 +1,103 @@
+"""NetBox plugin for attaching secrets to objects, backed by AWS Secrets Manager.
+
+NetBox stores only metadata: the ARN, which object a secret belongs to, and
+which shape it has. AWS Secrets Manager is the system of record. No field on
+any model in this package ever holds plaintext or ciphertext.
+"""
+
+from netbox.plugins import PluginConfig
+
+__version__ = '0.1.0'
+
+
+class SecretsManagerConfig(PluginConfig):
+    name = 'netbox_secrets_manager'
+    verbose_name = 'Secrets Manager'
+    description = 'Attach secrets to NetBox objects, backed by AWS Secrets Manager'
+    version = __version__
+    author = 'SF Compute'
+    base_url = 'secrets-manager'
+
+    # 4.6.0 is the floor because custom model actions (the `decrypt` permission)
+    # were introduced there. The upper bound is deliberate rather than open:
+    # this plugin reaches into a handful of undocumented internals (see
+    # compat.py), so a new major should be tested before it is allowed.
+    min_version = '4.6.0'
+    max_version = '4.7.99'
+
+    menu = 'navigation.menu'
+    search_indexes = 'search.indexes'
+    # Points at the list inside the module, not the module itself.
+    graphql_schema = 'graphql.schema.schema'
+    # Ignored on 4.6, which has no collection point for it. The module guards
+    # itself as well, so it is inert there even if something force-imports it.
+    graphql_type_extensions = 'graphql_extensions.type_extensions'
+    graphql_filter_extensions = 'graphql_extensions.filter_extensions'
+
+    required_settings = ['apps']
+
+    default_settings = {
+        # --- AWS -----------------------------------------------------------
+        'aws_region': 'us-east-1',
+        # Left None to use the default boto3 credential chain: IRSA, instance
+        # profile, environment, ~/.aws. Set to assume a role instead.
+        'assume_role_arn': None,
+        'assume_role_session_name': 'netbox-secrets-manager',
+        'assume_role_external_id': None,
+        # LocalStack or a VPC endpoint.
+        'endpoint_url': None,
+        # None means AWS's own aws/secretsmanager key.
+        'kms_key_id': None,
+        # Merged into the botocore Config; see backends/aws.py for the defaults
+        # this overrides.
+        'boto_config': {},
+        # Tagged onto every secret this install owns. Two NetBox instances
+        # sharing one AWS account MUST set different values, or each will treat
+        # the other's secrets as its own and may overwrite them.
+        'instance_id': 'default',
+        # --- Naming and lifecycle -------------------------------------------
+        'secret_name_template': 'netbox/{app_label}/{model}/{object_id}/{secret_type}/{name}',
+        'secret_tags': {'ManagedBy': 'netbox'},
+        # 7-30 schedules deletion with that recovery window; 0 force-deletes
+        # immediately; None leaves the AWS secret alone and only drops NetBox's
+        # metadata row.
+        'deletion_recovery_days': 30,
+        # --- Limits ---------------------------------------------------------
+        # Each decrypt is one GetSecretValue call. Without a cap, one bulk
+        # request or one GraphQL query can turn into thousands.
+        'bulk_decrypt_max': 100,
+        'graphql_decrypt_max': 25,
+        # --- UI -------------------------------------------------------------
+        # Vocabulary matches netbox-secrets so the migration is familiar.
+        'display_default': 'right_page',
+        'display_setting': {},
+        'top_level_menu': True,
+        # --- Backend --------------------------------------------------------
+        # Swap for 'netbox_secrets_manager.backends.memory.MemoryBackend' in
+        # tests, or point at your own SecretBackend subclass.
+        'backend': 'netbox_secrets_manager.backends.aws.AWSSecretsManagerBackend',
+    }
+
+    def ready(self):
+        super().ready()
+
+        from .config import validate_config
+
+        # A bad `apps` entry or an illegal recovery window is a deployment
+        # mistake. Surface it at startup, not at first write.
+        validate_config()
+
+        # Imported for their registration side effects only:
+        #   events   - registers the event types webhooks and event rules fire on.
+        #   signals  - AWS deletion on row delete, plus the post_delete receivers
+        #              that clean up secrets orphaned by a deleted parent object
+        #              (a GenericForeignKey does not cascade).
+        from . import (  # noqa: F401
+            events,
+            signals,
+        )
+
+        signals.connect_orphan_receivers()
+
+
+config = SecretsManagerConfig

netbox_secrets_manager-0.1.0/netbox_secrets_manager/api/exceptions.py

@@ -0,0 +1,28 @@
+"""Mapping backend failures onto HTTP statuses.
+
+Without this, every AWS problem - throttling, an expired role, a network blip -
+surfaces as a bare 500 that says nothing useful and looks like a plugin bug.
+"""
+
+from rest_framework.response import Response
+from rest_framework.views import exception_handler as drf_exception_handler
+
+from ..exceptions import SchemaValidationError, SecretBackendError
+
+
+def secrets_exception_handler(exc, context):
+    """DRF exception handler covering our own exception families.
+
+    Wire up with ``REST_FRAMEWORK['EXCEPTION_HANDLER']``, or rely on the
+    viewset's ``handle_exception`` override, which calls this directly.
+    """
+    if isinstance(exc, SchemaValidationError):
+        return Response(exc.errors, status=400)
+
+    if isinstance(exc, SecretBackendError):
+        return Response(
+            {'detail': str(exc), 'aws_code': exc.aws_code},
+            status=exc.http_status,
+        )
+
+    return drf_exception_handler(exc, context)

netbox_secrets_manager-0.1.0/netbox_secrets_manager/api/reveal.py

@@ -0,0 +1,30 @@
+"""The only serializers in this package that can represent a secret value.
+
+Kept in its own module, imported solely by the decrypt actions, and never set
+as a viewset's ``serializer_class``. That last point matters for more than
+tidiness: it keeps drf-spectacular from attaching this shape to any CRUD
+operation in the generated schema.
+"""
+
+from rest_framework import serializers
+
+
+class SecretValueSerializer(serializers.Serializer):
+    """A decrypted secret. Output only."""
+
+    id = serializers.IntegerField(read_only=True)
+    name = serializers.CharField(read_only=True)
+    secret_type = serializers.CharField(read_only=True)
+    data = serializers.DictField(read_only=True)
+    retrieved_at = serializers.DateTimeField(read_only=True)
+
+
+class BulkDecryptSerializer(serializers.Serializer):
+    """Input for the bulk decrypt endpoint."""
+
+    ids = serializers.ListField(
+        child=serializers.IntegerField(),
+        allow_empty=False,
+        help_text='Secret IDs to decrypt. IDs the caller may not decrypt are omitted from the response '
+        'rather than raising, so a partial grant still returns what it can.',
+    )

netbox_secrets_manager-0.1.0/netbox_secrets_manager/api/serializers.py

@@ -0,0 +1,191 @@
+"""Serializers that cannot emit a secret value.
+
+This module contains **no serializer capable of representing plaintext**. The
+one that can lives in ``reveal.py`` and is imported only by the decrypt
+actions. That split is the first and strongest of the guarantees here, because
+it means no amount of editing this file can accidentally expose a value through
+the CRUD endpoints.
+
+The rest, in descending order of strength:
+
+* ``fields`` is enumerated, never ``__all__``, so a new model field cannot
+  appear in the API by accident.
+* ``data``/``clear``/``merge`` are ``write_only``, which DRF enforces
+  structurally: ``to_representation`` iterates ``_readable_fields``, which
+  excludes them. There is no code path that includes them.
+* A defensive strip in ``to_representation``, which a test asserts is dead code.
+"""
+
+from core.models import ObjectType
+from netbox.api.fields import ContentTypeField
+from netbox.api.gfk_fields import GFKSerializerField
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
+
+from ..constants import WRITE_ONLY_FIELDS
+from ..models import Secret, SecretType
+
+
+class SecretTypeSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_secrets_manager-api:secrettype-detail')
+    secret_count = serializers.IntegerField(read_only=True)
+
+    class Meta:
+        model = SecretType
+        fields = (
+            'id',
+            'url',
+            'display_url',
+            'display',
+            'name',
+            'slug',
+            'description',
+            'schema',
+            'name_template',
+            'kms_key_id',
+            'secret_count',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'slug', 'description')
+
+
+class SecretSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name='plugins-api:netbox_secrets_manager-api:secret-detail')
+    object_type = ContentTypeField(queryset=ObjectType.objects.all())
+    assigned_object = GFKSerializerField(read_only=True)
+    secret_type = SecretTypeSerializer(nested=True)
+
+    # Declared explicitly because editable=False keeps ModelSerializer from
+    # generating them at all, and read_only so they can never be written: the
+    # ARN is the plugin's own bookkeeping, not user input.
+    arn = serializers.CharField(read_only=True)
+    aws_secret_name = serializers.CharField(read_only=True)
+    version_id = serializers.CharField(read_only=True)
+    has_previous_version = serializers.BooleanField(read_only=True)
+    last_written = serializers.DateTimeField(read_only=True)
+
+    # The write path. write_only means DRF never includes these in output.
+    data = serializers.DictField(
+        write_only=True,
+        required=False,
+        help_text='Field values to write. On PATCH, fields omitted here keep their current value.',
+    )
+    clear = serializers.ListField(
+        child=serializers.CharField(),
+        write_only=True,
+        required=False,
+        help_text='Field names to set to an empty value. Distinct from omitting them, which leaves them alone.',
+    )
+    merge = serializers.BooleanField(
+        write_only=True,
+        default=True,
+        help_text='When false, the submitted data replaces the stored value wholesale and must satisfy '
+        'every required field.',
+    )
+
+    class Meta:
+        model = Secret
+        fields = (
+            'id',
+            'url',
+            'display_url',
+            'display',
+            'object_type',
+            'object_id',
+            'assigned_object',
+            'secret_type',
+            'name',
+            'arn',
+            'aws_secret_name',
+            'version_id',
+            'has_previous_version',
+            'last_written',
+            'data',
+            'clear',
+            'merge',
+            'description',
+            'comments',
+            'tags',
+            'custom_fields',
+            'created',
+            'last_updated',
+        )
+        brief_fields = ('id', 'url', 'display', 'name', 'secret_type')
+
+    def validate(self, data):
+        """Keep the write-only keys away from the model constructor.
+
+        NetBox's serializer base instantiates ``Meta.model(**attrs)`` to run
+        model-level validation. ``data``/``clear``/``merge`` are serializer
+        inputs, not model fields, so they have to be lifted out first and put
+        back afterwards for create()/update() to consume.
+        """
+        carried = {key: data.pop(key) for key in list(WRITE_ONLY_FIELDS) if key in data}
+        data = super().validate(data)
+        data.update(carried)
+        return data
+
+    def to_representation(self, instance):
+        representation = super().to_representation(instance)
+        # Belt and braces. write_only already excludes these; if this loop ever
+        # removes anything, DRF's contract has changed underneath us and
+        # test_no_plaintext will say so.
+        for key in WRITE_ONLY_FIELDS & representation.keys():
+            del representation[key]
+        return representation
+
+    def create(self, validated_data):
+        from .. import services
+
+        data = validated_data.pop('data', None)
+        validated_data.pop('clear', None)
+        validated_data.pop('merge', None)
+
+        if not data:
+            raise serializers.ValidationError({'data': 'This field is required when creating a secret.'})
+
+        tags = validated_data.pop('tags', None)
+        custom_fields = validated_data.pop('custom_field_data', None)
+
+        secret = Secret(**validated_data)
+        if custom_fields is not None:
+            secret.custom_field_data = custom_fields
+
+        secret = services.create_secret(secret, data, user=self._user(), request=self._request())
+        if tags is not None:
+            secret.tags.set(tags)
+        return secret
+
+    def update(self, instance, validated_data):
+        from .. import services
+
+        data = validated_data.pop('data', {})
+        clear = set(validated_data.pop('clear', ()) or ())
+        merge = validated_data.pop('merge', True)
+        tags = validated_data.pop('tags', None)
+
+        for key, value in validated_data.items():
+            setattr(instance, key, value)
+        # Runs the set-once check on object_type/object_id/secret_type.
+        instance.full_clean(exclude=('arn', 'aws_secret_name', 'version_id'))
+        instance.save()
+
+        if tags is not None:
+            instance.tags.set(tags)
+
+        if data or clear:
+            instance = services.update_secret(
+                instance, data, clear=clear, merge=merge, user=self._user(), request=self._request()
+            )
+        return instance
+
+    def _request(self):
+        return self.context.get('request')
+
+    def _user(self):
+        request = self._request()
+        return getattr(request, 'user', None) if request else None

netbox_secrets_manager-0.1.0/netbox_secrets_manager/api/urls.py

@@ -0,0 +1,12 @@
+"""API routing. Mounts at /api/plugins/secrets-manager/."""
+
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+router = NetBoxRouter()
+router.register('secrets', views.SecretViewSet)
+router.register('secret-types', views.SecretTypeViewSet)
+
+app_name = 'netbox_secrets_manager-api'
+urlpatterns = router.urls