forward-netbox 2.0.3

NetBox plugin to sync Forward data into NetBox via built-in NQE queries

Forward NetBox Plugin

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. Large trusted baselines can optionally use the fast bootstrap backend before returning to the normal Branching workflow.

Forward 26.6 is the baseline for async NQE.

Release Compatibility

Plugin Release	NetBox Version	Status
v2.0.3	4.6.3 required; needs netbox-branching 1.1.0+	Current release; 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.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.
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 while keeping lifecycle enrichment and predict deferred
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

Version History

Release	Summary
v1.5.0.1	Fixes platform NQE query (normalizePlatformName), adds --overwrite to validation-org repair, hardens org-publish commit to retry on 409 INVALID_CHANGE_PATH.
v1.5.0	Hardens ingest throughput: adaptive async-NQE poll backoff, ndjson streaming, webhook/event-rule signal suppression during apply, targeted validation on existing objects (skips DB-hitting uniqueness checks in both bulk engine paths), and async advanced-reachability trigger (FWD-53559). Full suite green on NetBox 4.5.9 and 4.6.2.
v1.4.3	Hardens query provenance with source-backed query-id repair during preflight, adds async execution path readiness for 26.6 with resilient NDJSON/JSONL result handling, and proves CIMC/APIC platform/type updates from command-source evidence while preserving prior 1.4 protections.
v1.4.2	Adds CIMC platform separation, visible query-drift repair and dependency preview on the sync detail page, and keeps module-bay merge hardening plus parent-interface description preservation.
v1.4.1.1	Prevents optional module sync from creating dcim.modulebay side-effect changes during merge, skips missing module bays with a readiness/import warning, and keeps LAG member rows from clearing existing parent interface descriptions.
v1.4.1	Publishes the 1.4 patch release line with query-ID drift remediation and support-bundle diagnostics on top of the parent-device contract and release surfaces.
v1.3.6	Enforces a hard parent-device sync contract so child models cannot run without dcim.device, preventing stale sync configs from skipping the device shard and breaking dependent imports.
v1.3.5.5	Adds compressed support-bundle ZIP downloads with optional password protection and folds live source/query-drift/data-file diagnostics into the troubleshooting bundle.
v1.3.5.4	Republishes the v1.3.5.3 query-contract hardening as the prior patch release.
v1.3.5.3	Preserves the claimed-step and payload-compaction protections from v1.3.5.2, 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.2	Prevents shard execution drift by tying resume/overlap workers to the claimed execution step and compacts sync execution payloads (plan_items, workload previews, and advisory branch summaries) so large runs remain user-visible but lightweight in UI/log exports.
v1.3.5.1	Removes the raw model_results payload from sync telemetry summaries and stops unparameterized query IDs from inheriting source-level tag parameters, which keeps sync-detail rendering responsive while preserving the saved-query-ID path.
v1.3.5	Tightens the saved-query-ID path for 1.3.x, keeps shipped maps parameter-compatible with forward_netbox_shard_keys, and uses command-inventory signals to avoid misclassifying ACI platforms during repeat syncs.
v1.3.4	Makes non-retryable Branching merge errors operator-visible by persisting the failure reason before the job terminates, marks branches still stuck in Merging as Failed, preserves timeout/transient retry behavior, and adds disabled-by-default async NQE client support for the future Forward 26.6 execution API.
v1.3.3	Refreshes shipped NQE syntax so saved query IDs accept the standard forward_netbox_shard_keys parameter payload, republishes the saved validation-folder query set, and validates the affected saved query IDs against a live Forward SaaS dataset.
v1.3.2	Adds optional netbox-cisco-aci plugin support with disabled-by-default ACI fabric, pod, node, tenant, VRF, and filter maps; keeps deeper ACI policy maps conservative until source identity is proven; and hardens duplicate ACI node observations so repeat syncs remain no-op when source data is unchanged.
v1.3.1	Fixes repeat prefix sync accounting by treating unchanged NetBox ipam.prefix rows as unchanged, avoids dependency VRF metadata rewrites from prefix/IP/FHRP imports, removes the legacy sync column-filter shard path, and preserves the v1.3.0 parameterized NQE path.
v1.3.0	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	Coalesces compatible sibling shard column-filter fetches into bounded EQUALS_ANY requests, caches prefetched sibling rows locally to avoid repeated Forward calls, and surfaces local Branching change-explainability summaries in support bundles and the ingestion UI.
v1.2.2	Adds operator-visible Forward API usage budgets/rate evidence in Sync Health and support bundles, extends repeat-sync no-op hardening across key adapters, and persists successful staged deletes into ingestion statistics so active delete shards are visible before merge accounting catches up.
v1.2.1	Fixes repeat prefix sync churn where otherwise unchanged ipam.prefix rows could be updated only because the VRF foreign key was re-resolved; built-in prefix maps now use exact prefix + vrf identity while prefix shard fetches still use parameterized NQE.
v1.2.0	Adds optional NetBox-native HSRP/VRRP FHRP import from Forward native FHRP state, bounded access/native interface VLAN assignment from existing site-scoped VLANs, keeps FHRP upgrade behavior safe for existing 1.1 IPAM data, and hardens current NetBox job-test compatibility.
v1.1.1	Adds optional NetBox-native HSRP/FHRP import from Forward native FHRP state, keeps FHRP upgrade behavior safe for existing 1.1 IPAM data, and hardens current NetBox job-test compatibility.
v1.1.0	Adds Forward SaaS API request pacing, parameterized prefix shard execution, single-pass interface NQE, configured max-shard persistence in smoke evidence, and release-validation gates for API/NQE scale validation.
v1.0.0	Introduced the first v1.0.0 release line and initial API/NQE release validation flow before the 1.1 runtime and request-pacing enhancements.
v0.9.4.6	Tightens delete-heavy dcim.device cleanup planning to about 500 planned delete rows per 10k branch-change budget after live shard evidence showed the earlier estimate was still too high.
v0.9.4.5	Plans delete-heavy dcim.device cleanup shards with a conservative row budget so tag-scope prune runs do not pack thousands of cascading device deletes into one Branching shard.
v0.9.4.4	Clarifies large branching progress by clamping utilization display to 100% during intermediate accounting overshoots and showing current shard row progress in the ingestion UI.
v0.9.4.3	Converts NetBox protected-reference delete failures into dependency skips so large tag-scope prune/device cleanup runs continue without shard-failing delete rows.
v0.9.4.1.1	Keeps the shared 4.5/4.6 branch line, execution ledger, support logging, and scale hardening while preserving the read-only advisory surfaces from v0.9.0.
v0.9.0	Adds read-only analysis, workload preview, advisory summaries, and native log export for troubleshooting while keeping lifecycle enrichment and predict deferred.
v0.8.6.3	Hardens beta routing scope resolution, filters invalid BGP ASN rows in shipped NQE, skips positionless virtual-chassis rows conservatively, and lets fast bootstrap retain its diff baseline when only optional model issues remain.
v0.8.6.2	Hardens issue and job-log rendering for JSON safety when unexpected nested payload objects leak into failure data.
v0.8.6.1	Clarifies NQE map bulk edit labels and help text so operators use repository query paths and understand query IDs are resolved automatically during sync and diff execution.
v0.8.6	Publishes flattened built-in NQE to Forward org repositories, filters IPv4 host/any/loopback prefix artifacts, reports IP rows missing imported parent prefixes on full baselines, and prevents stale virtual-chassis/device/routing row failures from blocking unrelated models.
v0.8.5	Makes the beta routing and module maps broadly available by default, preserves the conservative bundled virtual chassis map, handles Forward repository query lookups that return a queries list, and makes failed sync activity show the terminal failure instead of stale row heartbeat text.
v0.8.3	Isolates stale or invalid per-model query output, rejects virtual-chassis rows missing vc_position, records row issues without aborting later multi-branch shards, and prevents dirty runs from becoming diff baselines.
v0.8.2	Adds portable repository query_path execution with Forward-backed selectors, true native bulk edit for publishing bundled NQE into the Forward Org Repository, binding selected maps to repository paths, restoring bundled raw NQE, and clearer skipping for IP address rows whose interface cannot be resolved.
v0.8.1.1	Emits vc_position in the built-in virtual chassis NQE map for vPC and MLAG memberships so NetBox does not reject virtual chassis device assignments without a member position.
v0.8.1	Runs fast bootstrap inside native NetBox change tracking, shows branchless ingestion changes from ObjectChange rows, updates fast-bootstrap counters from real object changes, warns about undersized worker timeouts, and retries transient Forward API HTTP timeouts/gateway responses.
v0.8.0	Adds an opt-in fast bootstrap direct-write backend for trusted large baselines, keeps NQE validation and row adapters shared with Branching, and skips LAG cable endpoints that NetBox cannot cable directly.
v0.7.1	Keeps the NetBox-native multi-branch workflow stable while hardening cable ingestion, retry handling, and shard re-planning for large runs.
v0.7.0	Splits the remaining sync orchestration, reporting, and validation helpers into dedicated boundaries, adds shard heartbeat visibility, and preserves the NetBox-native branch workflow.
v0.6.5	Adds audited validation force-allow overrides and routing evidence enrichment while reducing skipped routing rows through conservative NQE-side identity inference.
v0.6.4	Adds beta optional routing and peering imports for netbox-routing and netbox-peering-manager, including BGP peers, BGP address families, OSPF objects, peering sessions, routing diagnostics, and query-ID-aware built-in map handling.
v0.6.3	Models Forward aggregate interfaces as native NetBox LAGs, attaches member interfaces through Interface.lag, and keeps the MTU value sourced from Forward's normalized interface field.
v0.6.2	Canonicalizes duplicate global-table IP address rows by host IP before import and records row-scoped apply/delete failures as ingestion issues without aborting the rest of the shard.
v0.6.1	Filters interface IP rows that NetBox cannot assign, such as subnet network IDs and IPv4 broadcasts, while reporting aggregate diagnostics for filtered addresses.
v0.6.0	Adds beta native dcim.module import for chassis modules and similar bay-aware hardware, improves inventory item normalization, and avoids duplicate generic inventory rows when beta module sync is enabled.
v0.5.9.1	Keeps job logs visible during execution by persisting plugin log entries into the native NetBox job log tab while preserving the full plugin ingestion log view.
v0.5.9	Balances query preflight and workload fetch with bounded parallelism, reducing long planning pauses on large datasets.
v0.5.8	Defers event flushing until commit so large prefix ingestions do not trip transaction state changes mid-run.
v0.5.5	Applies a consistent model conflict policy for cable sync rows: skip occupied-interface conflicts, aggregate warning spam, and keep non-conflict updates/creates unchanged.
v0.5.4	Persists ingestion change counters so list/detail values stay consistent after branch merge cleanup, matching merge summaries.
v0.5.3	Surfaces preflight activity and elapsed phase timing on sync detail, emits early phase logs before ingestion rows, and sets source status to Syncing while runs are active.
v0.5.2.1	Fixes plugin admin version display and ships inferred cable query parser compatibility update (no let declarations) while preserving synthetic endpoint filtering.
v0.4.0	Corrects built-in IPv4/IPv6 prefix NQE filters to exclude host routes (/32 and /128) from prefix import and validates the behavior against a live smoke dataset.
v0.3.1	Adds optional data-file-aware device type alias maps, a Device Type Library alias data-file builder, and documentation for the snapshot requirement while keeping the default no-data-file maps available.
v0.3.0.1	Fixes the validation-run list UI by removing unsupported edit actions from read-only validation records, and adds Playwright coverage for the validation-run list route.
v0.3.0	Adds the NetBox 4.5.8-validated harness architecture with first-class validation runs, drift policies, query-fetch boundaries, model-result reporting, and Playwright-covered UI workflow validation.
v0.2.4	Hardens native multi-branch resilience with adaptive shard splitting and retry on branch-budget overflow, plus model-density tracking to keep large initial syncs within NetBox branching guidance.
v0.2.3	Adds native sync preflight validation before full multi-branch planning so invalid model/query rows fail earlier in the UI/API run path.
v0.2.2	NQE-only correction release: filters zero-length prefixes, broadens interface coverage for IP assignment targets, and enforces inventory part_id length limits.
v0.2.1	Makes NetBox-native multi-branch execution the only UI/API sync path and exposes the branch budget in the sync form.
v0.2.0	Adds NetBox-native multi-branch baseline syncs for large datasets, uses NetBox outbound proxy routing for Forward API calls, and keeps branch event queues bounded during large imports.
v0.1.6.0	Adds explicit diff baselines, Forward nqe-diffs execution for eligible query_id maps, and updated large-dataset guidance for baseline versus incremental syncs.
v0.1.5.1	Patch release that validates and hardens null-VRF coalesce behavior and inventory-item serial bounds against the live dataset.
v0.1.5	Fixes null VRF coalesce handling, imports loopback interfaces for IP attachment, and hardens inventory-item identity fallbacks.
v0.1.4.2	CI/package patch release that applies repository formatting/import-order fixes and publishes a clean artifact line.
v0.1.4.1	Patch release that bounds built-in dcim.virtualchassis names/domains to NetBox field limits.
v0.1.4	Hardened built-in NQE mappings and docs for large real-world datasets.
v0.1.3	Enforced deterministic model identity contracts during sync ingestion.
v0.1.2	Improved ingestion safety, diagnostics, and compatibility with custom NetBox data.
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

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.

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
• Feature-flagged beta BGP and OSPF maps for optional netbox-routing and netbox-peering-manager deployments
• 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
  • device feature tags
  • dcim.interface
  • dcim.cable from exact Forward inferred interface matches
  • dcim.macaddress
  • dcim.inventoryitem
  • optional beta dcim.module
  • optional beta BGP peers, BGP address families, OSPF objects, and peering sessions through external NetBox plugins
  • ipam.vlan
  • ipam.vrf
  • ipam.prefix for IPv4 and IPv6
  • ipam.ipaddress

Quickstart

1. Install the plugin into the same Python environment as NetBox:

Install the wheel or source archive from GitHub Releases:

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

2. Enable both plugins in the NetBox configuration:

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

3. Apply migrations:

python manage.py migrate

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

For large datasets, prefer committed Forward Org Repository queries referenced by query_id, leave Snapshot at latestProcessed, and establish one clean baseline first. Use the default Branching backend when the initial changes should be reviewed in native NetBox Branching shards. Use Fast bootstrap only for trusted initial baselines where direct NetBox writes are acceptable; it keeps the same NQE, preflight, model validation, ingestion issue reporting, and native NetBox change tracking contracts but does not create review branches. After a fast-bootstrap baseline completes, switch the sync back to Branching so later latestProcessed runs can use Forward nqe-diffs and remain 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:

1. Create a Forward Source using https://fwd.app or your custom Forward URL.
2. Enter a Forward username and password, then confirm the Network field populates from the live Forward tenant.
3. Open NQE Maps and verify the built-in maps are present.
4. Create a Forward Sync tied to the source, leaving Snapshot at latestProcessed for the first run.
5. Run the sync from the sync detail page.
6. Review the generated Forward Ingestion, Issues, snapshot details, snapshot metrics, and change diff.
7. Merge the branch and confirm the synced objects appear in NetBox.

Local Validation

The repository now includes local validation tasks:

• invoke forward_netbox.lint
• invoke forward_netbox.check
• invoke forward_netbox.test
• invoke forward_netbox.docs
• invoke forward_netbox.package
• invoke forward_netbox.ci

For a live Forward smoke run outside CI, set these environment variables and run the smoke task locally:

export FORWARD_SMOKE_USERNAME='your-forward-username'
export FORWARD_SMOKE_PASSWORD='your-forward-password'
export FORWARD_SMOKE_NETWORK_ID='your-network-id'
invoke forward_netbox.smoke-sync

Optional smoke-sync variables:

• FORWARD_SMOKE_URL defaults to https://fwd.app
• FORWARD_SMOKE_SNAPSHOT_ID defaults to latestProcessed
• FORWARD_SMOKE_MODELS accepts a comma-separated subset such as dcim.site,dcim.device,dcim.interface
• invoke forward_netbox.smoke-sync --validate-only runs live snapshot/query validation without executing an ingestion
• invoke forward_netbox.smoke-sync --plan-only prints the native NetBox Branching shard plan without creating branches
• invoke forward_netbox.smoke-sync --max-changes-per-branch 10000 stages and merges large baselines in multiple native branches
• invoke forward_netbox.smoke-sync --no-auto-merge --max-changes-per-branch 10000 stages one shard and pauses for review
• invoke forward_netbox.smoke-sync --execution-backend fast_bootstrap runs the trusted direct-write baseline backend after validation

Normal UI/API sync jobs default to native multi-branch execution, with a default branch budget of 10000 changes. Auto merge controls whether Branching shards advance automatically or pause for review after each shard. For trusted large baselines, select the fast bootstrap execution backend and switch back to Branching for reviewable steady-state diffs. See the Initial Baseline Strategy for the decision table.

Documentation

• Documentation Home
• Installation
• Configuration
• Usage and Validation
• Troubleshooting
• Architecture Flow
• Built-In NQE Reference
• Device Type Alias Data File
• Model Mapping Matrix
• Shipped NQE Query Files
• License