forward-netbox 0.1.1__tar.gz

forward_netbox-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craig Johnson, Forward Networks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forward_netbox-0.1.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: forward-netbox
+Version: 0.1.1
+Summary: NetBox plugin to sync Forward Networks data into NetBox via built-in NQE queries
+License: MIT
+License-File: LICENSE
+Keywords: netbox,forward,plugin,sync,nqe
+Author: Craig Johnson
+Author-email: craigjohnson@forwardnetworks.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>0.26,<0.29)
+Requires-Dist: netboxlabs-netbox-branching (>=0.7.0)
+Description-Content-Type: text/markdown
+
+# Forward NetBox Plugin
+
+`forward_netbox` is a NetBox plugin that syncs Forward Networks inventory into NetBox through direct Forward API connectivity and NQE while preserving the branch-backed sync, diff, and merge workflow.
+
+## Release Compatibility
+
+| Plugin Release | NetBox Version | Status |
+| --- | --- | --- |
+| `v0.1.1` | `4.5.x` only | Current unsupported release |
+
+## Support Disclaimer
+
+This repository is provided for use at your own risk. It is an unsupported release and is not an officially supported Forward Networks product. There is no warranty, support commitment, or compatibility guarantee beyond the version table above.
+
+## Features
+
+- Branch-backed sync, diff, and merge flow through `netbox_branching`
+- Forward `Sources`, `NQE Maps`, `Syncs`, and `Ingestions`
+- Built-in shipped NQE maps seeded automatically after migration
+- Support for either published Forward `query_id` references or raw NQE `query` text
+- Repository-authored built-in queries can share local helper modules and still execute as flattened raw NQE when bundled
+- Automatic paging across multi-page Forward NQE result sets during sync execution
+- Snapshot-aware execution with `latestProcessed` or an explicit Forward snapshot per sync
+- Ingestion records that preserve the selected snapshot mode, resolved snapshot ID, and Forward snapshot metrics
+- Built-in coverage for:
+  - `dcim.site`
+  - `dcim.manufacturer`
+  - `dcim.devicerole`
+  - `dcim.platform`
+  - `dcim.devicetype`
+  - `dcim.device`
+  - `dcim.virtualchassis`
+  - `dcim.interface`
+  - `dcim.macaddress`
+  - `dcim.inventoryitem`
+  - `ipam.vlan`
+  - `ipam.vrf`
+  - `ipam.prefix` for IPv4 and IPv6
+  - `ipam.ipaddress`
+
+## Quickstart
+
+1. Install the plugin into the same Python environment as NetBox:
+
+```bash
+pip install forward-netbox==0.1.1
+```
+
+If you need an offline or pinned artifact workflow, install the wheel or source archive from GitHub Releases instead:
+
+```bash
+pip install /path/to/forward_netbox-0.1.1-py3-none-any.whl
+```
+
+2. Enable both plugins in the NetBox configuration:
+
+```python
+PLUGINS = [
+    "netbox_branching",
+    "forward_netbox",
+]
+```
+
+3. Apply migrations:
+
+```bash
+python manage.py migrate
+```
+
+4. Open NetBox and create a `Forward Source`.
+5. Select a Forward network for that source.
+6. Create a `Forward Sync`, choose the snapshot selector, and enable the NetBox models you want to sync.
+7. Run an adhoc ingestion, review the staged branch diff, review the recorded snapshot details and metrics, and merge when the changes look correct.
+
+## Test It Yourself
+
+Use this quick validation flow after installation:
+
+1. Create a `Forward Source` using `https://fwd.app` or your custom Forward URL.
+2. Enter a Forward username and password, then confirm the `Network` field populates from the live Forward tenant.
+3. Open `NQE Maps` and verify the built-in maps are present.
+4. Create a `Forward Sync` tied to the source, leaving `Snapshot` at `latestProcessed` for the first run.
+5. Run the sync from the sync detail page.
+6. Review the generated `Forward Ingestion`, `Issues`, snapshot details, snapshot metrics, and change diff.
+7. Merge the branch and confirm the synced objects appear in NetBox.
+
+## Local Validation
+
+The repository now includes local validation tasks:
+
+- `invoke forward_netbox.lint`
+- `invoke forward_netbox.check`
+- `invoke forward_netbox.test`
+- `invoke forward_netbox.docs`
+- `invoke forward_netbox.package`
+- `invoke forward_netbox.ci`
+
+For a live Forward smoke run outside CI, set these environment variables and run the smoke task locally:
+
+```bash
+export FORWARD_SMOKE_USERNAME='your-forward-username'
+export FORWARD_SMOKE_PASSWORD='your-forward-password'
+export FORWARD_SMOKE_NETWORK_ID='your-network-id'
+invoke forward_netbox.smoke-sync
+```
+
+Optional smoke-sync variables:
+
+- `FORWARD_SMOKE_URL` defaults to `https://fwd.app`
+- `FORWARD_SMOKE_SNAPSHOT_ID` defaults to `latestProcessed`
+- `FORWARD_SMOKE_MODELS` accepts a comma-separated subset such as `dcim.site,dcim.device,dcim.interface`
+- `invoke forward_netbox.smoke-sync --validate-only` runs live snapshot/query validation without executing an ingestion
+- `invoke forward_netbox.smoke-sync --merge` will merge the staged branch after a clean run
+
+## Documentation
+
+- [Documentation Home](docs/README.md)
+- [Installation](docs/01_User_Guide/README.md)
+- [Configuration](docs/01_User_Guide/configuration.md)
+- [Usage and Validation](docs/01_User_Guide/usage.md)
+- [Troubleshooting](docs/01_User_Guide/troubleshooting.md)
+- [Built-In NQE Reference](docs/02_Reference/built-in-nqe-maps.md)
+- [Model Mapping Matrix](docs/02_Reference/model-mapping-matrix.md)
+- [Shipped NQE Query Files](https://github.com/forwardnetworks/forward-netbox/tree/main/forward_netbox/queries)
+- [License](LICENSE)
+

forward_netbox-0.1.1/README.md

@@ -0,0 +1,125 @@
+# Forward NetBox Plugin
+
+`forward_netbox` is a NetBox plugin that syncs Forward Networks inventory into NetBox through direct Forward API connectivity and NQE while preserving the branch-backed sync, diff, and merge workflow.
+
+## Release Compatibility
+
+| Plugin Release | NetBox Version | Status |
+| --- | --- | --- |
+| `v0.1.1` | `4.5.x` only | Current unsupported release |
+
+## Support Disclaimer
+
+This repository is provided for use at your own risk. It is an unsupported release and is not an officially supported Forward Networks product. There is no warranty, support commitment, or compatibility guarantee beyond the version table above.
+
+## Features
+
+- Branch-backed sync, diff, and merge flow through `netbox_branching`
+- Forward `Sources`, `NQE Maps`, `Syncs`, and `Ingestions`
+- Built-in shipped NQE maps seeded automatically after migration
+- Support for either published Forward `query_id` references or raw NQE `query` text
+- Repository-authored built-in queries can share local helper modules and still execute as flattened raw NQE when bundled
+- Automatic paging across multi-page Forward NQE result sets during sync execution
+- Snapshot-aware execution with `latestProcessed` or an explicit Forward snapshot per sync
+- Ingestion records that preserve the selected snapshot mode, resolved snapshot ID, and Forward snapshot metrics
+- Built-in coverage for:
+  - `dcim.site`
+  - `dcim.manufacturer`
+  - `dcim.devicerole`
+  - `dcim.platform`
+  - `dcim.devicetype`
+  - `dcim.device`
+  - `dcim.virtualchassis`
+  - `dcim.interface`
+  - `dcim.macaddress`
+  - `dcim.inventoryitem`
+  - `ipam.vlan`
+  - `ipam.vrf`
+  - `ipam.prefix` for IPv4 and IPv6
+  - `ipam.ipaddress`
+
+## Quickstart
+
+1. Install the plugin into the same Python environment as NetBox:
+
+```bash
+pip install forward-netbox==0.1.1
+```
+
+If you need an offline or pinned artifact workflow, install the wheel or source archive from GitHub Releases instead:
+
+```bash
+pip install /path/to/forward_netbox-0.1.1-py3-none-any.whl
+```
+
+2. Enable both plugins in the NetBox configuration:
+
+```python
+PLUGINS = [
+    "netbox_branching",
+    "forward_netbox",
+]
+```
+
+3. Apply migrations:
+
+```bash
+python manage.py migrate
+```
+
+4. Open NetBox and create a `Forward Source`.
+5. Select a Forward network for that source.
+6. Create a `Forward Sync`, choose the snapshot selector, and enable the NetBox models you want to sync.
+7. Run an adhoc ingestion, review the staged branch diff, review the recorded snapshot details and metrics, and merge when the changes look correct.
+
+## Test It Yourself
+
+Use this quick validation flow after installation:
+
+1. Create a `Forward Source` using `https://fwd.app` or your custom Forward URL.
+2. Enter a Forward username and password, then confirm the `Network` field populates from the live Forward tenant.
+3. Open `NQE Maps` and verify the built-in maps are present.
+4. Create a `Forward Sync` tied to the source, leaving `Snapshot` at `latestProcessed` for the first run.
+5. Run the sync from the sync detail page.
+6. Review the generated `Forward Ingestion`, `Issues`, snapshot details, snapshot metrics, and change diff.
+7. Merge the branch and confirm the synced objects appear in NetBox.
+
+## Local Validation
+
+The repository now includes local validation tasks:
+
+- `invoke forward_netbox.lint`
+- `invoke forward_netbox.check`
+- `invoke forward_netbox.test`
+- `invoke forward_netbox.docs`
+- `invoke forward_netbox.package`
+- `invoke forward_netbox.ci`
+
+For a live Forward smoke run outside CI, set these environment variables and run the smoke task locally:
+
+```bash
+export FORWARD_SMOKE_USERNAME='your-forward-username'
+export FORWARD_SMOKE_PASSWORD='your-forward-password'
+export FORWARD_SMOKE_NETWORK_ID='your-network-id'
+invoke forward_netbox.smoke-sync
+```
+
+Optional smoke-sync variables:
+
+- `FORWARD_SMOKE_URL` defaults to `https://fwd.app`
+- `FORWARD_SMOKE_SNAPSHOT_ID` defaults to `latestProcessed`
+- `FORWARD_SMOKE_MODELS` accepts a comma-separated subset such as `dcim.site,dcim.device,dcim.interface`
+- `invoke forward_netbox.smoke-sync --validate-only` runs live snapshot/query validation without executing an ingestion
+- `invoke forward_netbox.smoke-sync --merge` will merge the staged branch after a clean run
+
+## Documentation
+
+- [Documentation Home](docs/README.md)
+- [Installation](docs/01_User_Guide/README.md)
+- [Configuration](docs/01_User_Guide/configuration.md)
+- [Usage and Validation](docs/01_User_Guide/usage.md)
+- [Troubleshooting](docs/01_User_Guide/troubleshooting.md)
+- [Built-In NQE Reference](docs/02_Reference/built-in-nqe-maps.md)
+- [Model Mapping Matrix](docs/02_Reference/model-mapping-matrix.md)
+- [Shipped NQE Query Files](https://github.com/forwardnetworks/forward-netbox/tree/main/forward_netbox/queries)
+- [License](LICENSE)

forward_netbox-0.1.1/forward_netbox/__init__.py

@@ -0,0 +1,17 @@
+from netbox.plugins import PluginConfig
+
+
+class NetboxForwardConfig(PluginConfig):
+    name = "forward_netbox"
+    verbose_name = "NetBox Forward Networks Plugin"
+    description = "Sync Forward Networks data into NetBox using built-in NQE queries."
+    version = "0.1.1"
+    base_url = "forward"
+    min_version = "4.5.0"
+
+    def ready(self):
+        super().ready()
+        from . import signals  # noqa: F401
+
+
+config = NetboxForwardConfig

forward_netbox-0.1.1/forward_netbox/api/__init__.py

@@ -0,0 +1 @@
+from .serializers import *  # noqa: F401, F403

forward_netbox-0.1.1/forward_netbox/api/serializers.py

@@ -0,0 +1,174 @@
+from django.contrib.contenttypes.models import ContentType
+from netbox.api.fields import ChoiceField
+from netbox.api.fields import ContentTypeField
+from netbox.api.serializers import NestedGroupModelSerializer
+from netbox_branching.api.serializers import BranchSerializer
+from rest_framework import serializers
+
+from forward_netbox.choices import ForwardIngestionPhaseChoices
+from forward_netbox.choices import ForwardSourceDeploymentChoices
+from forward_netbox.choices import ForwardSourceStatusChoices
+from forward_netbox.choices import ForwardSyncStatusChoices
+from forward_netbox.models import FORWARD_SUPPORTED_SYNC_MODELS
+from forward_netbox.models import ForwardIngestion
+from forward_netbox.models import ForwardIngestionIssue
+from forward_netbox.models import ForwardNQEMap
+from forward_netbox.models import ForwardSource
+from forward_netbox.models import ForwardSync
+
+
+class EmptySerializer(serializers.Serializer):
+    pass
+
+
+class ForwardNQEMapSerializer(NestedGroupModelSerializer):
+    netbox_model = ContentTypeField(
+        queryset=ContentType.objects.filter(FORWARD_SUPPORTED_SYNC_MODELS)
+    )
+    execution_mode = serializers.CharField(read_only=True)
+    execution_value = serializers.CharField(read_only=True)
+
+    class Meta:
+        model = ForwardNQEMap
+        fields = (
+            "id",
+            "name",
+            "display",
+            "netbox_model",
+            "query_id",
+            "query",
+            "commit_id",
+            "parameters",
+            "execution_mode",
+            "execution_value",
+            "enabled",
+            "built_in",
+            "weight",
+            "created",
+            "last_updated",
+        )
+        brief_fields = (
+            "id",
+            "name",
+            "display",
+            "netbox_model",
+            "execution_mode",
+            "execution_value",
+            "enabled",
+        )
+
+
+class ForwardSourceSerializer(NestedGroupModelSerializer):
+    status = ChoiceField(choices=ForwardSourceStatusChoices, read_only=True)
+    type = ChoiceField(choices=ForwardSourceDeploymentChoices)
+
+    class Meta:
+        model = ForwardSource
+        fields = (
+            "id",
+            "display",
+            "name",
+            "type",
+            "url",
+            "status",
+            "parameters",
+            "description",
+            "comments",
+            "last_synced",
+            "created",
+            "last_updated",
+        )
+        brief_fields = (
+            "id",
+            "display",
+            "name",
+            "type",
+            "url",
+            "status",
+        )
+
+    def to_representation(self, instance):
+        data = super().to_representation(instance)
+        data["parameters"] = instance.get_masked_parameters()
+        return data
+
+
+class ForwardSyncSerializer(NestedGroupModelSerializer):
+    status = ChoiceField(choices=ForwardSyncStatusChoices, read_only=True)
+    source = ForwardSourceSerializer(nested=True)
+    enabled_models = serializers.SerializerMethodField(read_only=True)
+
+    class Meta:
+        model = ForwardSync
+        fields = (
+            "id",
+            "display",
+            "name",
+            "source",
+            "enabled_models",
+            "status",
+            "parameters",
+            "auto_merge",
+            "last_synced",
+            "scheduled",
+            "interval",
+            "user",
+            "created",
+            "last_updated",
+        )
+        brief_fields = (
+            "id",
+            "display",
+            "name",
+            "source",
+            "enabled_models",
+            "status",
+            "auto_merge",
+        )
+
+    def get_enabled_models(self, obj):
+        return obj.enabled_models()
+
+    def to_representation(self, instance):
+        data = super().to_representation(instance)
+        data["parameters"] = instance.get_display_parameters()
+        return data
+
+
+class ForwardIngestionSerializer(NestedGroupModelSerializer):
+    branch = BranchSerializer(read_only=True)
+    sync = ForwardSyncSerializer(nested=True)
+
+    class Meta:
+        model = ForwardIngestion
+        fields = (
+            "id",
+            "display",
+            "name",
+            "branch",
+            "sync",
+            "snapshot_selector",
+            "snapshot_id",
+            "snapshot_info",
+            "snapshot_metrics",
+            "created",
+        )
+        brief_fields = ("id", "display", "name", "branch", "sync", "snapshot_id")
+
+
+class ForwardIngestionIssueSerializer(NestedGroupModelSerializer):
+    phase = ChoiceField(choices=ForwardIngestionPhaseChoices, read_only=True)
+    ingestion = ForwardIngestionSerializer(nested=True)
+
+    class Meta:
+        model = ForwardIngestionIssue
+        fields = (
+            "id",
+            "ingestion",
+            "timestamp",
+            "phase",
+            "model",
+            "message",
+            "raw_data",
+            "exception",
+        )

forward_netbox-0.1.1/forward_netbox/api/urls.py

@@ -0,0 +1,16 @@
+from netbox.api.routers import NetBoxRouter
+
+from forward_netbox.api.views import ForwardIngestionIssueViewSet
+from forward_netbox.api.views import ForwardIngestionViewSet
+from forward_netbox.api.views import ForwardNQEMapViewSet
+from forward_netbox.api.views import ForwardSourceViewSet
+from forward_netbox.api.views import ForwardSyncViewSet
+
+
+router = NetBoxRouter()
+router.register("source", ForwardSourceViewSet)
+router.register("sync", ForwardSyncViewSet)
+router.register("ingestion", ForwardIngestionViewSet)
+router.register("ingestion-issues", ForwardIngestionIssueViewSet)
+router.register("nqe-map", ForwardNQEMapViewSet)
+urlpatterns = router.urls