Fixes #21357: Add API for registering custom model actions

docs/administration/permissions.md

@@ -20,7 +20,9 @@ There are four core actions that can be permitted for each type of object within
 * **Change** - Modify an existing object
 * **Delete** - Delete an existing object
 
-In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `run` permission for scripts allows a user to execute custom scripts. These can be specified when granting a permission in the "additional actions" field.
+In addition to these, permissions can also grant custom actions that may be required by a specific model or plugin. For example, the `sync` action for data sources allows a user to synchronize data from a remote source, and the `render_config` action for devices and virtual machines allows rendering configuration templates.
+
+Some models have registered actions that appear as checkboxes in the "Actions" section when creating or editing a permission. These are shown in a flat list alongside the built-in CRUD actions. Additional actions (such as those not yet registered by a plugin, or for backwards compatibility) can be entered manually in the "Additional actions" field.
 
 !!! note
     Internally, all actions granted by a permission (both built-in and custom) are stored as strings in an array field named `actions`.

docs/plugins/development/permissions.md

@@ -0,0 +1,51 @@
+# Custom Model Actions
+
+Plugins can register custom permission actions for their models. These actions appear as checkboxes in the ObjectPermission form, making it easy for administrators to grant or restrict access to plugin-specific functionality without manually entering action names.
+
+For example, a plugin might define a "sync" action for a model that syncs data from an external source, or a "bypass" action that allows users to bypass certain restrictions.
+
+## Registering Model Actions
+
+The preferred way to register custom actions is via Django's `Meta.permissions` on the model class. NetBox will automatically register these as model actions when the app is loaded:
+
+```python
+from netbox.models import NetBoxModel
+
+class MyModel(NetBoxModel):
+    # ...
+
+    class Meta:
+        permissions = [
+            ('sync', 'Synchronize data from external source'),
+            ('export', 'Export data to external system'),
+        ]
+```
+
+For dynamic registration (e.g. when actions depend on runtime state), you can call `register_model_actions()` directly, typically in your plugin's `ready()` method:
+
+```python
+# __init__.py
+from netbox.plugins import PluginConfig
+
+class MyPluginConfig(PluginConfig):
+    name = 'my_plugin'
+    # ...
+
+    def ready(self):
+        super().ready()
+        from utilities.permissions import ModelAction, register_model_actions
+        from .models import MyModel
+
+        register_model_actions(MyModel, [
+            ModelAction('sync', help_text='Synchronize data from external source'),
+            ModelAction('export', help_text='Export data to external system'),
+        ])
+
+config = MyPluginConfig
+```
+
+Once registered, these actions appear as checkboxes in a flat list when creating or editing an ObjectPermission.
+
+::: utilities.permissions.ModelAction
+
+::: utilities.permissions.register_model_actions

mkdocs.yml

@@ -152,6 +152,7 @@ nav:
             - Filters & Filter Sets: 'plugins/development/filtersets.md'
             - Search: 'plugins/development/search.md'
             - Event Types: 'plugins/development/event-types.md'
+            - Permissions: 'plugins/development/permissions.md'
             - Data Backends: 'plugins/development/data-backends.md'
             - Webhooks: 'plugins/development/webhooks.md'
             - User Interface: 'plugins/development/user-interface.md'

netbox/core/migrations/0022_datasource_sync_permission.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.11 on 2026-03-31 21:19
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0021_job_queue_name'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='datasource',
+            options={'ordering': ('name',), 'permissions': [('sync', 'Synchronize data from remote source')]},
+        ),
+    ]

netbox/core/models/data.py

@@ -87,6 +87,9 @@ class Meta:
         ordering = ('name',)
         verbose_name = _('data source')
         verbose_name_plural = _('data sources')
+        permissions = [
+            ('sync', 'Synchronize data from remote source'),
+        ]
 
     def __str__(self):
         return f'{self.name}'

netbox/dcim/migrations/0231_device_render_config_permission.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.11 on 2026-03-31 21:19
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('dcim', '0230_interface_rf_channel_frequency_precision'),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name='device',
+            options={'ordering': ('name', 'pk'), 'permissions': [('render_config', 'Render configuration')]},
+        ),
+    ]

netbox/dcim/models/devices.py

@@ -759,6 +759,9 @@ class Meta:
         )
         verbose_name = _('device')
         verbose_name_plural = _('devices')
+        permissions = [
+            ('render_config', 'Render configuration'),
+        ]
 
     def __str__(self):
         if self.label and self.asset_tag:

netbox/netbox/models/features.py

@@ -25,6 +25,7 @@
 from netbox.signals import post_clean
 from netbox.utils import register_model_feature
 from utilities.json import CustomFieldJSONEncoder
+from utilities.permissions import ModelAction, register_model_actions
 from utilities.serialization import serialize_object
 
 __all__ = (
@@ -752,3 +753,12 @@ def register_models(*models):
             register_model_view(model, 'sync', kwargs={'model': model})(
                 'netbox.views.generic.ObjectSyncDataView'
             )
+
+        # Auto-register custom permission actions declared in Meta.permissions
+        if meta_permissions := getattr(model._meta, 'permissions', None):
+            actions = [
+                ModelAction(codename, help_text=_(name))
+                for codename, name in meta_permissions
+            ]
+            if actions:
+                register_model_actions(model, actions)

netbox/netbox/registry.py

@@ -28,6 +28,7 @@ def __delitem__(self, key):
     'denormalized_fields': collections.defaultdict(list),
     'event_types': dict(),
     'filtersets': dict(),
+    'model_actions': collections.defaultdict(set),
     'model_features': dict(),
     'models': collections.defaultdict(set),
     'plugins': dict(),

netbox/project-static/src/forms/index.ts

@@ -1,10 +1,17 @@
 import { initClearField } from './clearField';
 import { initFormElements } from './elements';
 import { initFilterModifiers } from './filterModifiers';
+import { initRegisteredActions } from './registeredActions';
 import { initSpeedSelector } from './speedSelector';
 
 export function initForms(): void {
-  for (const func of [initFormElements, initSpeedSelector, initFilterModifiers, initClearField]) {
+  for (const func of [
+    initFormElements,
+    initSpeedSelector,
+    initFilterModifiers,
+    initClearField,
+    initRegisteredActions,
+  ]) {
     func();
   }
 }

netbox/project-static/src/forms/registeredActions.ts

@@ -0,0 +1,62 @@
+import { getElements } from '../util';
+
+/**
+ * Enable/disable registered action checkboxes based on selected object_types.
+ */
+export function initRegisteredActions(): void {
+  const selectedList = document.querySelector<HTMLSelectElement>(
+    'select[data-object-types-selected]',
+  );
+
+  if (!selectedList) {
+    return;
+  }
+
+  const actionCheckboxes = Array.from(
+    document.querySelectorAll<HTMLInputElement>('input[type="checkbox"][data-models]'),
+  );
+
+  if (actionCheckboxes.length === 0) {
+    return;
+  }
+
+  function updateState(): void {
+    const selectedModels = new Set<string>();
+
+    // Get model keys from selected options
+    for (const option of Array.from(selectedList!.options)) {
+      const modelKey = option.dataset.modelKey;
+      if (modelKey) {
+        selectedModels.add(modelKey);
+      }
+    }
+
+    // Enable a checkbox if any of its supported models is selected
+    for (const checkbox of actionCheckboxes) {
+      const modelKeys = (checkbox.dataset.models ?? '').split(',').filter(Boolean);
+      const enabled = modelKeys.some(m => selectedModels.has(m));
+      checkbox.disabled = !enabled;
+      if (!enabled) {
+        checkbox.checked = false;
+      }
+      checkbox.style.opacity = enabled ? '' : '0.75';
+
+      // Fade the label text when disabled
+      const label = checkbox.nextElementSibling as HTMLElement | null;
+      if (label) {
+        label.style.opacity = enabled ? '' : '0.5';
+      }
+    }
+  }
+
+  // Initial update
+  updateState();
+
+  // Listen to move button clicks
+  for (const btn of getElements<HTMLButtonElement>('.move-option')) {
+    btn.addEventListener('click', () => {
+      // Wait for DOM update
+      setTimeout(updateState, 0);
+    });
+  }
+}

netbox/templates/users/panels/actions.html

@@ -0,0 +1,26 @@
+{% extends "ui/panels/_base.html" %}
+{% load helpers %}
+
+{% block panel_content %}
+  <table class="table table-hover attr-table">
+    {% for label, enabled in crud_actions %}
+      <tr>
+        <th scope="row">{{ label }}</th>
+        <td>{% checkmark enabled %}</td>
+      </tr>
+    {% endfor %}
+    {% for action, enabled, models in registered_actions %}
+      <tr>
+        <th scope="row">{{ action }}</th>
+        <td>
+          <div class="d-flex justify-content-between align-items-start">
+            {% checkmark enabled %}
+            {% if models %}
+              <small class="text-muted">{{ models }}</small>
+            {% endif %}
+          </div>
+        </td>
+      </tr>
+    {% endfor %}
+  </table>
+{% endblock panel_content %}

netbox/users/constants.py

@@ -10,6 +10,11 @@
 
 CONSTRAINT_TOKEN_USER = '$user'
 
+# Django's four default model permissions. These receive special handling
+# (dedicated checkboxes, model properties) and should not be registered
+# as custom model actions.
+RESERVED_ACTIONS = ('view', 'add', 'change', 'delete')
+
 # API tokens
 TOKEN_PREFIX = 'nbt_'  # Used for v2 tokens only
 TOKEN_KEY_LENGTH = 12