Add factual analysis notes for PR owasp-modsecurity#3540 Sonar and backend split

Author: Easton97-Jens

doc/pr-3540-sonar-json-analysis.md

@@ -0,0 +1,97 @@
+# Analyse PR #3540 (SonarQubeCloud + JSON-Backend-Trennung)
+
+Datum der Analyse: 2026-04-13 (UTC)
+
+## Verifizierte externe Quellen
+
+- GitHub Pull Request: https://github.com/owasp-modsecurity/ModSecurity/pull/3540
+- GitHub Checks API für Head-Commit `5dd7b3539977de85f0a2aebd2cb28b9ea1640211`
+- SonarCloud API (öffentlich):
+  - `api/qualitygates/project_status?projectKey=owasp-modsecurity_ModSecurity&pullRequest=3540`
+  - `api/measures/component?component=owasp-modsecurity_ModSecurity&pullRequest=3540&metricKeys=...`
+  - `api/hotspots/search?projectKey=owasp-modsecurity_ModSecurity&pullRequest=3540`
+  - `api/hotspots/show?hotspot=AZ2DWE24t-zbsGOGdN_L`
+
+## Relevante, lokal verifizierte Projektstellen
+
+- Backend-Selektion via Configure-Option und Compile-Defines: `configure.ac`.
+- Backend-spezifische Source-Auswahl in `src/Makefile.am`.
+- Adapter-Schicht und Ergebnis-Normalisierung in `src/request_body_processor/json_adapter.*`.
+- Gemeinsames Sink-Interface + Parse-Status in `src/request_body_processor/json_backend.h`.
+- JSON-Prozessor (Parser-Entry für Transaktion) in `src/request_body_processor/json.*`.
+- Backend-Implementierungen:
+  - `src/request_body_processor/json_backend_simdjson.cc`
+  - `src/request_body_processor/json_backend_jsoncons.cc`
+- Instrumentation in `src/request_body_processor/json_instrumentation.*`.
+- Matrix-Testskript über beide Backends in `test/run-json-backend-matrix.sh`.
+- Backend-spezifische Tiefe/Number-Lexeme-Tests in `test/unit/json_backend_depth_tests.cc`.
+- Regression-Edgecases in `test/test-cases/regression/request-body-parser-json-backend-edgecases.json`.
+
+## SonarQubeCloud: verifizierter Gate-Status
+
+`qualitygates/project_status` liefert:
+
+- `status=ERROR`
+- `new_security_hotspots_reviewed = 0.0` bei Schwellwert `>= 100` (Gate-Fehler)
+- `new_duplicated_lines_density = 1.3` bei Schwellwert `<= 3` (Gate **nicht** verletzt)
+
+Damit ist auf Basis der API der Quality-Gate-Fehler auf den nicht reviewten Security Hotspot zurückzuführen, nicht auf Duplikation.
+
+## Security Hotspot (verifiziert)
+
+- Datei: `test/benchmark/json_benchmark.cc`
+- Zeile: 318
+- Regel: `cpp:S1313` („Using hardcoded IP addresses is security-sensitive“)
+- Meldung: „Make sure using this hardcoded IP address is safe here.“
+- Sonar-Status: `TO_REVIEW`, `vulnerabilityProbability=LOW`
+
+Hinweis: Der Hotspot liegt in Test-/Benchmark-Code, nicht in den produktiven JSON-Backend-Dateien.
+
+## JSON-Backend-Trennung: verifizierte Architektur
+
+1. **Build-Time Auswahl (mutuell exklusiv)**
+   - `--with-json-backend=simdjson|jsoncons` in `configure.ac`.
+   - Definiert genau eines von `MSC_JSON_BACKEND_SIMDJSON` oder `MSC_JSON_BACKEND_JSONCONS`.
+   - `src/Makefile.am` fügt abhängig davon genau eine Backend-Datei (`json_backend_simdjson.cc` oder `json_backend_jsoncons.cc`) hinzu.
+
+2. **Gemeinsame Laufzeit-Abstraktion**
+   - Gemeinsames Event-/Status-Interface in `json_backend.h` (`JsonEventSink`, `JsonParseResult`, `JsonParseStatus`, `JsonSinkStatus`).
+   - `JSONAdapter::parseImpl()` dispatcht per Compile-Makro auf genau ein Backend.
+
+3. **Gemeinsame Verarbeitungsschicht oberhalb der Backends**
+   - `JSON` implementiert `JsonEventSink` und mappt Events auf `Transaction::addArgument(...)`.
+   - Dadurch teilen beide Backends denselben Semantikpfad für Argument-Erzeugung/Depth-Handling im Sink.
+
+## Verifizierte Überschneidungen / Kopplungen
+
+- **Gewollte Kopplung über gemeinsames Sink-Interface**: beide Backends liefern identische Event-Arten an dieselbe `JSON`-Klasse.
+- **Build-Kopplung in Tests**: `test/Makefile.am` enthält `-I$(top_srcdir)/others/jsoncons/include` in allgemeinen Test-CPPFLAGS, auch wenn simdjson als Backend gewählt ist.
+- **Teilweise duplizierte Helper-Logik** zwischen Backends (z. B. `makeResult(...)`, `stopTraversal(...)`, ähnliche Event-Dispatch-Strukturen), jedoch jeweils mit backend-spezifischen Parser-APIs.
+
+## Sonar-relevante Open-Issues in JSON-Dateien (Auszug)
+
+- `json_backend_jsoncons.cc`:
+  - hohe Cognitive Complexity (mehrere Funktionen)
+  - Nesting-Tiefe > 3 in mehreren Blöcken
+- `json.cc`:
+  - hohe Cognitive Complexity in `complete(...)`
+  - Nesting-Verstöße in `complete(...)`
+  - Rule zu manuellem `delete`
+- `json.h`:
+  - Rule zu Copy-/Move-Semantik (`JSON` besitzt rohe Pointer in Containern)
+- `json_instrumentation.cc`:
+  - Rule zu globaler Variable (`thread_local JsonInstrumentationMetrics g_metrics`)
+- `json_backend_simdjson.cc`:
+  - `enforceTechnicalDepth(...)` sollte laut Sonar `const` sein
+- `json_adapter.cc`:
+  - mehrere Minor-Hinweise zu `std::string_view`/`const`-Parametern
+
+## Minimal-invasive Refactoring-Ideen (direkt aus Code ableitbar)
+
+1. `json.cc::complete(...)` in kleine Mapper-Funktion für Fehlertext aufspalten.
+2. `json_backend_jsoncons.cc::emitEvent(...)` in Event-Handler-Funktionen splitten (`handleStringEvent`, `handleNumberEvent`, etc.).
+3. `json_backend_jsoncons.cc::consumeStringAt(...)` und `consumeNumberAt(...)` in kleinere Validator-Helfer extrahieren.
+4. `json.h/json.cc`: Ownership von `m_containers` auf `std::unique_ptr<JSONContainer>` umstellen, `delete` entfernen.
+5. `json_instrumentation.cc`: `g_metrics` in Funktion-scope kapseln (`metricsRef()`), Zugriffe zentralisieren.
+6. `json_backend_simdjson.cc`: `enforceTechnicalDepth(...) const` markieren (wenn API-Aufrufe const-korrekt bleiben).
+