Pr/inventory core

.devcontainer/config/codespaces-configuration.py

@@ -19,6 +19,8 @@
         "127.0.0.1",
         "*",
     ]
+    # Development environment — logging config values is an accepted tradeoff here.
+    # CodeQL alert for this is dismissed intentionally.
     print(f"🔗 Codespaces detected: {codespace_name}")
     print(f"🔒 CSRF Trusted Origins: {CSRF_TRUSTED_ORIGINS}")
     print(f"🌐 Allowed Hosts: {ALLOWED_HOSTS}")

.github/copilot-instructions.md

@@ -70,6 +70,29 @@
 - Navigation menu (`navigation.py`) has 3 groups: **Settings** (Plugin Settings, Interface Mappings), **Import** (LibreNMS Import), **Status Check** (Site & Location Sync, Device Status, VM Status). All items use `permissions=[PERM_VIEW_PLUGIN]`.
 - **Background job polling requires superuser** — non-superusers fall back to synchronous mode. See `background-jobs.instructions.md` for details.
 
+## CodeQL & Security Patterns
+
+### Clearing CodeQL `py/reflected-xss` false positives
+When a view builds an `HttpResponse` from Django-template-rendered HTML (decoded via `.content.decode()`), CodeQL traces `request → template-render → HttpResponse` as reflected XSS even though Django templates auto-escape all user values.
+
+**Correct fix:** use `format_html()` to compose the envelope and `mark_safe()` as a **trust assertion** on the inner HTML — CodeQL's Django taint model recognises this pattern and stops tracking the taint:
+
+```python
+from django.utils.html import format_html
+from django.utils.safestring import mark_safe
+
+modal_html = some_view.get(request, pk).content.decode("utf-8")
+oob = format_html('<div id="target" hx-swap-oob="innerHTML">{}</div>', mark_safe(modal_html))
+return HttpResponse(oob, content_type="text/html")
+```
+
+> **Important:** `mark_safe()` is a trust assertion, not a sanitizer — it tells Django "I guarantee this string is already safe HTML." Only use it when `modal_html` comes from a server-rendered Django view (whose templates auto-escape all user values). Never pass untrusted user input to `mark_safe()` — that would introduce real XSS.
+
+**Do NOT** use `# lgtm[py/reflected-xss]` — that is LGTM.com legacy syntax and is **not** honoured by GitHub's modern CodeQL Action.
+
+### URL converters
+Always use `<int:pk>` (not `<str:pk>`) for numeric IDs in URL patterns. Django's `<int:>` converter auto-validates and returns 404 for non-integer values, eliminating the URL-parameter taint source that CodeQL otherwise flags.
+
 ## When in Doubt
 - Check docs in `docs/development/` for structure, view inheritance, mixins, and template conventions before introducing new patterns.
 - Review the existing sync views (e.g., `views/sync/interfaces.py`) as reference implementations for data flow and caching patterns.

.github/instructions/testing.instructions.md

@@ -29,6 +29,8 @@ description: Testing patterns and conventions for the NetBox LibreNMS plugin
 - `librenms_api.py` → `test_librenms_api.py`, `test_librenms_api_helpers.py`
 - `import_utils/` package (`filters.py`, `device_operations.py`, `vm_operations.py`, `cache.py`, `permissions.py`, `virtual_chassis.py`), `import_validation_helpers.py`, `utils.py` → `test_import_utils.py`, `test_import_validation_helpers.py`, `test_utils.py`
 - `jobs.py`, `views/imports/list.py` → `test_background_jobs.py`
+- `import_utils/bulk_import.py` → `test_coverage_bulk_import.py`
+- Utility helpers (`utils.py` coverage tests) → `test_coverage_utils.py`
 - Permission mixins, API permissions, constants → `test_permissions.py`
 - VLAN API, mode detection, comparison, sync → `test_vlan_sync.py`
 - `VlanAssignmentMixin`, VLAN enrichment → `test_interface_vlan_sync.py`

.github/workflows/codeql.yml

@@ -0,0 +1,103 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "master", "develop" ]
+  pull_request:
+    branches: [ "master", "develop" ]
+  schedule:
+    - cron: '35 13 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

contrib/README.md

@@ -0,0 +1,31 @@
+# Contrib: Example Mapping Files
+
+This directory contains example YAML mapping files for bulk import into the
+NetBox LibreNMS Plugin. Each file can be imported via the plugin's bulk import
+feature in the NetBox UI.
+
+## How to Import
+
+1. Navigate to the mapping page (e.g., **LibreNMS → Device Type Mappings**)
+2. Click the **Import** button (upload icon) in the top right
+3. Select **YAML** format
+4. Paste the contents of the relevant YAML file
+5. Click **Submit**
+
+## Available Mappings
+
+| File | Description |
+|------|-------------|
+| `interface_type_mappings.yaml` | Maps LibreNMS interface types + speeds to NetBox interface types |
+| `device_type_mappings.yaml` | Maps LibreNMS hardware strings to NetBox device types |
+| `module_type_mappings.yaml` | Maps LibreNMS inventory model names to NetBox module types (incl. transceivers) |
+| `module_bay_mappings.yaml` | Maps LibreNMS inventory container names to NetBox module bay names |
+| `normalization_rules.yaml` | Regex-based string normalization applied before module type/bay lookups |
+| `inventory_ignore_rules.yaml` | Suppresses phantom ENTITY-MIB entries (e.g. Cisco IOS-XR IDPROM artefacts) |
+| `platform_mappings.yaml` | Maps LibreNMS platform strings to NetBox device platforms |
+
+## Customisation
+
+These files are **examples** — adjust values to match the device types, module
+types, and interface types defined in your NetBox instance.  The `netbox_*`
+fields must reference objects that already exist in your NetBox.

contrib/carrier_auto_install_rules.yaml

@@ -0,0 +1,31 @@
+# Carrier Auto-Install Rules
+#
+# Suggest a holder/carrier ModuleType to install when LibreNMS reports orphan
+# child modules (e.g. CPM cards, mezzanines, MDAs) that have no matching NetBox
+# bay because their parent carrier was never installed in NetBox.
+#
+# Import via: LibreNMS Plugin → Carrier Auto-Install Rules → Import
+#
+# Fields:
+#   manufacturer:                Optional manufacturer name (exact). Empty = any vendor.
+#   device_type_pattern:         Optional regex on device_type.model. Empty = any model.
+#   librenms_child_class:        Exact entPhysicalClass of the orphan child (e.g. cpmModule).
+#   librenms_child_name_pattern: Regex on entPhysicalName of the orphan child.
+#   netbox_bay_name_pattern:     Regex on candidate empty device-level bay name.
+#   carrier_module_type:         NetBox ModuleType model (slug-style model field) to install.
+#   description:                 Optional description.
+#
+# Patterns use Python re.fullmatch() — they must match the entire string.
+# When the chassis has at least one empty bay matching netbox_bay_name_pattern,
+# an "Install Carrier" button appears on the module sync page (suggest-only,
+# never auto-installed). Multiple matching empty bays produce one button each.
+
+# Nokia 7750 SR-s chassis (e.g. SR-7s, SR-14s) report CPM cards in slots A/B
+# but the physical CMA carrier that holds them is invisible to LibreNMS.
+- manufacturer: Nokia
+  device_type_pattern: '^7750 SR-.*$'
+  librenms_child_class: cpmModule
+  librenms_child_name_pattern: '^Slot [AB]$'
+  netbox_bay_name_pattern: '^CMA$'
+  carrier_module_type: CMA2-7s
+  description: Install CMA2-7s carrier when CPM cards are reported orphaned

contrib/device_type_mappings.yaml

@@ -0,0 +1,73 @@
+# Device Type Mappings
+#
+# Maps LibreNMS hardware strings to NetBox device types.
+# Import via: LibreNMS Plugin > Device Type Mappings > Import
+#
+# Fields:
+#   librenms_hardware    — Hardware string exactly as shown in LibreNMS
+#   netbox_device_type   — NetBox DeviceType (matched by model name or ID)
+#   description          — Optional note
+#
+# The librenms_hardware value is matched case-insensitively.
+# These mappings are checked BEFORE the built-in part_number/model fallback.
+
+# Juniper — LibreNMS reports verbose marketing names
+- librenms_hardware: "Juniper MX480 Internet Backbone Router"
+  netbox_device_type: "MX480"
+  description: "Juniper MX480 chassis"
+
+- librenms_hardware: "Juniper MX960 Internet Backbone Router"
+  netbox_device_type: "MX960"
+  description: "Juniper MX960 chassis"
+
+- librenms_hardware: "Juniper MX304 Edge Router"
+  netbox_device_type: "MX304"
+  description: "Juniper MX304 edge router"
+
+- librenms_hardware: "JNP10008 [PTX10008]"
+  netbox_device_type: "PTX10008"
+  description: "Juniper PTX10008 core router"
+
+- librenms_hardware: "JNP7100-32C [ACX7100-32C]"
+  netbox_device_type: "ACX7100-32C"
+  description: "Juniper ACX7100-32C"
+
+- librenms_hardware: "JNP7024 [ACX7024]"
+  netbox_device_type: "ACX7024"
+  description: "Juniper ACX7024"
+
+- librenms_hardware: "Juniper JNP10008 Internet Backbone Router"
+  netbox_device_type: "PTX10008"
+  description: "Juniper PTX10008 (alternate hardware string)"
+
+- librenms_hardware: "Juniper VRR Internet Backbone Router"
+  netbox_device_type: "VRR"
+  description: "Juniper Virtual Route Reflector"
+
+# Nokia — model string matches directly in most cases
+- librenms_hardware: "7750 SR-7s"
+  netbox_device_type: "7750 SR-7s"
+  description: "Nokia 7750 SR-7s service router"
+
+# Cisco — often matches by part_number but not always
+- librenms_hardware: "WS-C4900M"
+  netbox_device_type: "WS-C4900M"
+  description: "Cisco Catalyst 4900M"
+
+# Cisco IOS XR
+- librenms_hardware: "8201-SYS"
+  netbox_device_type: "8201"
+  description: "Cisco 8201 (hardware string differs from model)"
+
+# UfiSpace — LibreNMS reports SONiC/ONIE platform names
+- librenms_hardware: "x86-64-ufispace-s9610-36d-r0"
+  netbox_device_type: "S9610-36D"
+  description: "UfiSpace S9610-36D"
+
+- librenms_hardware: "x86-64-ufispace-s9610-46dx-r0"
+  netbox_device_type: "S9610-46DX"
+  description: "UfiSpace S9610-46DX"
+
+- librenms_hardware: "x86-64-ufispace-s9700-53dx-r9"
+  netbox_device_type: "S9700-53DX"
+  description: "UfiSpace S9700-53DX"

contrib/interface_type_mappings.yaml

@@ -0,0 +1,75 @@
+# Interface Type Mappings
+#
+# Maps LibreNMS interface types (and optional speeds) to NetBox interface types.
+# Import via: LibreNMS Plugin > Interface Mappings > Import
+#
+# Fields:
+#   librenms_type  — IANA ifType string from LibreNMS (e.g. ethernetCsmacd)
+#   librenms_speed — Speed in Kbps (optional, null matches any speed)
+#   netbox_type    — NetBox InterfaceTypeChoices slug
+#   description    — Optional note
+#
+# Common NetBox interface type slugs:
+#   1000base-t, 10gbase-t, 10gbase-x-sfpp, 25gbase-x-sfp28,
+#   40gbase-x-qsfpp, 100gbase-x-qsfp28, 400gbase-x-qsfpdd,
+#   ieee802.11ax, lag, virtual, other
+
+# WARNING: Speed-only matching cannot distinguish copper from fiber optics.
+# For example, 1G ethernetCsmacd could be 1000base-t (copper), 1000base-x-sfp (fiber),
+# or other media types. Review and adjust these mappings for your environment before
+# importing — incorrect mappings will mislabel ports.
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 1000000
+  netbox_type: 1000base-t
+  description: "1G Ethernet copper"
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 10000000
+  netbox_type: 10gbase-x-sfpp
+  description: "10G Ethernet SFP+"
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 25000000
+  netbox_type: 25gbase-x-sfp28
+  description: "25G Ethernet SFP28"
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 40000000
+  netbox_type: 40gbase-x-qsfpp
+  description: "40G Ethernet QSFP+"
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 100000000
+  netbox_type: 100gbase-x-qsfp28
+  description: "100G Ethernet QSFP28"
+
+- librenms_type: ethernetCsmacd
+  librenms_speed: 400000000
+  netbox_type: 400gbase-x-qsfpdd
+  description: "400G Ethernet QSFP-DD"
+
+- librenms_type: ieee8023adLag
+  librenms_speed:
+  netbox_type: lag
+  description: "LACP/LAG aggregation"
+
+- librenms_type: propVirtual
+  librenms_speed:
+  netbox_type: virtual
+  description: "Virtual/loopback interface"
+
+- librenms_type: softwareLoopback
+  librenms_speed:
+  netbox_type: virtual
+  description: "Software loopback"
+
+- librenms_type: tunnel
+  librenms_speed:
+  netbox_type: virtual
+  description: "Tunnel interface"
+
+- librenms_type: l2vlan
+  librenms_speed:
+  netbox_type: virtual
+  description: "VLAN interface"