netbox-permissions-matrix-plugin 0.1.0__py3-none-any.whl

netbox_permissions_matrix_plugin/__init__.py

@@ -0,0 +1,25 @@
+from .version import __version__
+
+try:
+    from netbox.plugins import PluginConfig
+except ImportError:  # imported outside NetBox (pure unit tests, build tools)
+    PluginConfig = None
+
+if PluginConfig is not None:
+    from .conf import DEFAULTS
+
+    class PermissionsMatrixConfig(PluginConfig):
+        name = "netbox_permissions_matrix_plugin"
+        verbose_name = "Permissions Matrix"
+        description = "Show and edit NetBox object permissions as a matrix of object types and groups"
+        version = __version__
+        author = "Thomas Christory"
+        author_email = "9317624+thomaschristory@users.noreply.github.com"
+        base_url = "permissions-matrix"
+        min_version = "4.7.0"
+        # No max_version: the plugin only uses the stable permission model, and CI also runs against NetBox's next
+        # release.
+        required_settings = []
+        default_settings = DEFAULTS
+
+    config = PermissionsMatrixConfig

netbox_permissions_matrix_plugin/api/serializers.py

@@ -0,0 +1,72 @@
+from rest_framework import serializers
+
+from ..core.model import UNSET, CellChange, PermEdit, PrincipalRef
+
+ACTION = r"^[a-z_][a-z0-9_]{0,29}$"  # ObjectPermission.actions items are CharField(max_length=30)
+
+
+class PrincipalSerializer(serializers.Serializer):
+    type = serializers.ChoiceField(choices=["group", "user"])
+    id = serializers.IntegerField(min_value=1)
+
+    def to_internal_value(self, data):
+        value = super().to_internal_value(data)
+        return PrincipalRef(value["type"], value["id"])
+
+
+class CellChangeSerializer(serializers.Serializer):
+    principal = PrincipalSerializer()
+    object_type = serializers.RegexField(r"^[a-z0-9_]+\.[a-z0-9_]+$", max_length=200)
+    action = serializers.RegexField(ACTION)
+    granted = serializers.BooleanField()
+
+    def validate_object_type(self, value):
+        if value not in self.context["object_types"]:
+            raise serializers.ValidationError(f"{value} is not an object type permissions can be assigned to.")
+        return value
+
+    def to_internal_value(self, data):
+        return CellChange(**super().to_internal_value(data))
+
+
+class PermEditSerializer(serializers.Serializer):
+    principal = PrincipalSerializer()
+    action = serializers.RegexField(ACTION)
+    name = serializers.CharField(max_length=100, required=False)
+    description = serializers.CharField(max_length=200, required=False, allow_blank=True)
+    enabled = serializers.BooleanField(required=False)
+    constraints = serializers.JSONField(required=False, allow_null=True)
+    add_actions = serializers.ListField(child=serializers.RegexField(ACTION), required=False)
+    add_groups = serializers.ListField(child=serializers.IntegerField(min_value=1), required=False)
+    add_users = serializers.ListField(child=serializers.IntegerField(min_value=1), required=False)
+
+    def validate_constraints(self, value):
+        if value is not None and not isinstance(value, dict | list):
+            raise serializers.ValidationError("Constraints must be an object, a list of objects, or null.")
+        if isinstance(value, list) and not all(isinstance(c, dict) for c in value):
+            raise serializers.ValidationError("A list of constraints must contain only objects.")
+        return value
+
+    def to_internal_value(self, data):
+        value = super().to_internal_value(data)
+        return PermEdit(
+            principal=value["principal"],
+            action=value["action"],
+            name=value.get("name", UNSET),
+            description=value.get("description", UNSET),
+            enabled=value.get("enabled", UNSET),
+            constraints=value.get("constraints", UNSET),
+            add_actions=tuple(value.get("add_actions", ())),
+            add_groups=tuple(value.get("add_groups", ())),
+            add_users=tuple(value.get("add_users", ())),
+        )
+
+
+class ChangeSetSerializer(serializers.Serializer):
+    changes = CellChangeSerializer(many=True, required=False, default=list)
+    edits = PermEditSerializer(many=True, required=False, default=list)
+    token = serializers.CharField(required=False, max_length=64)
+
+
+class ImportSerializer(serializers.Serializer):
+    yaml = serializers.CharField(trim_whitespace=False)

netbox_permissions_matrix_plugin/api/urls.py

@@ -0,0 +1,11 @@
+from django.urls import path
+
+from . import views
+
+urlpatterns = [
+    path("matrix/", views.MatrixView.as_view(), name="matrix"),
+    path("principal/", views.PrincipalView.as_view(), name="principal"),
+    path("plan/", views.PlanView.as_view(), name="plan"),
+    path("apply/", views.ApplyView.as_view(), name="apply"),
+    path("import/", views.ImportView.as_view(), name="import"),
+]

netbox_permissions_matrix_plugin/api/views.py

@@ -0,0 +1,155 @@
+from django.core.exceptions import PermissionDenied, ValidationError
+from django.db import transaction
+from django.http import Http404
+from rest_framework import status
+from rest_framework.exceptions import NotFound
+from rest_framework.exceptions import PermissionDenied as APIPermissionDenied
+from rest_framework.exceptions import ValidationError as APIValidationError
+from rest_framework.permissions import SAFE_METHODS, BasePermission, IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from .. import loader, service
+from ..applier import apply_plan
+from ..conf import get_setting
+from ..core import yaml_io
+from ..core.model import PrincipalRef
+from .serializers import ChangeSetSerializer, ImportSerializer
+
+
+class WriteEnabled(BasePermission):
+    """Refuse API tokens without write enabled on unsafe methods, as NetBox's own write endpoints do.
+
+    NetBox's TokenWritePermission also refuses session authentication, which the matrix page uses (with CSRF).
+    """
+
+    message = "This API token is not write-enabled."
+
+    def has_permission(self, request, view):
+        token = request.auth
+        return request.method in SAFE_METHODS or token is None or bool(getattr(token, "write_enabled", False))
+
+
+def _ints(values):
+    try:
+        return tuple(int(v) for v in values)
+    except ValueError as exc:
+        raise APIValidationError({"detail": "IDs must be integers."}) from exc
+
+
+def _bool(value, default):
+    if value is None:
+        return default
+    return value.lower() in ("1", "true", "yes", "on")
+
+
+def _change_set(request):
+    object_types = {r.object_type for r in loader.rows()}
+    serializer = ChangeSetSerializer(data=request.data, context={"object_types": object_types})
+    serializer.is_valid(raise_exception=True)
+    return serializer.validated_data
+
+
+def _guard(func):
+    """Turn the service's Django exceptions into API responses."""
+
+    def wrapper(self, request, *args, **kwargs):
+        try:
+            return func(self, request, *args, **kwargs)
+        except PermissionDenied as exc:
+            raise APIPermissionDenied(str(exc)) from exc
+        except ValidationError as exc:
+            raise APIValidationError(exc.message_dict if hasattr(exc, "error_dict") else exc.messages) from exc
+
+    return wrapper
+
+
+class MatrixView(APIView):
+    """The matrix for one action: rows, columns, cell states and the permissions behind each cell."""
+
+    permission_classes = [IsAuthenticated]
+
+    @_guard
+    def get(self, request):
+        params = request.query_params
+        query = service.MatrixQuery(
+            action=params.get("action", "view"),
+            include_users=_bool(params.get("include_users"), get_setting("show_users_by_default")),
+            group_ids=_ints(params.getlist("group_id")),
+            user_ids=_ints(params.getlist("user_id")),
+            app_labels=tuple(params.getlist("app_label")),
+        )
+        return Response(service.matrix_payload(request.user, query))
+
+
+class PrincipalView(APIView):
+    """One group's or user's cells for every action."""
+
+    permission_classes = [IsAuthenticated]
+
+    @_guard
+    def get(self, request):
+        kind = request.query_params.get("type")
+        if kind not in ("group", "user"):
+            raise APIValidationError({"type": ["Must be group or user."]})
+        (pk,) = _ints([request.query_params.get("id", "")]) or (0,)
+        try:
+            return Response(service.principal_payload(request.user, PrincipalRef(kind, pk)))
+        except Http404 as exc:
+            raise NotFound(str(exc)) from exc
+
+
+class PlanView(APIView):
+    """Dry run: the operations a change set would perform, and the token to apply them with."""
+
+    permission_classes = [IsAuthenticated, WriteEnabled]
+
+    @_guard
+    def post(self, request):
+        service.check_edit(request.user)
+        data = _change_set(request)
+        snap, result, token = service.plan_for(request.user, data["changes"], data["edits"])
+        return Response(service.plan_json(snap, result, token))
+
+
+class ApplyView(APIView):
+    """Apply a change set in one transaction, if nothing changed since it was planned."""
+
+    permission_classes = [IsAuthenticated, WriteEnabled]
+
+    @_guard
+    def post(self, request):
+        service.check_edit(request.user)
+        data = _change_set(request)
+        if not data.get("token"):
+            raise APIValidationError({"token": ["Plan the change set first and send the token it returned."]})
+        with transaction.atomic():
+            # Lock the permission table for the plan-and-write, so two applies cannot interleave.
+            loader.lock_permissions()
+            snap, result, token = service.plan_for(request.user, data["changes"], data["edits"])
+            if token != data["token"]:
+                return Response(
+                    {"detail": "The permissions changed since this plan was made. Reload and review again."},
+                    status=status.HTTP_409_CONFLICT,
+                )
+            written = apply_plan(result, request.user)
+        body = service.plan_json(snap, result, token)
+        body["written"] = written
+        return Response(body)
+
+
+class ImportView(APIView):
+    """Read an exported YAML file and return the cell changes that would make it true. Nothing is written."""
+
+    permission_classes = [IsAuthenticated, WriteEnabled]
+
+    @_guard
+    def post(self, request):
+        service.check_edit(request.user)
+        serializer = ImportSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        try:
+            doc = yaml_io.load(serializer.validated_data["yaml"])
+        except ValueError as exc:
+            raise APIValidationError({"yaml": [str(exc)]}) from exc
+        return Response(service.import_for(request.user, doc))

netbox_permissions_matrix_plugin/applier.py

@@ -0,0 +1,78 @@
+"""Write a plan to NetBox in one transaction, checking the user's own permissions on every object it touches."""
+
+from __future__ import annotations
+
+import logging
+
+from core.models import ObjectType
+from django.core.exceptions import PermissionDenied
+from django.db import transaction
+from users.models import ObjectPermission
+
+from .core.model import Operation, Perm, Plan
+
+logger = logging.getLogger("netbox_permissions_matrix_plugin")
+
+
+def _object_types(plan: Plan) -> dict[str, ObjectType]:
+    labels = {ot for op in plan.operations if op.after for ot in op.after.object_types}
+    found = {}
+    for ot in ObjectType.objects.filter(app_label__in={label.split(".")[0] for label in labels}):
+        found[f"{ot.app_label}.{ot.model}"] = ot
+    missing = labels - set(found)
+    if missing:
+        raise ValueError(f"Unknown object types: {', '.join(sorted(missing))}")
+    return found
+
+
+def _write(obj: ObjectPermission, perm: Perm, object_types: dict[str, ObjectType]) -> None:
+    obj.name = perm.name
+    obj.description = perm.description
+    obj.enabled = perm.enabled
+    obj.actions = list(perm.actions)
+    obj.constraints = perm.constraints
+    obj.full_clean()
+    obj.save()
+    obj.object_types.set([object_types[label] for label in perm.object_types])
+    obj.groups.set(perm.groups)
+    obj.users.set(perm.users)
+
+
+def _denied(op: Operation, action: str) -> PermissionDenied:
+    name = (op.before or op.after).name
+    return PermissionDenied(f"You are not allowed to {action} the permission {name!r}; nothing was written.")
+
+
+def apply_plan(plan: Plan, user) -> list[dict]:
+    """Apply every operation or none. Returns what was written: [{"op", "id", "name"}]."""
+    object_types = _object_types(plan)
+    written = []
+    with transaction.atomic():
+        for op in plan.operations:
+            if op.op == "delete":
+                obj = ObjectPermission.objects.restrict(user, "delete").filter(pk=op.perm_id).first()
+                if obj is None:
+                    raise _denied(op, "delete")
+                obj.delete()
+                written.append({"op": "delete", "id": op.perm_id, "name": op.before.name})
+                continue
+            if op.op == "update":
+                obj = ObjectPermission.objects.restrict(user, "change").filter(pk=op.perm_id).first()
+                if obj is None:
+                    raise _denied(op, "change")
+                action = "change"
+            else:
+                obj = ObjectPermission()
+                action = "add"
+            _write(obj, op.after, object_types)
+            # Like NetBox's own edit views: the saved object must still be within what the user may add or change,
+            # so a constrained permission cannot be used to write an object outside its constraints.
+            if not ObjectPermission.objects.restrict(user, action).filter(pk=obj.pk).exists():
+                raise _denied(op, action)
+            written.append({"op": op.op, "id": obj.pk, "name": obj.name})
+    logger.info(
+        "%s applied a permissions matrix plan: %s",
+        user.username,
+        "; ".join(f"{w['op']} {w['name']!r} (#{w['id']})" for w in written) or "nothing to do",
+    )
+    return written

netbox_permissions_matrix_plugin/conf.py

@@ -0,0 +1,21 @@
+PLUGIN_NAME = "netbox_permissions_matrix_plugin"
+
+DEFAULTS = {
+    # Name of the simple permissions the plugin creates for new grants. {principal} is the group name or username,
+    # {action} the action. A number is appended when the name is taken.
+    "new_permission_name": "{principal} | {action}",
+    # "admin" puts the menu item below Permissions in Admin > Authentication; "plugins" uses the Plugins menu.
+    "menu_placement": "admin",
+    # Whether user columns are shown when the matrix opens.
+    "show_users_by_default": False,
+    # App labels whose object types get no row in the matrix (their grants are still kept intact).
+    "hidden_apps": [],
+}
+
+MENU_PLACEMENTS = ("admin", "plugins")
+
+
+def get_setting(key):
+    from netbox.plugins.utils import get_plugin_config
+
+    return get_plugin_config(PLUGIN_NAME, key, DEFAULTS[key])

netbox_permissions_matrix_plugin/core/__init__.py

@@ -0,0 +1,4 @@
+"""Pure-Python core: a snapshot of NetBox permissions, cell states and the change planner.
+
+Nothing here imports Django or NetBox, so it is tested exhaustively without a NetBox install.
+"""

netbox_permissions_matrix_plugin/core/cells.py

@@ -0,0 +1,48 @@
+"""What a matrix cell shows, worked out from the permissions that cover it."""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Iterable
+
+from .model import GROUP, Perm, PrincipalRef, Snapshot
+
+
+class CellState(enum.StrEnum):
+    NONE = "none"
+    GRANTED = "granted"
+    CONSTRAINED = "constrained"
+    DISABLED = "disabled"
+
+
+def covering(snap: Snapshot, ref: PrincipalRef, object_type: str, action: str) -> list[Perm]:
+    """Permissions assigned directly to the principal that list the object type and the action, by ID."""
+    return [snap.perms[pid] for pid in snap.covering_ids(ref, object_type, action)]
+
+
+def state_of(perms: Iterable[Perm]) -> CellState:
+    perms = list(perms)
+    if any(p.enabled and not p.constrained for p in perms):
+        return CellState.GRANTED
+    if any(p.enabled for p in perms):
+        return CellState.CONSTRAINED
+    if perms:
+        return CellState.DISABLED
+    return CellState.NONE
+
+
+def cell_state(snap: Snapshot, ref: PrincipalRef, object_type: str, action: str) -> CellState:
+    """The cell's state from the principal's own permissions. For a user, group grants do not count."""
+    return state_of(covering(snap, ref, object_type, action))
+
+
+def inherited_state(snap: Snapshot, user_id: int, object_type: str, action: str) -> tuple[CellState, list[str]]:
+    """What a user gets on this cell through group membership, and from which groups (by name)."""
+    perms, names = [], []
+    for group_id in sorted(snap.memberships.get(user_id, ())):
+        ref = PrincipalRef(GROUP, group_id)
+        found = covering(snap, ref, object_type, action)
+        if found:
+            perms += found
+            names.append(snap.name_of(ref))
+    return state_of(perms), sorted(names)

netbox_permissions_matrix_plugin/core/model.py

@@ -0,0 +1,164 @@
+"""Plain data describing NetBox permissions and the changes asked of them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+GROUP = "group"
+USER = "user"
+PrincipalKind = Literal["group", "user"]
+
+
+class _Unset:
+    def __repr__(self):
+        return "UNSET"
+
+    def __bool__(self):
+        return False
+
+
+# Marks a PermEdit field that was not given, as opposed to one given as None (constraints: remove them).
+UNSET: Any = _Unset()
+
+
+@dataclass(frozen=True, order=True)
+class PrincipalRef:
+    """A group or a user, by NetBox ID."""
+
+    kind: PrincipalKind
+    id: int
+
+    @property
+    def key(self) -> str:
+        return f"{self.kind}:{self.id}"
+
+    @classmethod
+    def parse(cls, key: str) -> PrincipalRef:
+        kind, _, pk = key.partition(":")
+        if kind not in (GROUP, USER) or not pk.isdigit():
+            raise ValueError(f"not a principal key: {key!r}")
+        return cls(kind, int(pk))  # type: ignore[arg-type]
+
+
+@dataclass(frozen=True)
+class Principal:
+    ref: PrincipalRef
+    name: str
+
+
+def is_constrained(constraints) -> bool:
+    """NetBox treats null, {} and [] as "no constraints": the permission matches every object."""
+    if not constraints:
+        return False
+    if isinstance(constraints, list):
+        # A list is OR-ed; one empty set in it matches everything.
+        return all(bool(c) for c in constraints)
+    return True
+
+
+@dataclass(frozen=True)
+class Perm:
+    """One NetBox ObjectPermission. object_types are "app_label.model" strings."""
+
+    id: int | None
+    name: str
+    description: str = ""
+    enabled: bool = True
+    actions: tuple[str, ...] = ()
+    object_types: frozenset[str] = frozenset()
+    groups: frozenset[int] = frozenset()
+    users: frozenset[int] = frozenset()
+    constraints: Any = None
+
+    def principals(self) -> frozenset[PrincipalRef]:
+        return frozenset({PrincipalRef(GROUP, g) for g in self.groups} | {PrincipalRef(USER, u) for u in self.users})
+
+    def assigned_to(self, ref: PrincipalRef) -> bool:
+        return ref.id in (self.groups if ref.kind == GROUP else self.users)
+
+    @property
+    def constrained(self) -> bool:
+        return is_constrained(self.constraints)
+
+    def covers(self, ref: PrincipalRef, object_type: str, action: str) -> bool:
+        return self.assigned_to(ref) and object_type in self.object_types and action in self.actions
+
+    def is_simple_for(self, ref: PrincipalRef, action: str) -> bool:
+        """One principal, one action, no constraints: the only kind of permission the plugin grows."""
+        return self.principals() == {ref} and self.actions == (action,) and not self.constrained
+
+
+@dataclass
+class Snapshot:
+    perms: dict[int, Perm]
+    principals: dict[PrincipalRef, Principal]
+    # user ID -> IDs of the groups the user belongs to
+    memberships: dict[int, frozenset[int]] = field(default_factory=dict)
+    _index: dict | None = field(default=None, init=False, repr=False, compare=False)
+
+    def covering_ids(self, ref: PrincipalRef, object_type: str, action: str) -> list[int]:
+        """IDs of the permissions covering a cell, from an index built on first use (snapshots are not mutated)."""
+        if self._index is None:
+            index: dict[tuple, list[int]] = {}
+            for pid in sorted(self.perms):
+                p = self.perms[pid]
+                for principal in p.principals():
+                    for ot in p.object_types:
+                        for a in p.actions:
+                            index.setdefault((principal, ot, a), []).append(pid)
+            self._index = index
+        return self._index.get((ref, object_type, action), [])
+
+    def name_of(self, ref: PrincipalRef) -> str:
+        principal = self.principals.get(ref)
+        return principal.name if principal else ref.key
+
+
+@dataclass(frozen=True)
+class CellChange:
+    principal: PrincipalRef
+    object_type: str
+    action: str
+    granted: bool
+
+
+@dataclass(frozen=True)
+class PermEdit:
+    """A gear-panel edit of a principal's simple permission for one action."""
+
+    principal: PrincipalRef
+    action: str
+    name: Any = UNSET
+    description: Any = UNSET
+    enabled: Any = UNSET
+    constraints: Any = UNSET
+    add_actions: tuple[str, ...] = ()
+    add_groups: tuple[int, ...] = ()
+    add_users: tuple[int, ...] = ()
+
+
+@dataclass(frozen=True)
+class Operation:
+    """One write. key is the permission ID as a string, or "new-N" for a permission the plan creates."""
+
+    op: Literal["create", "update", "delete"]
+    key: str
+    before: Perm | None
+    after: Perm | None
+    affects: frozenset[PrincipalRef]
+    reasons: tuple[str, ...] = ()
+
+    @property
+    def perm_id(self) -> int | None:
+        return self.before.id if self.before else None
+
+
+@dataclass
+class Plan:
+    operations: list[Operation]
+    warnings: list[str]
+
+    @property
+    def empty(self) -> bool:
+        return not self.operations