Forward Integration for NetBox

Forward Integration for NetBox (forward_netbox) is a NetBox plugin that syncs Forward Networks inventory into NetBox.

Status

Support model: field integration reference — not an officially supported Forward Networks product.
Requires: NetBox 4.6.5, netbox-branching 1.1.1; Forward 26.6 baseline for async NQE (full matrix in Release Compatibility).
Distribution: PyPI + GitHub releases. pip install forward-netbox is the core edition (NetBox-builtin models only); pip install forward-netbox[integrations] adds the optional netbox-dlm / netbox-routing / netbox-cisco-aci / netbox-peering-manager maps. See Editions.

What It Does

It pulls your Forward-discovered inventory into NetBox — devices, interfaces, IP addresses, prefixes, VLANs, VRFs, cables, LAGs, MAC addresses, and inventory items. It runs Forward NQE against a chosen snapshot, stages every change in a netbox_branching branch so you can review the diff, then merges when it looks right.

On top of the import it adds scope control (sync only devices carrying chosen Forward tags), orphan pruning, per-device analysis (reachability, connectivity blast-radius, CVE exposure), a drift report, and snapshot selection.

What It Does Not Do

It does not write back to Forward. The sync is one-way, Forward → NetBox; Forward stays the source of truth and the plugin keeps NetBox populated from what Forward collected. (The drift report only compares the two.)
It is not a source of truth for Forward configuration or intent — it populates NetBox from Forward's collected snapshot, nothing more.
It does not require the optional netbox-routing / netbox-peering-manager / netbox-cisco-aci / netbox-dlm plugins — the core edition ships without them. Install forward-netbox[integrations] and enable the relevant maps to use the supported BGP/OSPF, Cisco ACI, or device-lifecycle surfaces.

Screenshots

Sync — health, enabled models, and actions

Forward sync detail

Staged ingestion — progress, snapshot metrics, and issues

Forward ingestion detail

Drift report — per-model NetBox-vs-Forward divergence

Drift report

Forward sources

Forward sources list

Architecture

Forward NQE runs against a selected snapshot to fetch inventory. Every sync stages its dependency-ordered workloads into one netbox_branching branch and merges through the plugin's idempotent bulk merge. A merge with any failed row remains open for inspection and retry; it cannot become a completed baseline. See the Architecture Flow reference for detail.

Release Compatibility

The 2.6.3 release requires NetBox 4.6.5 and netbox-branching 1.1.1. Expand for the published release history and release notes.

Release compatibility history

Plugin Release	NetBox Version	Status
`v2.6.3`	`4.6.5` required; needs netbox-branching `1.1.1`	Current release; Corrective release. Published as `2.6.3`: `2.6.2` was tagged but never published, so no `2.6.2` artifact exists on PyPI. Fix: Ingestions list crashed with `NoReverseMatch` for `forwardingestion_delete`; ingestion rows now declare an explicit empty action set, and an installed-wheel route probe renders every plugin menu list from the packaged artifact so this class of failure cannot ship again. Fix: sync blocked by legacy repository-path query binding - maps bound by repository path with no stored query ID failed spec resolution and blocked validation. Maps now resolve read-only to their org query ID (exact path, then unique filename, then unique intent, failing closed on ambiguity), and a new Resolve to Query ID action lets an operator bind every map without NQE-library write permission. Fix: publish permission is now checked before any write, naming the missing capability instead of failing generically. Fix: `dcim.platform` query crashed on snapshots where a device reported no OS version (`matches()` received null); the bundled query defaults an absent version, and a source-level guard scans every bundled query for possibly-null values entering null-intolerant helpers. Fix: execution-contract safety - a full contract can never execute against a parameter-incompatible revision and a diff contract can never execute against a parameter-declaring revision; both fail closed with a type-only diagnostic and a preflight surfaces inconsistent contracts before a sync starts, replacing an opaque Forward `HTTP 400`. Fix: protected DLM software-version deletion was scheduled before the updates releasing its foreign key; destination values are now read in batches and update-before-delete ordering applied, while retained references still fail strictly. Feature: fast baseline load - a first sync into an empty NetBox applies directly to main in one transaction instead of staging and merging ~1.2M branch changes, cutting a first-time load from hours to roughly an hour on a 3,400-device dataset. Strictly gated: default off, exact pinned runtime tuple, full snapshots only, empty target and side tables, no prior ingestion or baseline, no competing branch, all rechecked under locks and rolled back entirely on any failure; every later sync uses the ordinary branch workflow. A read-only preflight reports eligibility, and a durable attestation records the engine and the branch evidence deliberately omitted. Performance: NQE async polling now backs off to a five-second plateau, cutting status calls by about 91% on a full sync. Observability: merge progress, rate and ETA are operator-visible, merge failures capture exit status and cause, and support-bundle job errors expose the inner exception type without customer data. Python/UI plus schema migrations `0043` and `0044`.
`v2.6.1`	`4.6.5` required; needs netbox-branching `1.1.1`	Superseded by `v2.6.3`; Compatibility fix: restores the supported Python range to `>=3.10,<3.15` (including Python 3.12) without changing runtime behavior.
`v2.6.0`	`4.6.5` required; needs netbox-branching `1.1.1`	Superseded by `v2.6.1`; Feature: durable convergence control plane - main-schema, per-sync identity and ownership claims are stamped with the exact merged ingestion generation. Managed scope/status tags and virtual-parent links materialize from the union of current claims, including shared tags across sources; only syncs with a completed baseline participate, every completed ingestion reconciles status ownership, and last-claim removal waits for every participating sync. Pending, failed, stale, conflicting, and missing materialization states block convergence in Drift, Health, support evidence, recovery, and the read-only ownership audit. Post-sync analysis, scope/status, and parent work runs through NetBox JobRunner with generation guards; invoking users become durable sync owners, and unattended execution fails closed without attributable ownership. A branch merge with any failed row remains retryable and cannot mark the ingestion complete or enqueue overlays. Merge recovery updates authoritative branch state instead of trusting stale worker objects, and every queued Forward job enforces a two-hour timeout minimum while preserving larger operator values. One Branching branch is used per sync; bounded workload shards target that branch, conservative density baselines shape unprofiled work, and module bays are created branch-natively. Migration `0037` converts retired execution keys, standing schedules, endpoint scope markers, owners, and built-in virtual-chassis state once; runtime rejects retired or unknown configuration instead of carrying compatibility shims. Unsupported no-op ACI maps and inventory contracts are removed. NetBox `4.6.5`, netbox-branching `1.1.1`, and Python `3.14` are exact startup, CI, and packaging requirements. Orphan deletion remains reviewed and manual. Python/UI plus schema and data migrations. Upgrades from any pre-2.6 release must run Publish Bundled Queries once with overwrite enabled before validation.
`v2.5.11`	`4.6.4` required; needs netbox-branching `1.1.0` - `1.1.x`	Superseded by `v2.6.0`; Fix: post-2.5.10 DLM and scope convergence - optional DLM maps seed when `netbox-dlm` migrates after Forward NetBox; runtime arguments are projected onto each NQE signature, including preflight; CVEs retain valid metadata when an optional advisory URL is malformed; observed vulnerabilities populate affected software; and platforms receive a manufacturer only when ownership is unambiguous. Fix: endpoint and CIMC identity - generic SNMP endpoints remain off unless explicitly enabled, imported console endpoints inherit their matched include tags, CIMCs are excluded from standalone devices and can map to exact-parent inventory through a disabled opt-in map, and legacy Opengear/Avocent software-bearing DeviceTypes are reported for reviewed cleanup. Fix: upgrade and drift evidence - Scope Reconciliation and support evidence classify stale catalog records, while dependency previews report workload upper bounds as not-measured drift. After upgrading, run Publish Bundled Queries once with overwrite enabled. Python and NQE; no migration.
`v2.5.10`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.11`; Fix: DLM CVE/Vulnerability execution - remove unsupported `@primaryKey` annotations stacked with parameterized `@query` declarations; Forward rejected both published queries before reading CVE data. After upgrading, run Publish Bundled Queries once with overwrite enabled. These parameterized maps require the default Allow full fallback mode; Forward's diff endpoint rejects them without a primary-key annotation, and this runtime cannot combine that annotation with `@query`. Fix: DLM installed-software associations - device-scoped software rows now carry lifecycle dates and create the SoftwareVersion plus DeviceSoftware link together; the standalone catalog map can only enrich an associated version, so versions from Forward-only devices no longer appear with zero devices. Vulnerability imports ensure the same association. Fix: SNMP endpoint safety and identity - imported endpoints use the same scope rules during reconciliation; endpoint tag intersections feed NetBox scope tags; legacy sources with include tags fail closed to endpoint include scope until they explicitly save an opt-out; new sources default it on. Avocent and Opengear endpoints use stable hardware DeviceTypes and Console Server roles instead of software-bearing sysDescr strings. Endpoint probe failures abort reconciliation, and the UI/audit payload report endpoint counts. Fix: architecture contract gate - `invoke architecture-audit-check` now runs focused model, fetch, and query contract tests instead of calling a management command removed in 2.0. Fix: drift report semantics - dependency-preview workload estimates are labeled as apply work, not exact drift, so candidate rows and deletes are no longer double-counted or reported as mostly drift. Fix: CIMC identity - CIMC SNMP endpoints are excluded from standalone device import while the APIC CIMC inventory map remains authoritative. Fix: release smoke validation - restore the removed `forward_smoke_sync` command on the current single-branch backend with automatic existing-source selection and redacted evidence. Security: require `pyzipper` 0.4.0+, which removes plaintext-revealing CRC32 values from small AES-encrypted support-bundle entry headers (`PYSEC-2026-3044`). Python and NQE; no migration.
`v2.5.9`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.10`; Fix: DLM/query reliability - Health now detects enabled optional maps whose models are not selected, base/alias hardware-notice mismatches, and missing DLM dependency readiness; dependency-related skips are rolled up into actionable ingestion issues. Fix: live query-path publishing - Publish Bundled Queries now updates the Forward Org Repository, clears stale direct query IDs, preserves explicit commit pins, and binds matching enabled maps to paths that resolve current head at each sync; the separate Refresh Query IDs action is removed. After upgrading, run Publish Bundled Queries once for each org-backed sync. Python-only; no migration and no bundled NQE source change.
`v2.5.8`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.9`; Feature: device CVE tab — with netbox-dlm installed and the Vulnerability feed enabled, each device with findings gets a CVEs tab (severity totals + one row per CVE: id, severity, affected software version, description); registered only when netbox-dlm is present, hidden when a device has no findings (live-verified against netbox-dlm 0.2.0). Feature: `forward_routing_dangling_audit` read-only command reports netbox-routing BGP rows whose device references dangle (the post-prune sweep only covers plugin-pruned devices). Feature: stability + scale hardening (all opt-in or default-identical, no query change) — (1) `forward_stuck_job_recover` command recovers a sync wedged by a dead worker (idempotent merge requeue, bounded retries, or clean fail so schedules resume); (2) opt-in per-workload wall-clock fetch budget (`workload_fetch_timeout_seconds`) + circuit breaker so a slow shard can't silently hang a multi-hour sync; (3) opt-in shard-key bucket-packing (`enable_branch_budget_split`) splits an oversized unsharded model into co-located branch plan items, with an always-on warning when a workload exceeds budget; (4) bulk-apply per-row isolation (tree-model + virtual-chassis) so one bad row no longer rolls back a whole model batch, all unbounded `__in` lookups chunked, and event-queue hygiene so a failed isolated row's change events don't leak. Fix: REST `PATCH` of the standing-schedule intent keys now reconciles immediately; transactional schedule persist; a latent per-item stats-reset bug in the branch executor. Python-only; no NQE query change.
`v2.5.7`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.8`; Feature: standing schedules land in the UI — the sync form's new Standing Schedules section sets recurring validation / dependency-preview intervals (blank disables), the sync detail page shows each schedule and its next run, and the intent is stored on the sync so schedules self-heal: recreated at the end of every sync run after a hard-killed worker, re-checked by every occurrence (a cancelled or re-configured chain stops or re-aligns itself — no more zombie or duplicate schedules from mid-run changes), and schedules created on 2.5.6 are adopted automatically. Cancel from the form (blank the field) or `POST {"interval": 0}`. Fix: cron-friendly responses — an already-active equivalent job now answers `202 {"status": "already_running"}` instead of `409` (idempotent for retry-blind schedulers, matching the webhook), prune during a sync run answers a distinct `202 {"status": "blocked_by_sync_run"}` (that prune did NOT run), idempotent schedule re-posts answer `200`, and schedule bodies on non-schedulable actions are rejected. Fix: recurring validation now trims its own history (newest 100 runs per sync; `PLUGINS_CONFIG["forward_netbox"]["validation_run_retention"]`, 0 disables). Fix: prune's `pruned_dangling_rows` tally and the 60-minute preview floor are enforced on raw parameter writes too. Python-only; no query change.
`v2.5.6`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.7`; Feature: operator-job automation — the four operator buttons (dependency preview, prune orphans, tag delete-eligible IPAM, create module bays) are now REST actions (`POST /api/plugins/forward/sync//dependency-preview
`v2.5.5`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.6`; Feature: push-triggered sync (webhooks) — trigger a sync from an external webhook (e.g. Forward firing on snapshot processed). Preferred path is the NetBox-native token-authenticated `POST /api/plugins/forward/sync/<id>/sync/`; for senders that cannot set an `Authorization` header, a new `POST .../sync/<id>/webhook/` endpoint authenticates with a per-sync Webhook secret (sync form, empty = disabled; `X-Forward-Webhook-Secret` header or `?secret=` fallback), is opaque on failure, and acknowledges an already-running sync without re-queueing so retries stay idempotent. Fix: prune orphans no longer fails on protected plugin references — with netbox-routing (or another optional plugin) in play, deleting out-of-scope devices hit `ProtectedError` (e.g. BGP peers whose peer/source IPs live on a pruned device's interfaces) and the single-transaction prune rolled back everything. The prune now sweeps the exact PROTECT-ing rows Django reports (children first, per the delete dependency order, plugin-agnostic) and retries, uses one transaction per batch so one stuck batch can't void the rest, and reports what it swept as `pruned_dependent_rows` in the job data and the reconciliation audit. A blocker owned by an in-scope neighbor (its peer FK targets a pruned device's IP) is swept too — the next sync recreates it from Forward. Python-only; no query change.
`v2.5.4`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.5`; Fix: tag-scoped SNMP endpoint + missing-interfaces clarity — (1) new opt-in Scope SNMP Endpoints by Include Tags source toggle: imported endpoints must also carry the device include tags ("all"/"any" per the include match; default off preserves the 2.4.4 import-all-endpoints behavior; exclude tags always apply). Query change; Publish Bundled Queries + Refresh Query IDs after upgrading. (2) A tag scope matching 0 collected devices while endpoints still import now logs an explicit warning — that state made devices appear while interfaces/IP addresses stayed empty (they require collected devices in scope; check the snapshot selector, e.g. `latestCollected`). (3) Duplicate device names across sites no longer fail the apply workload with `MultipleObjectsReturned` — the by-name lookup resolves deterministically to the earliest device and warns.
`v2.5.3`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.4`; Editions — `forward-netbox` is now one package with two install profiles: core (`pip install forward-netbox`, NetBox-builtin models only, no optional-plugin dependencies) and integrations (`pip install forward-netbox[integrations]`, or per-plugin `[dlm]`/`[routing]`/`[aci]`/`[peering]`) which install the opt-in netbox-dlm / netbox-routing / netbox-cisco-aci / netbox-peering-manager maps (still disabled until the plugin is installed and enabled). Fix: enabling the netbox-routing models no longer crashes the sync with `TypeError: '<' not supported between instances of 'NoneType' and 'int'` — the BGP/OSPF dependency-lookup cache sorted scope keys whose global-table VRF pk is `None` against a VRF peer on the same router/device; the sort is now None-safe. Fix: Drift Report clarity — the report replays a cached dependency-preview, so a stale or empty-baseline preview could read as real drift (field report: 18/19 models showing 100% pending). Now (1) an empty-baseline hint when every model shows all Forward rows pending with zero removals (the "preview ran before data was ingested/merged" signature — it is everything Forward has, not real mismatches), (2) the staleness banner also fires when the preview is over a day old (not only when a newer sync ran since), and (3) a Preview Dependencies button on the report to recompute on the spot. Fix: DLM hardware-notice skips — operators running the alias-aware device query saw netbox-dlm hardware notices skipped (`device type ... is not in NetBox yet`) because the notice looked up the raw Forward model while the aliased device query created the DeviceType under its NetBox-library name; a new opt-in Forward DLM Hardware Notices with NetBox Aliases map applies the same alias mapping (live-verified: the 24 device types that skipped now resolve). If you run the aliased device query, enable that variant instead of the base one and Publish Bundled Queries after upgrading. The editions/routing/drift changes are Python only; the hardware-notice variant is the only query change.
`v2.5.2`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.3`; Feature: optional netbox-dlm CVE + Vulnerability feed — two new opt-in NQE maps import Forward's security analysis into the netbox-dlm plugin: the CVE catalog (`network.cveDatabase.cves`, worst-case per-vendor severity mapped to the plugin's severity choices) and per-device vulnerabilities (`device.cveFindings`, one row per device↔CVE). Disabled by default; requires the netbox-dlm plugin (0.2.0+ ships migrations — run `migrate`; 0.1.0 needs `makemigrations netbox_dlm` first). The Vulnerability map is large (~16 rows/device) — enable it scoped or on a fresh branch first. Fix: SNMP endpoint platform unification — Avocent/Cyclades/AlterPath (enterprise OIDs `10418` + `2925` plus product-name signatures) now resolve to a single `Avocent` platform instead of fragmenting across `Avocent`/`AlterPath`/`SNMP`; a multiline `sysDescr` is whitespace-collapsed so it can't leak a junk platform name, and a missing `sysDescr` falls back to `Unknown` rather than a fake `SNMP` vendor. Query-only endpoint change; Publish Bundled Queries after upgrading.
`v2.5.1`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.2`; Fix: rows with a blank `device_type` were rejected with `model: This field cannot be blank` — a device with no resolved model (`device.platform.model` null) and, more commonly, an SNMP endpoint reporting an empty `sysDescr`. The bundled queries now guard both (null-safe/empty-safe fallbacks to `Unknown` / `SNMP Endpoint`) instead of dropping the row (live-verified: 0 blank device types across 5645 rows). Query-only change; Publish Bundled Queries after upgrading.
`v2.5.0`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.1`; Feature: optional netbox-dlm (Device Lifecycle Management) integration — three new opt-in NQE maps sync Forward's end-of-life analysis into the netbox-dlm plugin: OS software versions with vendor EOL dates per (platform, version), hardware end-of-life notices per device type (Cisco/Palo Alto/Fortinet part support), and each device's running software version. Disabled by default; requires the netbox-dlm plugin (run `makemigrations netbox_dlm && migrate` after installing it — it ships no migrations). Fix: syncs no longer crash mid-provision when an installed plugin's migrations were never applied (`relation ... does not exist`) — a preflight now fails in seconds with the app name and remedy, and a new Database tables Health check surfaces the gap before you sync.
`v2.4.5`	`4.6.4` required; needs netbox-branching `1.1.0` – `1.1.x`	Superseded by `v2.5.0`; Fix: sync no longer crashes on netbox-branching 1.1.1 (`SquashMergeStrategy has no attribute '_split_bidirectional_cycles'` — 1.1.1 removed that internal helper; the bidirectional-cycle split is now built into the plugin and the dependency is bounded to `<1.2`). Also fixes SNMP-endpoint rows failing validation: the bundled endpoint query branches now clamp sysDescr-derived `device_type` to NetBox's 100-char limit (`substring`) and guard empty slugs — the fix lives in the NQE queries (the source of truth), so Publish Bundled Queries again after upgrading (fixes the `Ensure this value has at most 100 characters` rejects and the `At least one coalesce lookup must be provided` error).
`v2.4.4`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.5`; Fix: SNMP-endpoint import now works on tag-scoped syncs — the device-tag include scope silently excluded every endpoint, both query-side and in the plugin's local scope filter (whose scoped-device set was built from modeled devices only, so endpoint rows were always dropped; with prune enabled they would even be deleted). Endpoint import now ignores the include scope (exclude tags still apply) and endpoint names join the scoped set (validated live: 355 Avocent endpoints import under a tag-scoped sync). Also fixes the merge-phase `Tag with this Name already exists` issues: a same-named/same-slug tag already on main is now treated as merged instead of failing the branch's tag create.
`v2.4.3`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.4`; Fix: the pinned-query opt-in Health warning (2.4.1) over-claimed failure — it reads "nothing new syncs" and fires on any pinned map with the feature on, even after the query is fixed, because the Health page can't read a pinned query's contents. Reworded to a "Pinned — can't verify locally" heads-up that points at Export Live Query Drift to confirm (`source_matches_bundled`), instead of asserting failure. No behavior change.
`v2.4.2`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.3`; Fix: endpoint import (`sync_endpoints`) and device-tag sync (`sync_device_tags`) now work with the alias-aware and rules-aware query variants (`forward_devices_with_netbox_aliases`, `forward_device_feature_tags_with_rules`), not just the base queries — operators running the variants saw the toggles silently do nothing (validated live: 355 Avocent endpoints import; `Mgmt_` tags sync). Adds a Publish Bundled Queries* button on the sync Health page (beside Refresh Query IDs) and two Health warnings: when an opt-in feature is enabled but no enabled map provides it, and when a base query and its opt-in variant are both enabled (they double-apply rows for the same model and churn — enable one). The alias-aware device query now emits the clean role name (e.g. `ROUTER`) to match the base query — expect a one-time role update on alias-mapped devices.
`v2.4.1`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.2`; Fix: opt-in features (SNMP endpoint import, device-tag sync) silently did nothing on sources that run org-managed pinned Forward query IDs predating the feature — the sync Health page now raises an actionable warning instead of a silent badge. Remediation: publish the bundled queries to your Forward org folder (Overwrite on), then use Refresh Query IDs, then re-sync.
`v2.4.0`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.1`; Fix: the "Import SNMP Endpoints as Devices" toggle now renders on the source form (the field shipped in 2.3.2 but was not in any fieldset, so it never showed), letting operators enable endpoint import from the GUI.
`v2.3.2`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.4.0`; Feature: optional import of Forward SNMP endpoints (e.g. Avocent console servers) as NetBox devices — off by default (`sync_endpoints`), enabled per source and scoped by the same device tags.
`v2.3.1`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.3.2`;
`v2.3.0`	`4.6.4` required; needs netbox-branching `1.1.0+`	Superseded by `v2.3.1`; 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
`v2.2.0`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.2.1`; Fix devices mis-assigned the ACI platform; link Palo vsys / Fortinet vdom firewalls to their physical chassis
`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.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`.
`v2.0.8`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.1.0`; Bugfix: progress bars now reach 100% on a completed sync. For relationship and two-phase models (cable+termination, device+primary_ip, module+moduletype, fhrp group+assignment) the per-model bar settled below 100% because the merge `total` counts ChangeDiff rows while `current` counts applied objects; a finished job now renders every model at 100%. Cosmetic only — no apply/merge/data change. Drop-in from `2.0.7`
`v2.0.7`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.8`; Bugfixes + diagnostics: (1) a MAC whose target interface was not imported is now a benign aggregated skip like the IP path (with the canonical-name fallback), not a red `ForwardSearchError` failure; (2) the two benign IP diagnostics (filtered-unassignable, no-parent-prefix) collapse to one summary line each instead of a 20-row wall; (3) when a `require_diff` sync is blocked by a failed diff fetch, the block now names that cause and the `Allow full fallback` remedy. Drop-in from `2.0.6`
`v2.0.6`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.7`; Bugfix: stop the pernicious FHRP-group sync churn. When a virtual IP is shared by two HSRP/VRRP groups (different group_id), the second group was created then immediately deleted every sync (VIP-conflict), so a fixed set of FHRP groups was added and removed on every run. The second group now persists with its interface assignment (the VIP stays attached to the first group; NetBox allows a VIP on only one group), and deleting a shared-VIP group no longer removes the other group's VIP. Drop-in from `2.0.5`
`v2.0.5`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.6`; Branding + polish: the plugin is now presented as Forward Field Integration (NetBox plugin name, sidebar menu, docs/site titles). Adds a theme-aware Forward Networks logo + `#ff3506` accent bar at the top of the Source/Sync/Ingestion pages. Display-only: package `forward_netbox`, the `forward` URL prefix, NQE query names, and all APIs are unchanged. Drop-in from `2.0.4`
`v2.0.4`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.5`; Patch: collapse the module-sync readiness warning wall into ONE summary. When module sync is enabled before a device's module bays exist in NetBox, every module row is skipped; 2.0.3 capped the per-row lines at 3, this replaces them entirely with a single actionable line per sync (total skipped + a few examples + the `forward_module_readiness` remedy). Other skip reasons are unchanged. No engine/schema/org changes; drop-in from `2.0.3`
`v2.0.3`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.4`; Patch: (1) module-sync readiness warnings no longer flood the log — the per-row `module bay does not exist; run forward_module_readiness` skip is capped to a few examples plus a suppressed-count summary (was up to 20 near-identical lines per sync); (2) fixes the release `CI` gate (`CHANGELOG matches README`) that had been red since v1.7.2 — the generator no longer depends on git tag-date timing; (3) removes dead executor code (`ForwardFastBootstrapExecutor.run`) and refreshes stale internal docs. No engine/schema changes; drop-in from `2.0.2`
`v2.0.2`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.3`; Patch: apply_device_scope_tags now works with multiple include tags in `any` match mode — each device is tagged with exactly the include tag(s) it carries (resolved per-device at fetch time), instead of skipping. Also silences the spurious `Skipping untagged VLAN 1` warning (VID 1 is NetBox's implicit access default and is intentionally not imported). No engine/schema changes; drop-in from `2.0.1`, no org republish
`v2.0.1`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.2`; Patch: fixes two 2.0.0 regressions an operator hits immediately — a false `netbox_branching is not installed; syncs will fail` startup warning (the dependency check used the wrong distribution name), and a 500 on the Sync list page (`KeyError: 'available'` from a removed execution-ledger summary). No engine or data changes; drop-in upgrade from `2.0.0`
`v2.0.0`	`4.6.3` required; needs netbox-branching `1.1.0+`	Superseded by `v2.0.1`; Breaking 2.0 — single-branch is the only execution path. Removed the per-shard branching/fast-bootstrap/resumable executor, 10k-change budget sharding, and the execution-ledger run-history; dropped the backend/max-changes/scheduler-overlap selectors
`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.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.
`v1.5.10`	`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.0`; promotes `ipam.prefix` into the default bulk-ORM safe set (the last model still on the adapter path) — it runs the per-object tree apply so NetBox prefix hierarchy `_depth` stays correct, with null-VRF (global) prefix identity and canonical-CIDR matching parity-tested against the adapter.
`v1.5.9`	`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.5.10`; adds a maintained `forward-backfilled` NetBox tag so operators can see which in-scope devices were backfilled (not freshly collected) in the latest snapshot — a Tag backfilled devices button on the Scope Reconciliation page plus a link to the filtered device list (`?tag=forward-backfilled`); the tag self-heals as devices collect again.
`v1.5.8`	`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.5.9`; `dcim.module` sync now adopts the device interfaces Forward already syncs instead of recreating them (fixes `dcim_interface_unique_device_name` IntegrityError when modules are enabled), and `ipam.fhrpgroup` no longer churns (delete+recreate the same HSRP groups every sync) — the snapshot diff no longer deletes a group it is simultaneously upserting. Preview Dependencies now runs as a background job (cached result on the preview page), fixing a 504 timeout on large fabrics.
`v1.5.7`	`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.5.8`; Prune orphans and Create missing module bays now run as background jobs (watch the Jobs tab) instead of synchronously, fixing a 504 gateway timeout on large fabrics. Module Readiness `Ready` reflects missing bays only (out-of-scope-device rows no longer hold it `No`), and the bulk `ipam.ipaddress` path tolerates duplicate global IPs.
`v1.5.6`	`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.5.7`; fixes an `ipam.ipaddress` sync failure (`Ambiguous coalesce lookup`) when a reused /30 link range leaves duplicate global (VRF-less) IPs for the same host — the adapter now resolves to one deterministically (preferring the copy already on the synced interface) and warns, instead of failing the row.
`v1.5.5`	`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.5.6`; surfaces the orphan-prune and module-bay readiness workflows in the sync detail UI (no CLI or CSV): a Scope Reconciliation page with a Prune orphans button, and a Module Readiness page with a Create missing module bays button that creates the bays directly in NetBox.
`v1.5.4`	`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.5.5`; adds `--prune-orphans`/`--apply` to `forward_device_scope_reconciliation_audit` to delete stale out-of-scope (orphan) NetBox devices left by an earlier broader sync that `device_tag_prune_out_of_scope` cannot reach (orphans are absent from the scoped Forward result). Dry-run by default; tagged-but-backfilled devices are preserved.
`v1.5.3`	`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.5.4`; classifies APIC controllers onto the `APIC` platform (distinct from ACI switches) so controller and switch software versions model separately; splits IP address import into independent `Forward IPv4 IP Addresses` and `Forward IPv6 IP Addresses` maps (a migration removes the combined map) so address families toggle independently; promotes `dcim.interface` and `ipam.ipaddress` into the default bulk-ORM safe set and removes bulk-apply update churn across every bulk model so steady-state syncs issue no redundant writes; preserves operator platform-manufacturer overrides on bulk update; and adds the opt-in `Apply Device Scope Tags` source option plus the `forward_device_scope_reconciliation_audit` and `forward_apic_cimc_readiness_audit` commands.
`v1.5.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.5.3`; collapses the flood of `dcim.modulebay` branch-merge failures (a NetBox Branching/MPTT limitation when a new device's module bays are auto-instantiated in a branch) into a single actionable `ModuleBayMergeUnsupported` ingestion issue that points at the `forward_module_readiness` import workflow. Device and interface sync are unaffected.
`v1.5.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.5.2`; adds the `latestCollected` snapshot selector that skips backfilled (collection-canceled) snapshots and resolves to the most recent snapshot with a freshly-collected in-scope device, warns when a `latestProcessed` run finds every in-scope device backfilled instead of silently applying zero changes, records the resolved snapshot's own metadata for `latestCollected` runs, and adds an Architecture Flow reference doc.
`v1.5.0.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.5.1`; fixes platform NQE query using `normalizePlatformName` to avoid evaluation failures on unsupported vendor/OS combinations, adds `--overwrite` flag to the validation-org repair command, and hardens the NQE org-publish commit loop to retry after 409 INVALID_CHANGE_PATH.
`v1.5.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.5.0.1`; hardens ingest throughput via adaptive async-NQE poll backoff, ndjson streaming, webhook/event-rule signal suppression during the apply loop, targeted validation (skips DB-hitting uniqueness checks on existing objects in both simple and tree-model bulk paths), and async advanced-reachability trigger (FWD-53559). Full test suite green on NetBox 4.5.9 (1092/0/0) and 4.6.2 (1092/0/26 routing-plugin version-gated).
`v1.4.3`	`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.5.0`; hardens query-path provenance by requiring source-backed query-id repair at preflight, enforces async NQE source parsing for 26.6 execution paths, proves CIMC/APIC custom-command updates in source and keeps the 1.4 production-hardening line intact.
`v1.4.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.4.3`; adds CIMC platform separation, visible query-drift repair and dependency preview on the sync detail page, and keeps the module-bay merge hardening plus parent-interface description preservation from the prior patch line.
`v1.4.1.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.4.2`; prevents optional `dcim.module` sync from emitting merge-breaking `dcim.modulebay` side-effect creates when module bays are missing and prevents LAG member rows from clearing existing parent interface descriptions.
`v1.4.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.4.2`; keeps the hard parent-device sync contract, adds query-ID drift remediation plus support-bundle diagnostics, and carries the 1.4 production-hardening tranche forward as the release line.
`v1.4.0`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.4.1`; enforces a hard parent-device sync contract so child models cannot run without `dcim.device`, which prevents stale sync configs from skipping the device shard and breaking dependent imports.
`v1.3.5.5`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.6`; adds compressed support-bundle ZIP downloads with optional password protection, and folds live source health, live query-drift, and live data-file diagnostics into the troubleshooting bundle so operator support can work from one artifact.
`v1.3.5.4`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5.5`; repackaged the `1.3.5.3` query-contract hardening on a fresh patch tag and kept strict shipped-query parameter-contract validation, legacy tag alias stripping, and summary-only support-bundle previews.
`v1.3.5.3`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5.4`; keeps the `1.3.5.2` claimed-step and payload compaction behavior, adds strict shipped-query parameter-contract validation, strips legacy tag aliases from runtime NQE payloads, and keeps support-bundle previews summary-only.
`v1.3.5.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5.2`; removes raw `model_results` from the sync telemetry summary and prevents unparameterized query IDs from receiving source-level tag parameters, which keeps the sync detail view responsive and preserves the saved-query-ID path compatibility.
`v1.3.5`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5.2`; keeps the 1.3.x saved-query-ID path parameter-compatible, tightens ACI platform detection with command-inventory signals, and preserves the lower-noise execution accounting used by the 1.3.x sync path
`v1.3.4`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5`; makes non-retryable Branching merge failures visible in job logs, leaves failed merge branches in a terminal `Failed` state instead of stale `Merging`, and carries disabled async NQE client staging for future Forward 26.6 support
`v1.3.3`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.5.2`; refreshes bundled NQE syntax for saved query-ID execution, keeps all shipped maps parameter-compatible with `forward_netbox_shard_keys`, and updates the saved validation-folder query IDs used by the 1.3.x sync path
`v1.3.2`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.3`; adds optional `netbox-cisco-aci` integration maps and adapter support, keeps ACI maps disabled by default, preserves parameterized NQE execution, and validates repeat-sync idempotence for the proven ACI write path
`v1.3.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.2`; preserves the `v1.3.0` parameterized NQE path, removes the legacy sync column-filter shard path, and fixes repeat prefix sync accounting so unchanged `ipam.prefix` rows report as unchanged instead of update churn
`v1.3.0`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.1`; eliminates default Forward NQE column-filter shard fetches in favor of query-side `forward_netbox_shard_keys` parameters, keeps local shard safety filtering, and preserves branch boundaries while reducing Forward SaaS API/NQE pressure
`v1.2.3`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.3.0`; further reduced Forward SaaS API/NQE pressure by coalescing compatible sibling shard EQUALS_ANY filters, added local change-explainability summaries, and kept staged branch boundaries unchanged
`v1.2.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.2.2`; fixes prefix VRF churn by making `ipam.prefix` identity exact for global and VRF-scoped rows while preserving parameterized prefix shard NQE execution
`v1.2.0`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.2.1`; adds optional NetBox-native HSRP/VRRP FHRP import, bounded access/native interface VLAN assignment from existing site-scoped VLANs, upgrade-safe FHRP VIP conflict handling, and NetBox 4.6 job-test compatibility hardening while preserving the 1.1 API/NQE limits
`v1.1.1`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.2.0`; adds optional NetBox-native HSRP/FHRP import, upgrade-safe FHRP VIP conflict handling, and NetBox 4.6 job-test compatibility hardening while preserving the 1.1 API/NQE limits
`v1.1.0`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.1.1`; reduces Forward SaaS API/NQE pressure with source-level API pacing, parameterized prefix shard queries, single-pass interface NQE, and release-validation smoke evidence
`v1.0.0`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.1.0`; first 1.x release line with API/NQE stability groundwork but without 1.1 API pacing and scale-optimized query improvements
`v0.9.4.6`	`4.5.9` and `4.6.1` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v1.1.0`; tightens delete-heavy device cleanup shard planning after live evidence showed device deletes still exceeded native Branching change-budget guidance
`v0.9.4.5`	`4.5.9` and `4.6.0` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v0.9.4.6`; plans delete-heavy device cleanup shards more conservatively so tag-scope prune runs stay closer to native Branching change-budget guidance
`v0.9.4.4`	`4.5.9` and `4.6.0` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v0.9.4.5`; clarifies large branching progress by clamping progress-bar display and surfacing current shard row progress in the ingestion UI
`v0.9.4.3`	`4.5.9` and `4.6.0` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v0.9.4.4`; hardens delete behavior by converting protected-reference delete failures into dependency skips so tag-scope prune/device cleanup runs continue safely
`v0.9.4.1.1`	`4.5.9` and `4.6.0` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v0.9.4.3`; keeps the shared-branch architecture, execution ledger, support logging, and scale hardening while preserving the read-only advisory surfaces from `v0.9.0`
`v0.9.0`	`4.5.9` and `4.6.0` validated; shared branch for `4.5.x` and `4.6.x` with capability-gated 4.6 features	Superseded by `v0.9.4.1.1`; adds read-only analysis, workload preview, advisory summaries, and native log export for troubleshooting
`v0.8.6.3`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.9.4.1.1`; hardens beta routing scope resolution, invalid ASN filtering, conservative virtual chassis skips, and fast-bootstrap baseline readiness when only optional model issues remain
`v0.8.6.2`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.6.3`; hardens issue and job-log rendering so unexpected nested payload objects stay JSON-safe in the UI and API
`v0.8.6.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.6.2`; clarifies the native NQE map bulk edit workflow so repository-path mode and runtime query-ID resolution are explicit in the UI
`v0.8.6`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.6.1`; refreshes org-repository query publishing with flattened built-ins, filters invalid IPv4 prefix artifacts, adds parent-prefix diagnostics, and hardens virtual chassis/device and routing issue handling
`v0.8.5`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.6`; makes the beta routing and module maps broadly available by default while keeping virtual chassis conservative, hardens repository query lookup responses, and clears stale row progress when a sync fails or advances phases
`v0.8.4`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.5`; stops importing Forward HA peers as NetBox virtual chassis by default, hardens repository query lookup responses, and clears stale row progress when a sync fails or advances phases
`v0.8.3`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.4`; isolates per-model query failures, blocks positionless virtual-chassis assignments before NetBox save, and lets later shards such as routing continue while withholding dirty diff baselines
`v0.8.2`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.3`; adds portable repository query-path execution with native NetBox selectors, publish-and-bind bulk edit, bidirectional restore, and fixes IP address rows whose Forward interface cannot be resolved
`v0.8.1.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.2`; fixes virtual chassis NQE output so NetBox receives a member position with virtual chassis assignments
`v0.8.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.1.1`; fixes fast-bootstrap native change tracking/statistics and adds timeout guidance plus transient Forward API HTTP retries
`v0.8.0`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.1`; adds an opt-in fast bootstrap backend for trusted large baselines while keeping Branching as default, and skips NetBox-invalid LAG cable endpoints
`v0.7.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.8.0`; keeps the NetBox-native multi-branch workflow, adds shard heartbeat visibility, and hardens large-shard retries and cable ingestion handling
`v0.7.0`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.7.1`; extracts the 0.7 sync boundaries and adds shard heartbeat visibility
`v0.6.5`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.7.0`; adds audited validation force-allow overrides and routing evidence enrichment; optional routing/peering import remains beta; native `dcim.module` import is beta
`v0.6.4`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.5`; optional routing/peering import is beta; native `dcim.module` import is beta
`v0.6.3`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.4`; native `dcim.module` import is beta
`v0.6.2`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.3`; native `dcim.module` import is beta
`v0.6.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.2`; native `dcim.module` import is beta
`v0.6.0`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.1`; native `dcim.module` import is beta
`v0.5.9.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.6.0`
`v0.5.9`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.5.9.1`
`v0.5.8`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.5.9`
`v0.5.7`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.5.8`
`v0.5.2.1`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.5.3`
`v0.4.0`	`4.5.9` validated; `4.5.x` only	Superseded by `v0.5.2.1`
`v0.3.1`	`4.5.8` validated; `4.5.x` only	Superseded by `v0.4.0`
`v0.3.0.1`	`4.5.8` validated; `4.5.x` only	Superseded by `v0.3.1`
`v0.3.0`	`4.5.8` validated; `4.5.x` only	Superseded by `v0.3.0.1`

Support

This is a field integration maintained by a Forward Networks SE — a reference integration, not an officially supported Forward Networks product, provided as-is with no SLA. Supported NetBox and netbox-branching versions are listed in the Release Compatibility table above; fixes target the latest released version.

Bugs / feature requests: open a GitHub issue using the provided templates.
Security vulnerabilities: report privately per SECURITY.md — do not open a public issue.
Upgrades: follow the Upgrade and Rollback guide; 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

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 repository query_path, direct Forward query_id, or raw NQE query text
Explicit identity contracts per map (coalesce_fields) with strict sync-time ambiguity detection
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
Optional disabled NQE maps for NetBox Device Type Library alias matching through a Forward JSON data file
Optional disabled NQE map for data-file-driven device feature tag rules
Supported BGP and OSPF maps for optional netbox-routing and netbox-peering-manager deployments
Supported device-lifecycle maps for the pinned optional netbox-dlm integration: OS/hardware end-of-life dates, per-device running software, CVEs, and device/software vulnerability associations from Forward's support analysis
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 through an explicit custom membership map
- device feature tags
- dcim.interface
- dcim.cable from exact Forward inferred interface matches
- dcim.macaddress
- dcim.inventoryitem
- supported dcim.module with branch-native module-bay creation
- optional BGP peers, BGP address families, OSPF objects, and peering sessions through supported external NetBox plugins
- ipam.vlan
- ipam.vrf
- ipam.prefix for IPv4 and IPv6
- ipam.ipaddress

Quickstart

Install the plugin into the same Python environment as NetBox. forward-netbox ships two profiles — core (NetBox-builtin models only) and integrations (adds the optional netbox-dlm / netbox-routing / netbox-cisco-aci / netbox-peering-manager maps). See Editions.

Install the latest release from PyPI:

pip install forward-netbox                # core
pip install forward-netbox[integrations]  # + optional plugin maps

Or install a specific wheel or source archive from GitHub Releases:

pip install /path/to/forward_netbox-2.6.0-py3-none-any.whl

Enable both plugins in the NetBox configuration:

PLUGINS = [
    "netbox_branching",
    "forward_netbox",
]

Apply migrations:

python manage.py migrate

Open NetBox and create a Forward Source.
Select a Forward network for that source.
Create a Forward Sync, choose the snapshot selector, and enable the NetBox models you want to sync.
Run an adhoc ingestion, review the staged branch diff, review the recorded snapshot details and metrics, and merge when the changes look correct.

For large datasets, prefer committed Forward Org Repository queries referenced by query_id, leave Snapshot at latestProcessed, and establish one clean baseline first. Every sync validates and stages its complete workload in one native NetBox Branching branch. Keep Max changes per staging item near local Branching guidance so the planner can partition work deterministically and warn about an indivisible oversized identity group, and set worker timeouts high enough for the complete stage and merge. After the clean baseline merges, later eligible latestProcessed runs can use Forward nqe-diffs while remaining reviewable.

The shipped query set includes both default maps and optional alias-aware maps. If your NetBox device types are pre-loaded from the NetBox Device Type Library, upload a Forward JSON data file named netbox_device_type_aliases.json with NQE name netbox_device_type_aliases, attach it to the Forward network, and run or reprocess a Forward snapshot before enabling the disabled alias-aware device maps or using committed query IDs for those variants. The NetBox plugin runs public /api/nqe against the selected snapshot, so latest uploaded data files do not affect plugin sync results until the selected snapshot exposes the data file value. The generated file carries both device type aliases and manufacturer override rows for the alias-aware maps. Without that data file in the selected snapshot, leave the default non-data-file maps enabled.

Test It Yourself

Use this quick validation flow after installation:

Create a Forward Source using https://fwd.app or your custom Forward URL.
Enter a Forward username and password, then confirm the Network field populates from the live Forward tenant.
Open NQE Maps and verify the built-in maps are present.
Create a Forward Sync tied to the source, leaving Snapshot at latestProcessed for the first run.
Run the sync from the sync detail page.
Review the generated Forward Ingestion, Issues, snapshot details, snapshot metrics, and change diff.
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, configure a Forward Source in NetBox and run the smoke task locally. The command selects the most recently used reachable source without copying its stored credential or printing its source, network, or snapshot identifiers:

invoke forward_netbox.smoke-sync --validate-only

Direct credential environment variables remain available only for bootstrapping a source in an approved environment. Prefer the stored-source path for routine validation.

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 --plan-only builds the single-branch workload plan without creating a branch
invoke forward_netbox.smoke-sync --max-changes-per-staging-item 10000 sets the workload planning budget
invoke forward_netbox.smoke-sync --no-auto-merge stages the one native branch and pauses for review
python manage.py forward_smoke_sync --check-source verifies stored-source selection and connectivity with redacted output

Normal UI/API sync jobs use one native Branching branch per sync. Auto merge controls whether that branch merges automatically or pauses for review.

Documentation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

forward_netbox-2.6.3.tar.gz (816.6 kB view details)

Uploaded Jul 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

forward_netbox-2.6.3-py3-none-any.whl (986.2 kB view details)

Uploaded Jul 28, 2026 Python 3

File details

Details for the file forward_netbox-2.6.3.tar.gz.

File metadata

Download URL: forward_netbox-2.6.3.tar.gz
Upload date: Jul 28, 2026
Size: 816.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for forward_netbox-2.6.3.tar.gz
Algorithm	Hash digest
SHA256	`507311af5705cfa669325029f7ef6acc62d342a6d7a106b018dcfefdec86c12a`
MD5	`fb9c7648d1bcf9ecc95602171927ead5`
BLAKE2b-256	`3a645f34567b61f9a00004a8f23f1c32d9882cac317235ad0a7c288264b35323`

See more details on using hashes here.

Provenance

The following attestation bundles were made for forward_netbox-2.6.3.tar.gz:

Publisher: release.yml on forwardnetworks/forward-netbox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: forward_netbox-2.6.3.tar.gz
- Subject digest: 507311af5705cfa669325029f7ef6acc62d342a6d7a106b018dcfefdec86c12a
- Sigstore transparency entry: 2271754487
- Sigstore integration time: Jul 28, 2026
Source repository:
- Permalink: forwardnetworks/forward-netbox@4b8dd5628a59de8f16d0b1d6ce910b07bc565706
- Branch / Tag: refs/tags/v2.6.3
- Owner: https://github.com/forwardnetworks
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@4b8dd5628a59de8f16d0b1d6ce910b07bc565706
- Trigger Event: push