@gpzhang2001/sharpkit-reporting 0.2.1

package/src/cvss.ts

@@ -0,0 +1,141 @@
+/**
+ * CVSS v3.1 base-score math, ported from strix's usage of the `cvss`
+ * package (tool.py `_calculate_cvss` :134-153): build the vector string,
+ * compute the base score and qualitative severity. The score uses the
+ * CVSS 3.1 spec formula with the spec's Roundup1 (ceil to one decimal with
+ * the IEEE-754 guard), and a "none" base severity is remapped to "info"
+ * (strix parity).
+ * @module @gpzhang2001/sharpkit-reporting/cvss
+ */
+
+/** The eight CVSS metrics with their allowed values (strix `_CVSS_VALID`). */
+export const CVSS_VALID = {
+  attack_vector: ['N', 'A', 'L', 'P'],
+  attack_complexity: ['L', 'H'],
+  privileges_required: ['N', 'L', 'H'],
+  user_interaction: ['N', 'R'],
+  scope: ['U', 'C'],
+  confidentiality: ['N', 'L', 'H'],
+  integrity: ['N', 'L', 'H'],
+  availability: ['N', 'L', 'H'],
+} as const
+
+export type CvssMetricName = keyof typeof CVSS_VALID
+
+/** The eight metrics in vector order (strix vector build order). */
+const METRIC_ORDER: readonly CvssMetricName[] = [
+  'attack_vector', 'attack_complexity', 'privileges_required', 'user_interaction',
+  'scope', 'confidentiality', 'integrity', 'availability',
+]
+
+/** Weight tables (CVSS v3.1 spec §3.1). */
+const AV: Record<string, number | undefined> = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 }
+const AC: Record<string, number | undefined> = { L: 0.77, H: 0.44 }
+const PR_UNCHANGED: Record<string, number | undefined> = { N: 0.85, L: 0.62, H: 0.27 }
+const PR_CHANGED: Record<string, number | undefined> = { N: 0.85, L: 0.68, H: 0.5 }
+const UI: Record<string, number | undefined> = { N: 0.85, R: 0.62 }
+const CIA: Record<string, number | undefined> = { H: 0.56, L: 0.22, N: 0 }
+
+/**
+ * CVSS 3.1 Roundup1: smallest one-decimal value >= the input (the `cvss`
+ * package quantizes with Decimal ROUND_CEILING; the 5-decimal pre-round
+ * absorbs float artifacts the same way the spec intends).
+ */
+function roundup(value: number): number {
+  const quantized = Number(value.toFixed(5))
+  return Math.ceil(Number((quantized * 10).toFixed(6))) / 10
+}
+
+/**
+ * Validate a breakdown against the allowed metric/value sets.
+ * @param breakdown - the model-supplied 8-metric dict.
+ * @returns validation errors, empty when valid.
+ */
+export function validateCvssBreakdown(breakdown: Record<string, unknown>): string[] {
+  const errors: string[] = []
+  if (typeof breakdown !== 'object' || breakdown === null || Object.keys(breakdown).length === 0) {
+    return ['cvss_breakdown must be a non-empty object with all 8 metrics']
+  }
+  for (const metric of METRIC_ORDER) {
+    const value = breakdown[metric]
+    const allowed = CVSS_VALID[metric]
+    if (typeof value !== 'string' || !(allowed as readonly string[]).includes(value)) {
+      errors.push(`Invalid ${metric}: ${String(value)}. Must be one of: [${allowed.join(', ')}]`)
+    }
+  }
+  return errors
+}
+
+/**
+ * Build the vector string (strix format: CVSS:3.1/AV:../AC:../PR:../UI:../S:../C:../I:../A:..).
+ * @param breakdown - a validated breakdown.
+ */
+export function buildCvssVector(breakdown: Readonly<Record<CvssMetricName, string>>): string {
+  const parts = METRIC_ORDER.map(metric => {
+    const short = { attack_vector: 'AV', attack_complexity: 'AC', privileges_required: 'PR', user_interaction: 'UI', scope: 'S', confidentiality: 'C', integrity: 'I', availability: 'A' }[metric]
+    return `${short}:${breakdown[metric]}`
+  })
+  return `CVSS:3.1/${parts.join('/')}`
+}
+
+/**
+ * Compute the CVSS v3.1 base score for a breakdown (the `cvss` package's
+ * `compute_base_score`: Scope U ISC = 6.42×ISCBase; Scope C ISC = the 7.52
+ * formula; Scope C multiplies the total by 1.08 before the cap).
+ * @param breakdown - a validated breakdown.
+ * @returns the rounded base score (0.0 when impact is non-positive).
+ */
+export function cvssBaseScore(breakdown: Readonly<Record<CvssMetricName, string>>): number {
+  const scopeChanged = breakdown.scope === 'C'
+  const c = CIA[breakdown.confidentiality] ?? 0
+  const i = CIA[breakdown.integrity] ?? 0
+  const a = CIA[breakdown.availability] ?? 0
+  const iscBase = 1 - (1 - c) * (1 - i) * (1 - a)
+  const isc = scopeChanged
+    ? 7.52 * (iscBase - 0.029) - 3.25 * (iscBase - 0.02) ** 15
+    : 6.42 * iscBase
+  if (isc <= 0) return 0
+  const pr = ((scopeChanged ? PR_CHANGED : PR_UNCHANGED)[breakdown.privileges_required]) ?? 0
+  const exploitability = 8.22 * (AV[breakdown.attack_vector] ?? 0) * (AC[breakdown.attack_complexity] ?? 0) * pr * (UI[breakdown.user_interaction] ?? 0)
+  const raw = scopeChanged ? Math.min(1.08 * (isc + exploitability), 10) : Math.min(isc + exploitability, 10)
+  return roundup(raw)
+}
+
+/**
+ * Qualitative severity banding (the `cvss` package's rating bands).
+ * @param score - the base score.
+ */
+export function cvssSeverity(score: number): 'none' | 'low' | 'medium' | 'high' | 'critical' {
+  if (score === 0) return 'none'
+  if (score <= 3.9) return 'low'
+  if (score <= 6.9) return 'medium'
+  if (score <= 8.9) return 'high'
+  return 'critical'
+}
+
+/**
+ * Full computation: vector + score + severity with the "none"→"info" remap
+ * (strix `_calculate_cvss` return contract).
+ * @param breakdown - a validated breakdown.
+ */
+export function calculateCvss(breakdown: Readonly<Record<CvssMetricName, string>>): { readonly vector: string; readonly score: number; readonly severity: string } {
+  const vector = buildCvssVector(breakdown)
+  const score = cvssBaseScore(breakdown)
+  const severity = cvssSeverity(score)
+  return { vector, score, severity: severity === 'none' ? 'info' : severity }
+}
+
+/**
+ * Dependency severity banding from an advisory score (strix
+ * `_DEP_SEVERITY_FROM_CVSS` :1363-1378, top band inclusive at 10.0).
+ * @param score - the advisory base score.
+ */
+export function dependencySeverity(score: number): string {
+  if (score === null || score === undefined || Number.isNaN(score)) return 'info'
+  const clamped = Math.min(10, Math.max(0, score))
+  if (clamped >= 9.0) return 'critical'
+  if (clamped >= 7.0) return 'high'
+  if (clamped >= 4.0) return 'medium'
+  if (clamped >= 0.0) return 'low'
+  return 'none'
+}

package/src/dedupe.ts

@@ -0,0 +1,136 @@
+/**
+ * Dedupe — port of strix report/dedupe.py decision flow: the deterministic
+ * dependency identity fast path (CVE × package × ecosystem, distinct
+ * manifests are separate findings, legacy word-bounded mention fallback) and
+ * an injectable LLM judge for dynamic findings. Every judge failure defaults
+ * to NOT duplicate (strix parity: dedupe failures never block a finding).
+ * @module @gpzhang2001/sharpkit-reporting/dedupe
+ */
+
+import type { VulnerabilityReport } from './state.ts'
+
+/** Dependency identity fields (strix `_dependency_identity`). */
+export interface DependencyIdentity {
+  readonly cve: string
+  readonly packageName: string
+  readonly ecosystem: string
+}
+
+/** The dedupe verdict shape (strix `DuplicateCheckResult`). */
+export interface DuplicateVerdict {
+  readonly isDuplicate: boolean
+  readonly duplicateId: string
+  readonly confidence: number
+  readonly reason: string
+}
+
+/** Pluggable LLM judge (Config-injected; dsh-side LLM wiring lands with M4). */
+export type DedupeJudge = (candidate: Record<string, unknown>, existing: readonly VulnerabilityReport[]) => Promise<DuplicateVerdict>
+
+/** Extract the dependency identity from metadata (strix :162-177). */
+export function dependencyIdentity(metadata: unknown): DependencyIdentity | null {
+  if (typeof metadata !== 'object' || metadata === null) return null
+  const record = metadata as Record<string, unknown>
+  const cve = record['cve']
+  const packageName = record['package_name']
+  const ecosystem = record['package_ecosystem']
+  if (typeof cve !== 'string' || cve === '' || typeof packageName !== 'string' || packageName === '' || typeof ecosystem !== 'string' || ecosystem === '') {
+    return null
+  }
+  return { cve: cve.toUpperCase(), packageName: packageName.toLowerCase(), ecosystem: ecosystem.toLowerCase() }
+}
+
+/** Whether two manifest paths are both present AND different (strix `_distinct_manifest_paths`). */
+export function distinctManifestPaths(a: unknown, b: unknown): boolean {
+  const first = typeof a === 'string' && a !== '' ? a : null
+  const second = typeof b === 'string' && b !== '' ? b : null
+  return first !== null && second !== null && first !== second
+}
+
+/** Word-bounded regex mention check over prose fields (strix `_legacy_report_mentions_package`). */
+export function legacyReportMentionsPackage(report: VulnerabilityReport, identity: DependencyIdentity): boolean {
+  const fields = ['title', 'description', 'impact', 'target', 'technical_analysis', 'poc_description', 'evidence']
+  // strix boundaries: [\w@./-] on both sides break the match (dedupe.py :218-224).
+  const packagePattern = new RegExp(`(?<![\\w@./-])${escapeRegExp(identity.packageName)}(?![\\w@./-])`, 'i')
+  const ecosystemPattern = new RegExp(`(?<![\\w@./-])${escapeRegExp(identity.ecosystem)}(?![\\w@./-])`, 'i')
+  for (const field of fields) {
+    const value = (report as unknown as Record<string, unknown>)[field]
+    if (typeof value !== 'string') continue
+    if (packagePattern.test(value) && ecosystemPattern.test(value)) return true
+  }
+  return false
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The deterministic dependency fast path (strix `_check_dependency_duplicate`).
+ * @param candidateIdentity - the candidate's identity.
+ * @param candidateMetadata - the candidate's dependency metadata (manifest comparison).
+ * @param existing - current reports.
+ * @returns a verdict, or null to defer to the LLM judge.
+ */
+export function checkDependencyDuplicate(
+  candidateIdentity: DependencyIdentity,
+  candidateMetadata: Record<string, unknown> | undefined,
+  existing: readonly VulnerabilityReport[],
+): DuplicateVerdict | null {
+  let sawLegacySameCve = false
+  for (const report of existing) {
+    const metadata = (report as unknown as Record<string, unknown>)['dependency_metadata']
+    const identity = dependencyIdentity(metadata)
+    if (identity === null) {
+      // Legacy report: CVE match + prose mention of the package.
+      if (String((report as unknown as Record<string, unknown>)['cve'] ?? '').toUpperCase() === candidateIdentity.cve) {
+        sawLegacySameCve = true
+        if (legacyReportMentionsPackage(report, candidateIdentity)) {
+          return { isDuplicate: true, duplicateId: report.id, confidence: 1.0, reason: 'Same dependency CVE/package identity (legacy report)' }
+        }
+      }
+      continue
+    }
+    if (identity.cve !== candidateIdentity.cve || identity.packageName !== candidateIdentity.packageName) continue
+    const existingMetadata = (report as unknown as Record<string, unknown>)['dependency_metadata'] as Record<string, unknown>
+    if (distinctManifestPaths(candidateMetadata?.['manifest_path'], existingMetadata['manifest_path'])) continue
+    if (identity.ecosystem === candidateIdentity.ecosystem) {
+      return { isDuplicate: true, duplicateId: report.id, confidence: 1.0, reason: 'Same dependency CVE/package identity' }
+    }
+    return { isDuplicate: true, duplicateId: report.id, confidence: 1.0, reason: 'Same dependency CVE/package identity with missing ecosystem' }
+  }
+  if (sawLegacySameCve) return null
+  return { isDuplicate: false, duplicateId: '', confidence: 1.0, reason: `No existing dependency report for ${candidateIdentity.cve} in ${candidateIdentity.ecosystem}/${candidateIdentity.packageName}` }
+}
+
+/**
+ * Entry point (strix `check_duplicate`): fast path for dependency
+ * candidates, then the injected judge; every judge failure is NOT duplicate.
+ * @param candidate - the candidate fields sent for comparison.
+ * @param candidateMetadata - dependency metadata when present.
+ * @param existing - current reports.
+ * @param judge - the injected LLM judge (absent → not duplicate).
+ */
+export async function checkDuplicate(
+  candidate: Record<string, unknown>,
+  candidateMetadata: Record<string, unknown> | undefined,
+  existing: readonly VulnerabilityReport[],
+  judge: DedupeJudge | undefined,
+): Promise<DuplicateVerdict> {
+  if (existing.length === 0) {
+    return { isDuplicate: false, duplicateId: '', confidence: 1.0, reason: 'No existing reports to compare against' }
+  }
+  const identity = dependencyIdentity(candidateMetadata)
+  if (identity !== null) {
+    const fastPath = checkDependencyDuplicate(identity, candidateMetadata, existing)
+    if (fastPath !== null) return fastPath
+  }
+  if (judge === undefined) {
+    return { isDuplicate: false, duplicateId: '', confidence: 0.0, reason: 'No dedupe judge is configured; defaulting to not duplicate' }
+  }
+  try {
+    return await judge(candidate, existing)
+  } catch (error) {
+    return { isDuplicate: false, duplicateId: '', confidence: 0.0, reason: `Deduplication check failed: ${String(error instanceof Error ? error.message : error)}` }
+  }
+}