Fix 2191 (#2192)

* add dev branch audit file

* Add version-controlled Dependabot config and document update policy

Closes #2191.

- Add .github/dependabot.yml managing the uv (Python) and github-actions
  ecosystems: weekly schedule, grouped patch/minor bumps, and ignore rules
  for major-version updates of the deliberately major-capped dependencies
  (urllib3, h2, hyperframe, priority). Docker is intentionally not managed
  in this repo (production images are built outside it).
- Expand docs/uvlock.rst with a "Dependabot and Automated Updates" section
  codifying the review policy: uv.lock-only PRs are the fast lane (merge on
  green CI), pyproject.toml-touching PRs are the manual lane (review the
  rewritten constraint), with just update-uvlock remaining canonical.

Note: This work was completed with AI assistance (Claude Code).

Author: oberstet

.audit/oberstet_fix_2191.md

@@ -0,0 +1,8 @@
+- [ ] I did **not** use any AI-assistance tools to help create this pull request.
+- [x] I **did** use AI-assistance tools to *help* create this pull request.
+- [x] I have read, understood and followed the project's AI_POLICY.md when creating code, documentation etc. for this pull request.
+
+Submitted by: @oberstet
+Date: 2026-06-13
+Related issue(s): #2191
+Branch: oberstet:fix_2191

.github/dependabot.yml

@@ -0,0 +1,108 @@
+# Dependabot configuration for Crossbar.io
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+#
+# Policy (see docs/uvlock.rst, section "Dependabot and Automated Updates"):
+#   - PR touching ONLY uv.lock        -> low risk, merge on green CI (fast lane)
+#   - PR also touching pyproject.toml -> a declared constraint was rewritten,
+#                                        review the changelog before merging (manual lane)
+#
+# `just update-uvlock` remains the canonical way we refresh the lockfile;
+# Dependabot is the notifier + CI gate, not the source of truth for resolution.
+
+version: 2
+
+updates:
+  # ---------------------------------------------------------------------------
+  # Python dependencies (uv / uv.lock + pyproject.toml)
+  #
+  # NOTE: `package-ecosystem: "uv"` requires Dependabot's native uv support.
+  # Verify against current Dependabot docs if no PRs are generated.
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+
+    # Group low-risk patch + minor bumps into a single PR to cut noise.
+    # A grouped PR that ends up touching pyproject.toml goes to the manual
+    # review lane as a whole (see docs/uvlock.rst).
+    groups:
+      python-minor-patch:
+        applies-to: version-updates
+        update-types:
+          - "minor"
+          - "patch"
+
+    ignore:
+      # Deliberately MAJOR-capped deps in pyproject.toml: never auto-cross a
+      # major boundary we set on purpose. These must be bumped by hand after
+      # reviewing the upstream migration guide (e.g. urllib3 1.x -> 2.x changes
+      # TLS/pyOpenSSL behavior, directly relevant to a TLS-terminating router).
+      # Security advisories still come through regardless of these ignores.
+      - dependency-name: "urllib3"      # pyproject: >=1.26.14,<1.27
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "h2"           # pyproject: >=3.2.0,<4.0.0
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "hyperframe"   # pyproject: >=5.2.0,<6.0.0
+        update-types: ["version-update:semver-major"]
+      - dependency-name: "priority"     # pyproject: >=1.3.0,<2.0
+        update-types: ["version-update:semver-major"]
+      # The following are MINOR-capped on purpose. We do NOT hard-ignore them
+      # here (a bump still surfaces as a PR), but because any such bump must
+      # rewrite the pyproject.toml cap, it lands in the manual review lane:
+      #   idna          >=2.5,<2.6
+      #   eth-abi       >=5.1.0,<5.2.0
+      #   parsimonious  >=0.9.0,<0.11.0
+
+  # ---------------------------------------------------------------------------
+  # GitHub Actions workflows (.github/workflows/*.yml)
+  # ---------------------------------------------------------------------------
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Europe/Berlin"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  # ---------------------------------------------------------------------------
+  # Docker base images -- DEFERRED.
+  # There is currently no production Dockerfile committed in this repo (only
+  # test/ and docs-cfx/ scaffolding). Enable this block, pointed at the right
+  # directory, once a production Dockerfile lands in the tree.
+  # ---------------------------------------------------------------------------
+  # - package-ecosystem: "docker"
+  #   directory: "/"
+  #   schedule:
+  #     interval: "weekly"
+  #     day: "monday"
+  #     time: "06:00"
+  #     timezone: "Europe/Berlin"
+  #   open-pull-requests-limit: 5
+  #   labels:
+  #     - "dependencies"
+  #     - "docker"
+  #   commit-message:
+  #     prefix: "docker"
+  #     include: "scope"

docs/uvlock.rst

@@ -186,6 +186,81 @@ For production Docker images, use the frozen lock file:
 This ensures the production container has exactly the same dependencies that were
 tested in CI and verified during development.
 
+Dependabot and Automated Updates
+--------------------------------
+
+Crossbar.io uses `Dependabot <https://docs.github.com/en/code-security/dependabot>`_
+to track upstream dependency releases. The configuration is version-controlled in
+``.github/dependabot.yml`` (not just GitHub UI settings), so the bot's behavior is
+explicit, reviewable, and reproducible.
+
+Because we maintain a two-tier dependency model — abstract ``>=`` floors (with
+deliberate caps) in ``pyproject.toml``, and exact pins in ``uv.lock`` — Dependabot
+PRs are reviewed using a simple rule based on **which files the PR touches**.
+
+The two-lane review policy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Fast lane — PR touches** ``uv.lock`` **only:**
+
+The new version fits *within* our existing ``pyproject.toml`` constraints. This is
+almost always a transitive dependency, or a direct one with headroom under its cap.
+Our declared compatibility contract is unchanged.
+
+- **Action:** merge once CI is green.
+
+**Manual lane — PR touches** ``pyproject.toml`` **as well:**
+
+Dependabot had to **rewrite a declared constraint** to let the new version in —
+usually to cross an upper cap we set on purpose. This is a change to our
+compatibility contract, not just a re-pin.
+
+- **Action:** review before merging. Read the upstream changelog/migration guide,
+  check *how* the constraint was rewritten (did it keep a sane cap?), and apply
+  extra scrutiny to major-version bumps of TLS/crypto-adjacent dependencies
+  (e.g. ``urllib3``, ``pyopenssl``, ``cryptography``) — green CI is necessary but
+  not sufficient for those, since CI may not exercise every TLS, proxy, or retry
+  code path.
+
+.. note::
+
+   Patch and minor bumps are **grouped** into a single PR to reduce noise. If a
+   grouped PR happens to touch ``pyproject.toml``, the whole PR is treated as the
+   manual lane.
+
+Ignored and capped dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``.github/dependabot.yml`` **ignores major-version updates** for dependencies that
+carry a deliberate major cap in ``pyproject.toml`` (``urllib3``, ``h2``,
+``hyperframe``, ``priority``). We never want to be auto-nudged across a major
+boundary we pinned on purpose; those bumps are done by hand after reviewing the
+upstream migration guide.
+
+A few dependencies are capped at the **minor** level instead (``idna``,
+``eth-abi``, ``parsimonious``). These are not hard-ignored, but any bump rewrites
+their ``pyproject.toml`` cap and therefore lands in the manual review lane anyway.
+
+.. note::
+
+   These ignore rules only suppress *routine version updates*. Dependabot
+   **security advisories** still raise PRs for vulnerable versions regardless of
+   the caps above — security fixes are never silently held back.
+
+Relationship to ``just update-uvlock``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Dependabot is the **notifier and CI gate**, not the source of truth for how the
+lockfile is resolved. The canonical way we refresh ``uv.lock`` remains:
+
+.. code-block:: bash
+
+   just update-uvlock
+
+which pins resolution to the lowest supported Python (3.11) for widest
+compatibility. When in doubt — for example, to reconcile several Dependabot PRs at
+once — re-run ``just update-uvlock`` locally and commit the result.
+
 References
 ----------