From ad27f0c67e9d3a11174ca9e4358bc8922ea9d093 Mon Sep 17 00:00:00 2001
From: alex s <46074070+bearsyankees@users.noreply.github.com>
Date: Tue, 21 Jul 2026 09:17:22 -0400
Subject: [PATCH] =?UTF-8?q?docs(reporting):=20add=20CVSS=20calibration=20g?=
 =?UTF-8?q?uidance=20to=20reduce=20severity=20inf=E2=80=A6=20(#821)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(reporting): add CVSS calibration guidance to reduce severity inflation

The create_vulnerability_report tool documents the cvss_breakdown format but
gives no guidance on choosing metric values, so findings are frequently
over-rated. Add a concise calibration block covering the most common
inflation mistakes: scoring scenarios that presuppose the attacker already
holds a stolen secret as unauthenticated (PR:N) criticals, using C:H/I:H for
single-user or read-only/enumeration impact, folding a chained worst case
into one vector, and ignoring adversary-in-the-middle or user-interaction
prerequisites.

* docs(reporting): drop 'one weakness per report' calibration bullet
---
 strix/tools/reporting/tool.py | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/strix/tools/reporting/tool.py b/strix/tools/reporting/tool.py
index b6f284ca..d6b6b209 100644
--- a/strix/tools/reporting/tool.py
+++ b/strix/tools/reporting/tool.py
@@ -422,6 +422,30 @@ async def create_vulnerability_report(
             "availability": "H"
         }
 
+    **CVSS calibration** — score the weakness you actually proved, not a
+    hypothetical worst case. Most over-rating comes from these mistakes:
+
+    - **Don't presuppose a separate compromise.** If exploitation
+      requires the attacker to already hold a victim secret (a stolen
+      session cookie/token, a leaked one-time link, intercepted traffic),
+      that acquisition is not free. Do not score it as
+      ``privileges_required:N`` with ``attack_complexity:L`` as if
+      directly reachable, and do not rate a replay-of-captured-secret
+      issue High/Critical unless the *same* finding demonstrates a
+      concrete way to obtain that secret. Issues like a session that
+      survives logout or a replayable link are session-management /
+      defense-in-depth weaknesses — usually Low/Medium on their own.
+    - **Reserve ``H`` impact for demonstrated broad impact.** ``C:H`` /
+      ``I:H`` require proof of wide or systemic read/write. A single
+      user's data, a read-only information leak, or merely confirming
+      that an account / domain / software version *exists* (enumeration)
+      is ``C:L`` (often ``I:N``) — not ``C:H``.
+    - **Model required position and interaction honestly.** An
+      adversary-in-the-middle prerequisite (e.g. cleartext transmission)
+      or a required victim action is not guaranteed — reflect it in
+      ``attack_complexity`` / ``user_interaction`` instead of assuming the
+      ideal condition always holds.
+
     **CVE / CWE rules**: pass the bare ID only (``CVE-2024-1234``,
     ``CWE-89``) — no name, no parenthetical. Be 100% certain; if
     unsure, use ``web_search`` to verify the ID before passing, or omit