docs: 3.3.x upgrade notes for the three deduplication identity changes

docs/content/releases/os_upgrading/3.3.md

@@ -2,6 +2,54 @@
 title: 'Upgrading to DefectDojo Version 3.3.x'
 toc_hide: true
 weight: -20260803
-description: No special instructions.
+description: Three parsers gain deduplication registrations, which changes the stored identity of their findings. Xeol Parser moves off the legacy hash so its identity stops depending on the wall clock; Checkmarx One Scan hashes the vendor id it already matches on; Checkmarx Scan detailed gains the same field list as its CxFlow sibling. Instances with the identity signature ledger enabled bridge these changes automatically; others should rehash the affected scan types after upgrading.
 ---
-There are no special instructions for upgrading to 3.3.x. Check the [Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/3.3.0) for the contents of the release.
+
+## Deduplication identity changes
+
+Three scan types gain `HASHCODE_FIELDS_PER_SCANNER` registrations in this release. A
+registration changes how `hash_code` is computed, so findings imported by these parsers
+before the upgrade carry a hash that no longer matches what an import computes after it.
+Left alone, the next re-import of an unchanged report would treat every affected finding
+as new, close the stored one as absent, and recreate it, detaching false positive
+history and risk acceptances along the way.
+
+| Scan type | New hash fields | Why |
+|---|---|---|
+| `Xeol Parser` | `title`, `component_name`, `component_version` | Its severity is derived from the current date against the component's EOL date, and the legacy hash meant finding identity moved on its own as time passed. Severity still escalates as an EOL date recedes; it just no longer decides what the finding is. |
+| `Checkmarx One Scan` | `unique_id_from_tool` | The parser already deduplicates on the vendor id. The stored hash previously fell through to the legacy field set, whose title and description are the same volatile text for every result family, so the stored identity moved whenever Checkmarx reworded a finding even though matching did not. |
+| `Checkmarx Scan detailed` | `vuln_id_from_tool`, `file_path`, `line` | The same three fields as its sibling `Checkmarx CxFlow SAST`, which the parser populates on every detailed-mode finding. None of them carries scan text. |
+
+### DefectDojo Pro
+
+Pro 3.2.300 and later record identity signatures by default
+(`identity_signature_dual_write`), and the nightly drift watch will notice these
+definition changes and notify. The notification is a report, not a repair: recompute the
+stored hashes with the same three commands below, or accept the definition change in the
+Tuner, which runs the equivalent scoped rehash.
+
+Two Pro-specific notes:
+
+* If your instance has a signature ledger worth keeping (it has been recording for a
+  while, or you ran a backfill), run `python manage.py identity_signatures_backfill` in a
+  maintenance window **before** this upgrade. The backfill records the identities
+  findings currently have, and a rehash replaces them; done in this order, the previous
+  identities stay in the ledger and remain matchable during the transition on instances
+  where signature matching is enabled.
+* `identity_signature_matching` remains opt-in per instance. Where it is enabled, imports
+  still carrying the old identity bridge through the ledger during the transition.
+
+### Open source, and Pro instances that skip the rehash
+
+Rehash the affected scan types after upgrading so stored hashes match what imports now
+compute:
+
+```bash
+docker compose exec uwsgi /bin/bash -c "python manage.py dedupe --parser 'Xeol Parser' --hash_code_only"
+docker compose exec uwsgi /bin/bash -c "python manage.py dedupe --parser 'Checkmarx One Scan' --hash_code_only"
+docker compose exec uwsgi /bin/bash -c "python manage.py dedupe --parser 'Checkmarx Scan detailed' --hash_code_only"
+```
+
+Installs that never imported these scan types are unaffected. Check the
+[Release Notes](https://github.com/DefectDojo/django-DefectDojo/releases/tag/3.3.0) for
+the full contents of the release.