netbox-passwork 1.3.1__py3-none-any.whl

netbox_passwork/__init__.py

@@ -0,0 +1,13 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .config import config
+
+try:
+    __version__ = version("netbox-passwork")
+except PackageNotFoundError:
+    __version__ = "dev"
+
+
+__all__ = [
+    "config",
+]

netbox_passwork/admin.py

@@ -0,0 +1,71 @@
+from django.contrib import admin
+
+from netbox_passwork.models import PassworkAuditLog, PassworkBinding
+
+
+@admin.register(PassworkBinding)
+class PassworkBindingAdmin(admin.ModelAdmin):
+    list_display = [
+        "id",
+        "object_type",
+        "object_id",
+        "passwork_item_id",
+        "created",
+        "created_by",
+    ]
+    list_filter = ["object_type"]
+    search_fields = ["passwork_item_id", "object_id"]
+    readonly_fields = [
+        "id",
+        "object_type",
+        "object_id",
+        "passwork_item_id",
+        "created",
+        "created_by",
+    ]
+    ordering = ["-created"]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(PassworkAuditLog)
+class PassworkAuditLogAdmin(admin.ModelAdmin):
+    list_display = [
+        "id",
+        "timestamp",
+        "netbox_user",
+        "passwork_item_id",
+        "object_type",
+        "object_id",
+        "action",
+        "ip_address",
+    ]
+    list_filter = ["action", "object_type"]
+    search_fields = ["passwork_item_id", "netbox_user__username", "object_id"]
+    readonly_fields = [
+        "id",
+        "timestamp",
+        "netbox_user",
+        "passwork_item_id",
+        "object_type",
+        "object_id",
+        "action",
+        "ip_address",
+    ]
+    ordering = ["-timestamp"]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False

netbox_passwork/api/serializers.py

@@ -0,0 +1,11 @@
+"""API serializers following NetBox convention (<plugin>.api.serializers).
+
+The NetBox events pipeline (webhooks/event rules, also triggered on changelog
+operations) serializes the object via
+utilities.api.get_serializer_for_model(), which looks up the serializer
+specifically in this module by the name <Model>Serializer.
+"""
+
+from netbox_passwork.serializers import PassworkBindingSerializer
+
+__all__ = ("PassworkBindingSerializer",)

netbox_passwork/config.py

@@ -0,0 +1,29 @@
+from importlib.metadata import version as _pkg_version
+
+from netbox.plugins import PluginConfig
+
+
+class NetboxPassworkConfig(PluginConfig):
+    name = "netbox_passwork"
+    verbose_name = "NetBox Passwork Integration"
+    version = _pkg_version("netbox-passwork")
+    author = "Pavel Krasotin"
+    author_email = "krasotinpa@gmail.com"
+    description = "Passwork secrets integration for NetBox devices, VMs and services"
+    base_url = "passwork"
+    required_settings = ["PASSWORK_URL", "SESSION_ENCRYPT_KEY"]
+    default_settings = {
+        "PASSWORK_VERIFY_SSL": True,
+        "TOKEN_REFRESH_MARGIN": 60,
+        "PASSWORK_REQUEST_TIMEOUT": 5,
+        "SECRET_REVEAL_TIMEOUT": 30,
+    }
+    min_version = "4.5"
+
+    def ready(self):
+        from netbox_passwork.template_extensions import _register_views
+
+        _register_views()
+
+
+config = NetboxPassworkConfig

netbox_passwork/exceptions.py

@@ -0,0 +1,54 @@
+class PassworkError(Exception):
+    """
+    Base exception of the Passwork gateway: a Passwork failure carrying HTTP meaning.
+
+    ``code`` and ``http_status`` are what goes into the plugin's JSON response; ``detail``
+    is a human-readable explanation. Subclasses set the defaults, and an operation that
+    knows the failure context (login, TOTP, reading a secret) may override them when
+    raising (ADR-0001).
+    """
+
+    code = "pw_error"
+    http_status = 502
+    detail = "Passwork error"
+
+    def __init__(self, detail: str | None = None, *, code: str | None = None, http_status: int | None = None):
+        if detail is not None:
+            self.detail = detail
+        if code is not None:
+            self.code = code
+        if http_status is not None:
+            self.http_status = http_status
+        super().__init__(self.detail)
+
+
+class PassworkSessionExpired(PassworkError):
+    """Refresh token expired or was rejected — a new login is required."""
+
+    code = "pw_session_expired"
+    http_status = 401
+    detail = "Passwork session expired"
+
+
+class PassworkAccessDenied(PassworkError):
+    """Passwork denied access (403 for a secret; invalid credentials on login/TOTP)."""
+
+    code = "pw_access_denied"
+    http_status = 403
+    detail = "Passwork access denied"
+
+
+class PassworkTimeout(PassworkError):
+    """Passwork did not respond within PASSWORK_REQUEST_TIMEOUT seconds."""
+
+    code = "pw_timeout"
+    http_status = 504
+    detail = "Passwork timeout"
+
+
+class PassworkBadResponse(PassworkError):
+    """Passwork returned a response that isn't JSON (e.g. a proxy error HTML page)."""
+
+    code = "pw_bad_response"
+    http_status = 502
+    detail = "Passwork returned a non-JSON response"

netbox_passwork/gateway.py

@@ -0,0 +1,156 @@
+"""
+Passwork gateway — the single point through which the plugin talks to Passwork on
+behalf of the Passwork session (see docs/adr/0001-passwork-gateway-not-middleware.md).
+
+The module owns everything related to the Passwork session: it is the only place that
+reads the plugin config, the only place that Fernet-encrypts its fields, reads/writes/
+deletes its record in storage (in production, the request's Django session), refreshes
+the access token, and provides six domain operations. Passwork failures are raised as
+``PassworkError`` with ``code``/``http_status`` — the failure context is known to the operation.
+"""
+
+import logging
+
+from cryptography.fernet import Fernet, InvalidToken
+from django.conf import settings
+
+from netbox_passwork.exceptions import PassworkError, PassworkSessionExpired
+from netbox_passwork.passwork_client import PassworkAuthClient
+
+logger = logging.getLogger("netbox_passwork")
+
+# The storage key and record shape are byte-for-byte compatible with pre-1.3.0
+# versions: existing users don't get logged out on upgrade.
+_STORAGE_KEY = "pw_session"
+_ENCRYPTED_FIELDS = ("access_token", "refresh_token", "csrf_token")
+
+
+def _not_authenticated(detail: str) -> PassworkError:
+    return PassworkError(detail, code="pw_not_authenticated", http_status=401)
+
+
+class PassworkGateway:
+    """
+    Six operations on behalf of the Passwork session, over storage with a ``dict`` interface.
+
+    ``storage`` — where the Passwork session record lives (``request.session`` in
+    production, a plain ``dict`` in tests); ``client`` — the HTTP implementation of the
+    Passwork API; ``config`` — the plugin config (``PLUGINS_CONFIG["netbox_passwork"]``),
+    from which the gateway takes ``SESSION_ENCRYPT_KEY``.
+    """
+
+    def __init__(self, storage, client: PassworkAuthClient, config):
+        self._storage = storage
+        self._client = client
+        key = config["SESSION_ENCRYPT_KEY"]
+        self._fernet = Fernet(key.encode() if isinstance(key, str) else key)
+        # The gateway lives for a single HTTP request: the Passwork session that's been
+        # read (and refreshed if needed) is reused by all operations of the request —
+        # without re-decrypting the record
+        self._passwork_session: dict | None = None
+
+    # ------------------------------------------------------------------
+    # Operations
+    # ------------------------------------------------------------------
+
+    def login(self, username: str, password: str) -> bool:
+        """Log in to Passwork; saves the Passwork session. Returns whether TOTP is required."""
+        passwork_session = self._client.login(username, password)
+        self._write(passwork_session)
+        return bool(passwork_session["requires_totp"])
+
+    def confirm_totp(self, code: str) -> None:
+        """Confirms TOTP for the saved Passwork session."""
+        passwork_session = self._client.confirm_totp(code, self._load())
+        self._write(passwork_session)
+
+    def get_item(self, pw_id: str) -> dict:
+        """Passwork item with the password and custom fields decoded."""
+        return self._client.get_item(pw_id, self._load())
+
+    def list_vaults(self) -> list:
+        """List of Passwork vaults."""
+        return self._client.list_vaults(self._load())
+
+    def search_items(self, query: str) -> list:
+        """Search Passwork items (the query is URL-encoded by the client)."""
+        return self._client.search_items(query, self._load())
+
+    def require_session(self) -> None:
+        """Guarantees the Passwork session exists and hasn't expired (refreshing it if needed)."""
+        self._load()
+
+    # ------------------------------------------------------------------
+    # Passwork session in storage
+    # ------------------------------------------------------------------
+
+    def _load(self) -> dict:
+        """
+        Reads and, if needed, refreshes the Passwork session.
+
+        Known failures: no record → 401 ``pw_not_authenticated``; refresh token expired
+        or rejected → record is deleted, 401 ``pw_session_expired``; ``InvalidToken``
+        (``SESSION_ENCRYPT_KEY`` changed) → record is deleted, warning, 401
+        ``pw_not_authenticated``; timeout/non-JSON during refresh → 504/502.
+        Other exceptions are not swallowed. The result is cached for the gateway's lifetime.
+        """
+        if self._passwork_session is not None:
+            return self._passwork_session
+        record = self._storage.get(_STORAGE_KEY)
+        if record is None:
+            raise _not_authenticated("Passwork session not found")
+        try:
+            passwork_session = self._decrypt(record)
+        except InvalidToken:
+            self._delete()
+            logger.warning(
+                "Passwork session record could not be decrypted (SESSION_ENCRYPT_KEY changed?); record dropped"
+            )
+            raise _not_authenticated("Passwork session could not be decrypted") from None
+
+        before = dict(passwork_session)
+        try:
+            passwork_session = self._client.refresh_if_needed(passwork_session)
+        except PassworkSessionExpired:
+            self._delete()
+            raise
+        # Rewrite the record only if the refresh changed it — avoids unnecessary session saves
+        if passwork_session != before:
+            self._write(passwork_session)
+        self._passwork_session = passwork_session
+        return passwork_session
+
+    def _write(self, passwork_session: dict) -> None:
+        # Assigning the key by itself marks the Django session as modified
+        self._storage[_STORAGE_KEY] = self._encrypt(passwork_session)
+        self._passwork_session = passwork_session
+
+    def _delete(self) -> None:
+        self._storage.pop(_STORAGE_KEY, None)
+        self._passwork_session = None
+
+    def _encrypt(self, passwork_session: dict) -> dict:
+        return {
+            k: self._fernet.encrypt(str(v).encode()).decode() if k in _ENCRYPTED_FIELDS else v
+            for k, v in passwork_session.items()
+        }
+
+    def _decrypt(self, record: dict) -> dict:
+        return {
+            k: self._fernet.decrypt(v.encode()).decode() if k in _ENCRYPTED_FIELDS else v for k, v in record.items()
+        }
+
+
+def build_gateway(request) -> PassworkGateway:
+    """
+    Builds the gateway from an HTTP request — the single point of composition and the
+    only place that reads the plugin config.
+    """
+    config = settings.PLUGINS_CONFIG["netbox_passwork"]
+    client = PassworkAuthClient(
+        base_url=config["PASSWORK_URL"],
+        verify_ssl=config.get("PASSWORK_VERIFY_SSL", True),
+        timeout=config.get("PASSWORK_REQUEST_TIMEOUT", 5),
+        refresh_margin=config.get("TOKEN_REFRESH_MARGIN", 60),
+    )
+    return PassworkGateway(request.session, client, config)

netbox_passwork/migrations/0001_initial.py

@@ -0,0 +1,141 @@
+import django.db.models.deletion
+import django.db.models.expressions
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="PassworkBinding",
+            fields=[
+                ("id", models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                (
+                    "object_type",
+                    models.CharField(
+                        choices=[("device", "Device"), ("vm", "Virtual Machine"), ("service", "Service")],
+                        max_length=32,
+                    ),
+                ),
+                ("object_id", models.PositiveIntegerField()),
+                ("passwork_item_id", models.CharField(db_index=True, max_length=128)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("deleted_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "created_by",
+                    models.ForeignKey(
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="+",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "deleted_by",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="+",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "permissions": [
+                    ("view_secrets", "Can view Passwork secrets"),
+                    ("reveal_secret", "Can reveal Passwork secret value"),
+                    ("add_binding", "Can create Passwork binding"),
+                    ("delete_binding", "Can delete Passwork binding"),
+                    ("view_auditlog", "Can view Passwork audit log"),
+                ],
+            },
+        ),
+        migrations.CreateModel(
+            name="PassworkBindingHistory",
+            fields=[
+                ("id", models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                ("timestamp", models.DateTimeField(auto_now_add=True)),
+                (
+                    "action",
+                    models.CharField(
+                        choices=[("created", "Created"), ("deleted", "Deleted"), ("restored", "Restored")],
+                        max_length=16,
+                    ),
+                ),
+                ("ip_address", models.GenericIPAddressField(null=True)),
+                (
+                    "binding",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="history",
+                        to="netbox_passwork.passworkbinding",
+                    ),
+                ),
+                (
+                    "netbox_user",
+                    models.ForeignKey(
+                        null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-timestamp"],
+            },
+        ),
+        migrations.CreateModel(
+            name="PassworkAuditLog",
+            fields=[
+                ("id", models.AutoField(auto_created=True, primary_key=True, serialize=False)),
+                ("timestamp", models.DateTimeField(auto_now_add=True)),
+                ("passwork_item_id", models.CharField(max_length=128)),
+                ("object_type", models.CharField(max_length=32)),
+                ("object_id", models.PositiveIntegerField()),
+                ("action", models.CharField(choices=[("reveal", "Reveal"), ("copy", "Copy")], max_length=16)),
+                ("ip_address", models.GenericIPAddressField(null=True)),
+                (
+                    "netbox_user",
+                    models.ForeignKey(
+                        null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["-timestamp"],
+            },
+        ),
+        migrations.AddIndex(
+            model_name="passworkbinding",
+            index=models.Index(
+                condition=models.Q(deleted_at__isnull=True),
+                fields=["object_type", "object_id"],
+                name="pb_active_object_idx",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="passworkbinding",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(deleted_at__isnull=True),
+                fields=["object_type", "object_id", "passwork_item_id"],
+                name="pb_unique_active_binding",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="passworkauditlog",
+            index=models.Index(fields=["netbox_user"], name="pal_user_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="passworkauditlog",
+            index=models.Index(fields=["passwork_item_id"], name="pal_item_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="passworkauditlog",
+            index=models.Index(fields=["-timestamp"], name="pal_ts_idx"),
+        ),
+    ]

netbox_passwork/migrations/0002_alter_ids.py

@@ -0,0 +1,25 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("netbox_passwork", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="passworkauditlog",
+            name="id",
+            field=models.BigAutoField(auto_created=True, primary_key=True, serialize=False),
+        ),
+        migrations.AlterField(
+            model_name="passworkbinding",
+            name="id",
+            field=models.BigAutoField(auto_created=True, primary_key=True, serialize=False),
+        ),
+        migrations.AlterField(
+            model_name="passworkbindinghistory",
+            name="id",
+            field=models.BigAutoField(auto_created=True, primary_key=True, serialize=False),
+        ),
+    ]

netbox_passwork/migrations/0003_changelog.py

@@ -0,0 +1,80 @@
+"""Move binding history over to the standard NetBox changelog.
+
+- The PassworkBindingHistory table is dropped (accumulated records are
+  deliberately not migrated).
+- Soft delete (deleted_at/deleted_by) is replaced with hard delete: soft-deleted
+  records are physically removed, the partial index/constraint become regular ones.
+- PassworkBinding gains the created/last_updated fields from ChangeLoggedModel
+  (created is populated from the former created_at via RenameField).
+
+WARNING: this migration is irreversible without a database backup — the history
+table and soft-deleted bindings are removed permanently.
+"""
+
+from django.conf import settings
+from django.db import migrations, models
+
+
+def purge_soft_deleted_bindings(apps, schema_editor):
+    # Raw SQL, not ORM .delete(): by this point DeleteModel has already dropped
+    # the PassworkBindingHistory table, but the PassworkBinding model still has
+    # a PROTECT back-reference to it. An ORM cascade (collector) on .delete()
+    # would hit the now-missing history table and fail with
+    # UndefinedTable. A direct DELETE bypasses the collector; history rows are
+    # already gone along with the table. The deleted_at column still exists
+    # at this point (RemoveField comes later).
+    schema_editor.execute('DELETE FROM "netbox_passwork_passworkbinding" WHERE "deleted_at" IS NOT NULL')
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("netbox_passwork", "0002_alter_ids"),
+    ]
+
+    operations = [
+        # History table first (FK PROTECT on PassworkBinding), then the
+        # physical removal of soft-deleted bindings — before applying the
+        # unconditional unique constraint.
+        migrations.DeleteModel(name="PassworkBindingHistory"),
+        migrations.RunPython(purge_soft_deleted_bindings, migrations.RunPython.noop),
+        # The partial index/constraint reference deleted_at — drop them
+        # before removing the field itself.
+        migrations.RemoveConstraint(
+            model_name="passworkbinding",
+            name="pb_unique_active_binding",
+        ),
+        migrations.RemoveIndex(
+            model_name="passworkbinding",
+            name="pb_active_object_idx",
+        ),
+        migrations.RemoveField(model_name="passworkbinding", name="deleted_at"),
+        migrations.RemoveField(model_name="passworkbinding", name="deleted_by"),
+        # created_at -> created (ChangeLoggedModel field), values are preserved.
+        migrations.RenameField(
+            model_name="passworkbinding",
+            old_name="created_at",
+            new_name="created",
+        ),
+        migrations.AlterField(
+            model_name="passworkbinding",
+            name="created",
+            field=models.DateTimeField(auto_now_add=True, blank=True, null=True, verbose_name="created"),
+        ),
+        migrations.AddField(
+            model_name="passworkbinding",
+            name="last_updated",
+            field=models.DateTimeField(auto_now=True, blank=True, null=True, verbose_name="last updated"),
+        ),
+        migrations.AddIndex(
+            model_name="passworkbinding",
+            index=models.Index(fields=["object_type", "object_id"], name="pb_object_idx"),
+        ),
+        migrations.AddConstraint(
+            model_name="passworkbinding",
+            constraint=models.UniqueConstraint(
+                fields=["object_type", "object_id", "passwork_item_id"],
+                name="pb_unique_binding",
+            ),
+        ),
+    ]