@gpzhang2001/sharpkit-reporting 0.2.1

package/src/sarif.ts

@@ -0,0 +1,531 @@
+/**
+ * SARIF 2.1.0 writer — port of strix report/sarif.py: rule ids normalized
+ * CWE→CVE→id→slug, GitHub security-severity, STRIDE tags from the CWE map,
+ * physical + synthetic (SECURITY.md anchor) locations with endpoint logical
+ * locations, PR-suggestion fixes, deterministic partial fingerprints
+ * (sha256), and the strix-namespaced properties (PoC script body never
+ * exported). Key insertion order matches Python dict construction
+ * byte-for-byte (golden-diff locked).
+ * @module @gpzhang2001/sharpkit-reporting/sarif
+ */
+
+import { createHash } from 'node:crypto'
+import { rename, writeFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { dumpsIndent } from './writers.ts'
+import type { VulnerabilityReport } from './state.ts'
+
+export const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json'
+export const SARIF_VERSION = '2.1.0'
+export const TOOL_NAME = 'sharpkit'
+export const TOOL_INFORMATION_URI = 'https://github.com/gpzhang2001/sharpkit'
+const SYNTHETIC_LOCATION_URI = 'SECURITY.md'
+const DEFAULT_STRIDE_LEGS: readonly string[] = ['T', 'I']
+
+/** CWE → STRIDE legs (sarif.py `_CWE_TO_STRIDE`, verbatim). */
+const CWE_TO_STRIDE: Readonly<Record<string, readonly string[]>> = {
+  '287': ['S'], '290': ['S'], '294': ['S'], '306': ['S', 'E'], '345': ['S', 'T'], '346': ['S'],
+  '352': ['T', 'S'], '384': ['S'], '521': ['S'], '613': ['S'], '640': ['S'],
+  '259': ['S', 'I'], '798': ['S', 'I'], '1391': ['S'],
+  '20': ['T'], '73': ['T', 'I'], '78': ['T', 'E'], '79': ['T', 'I'], '89': ['T'], '91': ['T'],
+  '94': ['T', 'E'], '434': ['T'], '502': ['T', 'E'], '915': ['E', 'T'], '918': ['T', 'I'], '1336': ['T', 'E'],
+  '117': ['R'], '223': ['R'], '778': ['R'],
+  '200': ['I'], '201': ['I'], '209': ['I'], '256': ['I'], '311': ['I'], '319': ['I'], '327': ['I'],
+  '328': ['I'], '522': ['I'], '525': ['I'], '532': ['I'], '538': ['I'], '598': ['I'],
+  '400': ['D'], '770': ['D'], '1333': ['D'],
+  '269': ['E'], '284': ['E'], '285': ['E'], '639': ['E'], '732': ['E'], '862': ['E'], '863': ['E'], '1220': ['E'],
+  '22': ['T', 'I'], '611': ['I', 'T'],
+}
+
+/** Curated vulnerability-class keywords (sarif.py `_VULN_CLASS_KEYWORDS`). */
+const VULN_CLASS_KEYWORDS: readonly string[] = [
+  'missing authentication', 'missing authorization', 'broken access control', 'incorrect authorization',
+  'default credentials', 'hardcoded credentials', 'hardcoded secret', 'hardcoded password', 'default admin',
+  'default password', 'session fixation', 'open redirect', 'path traversal', 'directory traversal',
+  'command injection', 'sql injection', 'code injection', 'template injection', 'xpath injection',
+  'ldap injection', 'log injection', 'header injection', 'csv injection', 'prompt injection',
+  'deserialization', 'ssrf', 'xss', 'csrf', 'xxe', 'race condition', 'toctou', 'information disclosure',
+  'insecure direct object reference', 'idor', 'bola', 'bfla', 'cross-tenant', 'cross-project', 'tenant bypass',
+]
+
+const SEVERITY_TO_LEVEL: Readonly<Record<string, string>> = {
+  critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'note', informational: 'note',
+}
+
+const SEVERITY_TO_SCORE: Readonly<Record<string, string>> = {
+  critical: '9.5', high: '8.0', medium: '5.5', low: '3.0', info: '1.0', informational: '1.0',
+}
+
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+function stringValue(value: unknown): string | null {
+  if (typeof value === 'string') {
+    const stripped = value.trim()
+    return stripped === '' ? null : stripped
+  }
+  return null
+}
+
+function sha256(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/** CWE variants (`CWE-89` / `cwe: 89` / `89`) → `CWE-89`. */
+function normalizeCwe(value: string): string | null {
+  const digits = value.replace(/\D/g, '')
+  return digits === '' ? null : `CWE-${digits}`
+}
+
+/** Stable rule id: CWE → CVE → finding id → slug → sharpkit-finding. */
+export function ruleIdOf(report: VulnerabilityReport): string {
+  const cwe = stringValue(report.cwe)
+  if (cwe !== null) {
+    const normalized = normalizeCwe(cwe)
+    if (normalized !== null) return normalized
+  }
+  const cve = stringValue(report.cve)
+  if (cve !== null) return cve
+  const id = stringValue(report.id)
+  if (id !== null) return id
+  const title = stringValue(report.title)
+  return title === null ? 'sharpkit-finding' : slugify(title)
+}
+
+/** Lowercase slug joined by dashes (sarif.py `_slugify`). */
+export function slugify(value: string): string {
+  const chars = [...value.toLowerCase()].map(char => (/[a-z0-9]/.test(char) ? char : '-')).join('')
+  const slug = chars.split('-').filter(part => part !== '').join('-')
+  return slug === '' ? 'sharpkit-finding' : slug
+}
+
+/** STRIDE legs for a CWE, default legs when unmapped (every finding gets ≥1). */
+export function strideLegsForCwe(cwe: unknown): readonly string[] {
+  if (typeof cwe !== 'string' || cwe === '') return DEFAULT_STRIDE_LEGS
+  const digits = cwe.replace(/\D/g, '')
+  if (digits === '') return DEFAULT_STRIDE_LEGS
+  return CWE_TO_STRIDE[digits] ?? DEFAULT_STRIDE_LEGS
+}
+
+/** First curated keyword in the title, else the first 5 alphanumeric words. */
+export function classKeyword(title: string): string {
+  const lower = title.toLowerCase()
+  for (const keyword of VULN_CLASS_KEYWORDS) {
+    if (lower.includes(keyword)) return keyword
+  }
+  const words = lower.match(/[a-z0-9]+/g)?.slice(0, 5) ?? []
+  return words.join(' ')
+}
+
+/** SARIF level mapping. */
+export function sarifLevel(severity: unknown): string {
+  const normalized = (typeof severity === 'string' ? severity : '').toLowerCase()
+  return SEVERITY_TO_LEVEL[normalized] ?? 'note'
+}
+
+/** GitHub security-severity: "%.1f" CVSS else the label score. */
+export function securitySeverity(report: VulnerabilityReport): string {
+  if (report.cvss !== null && report.cvss !== undefined) {
+    const score = Number(report.cvss)
+    if (!Number.isNaN(score)) return score.toFixed(1)
+  }
+  const normalized = (typeof report.severity === 'string' ? report.severity : 'info').toLowerCase()
+  return SEVERITY_TO_SCORE[normalized] ?? '1.0'
+}
+
+/** Reject unsafe SARIF artifact URIs; normalize backslashes (sarif.py `_sarif_uri`). */
+export function sarifUri(file: string): string | null {
+  const uri = file.replace(/\\/g, '/')
+  if (uri.startsWith('/')) return null
+  const first = uri.split('/')[0] ?? ''
+  if (/^[A-Za-z]:$/.test(first)) return null
+  if (uri.split('/').some(part => part === '..')) return null
+  return uri
+}
+
+/** Help text: description + impact + remediation joined by blank lines. */
+function helpText(report: VulnerabilityReport, fallback: string): string {
+  const sections = [report.description, report.impact, report.remediation_steps]
+    .filter((value): value is string => typeof value === 'string' && value.trim() !== '')
+  return sections.length > 0 ? sections.join('\n\n') : fallback
+}
+
+interface PhysicalLocationInput {
+  readonly file: unknown
+  readonly start_line: unknown
+  readonly end_line?: unknown
+  readonly snippet?: unknown
+  readonly label?: unknown
+}
+
+/** Validated physical locations + dropped count (sarif.py `_build_physical_locations`). */
+function buildPhysicalLocations(rawLocations: unknown): { readonly locations: Json[]; readonly dropped: number } {
+  const locations: Json[] = []
+  let dropped = 0
+  if (!Array.isArray(rawLocations)) return { locations, dropped }
+  for (const raw of rawLocations) {
+    if (typeof raw !== 'object' || raw === null) continue
+    const location = raw as PhysicalLocationInput
+    const file = stringValue(location.file)
+    const startLine = location.start_line
+    if (file === null || typeof startLine !== 'number' || !Number.isInteger(startLine) || startLine < 1) {
+      dropped++
+      continue
+    }
+    const uri = sarifUri(file)
+    if (uri === null) {
+      dropped++
+      continue
+    }
+    const physical: { [key: string]: Json } = {
+      artifactLocation: { uri },
+    }
+    const region: { [key: string]: Json } = { startLine }
+    const endLine = location.end_line
+    if (typeof endLine === 'number' && Number.isInteger(endLine) && endLine >= startLine) region['endLine'] = endLine
+    const snippet = stringValue(location.snippet)
+    if (snippet !== null) region['snippet'] = { text: snippet }
+    physical['region'] = region
+    const entry: { [key: string]: Json } = { physicalLocation: physical }
+    const label = stringValue(location.label)
+    if (label !== null) entry['message'] = { text: label }
+    locations.push(entry)
+  }
+  return { locations, dropped }
+}
+
+/** Locations with the synthetic anchor and endpoint/resource logical entries. */
+function buildLocations(report: VulnerabilityReport): { readonly locations: Json[]; readonly isSynthetic: boolean; readonly dropped: number } {
+  const physical = buildPhysicalLocations(report.code_locations)
+  const isSynthetic = physical.locations.length === 0
+  const locations: Json[] = isSynthetic ? [{ physicalLocation: { artifactLocation: { uri: SYNTHETIC_LOCATION_URI } } }] : [...physical.locations]
+  const endpoint = stringValue(report.endpoint)
+  if (endpoint !== null) {
+    locations.push({ logicalLocations: [{ fullyQualifiedName: endpoint, kind: 'endpoint' }] })
+  } else if (isSynthetic) {
+    const resource = stringValue(report.target) ?? stringValue(report.title)
+    if (resource !== null) locations.push({ logicalLocations: [{ fullyQualifiedName: resource, kind: 'resource' }] })
+  }
+  return { locations, isSynthetic, dropped: physical.dropped }
+}
+
+/** Deterministic per-finding fingerprint (sarif.py `_primary_fingerprint`). */
+function primaryFingerprint(ruleId: string, report: VulnerabilityReport, locations: readonly Json[], isSynthetic: boolean): string | null {
+  let uri = ''
+  let startLine: number | null = null
+  const first = locations.find(location => typeof location === 'object' && location !== null && 'physicalLocation' in location) as { physicalLocation?: { artifactLocation?: { uri?: unknown }; region?: { startLine?: unknown } } } | undefined
+  if (first?.physicalLocation !== undefined) {
+    uri = typeof first.physicalLocation.artifactLocation?.uri === 'string' ? first.physicalLocation.artifactLocation.uri : ''
+    const line = first.physicalLocation.region?.startLine
+    if (typeof line === 'number' && Number.isInteger(line) && line >= 1) startLine = line
+  }
+  const method = stringValue(report.method) ?? ''
+  const endpoint = stringValue(report.endpoint) ?? ''
+  const route = method !== '' || endpoint !== '' ? `${method.toUpperCase()} ${endpoint}`.trim() : ''
+  if (uri === '' && route === '') return null
+  const parts: string[] = [`rule:${ruleId}`]
+  if (uri !== '') {
+    parts.push(`uri:${uri}`)
+    if (startLine !== null) parts.push(`line:${String(startLine)}`)
+  }
+  if (route !== '') parts.push(`route:${route}`)
+  if (isSynthetic) {
+    const title = stringValue(report.title)
+    if (title !== null) parts.push(`synth_class:${classKeyword(title)}`)
+  }
+  return sha256(parts.join('|'))
+}
+
+/** File-independent class fingerprint (sarif.py `_class_fingerprint`). */
+function classFingerprint(ruleId: string, report: VulnerabilityReport): string | null {
+  const title = stringValue(report.title)
+  if (title === null) return null
+  const keyword = classKeyword(title)
+  if (keyword === '') return null
+  return sha256(`rule:${ruleId}|class:${keyword}`)
+}
+
+/** PR-suggestion fixes from fix-bearing code locations (sarif.py `_build_fixes`). */
+function buildFixes(report: VulnerabilityReport): Json[] | null {
+  const artifactChanges: Json[] = []
+  if (!Array.isArray(report.code_locations)) return null
+  for (const raw of report.code_locations) {
+    if (typeof raw !== 'object' || raw === null) continue
+    const location = raw as Record<string, unknown>
+    const file = stringValue(location['file'])
+    const fixBefore = stringValue(location['fix_before'])
+    const fixAfter = stringValue(location['fix_after'])
+    const startLine = location['start_line']
+    if (file === null || fixBefore === null || fixAfter === null) continue
+    if (typeof startLine !== 'number' || !Number.isInteger(startLine) || startLine < 1) continue
+    const uri = sarifUri(file)
+    if (uri === null) continue
+    const deletedRegion: { [key: string]: Json } = { startLine }
+    const endLine = location['end_line']
+    if (typeof endLine === 'number' && Number.isInteger(endLine) && endLine >= startLine) deletedRegion['endLine'] = endLine
+    artifactChanges.push({
+      artifactLocation: { uri },
+      replacements: [{ deletedRegion, insertedContent: { text: fixAfter } }],
+    })
+  }
+  if (artifactChanges.length === 0) return null
+  const fix: { [key: string]: Json } = { artifactChanges }
+  const remediation = stringValue(report.remediation_steps)
+  if (remediation !== null) fix['description'] = { text: remediation, markdown: remediation }
+  return [fix]
+}
+
+/** Result properties (security-severity, class hash, synthetic flag, strix tree). */
+function resultProperties(report: VulnerabilityReport, classFp: string | null, isSynthetic: boolean): { [key: string]: Json } {
+  const properties: { [key: string]: Json } = { 'security-severity': securitySeverity(report) }
+  if (classFp !== null) properties['sharpkit_vuln_class_hash'] = classFp
+  if (isSynthetic) properties['synthetic_location'] = true
+  const sharpkitProps: { [key: string]: Json } = {}
+  for (const key of [
+    'id', 'severity', 'cvss', 'timestamp', 'target', 'endpoint', 'method', 'cve', 'cwe', 'impact',
+    'technical_analysis', 'remediation_steps', 'counterevidence', 'confidence', 'confidence_rationale',
+    'severity_change_conditions', 'fix_verification',
+  ]) {
+    const value = (report as unknown as Record<string, unknown>)[key]
+    if (value !== null && value !== undefined && value !== '') sharpkitProps[key] = value as Json
+  }
+  const metadata = (report as unknown as Record<string, unknown>)['dependency_metadata']
+  if (typeof metadata === 'object' && metadata !== null && Object.keys(metadata).length > 0) sharpkitProps['dependency_metadata'] = metadata as Json
+  const pocDescription = stringValue(report.poc_description)
+  const pocScript = stringValue(report.poc_script_code)
+  if (pocDescription !== null || pocScript !== null) {
+    const poc: { [key: string]: Json } = {}
+    if (pocDescription !== null) poc['description'] = pocDescription
+    if (pocScript !== null) poc['script_available'] = true
+    sharpkitProps['poc'] = poc
+  }
+  if (Object.keys(sharpkitProps).length > 0) properties['sharpkit'] = sharpkitProps
+  return properties
+}
+
+/** Build one rule descriptor (sarif.py `_build_rule` key order). */
+function buildRule(ruleId: string, report: VulnerabilityReport): { [key: string]: Json } {
+  const title = stringValue(report.title) ?? ruleId
+  const fullDescription = stringValue(report.description) ?? title
+  const help = helpText(report, fullDescription)
+  const rule: { [key: string]: Json } = {
+    id: ruleId,
+    name: title !== '' ? title : ruleId.replace(/-/g, '_'),
+    shortDescription: { text: title },
+    fullDescription: { text: fullDescription },
+    defaultConfiguration: { level: sarifLevel(report.severity) },
+    help: { text: help, markdown: help },
+  }
+  const properties: { [key: string]: Json } = { 'security-severity': securitySeverity(report) }
+  const tags: string[] = ['security']
+  if (ruleId.startsWith('CWE-')) tags.push(ruleId)
+  const cve = stringValue(report.cve)
+  if (cve !== null && !tags.includes(cve)) tags.push(cve)
+  for (const leg of strideLegsForCwe(report.cwe)) {
+    const tag = `stride:${leg}`
+    if (!tags.includes(tag)) tags.push(tag)
+  }
+  properties['tags'] = tags
+  rule['properties'] = properties
+  if (ruleId.startsWith('CWE-')) rule['helpUri'] = `https://cwe.mitre.org/data/definitions/${ruleId.slice('CWE-'.length)}.html`
+  return rule
+}
+
+/** Build one result (sarif.py `_build_result` key order). */
+function buildResult(ruleId: string, ruleIndex: number, report: VulnerabilityReport): { readonly result: { [key: string]: Json }; readonly synthetic: boolean; readonly dropped: number } {
+  const title = stringValue(report.title) ?? ruleId
+  const description = stringValue(report.description)
+  const messageText = description !== null ? `${title}\n\n${description}` : title
+  const { locations, isSynthetic, dropped } = buildLocations(report)
+  const result: { [key: string]: Json } = {
+    ruleId,
+    ruleIndex,
+    level: sarifLevel(report.severity),
+    message: { text: messageText },
+  }
+  if (locations.length > 0) result['locations'] = locations
+  const fixes = buildFixes(report)
+  if (fixes !== null) result['fixes'] = fixes
+  const fingerprint = primaryFingerprint(ruleId, report, locations, isSynthetic)
+  if (fingerprint !== null) result['partialFingerprints'] = { primaryLocationLineHash: fingerprint }
+  result['properties'] = resultProperties(report, classFingerprint(ruleId, report), isSynthetic)
+  return { result, synthetic: isSynthetic, dropped }
+}
+
+/** One coverage entry projected into SARIF (strix coverage.py shape). */
+export interface SarifCoverageEntry {
+  readonly risk_area: string
+  readonly surface: string
+  readonly outcome: string
+  readonly evidence?: unknown
+  readonly recorded_by?: unknown
+}
+
+/** The coverage document subset the SARIF bridge consumes. */
+export interface SarifCoverage {
+  readonly entries: readonly SarifCoverageEntry[]
+  readonly completeness?: { readonly complete?: boolean; readonly caveats?: readonly string[] } | undefined
+}
+
+/** Coverage outcome → SARIF result kind (`reported` deliberately absent). */
+const OUTCOME_TO_KIND: Readonly<Record<string, string>> = {
+  no_issue_found: 'pass',
+  ruled_out: 'pass',
+  not_applicable: 'notApplicable',
+  needs_follow_up: 'open',
+}
+
+const OUTCOME_LABELS: Readonly<Record<string, string>> = {
+  reported: 'Finding reported',
+  no_issue_found: 'No issue identified',
+  ruled_out: 'Ruled out',
+  not_applicable: 'Not applicable',
+  needs_follow_up: 'Requires further review',
+}
+
+export interface SarifOptions {
+  readonly toolVersion: string
+  readonly coverage?: SarifCoverage | undefined
+  /** Exactly-one-repository provenance (strix passes None in our port for now). */
+  readonly repositoryContext?: {
+    readonly repositoryUri?: string
+    readonly repositoryFullName?: string
+    readonly commitSha?: string
+    readonly branch?: string
+    readonly ref?: string
+  } | undefined
+}
+
+/**
+ * Build the full SARIF document (top-level key order and run properties).
+ * Coverage results and invocations join when the coverage tool lands (批 4).
+ * @param reports - all stored reports.
+ * @param options - tool version and optional repository provenance.
+ */
+export function buildSarif(reports: readonly VulnerabilityReport[], options: SarifOptions): { [key: string]: Json } {
+  const rules: { [key: string]: Json }[] = []
+  const ruleIndex = new Map<string, number>()
+  const results: Json[] = []
+  let syntheticCount = 0
+  const droppedFindings: { [key: string]: Json }[] = []
+  let droppedLocationCount = 0
+  for (const report of reports) {
+    const id = ruleIdOf(report)
+    let index = ruleIndex.get(id)
+    if (index === undefined) {
+      index = rules.length
+      ruleIndex.set(id, index)
+      rules.push(buildRule(id, report))
+    }
+    const { result, synthetic, dropped } = buildResult(id, index, report)
+    if (synthetic) syntheticCount++
+    if (dropped > 0) {
+      droppedLocationCount += dropped
+      droppedFindings.push({ droppedLocationCount: dropped, id: report.id, title: report.title })
+    }
+    results.push(result)
+  }
+  const driver: { [key: string]: Json } = {
+    name: TOOL_NAME,
+    informationUri: TOOL_INFORMATION_URI,
+    rules,
+    version: options.toolVersion,
+  }
+  const run: { [key: string]: Json } = { tool: { driver }, results }
+  if (options.coverage !== undefined) appendCoverage(run, options.coverage, ruleIndex, rules)
+  const runProperties: { [key: string]: Json } = {}
+  if (syntheticCount > 0) runProperties['syntheticLocationCount'] = syntheticCount
+  if (droppedLocationCount > 0) {
+    runProperties['droppedUnsafeLocationCount'] = droppedLocationCount
+    runProperties['droppedUnsafeLocationFindings'] = droppedFindings
+  }
+  const repo = options.repositoryContext
+  if (repo !== undefined) {
+    const provenance: { [key: string]: Json } = {}
+    if (repo.repositoryUri !== undefined) provenance['repositoryUri'] = repo.repositoryUri
+    if (repo.commitSha !== undefined) provenance['revisionId'] = repo.commitSha
+    if (repo.branch !== undefined) provenance['branch'] = repo.branch
+    if (Object.keys(provenance).length > 0) run['versionControlProvenance'] = [provenance]
+    if (repo.repositoryFullName !== undefined) runProperties['repository'] = repo.repositoryFullName
+    if (repo.ref !== undefined) runProperties['ref'] = repo.ref
+    if (repo.commitSha !== undefined) runProperties['commit_sha'] = repo.commitSha
+  }
+  if (Object.keys(runProperties).length > 0) run['properties'] = runProperties
+  return { version: SARIF_VERSION, $schema: SARIF_SCHEMA, runs: [run] }
+}
+
+/** Coverage rule + result builders and the run invocation (sarif.py :641-747). */
+function appendCoverage(run: { [key: string]: Json }, coverage: SarifCoverage, ruleIndex: Map<string, number>, rules: { [key: string]: Json }[]): void {
+  const coverageResults: Json[] = []
+  for (const entry of coverage.entries) {
+    const outcome = typeof entry.outcome === 'string' ? entry.outcome : ''
+    const kind = OUTCOME_TO_KIND[outcome]
+    if (kind === undefined) continue
+    const riskArea = typeof entry.risk_area === 'string' ? entry.risk_area : ''
+    const ruleId = `sharpkit-coverage/${riskArea === '' ? 'unspecified' : slugify(riskArea)}`
+    let index = ruleIndex.get(ruleId)
+    if (index === undefined) {
+      index = rules.length
+      ruleIndex.set(ruleId, index)
+      const name = riskArea !== '' ? riskArea : ruleId.replaceAll('-', '_')
+      const description = `Coverage: ${riskArea}`
+      rules.push({
+        id: ruleId,
+        name,
+        shortDescription: { text: description },
+        fullDescription: { text: description },
+        defaultConfiguration: { level: 'none' },
+        help: { text: description, markdown: description },
+        properties: { tags: ['coverage'] },
+      })
+    }
+    const label = OUTCOME_LABELS[outcome] ?? outcome
+    const surface = typeof entry.surface === 'string' ? entry.surface : ''
+    let messageText = `${riskArea} — ${label}: ${surface}`
+    const evidence = typeof entry.evidence === 'string' && entry.evidence !== '' ? entry.evidence : null
+    if (evidence !== null) messageText += `\n\n${evidence}`
+    const sharpkitProps: { [key: string]: Json } = { coverage_outcome: outcome, risk_area: riskArea, surface }
+    if (entry.recorded_by !== undefined && entry.recorded_by !== null) sharpkitProps['recorded_by'] = entry.recorded_by as Json
+    sharpkitProps['source'] = 'agent_reported'
+    coverageResults.push({
+      ruleId,
+      ruleIndex: index,
+      kind,
+      level: 'none',
+      message: { text: messageText },
+      locations: [{ logicalLocations: [{ fullyQualifiedName: surface }] }],
+      properties: { sharpkit: sharpkitProps },
+    })
+  }
+  if (coverageResults.length > 0) {
+    const existing = run['results']
+    run['results'] = [...(Array.isArray(existing) ? existing : []), ...coverageResults]
+  }
+  const invocation: { [key: string]: Json } = { executionSuccessful: coverage.completeness?.complete ?? true }
+  const caveats = coverage.completeness?.caveats?.filter(caveat => caveat !== '')
+  if (caveats !== undefined && caveats.length > 0) {
+    invocation['toolExecutionNotifications'] = caveats.map(caveat => ({ level: 'warning', message: { text: caveat } }))
+  }
+  run['invocations'] = [invocation]
+}
+
+/**
+ * Write findings.sarif (temp sibling + rename, trailing newline; sarif.py
+ * `write_sarif_report`). Always emitted, even with zero findings, so a fresh
+ * empty doc overwrites stale results.
+ * @param runDir - the run directory.
+ * @param reports - all stored reports.
+ * @param options - tool version and provenance.
+ */
+export async function writeSarif(runDir: string, reports: readonly VulnerabilityReport[], options: SarifOptions): Promise<void> {
+  const output = join(runDir, 'findings.sarif')
+  const temp = `${output}.${process.pid}.tmp`
+  try {
+    await writeFile(temp, `${dumpsIndent(buildSarif(reports, options))}\n`, 'utf8')
+    await rename(temp, output)
+  } finally {
+    await rm(temp, { force: true }).catch(() => {})
+  }
+}
+
+/** Reproduce a fingerprint for tests (exposed for golden diagnostics). */
+export const internals = { primaryFingerprint, classFingerprint }