forward-netbox 2.2.4__tar.gz → 2.3.0__tar.gz

forward_netbox-2.2.4/README.md → forward_netbox-2.3.0/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: forward-netbox
+Version: 2.3.0
+Summary: NetBox plugin to sync Forward 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: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+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
+Classifier: Topic :: System :: Networking
+Requires-Dist: httpx (>0.26,<0.29)
+Requires-Dist: netboxlabs-netbox-branching (>=1.1.0)
+Requires-Dist: pyzipper (>=0.3.6,<0.4.0)
+Project-URL: Changelog, https://github.com/forwardnetworks/forward-netbox/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/forwardnetworks/forward-netbox/tree/main/docs
+Project-URL: Homepage, https://github.com/forwardnetworks/forward-netbox
+Project-URL: Issue Tracker, https://github.com/forwardnetworks/forward-netbox/issues
+Project-URL: Repository, https://github.com/forwardnetworks/forward-netbox
+Description-Content-Type: text/markdown
+
 # Forward Field Integration
 
 **Forward Field Integration** (`forward_netbox`) is a NetBox plugin that syncs Forward inventory into NetBox through direct Forward API connectivity and NQE while preserving the branch-backed sync, diff, and merge workflow.
@@ -8,7 +41,9 @@ Forward 26.6 is the baseline for async NQE.
 
 | Plugin Release | NetBox Version | Status |
 | --- | --- | --- |
-| `v2.2.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Current release; Hotfix: device-analysis NQE (bare foreach) errored refresh + CVE list; surface job errors into job.data |
+| `v2.3.0` | `4.6.4` required; needs netbox-branching `1.1.0+` | Current release; GA/enterprise hardening: encrypted Forward credential at rest, PyPI Trusted Publishing + SBOM, Prometheus metrics + stuck-job alert, populated-DB upgrade test, dead-code removal (multi_branch/density-learning), reliability fixes (jittered/Retry-After backoff, SaaS rate clamp, PK-anchored device prune), and supported-product framing. Drop-in from 2.2.5 — stored credentials auto-encrypt on save; rotating SECRET_KEY requires re-entering them. |
+| `v2.2.5` | `4.6.4` required; needs netbox-branching `1.1.0+` | Superseded by `v2.3.0`; Feature: operator-selectable **Sync Device Tags** — pick which Forward device tags (e.g. `Mgmt_*`) become NetBox device tags (replaces the hardcoded feature-tag set); Fix dependency-preview AttributeError + vsys job pile-up guard (hung pending); test/require NetBox 4.6.4 |
+| `v2.2.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.5`; Hotfix: device-analysis NQE (bare foreach) errored refresh + CVE list; surface job errors into job.data |
 | `v2.2.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.4`; Field-feedback fixes: delete-count labeling, vsys/vdom auto-link, skip empty VRFs, per-device CVE list, churn pinpoint, query-ID status clarify |
 | `v2.2.2` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.3`; Fix 504 gateway timeouts on large syncs: stop recomputing change-explainability on every poll during a long merge + back off poll to 15s |
 | `v2.2.1` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.2`; Add read-only forward_apply_identity_audit diagnostic to pinpoint 1-created/1-deleted idempotency churn |
@@ -16,7 +51,6 @@ Forward 26.6 is the baseline for async NQE.
 | `v2.1.5` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.0`; Fix Prune orphans erroring on empty sites that still hold a VLAN/VM/prefix (delete only truly-empty sites) |
 | `v2.1.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.5`; Tag delete-eligible global IPAM (prefixes/VLANs/VRFs) for manual review |
 | `v2.1.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.4`; Prune empty orphan sites (zero devices + zero racks) alongside out-of-scope devices |
-| `v2.1.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.3`; Prune empty orphan sites (zero devices + zero racks) alongside out-of-scope devices |
 | `v2.1.2` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.3`; Feature + docs: (1) new out-of-scope orphan health signal — the sync health summary now shows how many NetBox devices match none of the included Forward tags (removable via Scope Reconciliation -> Prune orphans), mirroring the backfilled signal, via a self-healing `forward-out-of-scope` device tag and a `?tag=forward-out-of-scope` filter; (2) docs: the "no covering prefix" diagnostic now names /32 and /128 host addresses (loopbacks, anycast, some VIPs), and the Operations Guide documents backfilled (in-scope, kept) vs out-of-scope (removable) devices. Drop-in from `2.1.1`. |
 | `v2.1.1` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.2`; Bugfix + diagnostics: (1) the IPv4/IPv6 IP queries global dedup now pins the chosen interface to the chosen device (mirroring the VRF and MAC dedup blocks), so a deduped global address can no longer be attributed to an interface on a different device — the source of spurious "target interface was not imported" skips; (2) new read-only `forward_primary_ip_audit` command buckets Mgmt_ primary-IP resolution per device (resolvable / device-not-in-netbox / interface-not-matched / interface-present-no-IP) to pinpoint why a device does not get a primary IP. Drop-in from `2.1.0`. |
 | `v2.1.0` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.1`; Feature: `forward_scope_ipam_audit` management command — a read-only audit listing network-global IPAM (prefixes, VLANs, VRFs) that NetBox holds but the sync's latest Forward fetch no longer reports, as manual-review candidates. Device-tag scope prune is device-derived and never removes global IPAM; this surfaces stale global objects without deleting anything (identity matching reuses the apply engine so verdicts match the sync). Drop-in from `2.0.8`. |
@@ -32,7 +66,6 @@ Forward 26.6 is the baseline for async NQE.
 | `v1.7.2` | `4.6.3` required (4.5.x dropped); needs netbox-branching `1.1.0+` | Superseded by `v2.0.0`; Collection-gap diagnostics: per-reason backfill breakdown + staleness, growth/trend escalation, per-device collection result, ACI delete safety valve, opt-in auto-tag |
 | `v1.7.1` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.2`; ACI BD/L3Out graduation + FHRP churn fix (replaces yanked 1.7.0 and 1.6.2) |
 | `v1.7.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.1`; ACI bridge domain and L3Out NQE maps; query publish hardening |
-| `v1.7.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.0`; ACI bridge domain and L3Out NQE maps; query publish hardening |
 | `v1.6.2` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.0`; completes the 1.6.1 line (1.6.1 was yanked — its PyPI build predated these): device tag scope now covers VLANs/VRFs and prefixes derive from connected interface subnets; the FHRP group churn (delete+recreate every sync) is fixed by identity-bucket sharding; device analysis is a first-class model with a fleet list view, REST API, and an Open in Forward deep-link. |
 | `v1.6.1` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.6.2`; matures the 1.6.0 features and tooling — Device Analysis is now a NetBox model with a fleet-wide list view, REST API, and per-device-FK panel scoping (with up-interface blast-radius and opt-in post-sync refresh); adds a schedulable collection-gap alert command, run-history drill-down links, and hardened release tooling (one-command release script, generated CHANGELOG, conventional-commit hook). |
 | `v1.6.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.6.1`; ships the blue-sky tranche — release automation (`invoke release`), an Operations Guide, a collection-gap health signal, a sync run-history panel, a read-only device analysis panel (GA reachability / connectivity-degree blast radius / CVE exposure), and a bidirectional per-model drift report. |
@@ -184,9 +217,21 @@ Forward 26.6 is the baseline for async NQE.
 | `v0.1.1` | Added pagination, shared built-in NQE helpers, and release/doc cleanup. |
 | `v0.1.0` | Initial unsupported NetBox plugin release with built-in Forward sync workflow and seeded NQE maps. |
 
-## Support Disclaimer
+## Support
+
+Forward Field Integration is an officially maintained Forward Networks integration
+for NetBox. Supported NetBox and `netbox-branching` versions are listed in the
+Release Compatibility table above; support targets the latest released version.
 
-This repository is provided for use at your own risk. It is an unsupported release and is not an officially supported Forward product. There is no warranty, support commitment, or compatibility guarantee beyond the version table above.
+- **Bugs / feature requests:** open a GitHub issue using the provided templates.
+- **Security vulnerabilities:** report privately per [SECURITY.md](SECURITY.md) —
+  do not open a public issue.
+- **Upgrades:** follow the [Upgrade and Rollback guide](docs/01_User_Guide/upgrade.md);
+  back up the NetBox database before upgrading.
+
+Deploy on a supported NetBox version and review the deployment security notes in
+`SECURITY.md` (credential-at-rest and the sync trust boundary) before production
+use.
 
 ## Features
 
@@ -226,10 +271,16 @@ This repository is provided for use at your own risk. It is an unsupported relea
 
 1. Install the plugin into the same Python environment as NetBox:
 
-Install the wheel or source archive from GitHub Releases:
+Install the latest release from PyPI:
+
+```bash
+pip install forward-netbox
+```
+
+Or install a specific wheel or source archive from GitHub Releases:
 
 ```bash
-pip install /path/to/forward_netbox-0.9.4.1-py3-none-any.whl
+pip install /path/to/forward_netbox-2.2.5-py3-none-any.whl
 ```
 
 2. Enable both plugins in the NetBox configuration:
@@ -314,3 +365,4 @@ Normal UI/API sync jobs default to native multi-branch execution, with a default
 - [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-2.2.4/PKG-INFO → forward_netbox-2.3.0/README.md

@@ -1,26 +1,3 @@
-Metadata-Version: 2.4
-Name: forward-netbox
-Version: 2.2.4
-Summary: NetBox plugin to sync Forward 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 (>=1.1.0)
-Requires-Dist: pyzipper (>=0.3.6,<0.4.0)
-Description-Content-Type: text/markdown
-
 # Forward Field Integration
 
 **Forward Field Integration** (`forward_netbox`) is a NetBox plugin that syncs Forward inventory into NetBox through direct Forward API connectivity and NQE while preserving the branch-backed sync, diff, and merge workflow.
@@ -31,7 +8,9 @@ Forward 26.6 is the baseline for async NQE.
 
 | Plugin Release | NetBox Version | Status |
 | --- | --- | --- |
-| `v2.2.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Current release; Hotfix: device-analysis NQE (bare foreach) errored refresh + CVE list; surface job errors into job.data |
+| `v2.3.0` | `4.6.4` required; needs netbox-branching `1.1.0+` | Current release; GA/enterprise hardening: encrypted Forward credential at rest, PyPI Trusted Publishing + SBOM, Prometheus metrics + stuck-job alert, populated-DB upgrade test, dead-code removal (multi_branch/density-learning), reliability fixes (jittered/Retry-After backoff, SaaS rate clamp, PK-anchored device prune), and supported-product framing. Drop-in from 2.2.5 — stored credentials auto-encrypt on save; rotating SECRET_KEY requires re-entering them. |
+| `v2.2.5` | `4.6.4` required; needs netbox-branching `1.1.0+` | Superseded by `v2.3.0`; Feature: operator-selectable **Sync Device Tags** — pick which Forward device tags (e.g. `Mgmt_*`) become NetBox device tags (replaces the hardcoded feature-tag set); Fix dependency-preview AttributeError + vsys job pile-up guard (hung pending); test/require NetBox 4.6.4 |
+| `v2.2.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.5`; Hotfix: device-analysis NQE (bare foreach) errored refresh + CVE list; surface job errors into job.data |
 | `v2.2.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.4`; Field-feedback fixes: delete-count labeling, vsys/vdom auto-link, skip empty VRFs, per-device CVE list, churn pinpoint, query-ID status clarify |
 | `v2.2.2` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.3`; Fix 504 gateway timeouts on large syncs: stop recomputing change-explainability on every poll during a long merge + back off poll to 15s |
 | `v2.2.1` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.2`; Add read-only forward_apply_identity_audit diagnostic to pinpoint 1-created/1-deleted idempotency churn |
@@ -39,7 +18,6 @@ Forward 26.6 is the baseline for async NQE.
 | `v2.1.5` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.2.0`; Fix Prune orphans erroring on empty sites that still hold a VLAN/VM/prefix (delete only truly-empty sites) |
 | `v2.1.4` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.5`; Tag delete-eligible global IPAM (prefixes/VLANs/VRFs) for manual review |
 | `v2.1.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.4`; Prune empty orphan sites (zero devices + zero racks) alongside out-of-scope devices |
-| `v2.1.3` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.3`; Prune empty orphan sites (zero devices + zero racks) alongside out-of-scope devices |
 | `v2.1.2` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.3`; Feature + docs: (1) new out-of-scope orphan health signal — the sync health summary now shows how many NetBox devices match none of the included Forward tags (removable via Scope Reconciliation -> Prune orphans), mirroring the backfilled signal, via a self-healing `forward-out-of-scope` device tag and a `?tag=forward-out-of-scope` filter; (2) docs: the "no covering prefix" diagnostic now names /32 and /128 host addresses (loopbacks, anycast, some VIPs), and the Operations Guide documents backfilled (in-scope, kept) vs out-of-scope (removable) devices. Drop-in from `2.1.1`. |
 | `v2.1.1` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.2`; Bugfix + diagnostics: (1) the IPv4/IPv6 IP queries global dedup now pins the chosen interface to the chosen device (mirroring the VRF and MAC dedup blocks), so a deduped global address can no longer be attributed to an interface on a different device — the source of spurious "target interface was not imported" skips; (2) new read-only `forward_primary_ip_audit` command buckets Mgmt_ primary-IP resolution per device (resolvable / device-not-in-netbox / interface-not-matched / interface-present-no-IP) to pinpoint why a device does not get a primary IP. Drop-in from `2.1.0`. |
 | `v2.1.0` | `4.6.3` required; needs netbox-branching `1.1.0+` | Superseded by `v2.1.1`; Feature: `forward_scope_ipam_audit` management command — a read-only audit listing network-global IPAM (prefixes, VLANs, VRFs) that NetBox holds but the sync's latest Forward fetch no longer reports, as manual-review candidates. Device-tag scope prune is device-derived and never removes global IPAM; this surfaces stale global objects without deleting anything (identity matching reuses the apply engine so verdicts match the sync). Drop-in from `2.0.8`. |
@@ -55,7 +33,6 @@ Forward 26.6 is the baseline for async NQE.
 | `v1.7.2` | `4.6.3` required (4.5.x dropped); needs netbox-branching `1.1.0+` | Superseded by `v2.0.0`; Collection-gap diagnostics: per-reason backfill breakdown + staleness, growth/trend escalation, per-device collection result, ACI delete safety valve, opt-in auto-tag |
 | `v1.7.1` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.2`; ACI BD/L3Out graduation + FHRP churn fix (replaces yanked 1.7.0 and 1.6.2) |
 | `v1.7.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.1`; ACI bridge domain and L3Out NQE maps; query publish hardening |
-| `v1.7.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.0`; ACI bridge domain and L3Out NQE maps; query publish hardening |
 | `v1.6.2` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.7.0`; completes the 1.6.1 line (1.6.1 was yanked — its PyPI build predated these): device tag scope now covers VLANs/VRFs and prefixes derive from connected interface subnets; the FHRP group churn (delete+recreate every sync) is fixed by identity-bucket sharding; device analysis is a first-class model with a fleet list view, REST API, and an Open in Forward deep-link. |
 | `v1.6.1` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.6.2`; matures the 1.6.0 features and tooling — Device Analysis is now a NetBox model with a fleet-wide list view, REST API, and per-device-FK panel scoping (with up-interface blast-radius and opt-in post-sync refresh); adds a schedulable collection-gap alert command, run-history drill-down links, and hardened release tooling (one-command release script, generated CHANGELOG, conventional-commit hook). |
 | `v1.6.0` | `4.5.9` and `4.6.2` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features | Superseded by `v1.6.1`; ships the blue-sky tranche — release automation (`invoke release`), an Operations Guide, a collection-gap health signal, a sync run-history panel, a read-only device analysis panel (GA reachability / connectivity-degree blast radius / CVE exposure), and a bidirectional per-model drift report. |
@@ -207,9 +184,21 @@ Forward 26.6 is the baseline for async NQE.
 | `v0.1.1` | Added pagination, shared built-in NQE helpers, and release/doc cleanup. |
 | `v0.1.0` | Initial unsupported NetBox plugin release with built-in Forward sync workflow and seeded NQE maps. |
 
-## Support Disclaimer
+## Support
+
+Forward Field Integration is an officially maintained Forward Networks integration
+for NetBox. Supported NetBox and `netbox-branching` versions are listed in the
+Release Compatibility table above; support targets the latest released version.
 
-This repository is provided for use at your own risk. It is an unsupported release and is not an officially supported Forward product. There is no warranty, support commitment, or compatibility guarantee beyond the version table above.
+- **Bugs / feature requests:** open a GitHub issue using the provided templates.
+- **Security vulnerabilities:** report privately per [SECURITY.md](SECURITY.md) —
+  do not open a public issue.
+- **Upgrades:** follow the [Upgrade and Rollback guide](docs/01_User_Guide/upgrade.md);
+  back up the NetBox database before upgrading.
+
+Deploy on a supported NetBox version and review the deployment security notes in
+`SECURITY.md` (credential-at-rest and the sync trust boundary) before production
+use.
 
 ## Features
 
@@ -249,10 +238,16 @@ This repository is provided for use at your own risk. It is an unsupported relea
 
 1. Install the plugin into the same Python environment as NetBox:
 
-Install the wheel or source archive from GitHub Releases:
+Install the latest release from PyPI:
+
+```bash
+pip install forward-netbox
+```
+
+Or install a specific wheel or source archive from GitHub Releases:
 
 ```bash
-pip install /path/to/forward_netbox-0.9.4.1-py3-none-any.whl
+pip install /path/to/forward_netbox-2.2.5-py3-none-any.whl
 ```
 
 2. Enable both plugins in the NetBox configuration:
@@ -337,4 +332,3 @@ Normal UI/API sync jobs default to native multi-branch execution, with a default
 - [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-2.2.4 → forward_netbox-2.3.0}/forward_netbox/__init__.py

@@ -8,9 +8,9 @@ class NetboxForwardConfig(PluginConfig):
     name = "forward_netbox"
     verbose_name = "Forward Field Integration"
     description = "Sync Forward data into NetBox using built-in NQE queries."
-    version = "2.2.4"
+    version = "2.3.0"
     base_url = "forward"
-    min_version = "4.6.3"
+    min_version = "4.6.4"
 
     def ready(self):
         super().ready()

{forward_netbox-2.2.4 → forward_netbox-2.3.0}/forward_netbox/forms.py

@@ -436,6 +436,19 @@ class ForwardSourceForm(NetBoxModelForm):
                 "filtered in NetBox."
             ),
         )
+        self.fields["sync_device_tags"] = FlexibleMultipleChoiceField(
+            required=False,
+            choices=(),
+            widget=APISelectMultiple(
+                api_url="/api/plugins/forward/source/available-tags/"
+            ),
+            label="Sync Device Tags",
+            help_text=(
+                "Forward device tags (e.g. Mgmt_*) to sync onto NetBox devices as "
+                "device tags. Select one or more; leave empty to sync none. "
+                "Independent of the include/exclude scope filters above."
+            ),
+        )
         _configure_api_select(
             self.fields["network_id"].widget,
             {
@@ -448,6 +461,7 @@ class ForwardSourceForm(NetBoxModelForm):
         )
         self.fields["device_tag_include_tags"].widget.attrs["multiple"] = "multiple"
         self.fields["device_tag_exclude_tags"].widget.attrs["multiple"] = "multiple"
+        self.fields["sync_device_tags"].widget.attrs["multiple"] = "multiple"
         _configure_api_select(
             self.fields["device_tag_include_tags"].widget,
             {
@@ -470,6 +484,17 @@ class ForwardSourceForm(NetBoxModelForm):
                 "network_id": "$network_id",
             },
         )
+        _configure_api_select(
+            self.fields["sync_device_tags"].widget,
+            {
+                "type": "$type",
+                "url": "$url",
+                "username": "$username",
+                "password": "$password",
+                "verify": "$verify",
+                "network_id": "$network_id",
+            },
+        )
         if self.instance.pk:
             self.fields["network_id"].widget.add_query_param(
                 "source_id", self.instance.pk
@@ -480,6 +505,9 @@ class ForwardSourceForm(NetBoxModelForm):
             self.fields["device_tag_exclude_tags"].widget.add_query_param(
                 "source_id", self.instance.pk
             )
+            self.fields["sync_device_tags"].widget.add_query_param(
+                "source_id", self.instance.pk
+            )
 
         parameters = self.instance.parameters or {}
         existing_username = parameters.get("username")
@@ -549,9 +577,11 @@ class ForwardSourceForm(NetBoxModelForm):
         self.fields["network_id"].choices = _selected_choice(existing_network_id)
         include_bound = []
         exclude_bound = []
+        sync_tags_bound = []
         if self.is_bound:
             include_bound = self._bound_tag_values("device_tag_include_tags")
             exclude_bound = self._bound_tag_values("device_tag_exclude_tags")
+            sync_tags_bound = self._bound_tag_values("sync_device_tags")
         include_initial = (
             include_bound
             if self.is_bound
@@ -568,14 +598,22 @@ class ForwardSourceForm(NetBoxModelForm):
         if exclude_initial is None and parameters.get("device_tag_exclude"):
             exclude_initial = [parameters.get("device_tag_exclude")]
         exclude_initial = self._normalize_tag_values(exclude_initial)
+        sync_tags_initial = (
+            sync_tags_bound if self.is_bound else parameters.get("sync_device_tags")
+        )
+        sync_tags_initial = self._normalize_tag_values(sync_tags_initial)
         self.fields["device_tag_include_tags"].initial = include_initial
         self.fields["device_tag_exclude_tags"].initial = exclude_initial
+        self.fields["sync_device_tags"].initial = sync_tags_initial
         self.fields["device_tag_include_tags"].choices = [
             (tag, tag) for tag in include_initial
         ]
         self.fields["device_tag_exclude_tags"].choices = [
             (tag, tag) for tag in exclude_initial
         ]
+        self.fields["sync_device_tags"].choices = [
+            (tag, tag) for tag in sync_tags_initial
+        ]
         self.fields["device_tag_include_match"].initial = (
             parameters.get("device_tag_include_match") or "any"
         )
@@ -619,6 +657,7 @@ class ForwardSourceForm(NetBoxModelForm):
                     "device_tag_filter_mode",
                     "device_tag_prune_out_of_scope",
                     "apply_device_scope_tags",
+                    "sync_device_tags",
                     name="Parameters",
                 )
             )
@@ -649,6 +688,7 @@ class ForwardSourceForm(NetBoxModelForm):
                     "device_tag_filter_mode",
                     "device_tag_prune_out_of_scope",
                     "apply_device_scope_tags",
+                    "sync_device_tags",
                     name="Parameters",
                 )
             )
@@ -690,6 +730,11 @@ class ForwardSourceForm(NetBoxModelForm):
             exclude_tags = self._normalize_tag_values(
                 self._bound_tag_values("device_tag_exclude_tags")
             )
+        sync_device_tags = self._normalize_tag_values(cleaned.get("sync_device_tags"))
+        if not sync_device_tags:
+            sync_device_tags = self._normalize_tag_values(
+                self._bound_tag_values("sync_device_tags")
+            )
         candidate_parameters = {
             "username": username,
             "password": password,
@@ -794,6 +839,7 @@ class ForwardSourceForm(NetBoxModelForm):
                 cleaned.get("device_tag_prune_out_of_scope")
             ),
             "apply_device_scope_tags": bool(cleaned.get("apply_device_scope_tags")),
+            "sync_device_tags": sync_device_tags,
         }
         self.instance.type = source_type
         self.instance.url = (
@@ -834,6 +880,9 @@ class ForwardSourceForm(NetBoxModelForm):
         self.fields["device_tag_exclude_tags"].choices = [
             (tag, tag) for tag in exclude_tags
         ]
+        self.fields["sync_device_tags"].choices = [
+            (tag, tag) for tag in sync_device_tags
+        ]
         return cleaned
 
     def save(self, *args, **kwargs):
@@ -861,6 +910,13 @@ class ForwardSourceForm(NetBoxModelForm):
             exclude_tags = self._normalize_tag_values(
                 self._bound_tag_values("device_tag_exclude_tags")
             )
+        sync_device_tags = self._normalize_tag_values(
+            self.cleaned_data.get("sync_device_tags")
+        )
+        if not sync_device_tags:
+            sync_device_tags = self._normalize_tag_values(
+                self._bound_tag_values("sync_device_tags")
+            )
         self.instance.parameters = {
             "username": self.cleaned_data.get("username")
             or existing_parameters.get("username")
@@ -976,6 +1032,7 @@ class ForwardSourceForm(NetBoxModelForm):
             "apply_device_scope_tags": bool(
                 self.cleaned_data.get("apply_device_scope_tags")
             ),
+            "sync_device_tags": sync_device_tags,
         }
         self.instance.status = ForwardSourceStatusChoices.NEW
         return super().save(*args, **kwargs)
@@ -1205,7 +1262,6 @@ class ForwardSyncForm(NetBoxModelForm):
         parameters = {
             "execution_backend": ForwardExecutionBackendChoices.SINGLE_BRANCH,
             "auto_merge": cleaned.get("auto_merge", False),
-            "multi_branch": True,
             "snapshot_id": snapshot_id,
             "enable_bulk_orm": bool(cleaned.get("enable_bulk_orm", False)),
             "bulk_orm_models": list(
@@ -1230,7 +1286,6 @@ class ForwardSyncForm(NetBoxModelForm):
         parameters = {
             "execution_backend": ForwardExecutionBackendChoices.SINGLE_BRANCH,
             "auto_merge": self.cleaned_data.get("auto_merge", False),
-            "multi_branch": True,
             "snapshot_id": self.cleaned_data.get("snapshot_id")
             or LATEST_PROCESSED_SNAPSHOT,
             "enable_bulk_orm": bool(self.cleaned_data.get("enable_bulk_orm", False)),

{forward_netbox-2.2.4 → forward_netbox-2.3.0}/forward_netbox/jobs.py

@@ -53,8 +53,23 @@ def _resolve_request_user(*, sync, job=None):
         return job.user
     if getattr(sync, "user", None) is not None:
         return sync.user
+    # No invoking or owning user. Inventory-wide writes and their ObjectChange
+    # attribution would otherwise SILENTLY run as an arbitrary superuser, leaving
+    # an unexplainable audit trail. Keep the run working (a user FK is required
+    # downstream) but surface the fallback loudly so an operator assigns a proper
+    # sync owner.
     User = get_user_model()
-    return User.objects.filter(is_active=True, is_superuser=True).order_by("pk").first()
+    fallback = (
+        User.objects.filter(is_active=True, is_superuser=True).order_by("pk").first()
+    )
+    logger.warning(
+        "Forward sync %s has no invoking or owning user; attributing changes to "
+        "fallback superuser '%s'. Assign an owner to the sync so inventory writes "
+        "are attributed correctly.",
+        getattr(sync, "pk", "?"),
+        getattr(fallback, "username", None) or "<none>",
+    )
+    return fallback
 
 
 def _normalize_job_log_level(level):
@@ -121,6 +136,24 @@ def record_timeout_issue(ingestion, phase, message):
     )
 
 
+def _sync_has_active_job(sync, name):
+    """True if a pending/running job with ``name`` already exists for ``sync``.
+
+    Post-sync overlays are enqueued after EVERY sync; a slow/large overlay (e.g.
+    the vsys parent-link's full-network fetch) can still be running when the next
+    sync fires, so without this guard duplicate jobs pile up in PENDING behind it
+    and look 'hung'. Skipping the enqueue when one is already active keeps at most
+    one overlay of each kind queued per sync.
+    """
+    return sync.jobs.filter(
+        name=name,
+        status__in=[
+            JobStatusChoices.STATUS_PENDING,
+            JobStatusChoices.STATUS_RUNNING,
+        ],
+    ).exists()
+
+
 def _maybe_enqueue_device_analysis_refresh(sync):
     """Opt-in: after a successful sync, refresh the device-analysis overlay.
 
@@ -132,11 +165,14 @@ def _maybe_enqueue_device_analysis_refresh(sync):
     try:
         from django.utils.module_loading import import_string
 
+        name = f"{sync.name} - refresh device analysis (auto)"
+        if _sync_has_active_job(sync, name):
+            return
         Job.enqueue(
             import_string("forward_netbox.jobs.refresh_forward_device_analysis"),
             instance=sync,
             user=sync.user,
-            name=f"{sync.name} - refresh device analysis (auto)",
+            name=name,
         )
     except Exception as exc:  # pragma: no cover - defensive
         logger.warning("Auto device-analysis refresh enqueue failed: %s", exc)
@@ -156,11 +192,14 @@ def _maybe_enqueue_backfilled_tag_refresh(sync):
     try:
         from django.utils.module_loading import import_string
 
+        name = f"{sync.name} - tag backfilled devices (auto)"
+        if _sync_has_active_job(sync, name):
+            return
         Job.enqueue(
             import_string("forward_netbox.jobs.tag_forward_backfilled_devices"),
             instance=sync,
             user=sync.user,
-            name=f"{sync.name} - tag backfilled devices (auto)",
+            name=name,
         )
     except Exception as exc:  # pragma: no cover - defensive
         logger.warning("Auto backfilled-tag refresh enqueue failed: %s", exc)
@@ -180,11 +219,14 @@ def _maybe_enqueue_vsys_parent_link(sync):
     try:
         from django.utils.module_loading import import_string
 
+        name = f"{sync.name} - link vsys/vdom parents (auto)"
+        if _sync_has_active_job(sync, name):
+            return
         Job.enqueue(
             import_string("forward_netbox.jobs.link_forward_vsys_parents"),
             instance=sync,
             user=sync.user,
-            name=f"{sync.name} - link vsys/vdom parents (auto)",
+            name=name,
         )
     except Exception as exc:  # pragma: no cover - defensive
         logger.warning("Auto vsys parent-link enqueue failed: %s", exc)
@@ -202,11 +244,14 @@ def _maybe_enqueue_auto_prune(sync):
     try:
         from django.utils.module_loading import import_string
 
+        name = f"{sync.name} - prune orphans (auto)"
+        if _sync_has_active_job(sync, name):
+            return
         Job.enqueue(
             import_string("forward_netbox.jobs.prune_forward_orphans"),
             instance=sync,
             user=sync.user,
-            name=f"{sync.name} - prune orphans (auto)",
+            name=name,
         )
     except Exception as exc:  # pragma: no cover - defensive
         logger.warning("Auto prune-orphans enqueue failed: %s", exc)
@@ -523,7 +568,7 @@ def create_forward_module_bays(job, *args, **kwargs):
 def forward_dependency_preview(job, *args, **kwargs):
     """Background dependency dry-run preview for a sync.
 
-    The dry-run builds a full multi-branch plan against live Forward data, which
+    The dry-run builds a full single-branch plan against live Forward data, which
     far exceeds an HTTP gateway timeout on large fabrics. Run it as a job and
     cache the JSON payload on ``job.data`` so the preview page can render it
     later without a Forward round-trip.

forward_netbox-2.3.0/forward_netbox/management/commands/forward_metrics.py

@@ -0,0 +1,105 @@
+import logging
+
+from core.choices import JobStatusChoices
+from core.models import Job
+from django.contrib.contenttypes.models import ContentType
+from django.core.management.base import BaseCommand
+from django.utils import timezone
+
+from forward_netbox.models import ForwardIngestion
+from forward_netbox.models import ForwardSource
+from forward_netbox.models import ForwardSync
+from forward_netbox.utilities.job_liveness import job_has_live_execution
+
+logger = logging.getLogger("forward_netbox.metrics")
+
+ACTIVE_JOB_STATUSES = (
+    JobStatusChoices.STATUS_PENDING,
+    JobStatusChoices.STATUS_RUNNING,
+)
+
+
+def _metric(lines, name, help_text, value, mtype="gauge", labels=""):
+    lines.append(f"# HELP {name} {help_text}")
+    lines.append(f"# TYPE {name} {mtype}")
+    label_block = f"{{{labels}}}" if labels else ""
+    lines.append(f"{name}{label_block} {value}")
+
+
+class Command(BaseCommand):
+    help = (
+        "Emit forward_netbox metrics in Prometheus text-exposition format on "
+        "stdout, for a node_exporter textfile collector or a scrape sidecar. "
+        "Read-only; safe to run on a schedule."
+    )
+
+    def handle(self, *args, **options):
+        lines = []
+
+        _metric(
+            lines,
+            "forward_sources_total",
+            "Configured Forward sources.",
+            ForwardSource.objects.count(),
+        )
+        _metric(
+            lines,
+            "forward_syncs_total",
+            "Configured Forward syncs.",
+            ForwardSync.objects.count(),
+        )
+        _metric(
+            lines,
+            "forward_ingestions_total",
+            "Recorded Forward ingestion runs.",
+            ForwardIngestion.objects.count(),
+        )
+
+        forward_type_ids = list(
+            ContentType.objects.filter(app_label="forward_netbox").values_list(
+                "pk", flat=True
+            )
+        )
+        jobs = Job.objects.filter(object_type_id__in=forward_type_ids)
+
+        status_counts = {}
+        # ChoiceSet entries may be (value, label) or (value, label, color); take
+        # the value.
+        for choice in JobStatusChoices.CHOICES:
+            status = choice[0]
+            status_counts[status] = jobs.filter(status=status).count()
+        lines.append("# HELP forward_jobs Forward background jobs by status.")
+        lines.append("# TYPE forward_jobs gauge")
+        for status, count in status_counts.items():
+            lines.append(f'forward_jobs{{status="{status}"}} {count}')
+
+        active = jobs.filter(status__in=ACTIVE_JOB_STATUSES)
+        stuck = sum(1 for job in active if not job_has_live_execution(job))
+        _metric(
+            lines,
+            "forward_stuck_jobs",
+            "Active jobs with no live worker execution (wedged).",
+            stuck,
+        )
+
+        last_completed = (
+            jobs.filter(status=JobStatusChoices.STATUS_COMPLETED)
+            .exclude(completed__isnull=True)
+            .order_by("-completed")
+            .first()
+        )
+        if last_completed and last_completed.completed:
+            _metric(
+                lines,
+                "forward_last_completed_job_timestamp_seconds",
+                "Unix time of the most recent completed Forward job.",
+                int(last_completed.completed.timestamp()),
+            )
+            _metric(
+                lines,
+                "forward_last_completed_job_age_seconds",
+                "Seconds since the most recent completed Forward job.",
+                int((timezone.now() - last_completed.completed).total_seconds()),
+            )
+
+        self.stdout.write("\n".join(lines) + "\n")