@gpzhang2001/sharpkit-reporting 0.2.1

package/lib/index.js

@@ -0,0 +1,2789 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createHash } from "node:crypto";
+//#region src/cvss.ts
+/**
+* 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`). */
+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"
+	]
+};
+/** The eight metrics in vector order (strix vector build order). */
+const METRIC_ORDER = [
+	"attack_vector",
+	"attack_complexity",
+	"privileges_required",
+	"user_interaction",
+	"scope",
+	"confidentiality",
+	"integrity",
+	"availability"
+];
+/** Weight tables (CVSS v3.1 spec §3.1). */
+const AV = {
+	N: .85,
+	A: .62,
+	L: .55,
+	P: .2
+};
+const AC = {
+	L: .77,
+	H: .44
+};
+const PR_UNCHANGED = {
+	N: .85,
+	L: .62,
+	H: .27
+};
+const PR_CHANGED = {
+	N: .85,
+	L: .68,
+	H: .5
+};
+const UI = {
+	N: .85,
+	R: .62
+};
+const CIA = {
+	H: .56,
+	L: .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) {
+	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.
+*/
+function validateCvssBreakdown(breakdown) {
+	const errors = [];
+	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.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.
+*/
+function buildCvssVector(breakdown) {
+	return `CVSS:3.1/${METRIC_ORDER.map((metric) => {
+		return `${{
+			attack_vector: "AV",
+			attack_complexity: "AC",
+			privileges_required: "PR",
+			user_interaction: "UI",
+			scope: "S",
+			confidentiality: "C",
+			integrity: "I",
+			availability: "A"
+		}[metric]}:${breakdown[metric]}`;
+	}).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).
+*/
+function cvssBaseScore(breakdown) {
+	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 - .029) - 3.25 * (iscBase - .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);
+	return roundup(scopeChanged ? Math.min(1.08 * (isc + exploitability), 10) : Math.min(isc + exploitability, 10));
+}
+/**
+* Qualitative severity banding (the `cvss` package's rating bands).
+* @param score - the base score.
+*/
+function cvssSeverity(score) {
+	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.
+*/
+function calculateCvss(breakdown) {
+	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.
+*/
+function dependencySeverity(score) {
+	if (score === null || score === void 0 || Number.isNaN(score)) return "info";
+	const clamped = Math.min(10, Math.max(0, score));
+	if (clamped >= 9) return "critical";
+	if (clamped >= 7) return "high";
+	if (clamped >= 4) return "medium";
+	if (clamped >= 0) return "low";
+	return "none";
+}
+//#endregion
+//#region src/dedupe.ts
+/** Extract the dependency identity from metadata (strix :162-177). */
+function dependencyIdentity(metadata) {
+	if (typeof metadata !== "object" || metadata === null) return null;
+	const record = metadata;
+	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`). */
+function distinctManifestPaths(a, b) {
+	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`). */
+function legacyReportMentionsPackage(report, identity) {
+	const fields = [
+		"title",
+		"description",
+		"impact",
+		"target",
+		"technical_analysis",
+		"poc_description",
+		"evidence"
+	];
+	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[field];
+		if (typeof value !== "string") continue;
+		if (packagePattern.test(value) && ecosystemPattern.test(value)) return true;
+	}
+	return false;
+}
+function escapeRegExp(value) {
+	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.
+*/
+function checkDependencyDuplicate(candidateIdentity, candidateMetadata, existing) {
+	let sawLegacySameCve = false;
+	for (const report of existing) {
+		const metadata = report["dependency_metadata"];
+		const identity = dependencyIdentity(metadata);
+		if (identity === null) {
+			if (String(report["cve"] ?? "").toUpperCase() === candidateIdentity.cve) {
+				sawLegacySameCve = true;
+				if (legacyReportMentionsPackage(report, candidateIdentity)) return {
+					isDuplicate: true,
+					duplicateId: report.id,
+					confidence: 1,
+					reason: "Same dependency CVE/package identity (legacy report)"
+				};
+			}
+			continue;
+		}
+		if (identity.cve !== candidateIdentity.cve || identity.packageName !== candidateIdentity.packageName) continue;
+		const existingMetadata = report["dependency_metadata"];
+		if (distinctManifestPaths(candidateMetadata?.["manifest_path"], existingMetadata["manifest_path"])) continue;
+		if (identity.ecosystem === candidateIdentity.ecosystem) return {
+			isDuplicate: true,
+			duplicateId: report.id,
+			confidence: 1,
+			reason: "Same dependency CVE/package identity"
+		};
+		return {
+			isDuplicate: true,
+			duplicateId: report.id,
+			confidence: 1,
+			reason: "Same dependency CVE/package identity with missing ecosystem"
+		};
+	}
+	if (sawLegacySameCve) return null;
+	return {
+		isDuplicate: false,
+		duplicateId: "",
+		confidence: 1,
+		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).
+*/
+async function checkDuplicate(candidate, candidateMetadata, existing, judge) {
+	if (existing.length === 0) return {
+		isDuplicate: false,
+		duplicateId: "",
+		confidence: 1,
+		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 === void 0) return {
+		isDuplicate: false,
+		duplicateId: "",
+		confidence: 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,
+			reason: `Deduplication check failed: ${String(error instanceof Error ? error.message : error)}`
+		};
+	}
+}
+//#endregion
+//#region src/state.ts
+/** strix display timestamp format (state.py :349). */
+function formatTimestamp(date) {
+	const pad = (value) => String(value).padStart(2, "0");
+	return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} UTC`;
+}
+/** strix ISO instant format (start/end times). */
+function formatIso(date) {
+	return date.toISOString().replace("Z", "+00:00");
+}
+/** Control-char → space + whitespace collapse (state.py `_clean_title`). */
+function cleanTitle(title) {
+	return title.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+}
+/** strix severity order (tool.py `_SEVERITY_ORDER`). */
+const SEVERITY_ORDER = [
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info",
+	"none"
+];
+/** Severity rank with unknown → last (writer parity). */
+function severityRank(severity) {
+	const index = SEVERITY_ORDER.indexOf(severity);
+	return index === -1 ? SEVERITY_ORDER.length : index;
+}
+/** Field insertion order for optional string fields (state.py :352-396). */
+const OPTIONAL_STRING_FIELDS = [
+	"description",
+	"impact",
+	"target",
+	"technical_analysis",
+	"poc_description",
+	"poc_script_code",
+	"remediation_steps",
+	"evidence",
+	"assumptions",
+	"counterevidence",
+	"confidence_rationale",
+	"severity_change_conditions",
+	"fix_verification",
+	"fix_pr_body",
+	"endpoint",
+	"method",
+	"cve"
+];
+/** Lowercased optional fields (state.py `_LOWERCASE_REPORT_FIELDS` subset). */
+const LOWERCASE_FIELDS = /* @__PURE__ */ new Set(["confidence", "fix_effort"]);
+/** Updatable field whitelist (state.py `UPDATABLE_REPORT_FIELDS`). */
+const UPDATABLE_REPORT_FIELDS = /* @__PURE__ */ new Set([
+	"title",
+	"dependency_metadata",
+	"severity",
+	"description",
+	"impact",
+	"target",
+	"technical_analysis",
+	"poc_description",
+	"poc_script_code",
+	"remediation_steps",
+	"evidence",
+	"assumptions",
+	"counterevidence",
+	"confidence",
+	"confidence_rationale",
+	"severity_change_conditions",
+	"fix_effort",
+	"cvss",
+	"cvss_breakdown",
+	"endpoint",
+	"method",
+	"cve",
+	"cwe",
+	"code_locations",
+	"fix_verification",
+	"fix_pr_body"
+]);
+/** Dependent fields dropped when their primary changes without replacement. */
+const DEPENDENT_REPORT_FIELDS = {
+	confidence: "confidence_rationale",
+	severity: "severity_change_conditions",
+	cvss: "cvss_breakdown",
+	code_locations: "fix_verification"
+};
+/**
+* One scan's report store. Not a process singleton — the suite runs one per
+* scan id inside the tool package's closure (strix's module-global maps to a
+* per-scan instance in dsh).
+*/
+var ReportState = class {
+	runId;
+	runName;
+	startTime;
+	endTime = null;
+	status = "running";
+	finalScanResult = null;
+	vulnerabilityReports = [];
+	/** Ids already rendered to markdown (incremental writer input). */
+	savedVulnIds = /* @__PURE__ */ new Set();
+	updateHistoryAgent;
+	clock;
+	constructor(options = {}) {
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		this.runId = options.runId ?? `run-${Math.random().toString(16).slice(2, 10)}`;
+		this.runName = options.runName ?? null;
+		this.startTime = formatIso(this.clock());
+	}
+	/** Allocate the next sequential id (state.py :343 — length-derived). */
+	nextId() {
+		return `vuln-${String(this.vulnerabilityReports.length + 1).padStart(4, "0")}`;
+	}
+	/**
+	* Add one report with strix's exact field construction order.
+	* @param input - the validated/normalized create payload.
+	*/
+	addVulnerabilityReport(input) {
+		const report = {
+			id: this.nextId(),
+			title: cleanTitle(input.title),
+			severity: input.severity.toLowerCase().trim(),
+			timestamp: formatTimestamp(this.clock())
+		};
+		for (const field of OPTIONAL_STRING_FIELDS) {
+			const value = input.fields[field];
+			if (typeof value === "string" && value.trim() !== "") report[field] = value.trim();
+		}
+		const confidence = input.fields["confidence"];
+		if (typeof confidence === "string" && confidence.trim() !== "") report["confidence"] = confidence.trim().toLowerCase();
+		const fixEffort = input.fields["fix_effort"];
+		if (typeof fixEffort === "string" && fixEffort.trim() !== "") report["fix_effort"] = fixEffort.trim().toLowerCase();
+		const cvss = input.fields["cvss"];
+		if (cvss !== null && cvss !== void 0) report["cvss"] = cvss;
+		const breakdown = input.fields["cvss_breakdown"];
+		if (breakdown !== null && breakdown !== void 0 && Object.keys(breakdown).length > 0) report["cvss_breakdown"] = breakdown;
+		const cwe = input.fields["cwe"];
+		if (typeof cwe === "string" && cwe.trim() !== "") report["cwe"] = cwe.trim();
+		const codeLocations = input.fields["code_locations"];
+		if (codeLocations !== null && codeLocations !== void 0 && codeLocations.length > 0) report["code_locations"] = codeLocations;
+		report["finding_class"] = (input.findingClass ?? "dynamic").toLowerCase().trim();
+		if (input.dependencyMetadata !== void 0 && Object.keys(input.dependencyMetadata).length > 0) report["dependency_metadata"] = input.dependencyMetadata;
+		if (input.agentId !== void 0 && input.agentId !== "") report["agent_id"] = input.agentId;
+		if (input.agentName !== void 0 && input.agentName !== "") report["agent_name"] = input.agentName;
+		const frozen = report;
+		this.vulnerabilityReports.push(frozen);
+		return frozen;
+	}
+	/**
+	* Revise one report in place (state.py `update_vulnerability_report`):
+	* whitelist + strip/lowercase, unchanged-skip, dependent-field dropping,
+	* history append, and the MD invalidation marker.
+	* @param reportId - the `vuln-NNNN` id.
+	* @param changes - only the fields the model passed.
+	* @param reason - the update_reason (truncated to 500).
+	*/
+	updateVulnerabilityReport(reportId, changes, reason) {
+		const report = this.vulnerabilityReports.find((entry) => entry.id === reportId);
+		if (report === void 0) return { noop: true };
+		const mutable = report;
+		const changed = [];
+		const dropped = [];
+		const history = {
+			timestamp: formatTimestamp(this.clock()),
+			fields: [],
+			reason: reason.slice(0, 500),
+			...this.updateHistoryAgent?.agentId !== void 0 ? { agent_id: this.updateHistoryAgent.agentId } : {},
+			...this.updateHistoryAgent?.agentName !== void 0 ? { agent_name: this.updateHistoryAgent.agentName } : {}
+		};
+		const previous = {};
+		for (const [field, rawValue] of Object.entries(changes)) {
+			if (!UPDATABLE_REPORT_FIELDS.has(field)) continue;
+			let value = rawValue;
+			if (field === "title" && typeof value === "string") value = cleanTitle(value);
+			else if (typeof value === "string") value = value.trim();
+			if (LOWERCASE_FIELDS.has(field) && typeof value === "string") value = value.toLowerCase();
+			if (Object.is(mutable[field], value)) continue;
+			if (JSON.stringify(mutable[field]) === JSON.stringify(value)) continue;
+			if (mutable[field] !== void 0) {
+				if (field === "severity") previous.severity = mutable["severity"];
+				if (field === "cvss") previous.cvss = mutable["cvss"];
+				if (field === "confidence") previous.confidence = mutable["confidence"];
+			}
+			const dependent = DEPENDENT_REPORT_FIELDS[field];
+			if (dependent !== void 0 && mutable[dependent] !== void 0 && changes[dependent] === void 0) {
+				delete mutable[dependent];
+				dropped.push(dependent);
+			}
+			mutable[field] = value;
+			changed.push(field);
+		}
+		if (changed.length === 0 && dropped.length === 0) return { noop: true };
+		history.fields = [...changed].sort();
+		if (dropped.length > 0) history.dropped_fields = [...dropped].sort();
+		if (previous.severity !== void 0) history.previous_severity = previous.severity;
+		if (previous.cvss !== void 0) history.previous_cvss = previous.cvss;
+		if (previous.confidence !== void 0) history.previous_confidence = previous.confidence;
+		const historyList = mutable["update_history"] ?? [];
+		historyList.push(history);
+		mutable["update_history"] = historyList;
+		mutable["updated_at"] = history.timestamp;
+		this.savedVulnIds.delete(reportId);
+		return { report };
+	}
+	/**
+	* Reload from a previous run's vulnerabilities.json so id allocation does
+	* not collide (state.py `hydrate_from_run_dir`; raises on corrupt JSON).
+	* @param reports - the parsed JSON array.
+	*/
+	hydrate(reports) {
+		if (!Array.isArray(reports)) throw new Error("corrupt vulnerabilities.json: expected a list of reports");
+		for (const entry of reports) {
+			const report = entry;
+			if (report["finding_class"] === void 0) report["finding_class"] = report["dependency_metadata"] !== void 0 ? "dependency_cve" : "dynamic";
+			if (typeof report["title"] === "string") report["title"] = cleanTitle(report["title"]);
+			this.vulnerabilityReports.push(report);
+			if (typeof report["id"] === "string") this.savedVulnIds.add(report["id"]);
+		}
+	}
+	/** Mark the run complete (status transition + end time). */
+	complete(exitStatus = "completed") {
+		this.endTime = formatIso(this.clock());
+		this.status = exitStatus;
+	}
+};
+//#endregion
+//#region src/writers.ts
+/**
+* Artifact writers — port of strix report/writer.py: atomic writes
+* (temp-in-same-dir + rename, no fsync), run.json, vulnerabilities.csv
+* (formula-injection guard, \r\n terminators, uppercase severity,
+* severity-then-timestamp ordering), vulnerabilities.json (byte-identical
+* serialization), the vuln-NNNN.md renderer (exact section order), and the
+* executive report template.
+* @module @gpzhang2001/sharpkit-reporting/writers
+*/
+/** JSON.stringify with Python `json.dumps(ensure_ascii=False, indent=2)` parity. */
+function dumpsIndent(value) {
+	return JSON.stringify(value, null, 2);
+}
+/**
+* Atomic text write (writer.py `atomic_write_text` :201-220): temp file in
+* the target's directory + rename; no fsync (strix parity).
+* @param path - target file path.
+* @param payload - exact bytes to write.
+*/
+async function atomicWriteText(path, payload) {
+	await mkdir(dirname(path), { recursive: true });
+	const temp = `${dirname(path)}/.${join("", basenameOf(path))}.${process.pid}.tmp`;
+	await writeFile(temp, payload, "utf8");
+	await rename(temp, path);
+}
+function basenameOf(path) {
+	const index = path.lastIndexOf("/");
+	return index === -1 ? path : path.slice(index + 1);
+}
+/**
+* Formula-injection guard (writer.py `csv_safe` :35-53): prefix `'` when the
+* rendered cell starts with `= + - @ \t \r`.
+* @param value - the cell value.
+*/
+function csvSafe(value) {
+	return /^[=+\-@\t\r]/.test(value) ? `'${value}` : value;
+}
+/** CSV columns (writer.py :165-184). */
+const CSV_COLUMNS = [
+	"id",
+	"title",
+	"severity",
+	"timestamp",
+	"file"
+];
+/** CSV-escape one cell per RFC 4180 as Python's csv module does. */
+function csvCell(value) {
+	const safe = csvSafe(value);
+	if (safe.includes("\"") || safe.includes(",") || safe.includes("\r") || safe.includes("\n")) return `"${safe.replace(/"/g, "\"\"")}"`;
+	return safe;
+}
+/**
+* Render vulnerabilities.csv: header + rows sorted by (severity rank,
+* timestamp), uppercase severity, \r\n terminators.
+* @param reports - the stored reports.
+*/
+function renderVulnerabilitiesCsv(reports) {
+	const sorted = [...reports].sort((a, b) => severityRank(String(a.severity)) - severityRank(String(b.severity)) || String(a.timestamp).localeCompare(String(b.timestamp)));
+	const lines = [CSV_COLUMNS.join(",")];
+	for (const report of sorted) {
+		const cells = [
+			csvCell(String(report.id)),
+			csvCell(String(report.title)),
+			csvCell(String(report.severity).toUpperCase()),
+			csvCell(String(report.timestamp)),
+			csvCell(`vulnerabilities/${String(report.id)}.md`)
+		];
+		lines.push(cells.join(","));
+	}
+	return `${lines.join("\r\n")}\r\n`;
+}
+/** title-case one word (strix Confidence/Fix Effort display). */
+function titleCase(value) {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/** Safe fence length: one longer than the longest backtick run (writer.py :56-66). */
+function safeFence(code) {
+	let longest = 0;
+	let current = 0;
+	for (const char of code) if (char === "`") {
+		current++;
+		longest = Math.max(longest, current);
+	} else current = 0;
+	return "`".repeat(Math.max(3, longest + 1));
+}
+/** Unwrap an existing fence and return its language (writer.py :69-82). */
+function parseFencedCode(code) {
+	const match = /^```([A-Za-z0-9_+-]*)\n([\s\S]*?)\n?```$/.exec(code.trim());
+	if (match === null) return {
+		language: "",
+		body: code
+	};
+	return {
+		language: match[1] ?? "",
+		body: match[2] ?? ""
+	};
+}
+/** Guess a fenced language for a PoC script (writer.py :107-116). */
+function guessLanguageName(code) {
+	if (/^\s*(import |from |def |class |print\()/.test(code)) return "python";
+	if (/^\s*(const |let |var |function |require\()/.test(code)) return "javascript";
+	if (/^\s*(curl |GET |POST |PUT |DELETE )/.test(code)) return "bash";
+	return "python";
+}
+/** Metadata lines of the vuln markdown header block (writer.py :222-259 order). */
+function renderMetadataLines(report) {
+	const lines = [
+		`**ID:** ${String(report["id"])}`,
+		`**Severity:** ${String(report["severity"]).toUpperCase()}`,
+		`**Found:** ${String(report["timestamp"])}`
+	];
+	const depMeta = report["dependency_metadata"] ?? {};
+	const cvss = report["cvss"];
+	const metadata = [
+		["Target", report["target"]],
+		["Package", depMeta["package_name"]],
+		["Ecosystem", depMeta["package_ecosystem"]],
+		["Installed Version", depMeta["installed_version"]],
+		["Fixed Version", depMeta["fixed_version"]],
+		["Introduced By", depMeta["introduced_by"]],
+		["Dependency Chain", depMeta["dependency_path"]],
+		["Endpoint", report["endpoint"]],
+		["Method", report["method"]],
+		["CVE", report["cve"]],
+		["CWE", report["cwe"]]
+	];
+	if (cvss !== null && cvss !== void 0) metadata.push(["CVSS", cvss]);
+	const advisory = depMeta["advisory_cvss"];
+	if (advisory !== null && advisory !== void 0 && advisory !== cvss) metadata.push(["Advisory CVSS", advisory]);
+	if (depMeta["contextual_cvss_vector"] !== void 0 && depMeta["contextual_cvss_vector"] !== null && depMeta["contextual_cvss_vector"] !== "") metadata.push(["Contextual CVSS Vector", depMeta["contextual_cvss_vector"]]);
+	if (report["confidence"] !== void 0 && report["confidence"] !== null && report["confidence"] !== "") metadata.push(["Confidence", titleCase(String(report["confidence"]))]);
+	if (report["fix_effort"] !== void 0 && report["fix_effort"] !== null && report["fix_effort"] !== "") metadata.push(["Fix Effort", titleCase(String(report["fix_effort"]))]);
+	for (const [label, value] of metadata) if (value !== null && value !== void 0 && value !== "") lines.push(`**${label}:** ${String(value)}`);
+	return lines;
+}
+/** One code-location section (writer.py :315-342, 2-space indents verbatim). */
+function renderCodeLocation(location, index) {
+	const lines = ["## Code Analysis", ""];
+	const file = String(location["file"] ?? "unknown");
+	const start = location["start_line"];
+	const end = location["end_line"];
+	let lineLabel = "";
+	if (start !== null && start !== void 0) lineLabel = end !== void 0 && end !== null && end !== start ? ` (lines ${String(start)}-${String(end)})` : ` (line ${String(start)})`;
+	lines.push(`**Location ${String(index + 1)}:** \`${file}\`${lineLabel}`);
+	const label = location["label"];
+	if (typeof label === "string" && label !== "") lines.push(`  ${label}`);
+	const snippet = location["snippet"];
+	if (typeof snippet === "string" && snippet !== "") {
+		const fence = safeFence(snippet);
+		lines.push(`  ${fence}`);
+		for (const line of snippet.split("\n")) lines.push(`  ${line}`);
+		lines.push(`  ${fence}`);
+	}
+	const fixBefore = location["fix_before"];
+	const fixAfter = location["fix_after"];
+	if (typeof fixBefore === "string" && fixBefore !== "" || typeof fixAfter === "string" && fixAfter !== "") {
+		lines.push("");
+		lines.push("  **Suggested Fix:**");
+		lines.push("```diff");
+		if (typeof fixBefore === "string" && fixBefore !== "") for (const line of fixBefore.split("\n")) lines.push(`- ${line}`);
+		if (typeof fixAfter === "string" && fixAfter !== "") for (const line of fixAfter.split("\n")) lines.push(`+ ${line}`);
+		lines.push("```");
+	}
+	lines.push("");
+	return lines;
+}
+/** Update history section (writer.py `render_update_history` :364-396). */
+function renderUpdateHistory(report) {
+	const history = report["update_history"];
+	if (history === void 0 || history.length === 0) return [];
+	const lines = ["## Update History", ""];
+	for (const entry of history) {
+		const who = entry["agent_name"] ?? entry["agent_id"] ?? "an agent";
+		const fields = entry["fields"]?.join(", ") ?? "";
+		lines.push(`**${String(entry["timestamp"])}** — ${who} updated: ${fields}`);
+		const dropped = entry["dropped_fields"];
+		if (dropped !== void 0 && dropped.length > 0) lines.push(`  Dropped as superseded: ${dropped.join(", ")}`);
+		const previousSeverity = entry["previous_severity"];
+		if (typeof previousSeverity === "string") lines.push(`  Previous severity: ${previousSeverity}`);
+		const previousCvss = entry["previous_cvss"];
+		if (previousCvss !== void 0 && previousCvss !== null) lines.push(`  Previous CVSS: ${String(previousCvss)}`);
+		const previousConfidence = entry["previous_confidence"];
+		if (typeof previousConfidence === "string") lines.push(`  Previous confidence: ${previousConfidence}`);
+		const reason = entry["reason"];
+		if (typeof reason === "string" && reason !== "") lines.push(`  Reason: ${reason}`);
+		lines.push("");
+	}
+	return lines;
+}
+/**
+* Render one vulnerability markdown document (writer.py
+* `render_vulnerability_md` :223-361 section order).
+* @param report - the stored report dict.
+*/
+function renderVulnerabilityMd(report) {
+	const record = report;
+	const lines = [`# ${String(record["title"])}`, ""];
+	lines.push(...renderMetadataLines(record), "");
+	const section = (heading, field) => {
+		const value = record[field];
+		if (typeof value === "string" && value !== "") lines.push(`## ${heading}`, "", value, "");
+	};
+	section("Description", "description");
+	section("Evidence", "evidence");
+	section("Impact", "impact");
+	section("Counterevidence", "counterevidence");
+	section("Confidence Rationale", "confidence_rationale");
+	section("What Would Change This Severity", "severity_change_conditions");
+	section("Technical Analysis", "technical_analysis");
+	const contextualReasoning = record["dependency_metadata"]?.["contextual_cvss_reasoning"];
+	if (typeof contextualReasoning === "string" && contextualReasoning !== "") lines.push("## Contextual CVSS", "", contextualReasoning, "");
+	const pocDescription = record["poc_description"];
+	const pocScript = record["poc_script_code"];
+	if (typeof pocDescription === "string" && pocDescription !== "" || typeof pocScript === "string" && pocScript !== "") {
+		lines.push("## Proof of Concept", "");
+		if (typeof pocDescription === "string" && pocDescription !== "") lines.push(pocDescription, "");
+		if (typeof pocScript === "string" && pocScript !== "") {
+			const fenced = parseFencedCode(pocScript);
+			const language = fenced.language !== "" ? fenced.language : guessLanguageName(fenced.body);
+			const fence = safeFence(fenced.body);
+			lines.push(`${fence}${language}`, fenced.body, fence, "");
+		}
+	}
+	const locations = record["code_locations"];
+	if (locations !== void 0 && locations.length > 0) for (const [index, location] of locations.entries()) lines.push(...renderCodeLocation(location, index));
+	section("Remediation", "remediation_steps");
+	section("Fix Verification", "fix_verification");
+	section("Assumptions", "assumptions");
+	lines.push(...renderUpdateHistory(record));
+	return lines.join("\n");
+}
+/**
+* Write the per-run artifacts handled outside SARIF (writer.py parity):
+* vulnerabilities/*.md (incremental), vulnerabilities.csv,
+* vulnerabilities.json.
+* @param runDir - the run directory.
+* @param reports - all stored reports.
+* @param savedIds - ids whose MD is already on disk (updated ids must be re-rendered by the caller removing them).
+*/
+async function writeVulnerabilities(runDir, reports, savedIds) {
+	for (const report of reports) {
+		if (savedIds.has(report.id)) continue;
+		await atomicWriteText(join(runDir, "vulnerabilities", `${report.id}.md`), renderVulnerabilityMd(report));
+	}
+	await atomicWriteText(join(runDir, "vulnerabilities.csv"), renderVulnerabilitiesCsv(reports));
+	await atomicWriteText(join(runDir, "vulnerabilities.json"), dumpsIndent(reports));
+}
+/**
+* Write the assembled coverage document (coverage.py `write_coverage`).
+* @param runDir - the run directory.
+* @param document - the assembled coverage document.
+*/
+async function writeCoverage(runDir, document) {
+	await atomicWriteText(join(runDir, "coverage.json"), dumpsIndent(document));
+}
+/**
+* Write run.json last (state.py ordering).
+* @param runDir - the run directory.
+* @param runRecord - the run record dict.
+*/
+async function writeRunRecord(runDir, runRecord) {
+	await atomicWriteText(join(runDir, "run.json"), dumpsIndent(runRecord));
+}
+/**
+* Write the executive report (plain truncate-write, writer.py :139-145).
+* @param runDir - the run directory.
+* @param finalScanResult - the composed final report body.
+* @param generatedAt - display timestamp.
+*/
+async function writeExecutiveReport(runDir, finalScanResult, generatedAt) {
+	await mkdir(runDir, { recursive: true });
+	await writeFile(join(runDir, "penetration_test_report.md"), `# Security Penetration Test Report\n\n**Generated:** ${generatedAt}\n\n${finalScanResult}`, "utf8");
+}
+//#endregion
+//#region src/sarif.ts
+/**
+* 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
+*/
+const SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+const SARIF_VERSION = "2.1.0";
+const TOOL_NAME = "sharpkit";
+const TOOL_INFORMATION_URI = "https://github.com/gpzhang2001/sharpkit";
+const SYNTHETIC_LOCATION_URI = "SECURITY.md";
+const DEFAULT_STRIDE_LEGS = ["T", "I"];
+/** CWE → STRIDE legs (sarif.py `_CWE_TO_STRIDE`, verbatim). */
+const CWE_TO_STRIDE = {
+	"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 = [
+	"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 = {
+	critical: "error",
+	high: "error",
+	medium: "warning",
+	low: "note",
+	info: "note",
+	informational: "note"
+};
+const SEVERITY_TO_SCORE = {
+	critical: "9.5",
+	high: "8.0",
+	medium: "5.5",
+	low: "3.0",
+	info: "1.0",
+	informational: "1.0"
+};
+function stringValue(value) {
+	if (typeof value === "string") {
+		const stripped = value.trim();
+		return stripped === "" ? null : stripped;
+	}
+	return null;
+}
+function sha256(text) {
+	return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** CWE variants (`CWE-89` / `cwe: 89` / `89`) → `CWE-89`. */
+function normalizeCwe$1(value) {
+	const digits = value.replace(/\D/g, "");
+	return digits === "" ? null : `CWE-${digits}`;
+}
+/** Stable rule id: CWE → CVE → finding id → slug → sharpkit-finding. */
+function ruleIdOf(report) {
+	const cwe = stringValue(report.cwe);
+	if (cwe !== null) {
+		const normalized = normalizeCwe$1(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`). */
+function slugify(value) {
+	const slug = [...value.toLowerCase()].map((char) => /[a-z0-9]/.test(char) ? char : "-").join("").split("-").filter((part) => part !== "").join("-");
+	return slug === "" ? "sharpkit-finding" : slug;
+}
+/** STRIDE legs for a CWE, default legs when unmapped (every finding gets ≥1). */
+function strideLegsForCwe(cwe) {
+	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. */
+function classKeyword(title) {
+	const lower = title.toLowerCase();
+	for (const keyword of VULN_CLASS_KEYWORDS) if (lower.includes(keyword)) return keyword;
+	return (lower.match(/[a-z0-9]+/g)?.slice(0, 5) ?? []).join(" ");
+}
+/** SARIF level mapping. */
+function sarifLevel(severity) {
+	const normalized = (typeof severity === "string" ? severity : "").toLowerCase();
+	return SEVERITY_TO_LEVEL[normalized] ?? "note";
+}
+/** GitHub security-severity: "%.1f" CVSS else the label score. */
+function securitySeverity(report) {
+	if (report.cvss !== null && report.cvss !== void 0) {
+		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`). */
+function sarifUri(file) {
+	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, fallback) {
+	const sections = [
+		report.description,
+		report.impact,
+		report.remediation_steps
+	].filter((value) => typeof value === "string" && value.trim() !== "");
+	return sections.length > 0 ? sections.join("\n\n") : fallback;
+}
+/** Validated physical locations + dropped count (sarif.py `_build_physical_locations`). */
+function buildPhysicalLocations(rawLocations) {
+	const locations = [];
+	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;
+		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 = { artifactLocation: { uri } };
+		const region = { 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 = { 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) {
+	const physical = buildPhysicalLocations(report.code_locations);
+	const isSynthetic = physical.locations.length === 0;
+	const locations = 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, report, locations, isSynthetic) {
+	let uri = "";
+	let startLine = null;
+	const first = locations.find((location) => typeof location === "object" && location !== null && "physicalLocation" in location);
+	if (first?.physicalLocation !== void 0) {
+		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 = [`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, report) {
+	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) {
+	const artifactChanges = [];
+	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;
+		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 = { 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 = { 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, classFp, isSynthetic) {
+	const properties = { "security-severity": securitySeverity(report) };
+	if (classFp !== null) properties["sharpkit_vuln_class_hash"] = classFp;
+	if (isSynthetic) properties["synthetic_location"] = true;
+	const sharpkitProps = {};
+	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[key];
+		if (value !== null && value !== void 0 && value !== "") sharpkitProps[key] = value;
+	}
+	const metadata = report["dependency_metadata"];
+	if (typeof metadata === "object" && metadata !== null && Object.keys(metadata).length > 0) sharpkitProps["dependency_metadata"] = metadata;
+	const pocDescription = stringValue(report.poc_description);
+	const pocScript = stringValue(report.poc_script_code);
+	if (pocDescription !== null || pocScript !== null) {
+		const poc = {};
+		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, report) {
+	const title = stringValue(report.title) ?? ruleId;
+	const fullDescription = stringValue(report.description) ?? title;
+	const help = helpText(report, fullDescription);
+	const rule = {
+		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 = { "security-severity": securitySeverity(report) };
+	const tags = ["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(4)}.html`;
+	return rule;
+}
+/** Build one result (sarif.py `_build_result` key order). */
+function buildResult(ruleId, ruleIndex, report) {
+	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 = {
+		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
+	};
+}
+/** Coverage outcome → SARIF result kind (`reported` deliberately absent). */
+const OUTCOME_TO_KIND = {
+	no_issue_found: "pass",
+	ruled_out: "pass",
+	not_applicable: "notApplicable",
+	needs_follow_up: "open"
+};
+const OUTCOME_LABELS = {
+	reported: "Finding reported",
+	no_issue_found: "No issue identified",
+	ruled_out: "Ruled out",
+	not_applicable: "Not applicable",
+	needs_follow_up: "Requires further review"
+};
+/**
+* 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.
+*/
+function buildSarif(reports, options) {
+	const rules = [];
+	const ruleIndex = /* @__PURE__ */ new Map();
+	const results = [];
+	let syntheticCount = 0;
+	const droppedFindings = [];
+	let droppedLocationCount = 0;
+	for (const report of reports) {
+		const id = ruleIdOf(report);
+		let index = ruleIndex.get(id);
+		if (index === void 0) {
+			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 run = {
+		tool: { driver: {
+			name: TOOL_NAME,
+			informationUri: TOOL_INFORMATION_URI,
+			rules,
+			version: options.toolVersion
+		} },
+		results
+	};
+	if (options.coverage !== void 0) appendCoverage(run, options.coverage, ruleIndex, rules);
+	const runProperties = {};
+	if (syntheticCount > 0) runProperties["syntheticLocationCount"] = syntheticCount;
+	if (droppedLocationCount > 0) {
+		runProperties["droppedUnsafeLocationCount"] = droppedLocationCount;
+		runProperties["droppedUnsafeLocationFindings"] = droppedFindings;
+	}
+	const repo = options.repositoryContext;
+	if (repo !== void 0) {
+		const provenance = {};
+		if (repo.repositoryUri !== void 0) provenance["repositoryUri"] = repo.repositoryUri;
+		if (repo.commitSha !== void 0) provenance["revisionId"] = repo.commitSha;
+		if (repo.branch !== void 0) provenance["branch"] = repo.branch;
+		if (Object.keys(provenance).length > 0) run["versionControlProvenance"] = [provenance];
+		if (repo.repositoryFullName !== void 0) runProperties["repository"] = repo.repositoryFullName;
+		if (repo.ref !== void 0) runProperties["ref"] = repo.ref;
+		if (repo.commitSha !== void 0) 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, coverage, ruleIndex, rules) {
+	const coverageResults = [];
+	for (const entry of coverage.entries) {
+		const outcome = typeof entry.outcome === "string" ? entry.outcome : "";
+		const kind = OUTCOME_TO_KIND[outcome];
+		if (kind === void 0) 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 === void 0) {
+			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 = {
+			coverage_outcome: outcome,
+			risk_area: riskArea,
+			surface
+		};
+		if (entry.recorded_by !== void 0 && entry.recorded_by !== null) sharpkitProps["recorded_by"] = entry.recorded_by;
+		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 = { executionSuccessful: coverage.completeness?.complete ?? true };
+	const caveats = coverage.completeness?.caveats?.filter((caveat) => caveat !== "");
+	if (caveats !== void 0 && 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.
+*/
+async function writeSarif(runDir, reports, options) {
+	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(() => {});
+	}
+}
+//#endregion
+//#region src/index.ts
+/**
+* Vulnerability / dependency reporting tools — port of strix
+* tools/reporting/tool.py: create_vulnerability_report,
+* create_dependency_report, update_vulnerability_report, list_reports,
+* get_report. Validation parity (runtime-validated value sets, CVSS
+* computation, cross-class update guards), strix's exact response JSON
+* shapes, and the artifacts fan-out on every mutation (md/csv/json/sarif +
+* run.json last, atomic writes; SARIF always emitted even when empty).
+* The dedupe LLM judge is a Config callback (deterministic dependency fast
+* path runs regardless; judge failures default to not-duplicate).
+* @module @gpzhang2001/sharpkit-reporting
+*/
+const name = "pentest-tool-reporting";
+const inject = ["tools"];
+const Config = z.object({
+	runName: z.string(),
+	runsRoot: z.string().default("sharpkit_runs"),
+	toolVersion: z.string().default("0.1.0"),
+	scanMode: z.string().default("quick"),
+	targetsInfo: z.array(z.object({})),
+	strictCwe: z.boolean().default(true),
+	authMode: z.string().default("none"),
+	instruction: z.string(),
+	diffScope: z.string(),
+	nonInteractive: z.boolean(),
+	localSources: z.array(z.object({})),
+	scopeMode: z.string().default("auto"),
+	diffBase: z.string(),
+	mcpConnections: z.array(z.string())
+});
+/** strix-clean an optional string: literal null-words and empties → undefined. */
+function cleanOptional(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	if (trimmed === "" || /^(null|none|nil|undefined)$/i.test(trimmed)) return void 0;
+	return trimmed;
+}
+/** CVSS metric enum value sets (schema-level, matching strix runtime validation). */
+const CVSS_METRIC_SCHEMAS = {
+	attack_vector: {
+		type: "string",
+		required: true,
+		enum: [
+			"N",
+			"A",
+			"L",
+			"P"
+		]
+	},
+	attack_complexity: {
+		type: "string",
+		required: true,
+		enum: ["L", "H"]
+	},
+	privileges_required: {
+		type: "string",
+		required: true,
+		enum: [
+			"N",
+			"L",
+			"H"
+		]
+	},
+	user_interaction: {
+		type: "string",
+		required: true,
+		enum: ["N", "R"]
+	},
+	scope: {
+		type: "string",
+		required: true,
+		enum: ["U", "C"]
+	},
+	confidentiality: {
+		type: "string",
+		required: true,
+		enum: [
+			"N",
+			"L",
+			"H"
+		]
+	},
+	integrity: {
+		type: "string",
+		required: true,
+		enum: [
+			"N",
+			"L",
+			"H"
+		]
+	},
+	availability: {
+		type: "string",
+		required: true,
+		enum: [
+			"N",
+			"L",
+			"H"
+		]
+	}
+};
+const CODE_LOCATION_SCHEMA = {
+	type: "object",
+	properties: {
+		file: {
+			type: "string",
+			required: true
+		},
+		start_line: {
+			type: "integer",
+			required: true
+		},
+		end_line: {
+			type: "integer",
+			required: true
+		},
+		snippet: { type: "string" },
+		label: { type: "string" },
+		fix_before: { type: "string" },
+		fix_after: { type: "string" }
+	},
+	additionalProperties: false
+};
+/** Normalize + validate code_locations (tool.py `_normalize_code_locations`). */
+function normalizeCodeLocations(raw) {
+	if (!Array.isArray(raw) || raw.length === 0) return { errors: [] };
+	const errors = [];
+	const locations = [];
+	for (const [index, item] of raw.entries()) {
+		if (typeof item !== "object" || item === null) continue;
+		const entry = item;
+		const normalized = {};
+		const file = entry["file"];
+		if (typeof file === "string" && file !== "") normalized["file"] = file.trim();
+		const startLine = entry["start_line"];
+		if (typeof startLine === "number" && Number.isInteger(startLine)) normalized["start_line"] = startLine;
+		else if (typeof startLine === "string" && startLine !== "" && Number.isInteger(Number(startLine))) normalized["start_line"] = Number(startLine);
+		const endLine = entry["end_line"];
+		if (typeof endLine === "number" && Number.isInteger(endLine)) normalized["end_line"] = endLine;
+		else if (typeof endLine === "string" && endLine !== "" && Number.isInteger(Number(endLine))) normalized["end_line"] = Number(endLine);
+		for (const field of [
+			"snippet",
+			"fix_before",
+			"fix_after"
+		]) {
+			const value = entry[field];
+			if (typeof value === "string" && value.trim() !== "") normalized[field] = value.replace(/^\n+|\n+$/g, "");
+		}
+		for (const field of ["label"]) {
+			const value = entry[field];
+			if (typeof value === "string" && value.trim() !== "") normalized[field] = value.trim();
+		}
+		if (normalized["file"] === void 0 || normalized["start_line"] === void 0) continue;
+		if (typeof normalized["file"] === "string" && normalized["file"].startsWith("/")) errors.push(`code_locations[${String(index)}]: file must be a repo-relative path (no leading '/')`);
+		if (typeof normalized["start_line"] !== "number" || normalized["start_line"] < 1) errors.push(`code_locations[${String(index)}]: start_line must be an integer >= 1`);
+		if (normalized["end_line"] === void 0) errors.push(`code_locations[${String(index)}]: end_line is required`);
+		else {
+			const start = normalized["start_line"];
+			const end = normalized["end_line"];
+			if (typeof end !== "number" || end < 1) errors.push(`code_locations[${String(index)}]: end_line must be an integer >= 1`);
+			else if (end < start) errors.push(`code_locations[${String(index)}]: end_line (${String(end)}) must be >= start_line (${String(start)})`);
+		}
+		locations.push(normalized);
+	}
+	return {
+		...locations.length > 0 ? { locations } : {},
+		errors
+	};
+}
+/** CVE normalization (tool.py `_extract_cve` + `_validate_cve`). */
+function normalizeCve(value) {
+	const cleaned = cleanOptional(value);
+	if (cleaned === void 0) return void 0;
+	const match = /CVE-\d{4}-\d{4,}/.exec(cleaned);
+	if (match === null) return void 0;
+	return match[0];
+}
+/** CWE normalization (tool.py `_extract_cwe`). */
+function normalizeCwe(value) {
+	const cleaned = cleanOptional(value);
+	if (cleaned === void 0) return void 0;
+	const match = /CWE-\d+/.exec(cleaned);
+	if (match === null) return void 0;
+	return match[0];
+}
+/** Dependency metadata builder (tool.py `_build_dependency_metadata` order). */
+function buildDependencyMetadata(fields) {
+	const metadata = {
+		package_name: fields.packageName,
+		installed_version: fields.installedVersion
+	};
+	if (fields.advisoryCvss !== void 0) metadata["advisory_cvss"] = fields.advisoryCvss;
+	metadata["package_ecosystem"] = fields.packageEcosystem;
+	metadata["manifest_path"] = fields.manifestPath;
+	if (fields.fixedVersion !== void 0) metadata["fixed_version"] = fields.fixedVersion;
+	if (fields.introducedBy !== void 0) metadata["introduced_by"] = fields.introducedBy;
+	if (fields.dependencyPath !== void 0) metadata["dependency_path"] = fields.dependencyPath;
+	metadata["reachability"] = fields.reachability;
+	if (fields.reachabilityEvidence !== void 0) metadata["reachability_evidence"] = fields.reachabilityEvidence;
+	if (fields.contextual !== void 0) {
+		metadata["contextual_cvss_breakdown"] = fields.contextual.breakdown;
+		metadata["contextual_cvss_score"] = fields.contextual.score;
+		metadata["contextual_cvss_vector"] = fields.contextual.vector;
+		metadata["contextual_cvss_reasoning"] = fields.contextual.reasoning.slice(0, 2e3);
+	}
+	return metadata;
+}
+/** Valid severities (strix `_VALID_SEVERITIES`). */
+const VALID_SEVERITIES = /* @__PURE__ */ new Set([
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info",
+	"none"
+]);
+const VALID_FIX_EFFORT = /* @__PURE__ */ new Set([
+	"trivial",
+	"low",
+	"medium",
+	"high"
+]);
+const VALID_CONFIDENCE = /* @__PURE__ */ new Set([
+	"high",
+	"medium",
+	"low"
+]);
+const VALID_FINDING_CLASSES = /* @__PURE__ */ new Set(["dynamic", "dependency_cve"]);
+const VALID_REACHABILITY = /* @__PURE__ */ new Set([
+	"not_imported",
+	"imported",
+	"vulnerable_symbol_used",
+	"reachable_call_path",
+	"unknown"
+]);
+/** Broad CWEs strix's guidance forbids (tool.py docstring; enforced lightly). */
+const BROADCWES = /* @__PURE__ */ new Set([
+	"CWE-74",
+	"CWE-20",
+	"CWE-200",
+	"CWE-284",
+	"CWE-693"
+]);
+/** Fields only a dynamic finding may carry on update (strix `_DYNAMIC_ONLY_UPDATE_FIELDS` inverse). */
+const DEPENDENCY_ONLY_UPDATE_FIELDS = /* @__PURE__ */ new Set(["contextual_cvss_reasoning"]);
+const DYNAMIC_ONLY_UPDATE_FIELDS = /* @__PURE__ */ new Set([
+	"endpoint",
+	"method",
+	"poc_description",
+	"poc_script_code"
+]);
+function apply(ctx, config = {}) {
+	const runsRoot = config.runsRoot ?? "sharpkit_runs";
+	const runName = config.runName ?? `pentest-${Math.random().toString(16).slice(2, 6)}`;
+	const runDir = resolve(join(resolve(runsRoot), runName));
+	const state = new ReportState({ runName });
+	const toolVersion = config.toolVersion ?? "0.1.0";
+	/** scan_results block, set by finishScan and appended to run.json. */
+	let scanResults;
+	const usageLedger = {
+		requests: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		totalTokens: 0
+	};
+	ctx.on("session/event", (_session, event) => {
+		const record = event;
+		if (record.type !== "assistant/message") return;
+		const usage = record.data?.usage;
+		if (usage === void 0 || usage === null) return;
+		usageLedger.requests += 1;
+		usageLedger.inputTokens += usage.inputTokens ?? 0;
+		usageLedger.outputTokens += usage.outputTokens ?? 0;
+		usageLedger.totalTokens += usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+	});
+	const llmUsageRecord = () => ({
+		requests: usageLedger.requests,
+		input_tokens: usageLedger.inputTokens,
+		output_tokens: usageLedger.outputTokens,
+		total_tokens: usageLedger.totalTokens,
+		cost: null,
+		agents: []
+	});
+	const ensureRunDir = async () => {
+		await mkdir(runDir, { recursive: true });
+		return runDir;
+	};
+	/** Resolve the coverage source: Config hook first, else the analysis package's service. */
+	const coverageSource = () => {
+		if (config.coverageSource !== void 0) return config.coverageSource;
+		const analysis = ctx.get("pentestAnalysis");
+		return analysis === void 0 ? void 0 : {
+			entries: () => analysis.coverageEntries(),
+			outcomeCounts: () => analysis.outcomeCounts()
+		};
+	};
+	/** Assemble the coverage document (state.py `_coverage_document`, minus agent-graph gaps). */
+	const coverageDocument = () => {
+		const source = coverageSource();
+		const entries = source?.entries() ?? [];
+		const outcomes = source?.outcomeCounts() ?? {};
+		return {
+			schema_version: 1,
+			generated_at: formatTimestamp(/* @__PURE__ */ new Date()),
+			run_id: state.runId,
+			run_name: state.runName,
+			scope: {
+				targets: config.targetsInfo ?? [],
+				scan_mode: config.scanMode ?? null,
+				scope_mode: null,
+				diff_scope: null,
+				instruction: ""
+			},
+			summary: {
+				surfaces_reviewed: entries.length,
+				outcomes,
+				findings_filed: state.vulnerabilityReports.length,
+				gaps: entries.filter((entry) => entry["outcome"] === "needs_follow_up").length
+			},
+			completeness: {
+				complete: state.status === "completed",
+				scan_status: state.status,
+				exit_reason: null,
+				caveats: state.status === "running" ? ["scan still running"] : []
+			},
+			entries: entries.map((entry) => ({
+				surface: entry["surface"],
+				risk_area: entry["risk_area"],
+				outcome: entry["outcome"],
+				outcome_label: {
+					reported: "Finding reported",
+					no_issue_found: "No issue identified",
+					ruled_out: "Ruled out",
+					not_applicable: "Not applicable",
+					needs_follow_up: "Requires further review"
+				}[String(entry["outcome"])] ?? String(entry["outcome"]),
+				...entry["evidence"] !== void 0 ? { evidence: entry["evidence"] } : {},
+				recorded_by: entry["agent_name"] ?? null,
+				recorded_at: entry["created_at"],
+				...entry["updated_at"] !== void 0 ? { updated_at: entry["updated_at"] } : {},
+				previous_outcomes: entry["history"]?.map((item) => item["outcome"]) ?? [],
+				source: "agent_reported"
+			})),
+			gaps: entries.filter((entry) => entry["outcome"] === "needs_follow_up").map((entry) => ({
+				kind: "needs_follow_up",
+				surface: entry["surface"],
+				risk_area: entry["risk_area"],
+				detail: `'${String(entry["surface"])}' (${String(entry["risk_area"])}) still needs follow-up.`
+			}))
+		};
+	};
+	/** Full artifacts fan-out (state.py `_save_artifacts` order; run.json LAST). */
+	const saveArtifacts = async () => {
+		try {
+			const dir = await ensureRunDir();
+			const coverage = coverageDocument();
+			await writeCoverage(dir, coverage);
+			await writeVulnerabilities(dir, state.vulnerabilityReports, state.savedVulnIds);
+			const sarifCoverage = coverageSource() === void 0 ? void 0 : {
+				entries: coverage["entries"],
+				completeness: coverage["completeness"]
+			};
+			await writeSarif(dir, state.vulnerabilityReports, {
+				toolVersion,
+				coverage: sarifCoverage
+			});
+			const runRecord = {
+				run_id: state.runId,
+				run_name: state.runName,
+				start_time: state.startTime,
+				end_time: state.endTime,
+				status: state.status,
+				auth_mode: config.authMode ?? "none",
+				targets_info: config.targetsInfo ?? [],
+				llm_usage: llmUsageRecord(),
+				instruction: config.instruction ?? null,
+				scan_mode: config.scanMode ?? "quick",
+				diff_scope: config.diffScope ?? null,
+				non_interactive: config.nonInteractive ?? false,
+				local_sources: config.localSources ?? [],
+				scope_mode: config.scopeMode ?? "auto",
+				diff_base: config.diffBase ?? null
+			};
+			if (config.mcpConnections !== void 0 && config.mcpConnections.length > 0) runRecord["mcp_connections"] = config.mcpConnections;
+			if (scanResults !== void 0) runRecord["scan_results"] = scanResults;
+			await writeRunRecord(dir, runRecord);
+		} catch (error) {
+			ctx.logger.warn(`pentest-reporting: artifact save failed: ${String(error instanceof Error ? error.message : error)}`);
+		}
+	};
+	/** The create-side validation + dedupe + persistence shared by both create tools. */
+	const persistCreate = async (input, dedupeCandidate) => {
+		const verdict = await checkDuplicate(dedupeCandidate, input.dependencyMetadata, state.vulnerabilityReports, config.dedupeJudge);
+		if (verdict.isDuplicate) return {
+			success: false,
+			error: `Potential duplicate of '${state.vulnerabilityReports.find((report) => report.id === verdict.duplicateId)?.title ?? ""}' (id=${verdict.duplicateId.slice(0, 8)}...) — do not re-report the same vulnerability`,
+			duplicate_of: verdict.duplicateId,
+			confidence: verdict.confidence,
+			reason: verdict.reason
+		};
+		try {
+			const report = state.addVulnerabilityReport(input);
+			await saveArtifacts();
+			return {
+				success: true,
+				message: `${input.findingClass === "dependency_cve" ? "Dependency finding" : "Vulnerability report"} '${input.title}' created successfully`,
+				report_id: report.id,
+				severity: report.severity,
+				...report.cvss !== void 0 ? { cvss_score: report.cvss } : {},
+				...input.findingClass === "dependency_cve" && report.cve !== void 0 ? { cve: report.cve } : {}
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: `Failed to create ${input.findingClass === "dependency_cve" ? "dependency" : "vulnerability"} report: ${String(error instanceof Error ? error.message : error)}`
+			};
+		}
+	};
+	ctx.tools.register(defineTool({
+		name: "create_vulnerability_report",
+		description: "File a vulnerability report — one report per fully-verified finding, with a working PoC. Severity and CVSS are computed from the 8-metric cvss_breakdown you provide. On a duplicate verdict, revise the existing report via update_vulnerability_report instead of retrying. Never for known-CVE dependency findings — use create_dependency_report.",
+		parameters: {
+			title: {
+				type: "string",
+				required: true,
+				description: "Specific finding title (e.g. \"SQL Injection in /api/users login parameter\")."
+			},
+			description: {
+				type: "string",
+				required: true,
+				description: "Concise, non-technical TL;DR (1-3 sentences)."
+			},
+			impact: {
+				type: "string",
+				required: true,
+				description: "The unauthorized result demonstrated by the PoC and its scope."
+			},
+			target: {
+				type: "string",
+				required: true,
+				description: "Affected URL / domain / repository."
+			},
+			technical_analysis: {
+				type: "string",
+				required: true,
+				description: "The mechanism and root cause."
+			},
+			poc_description: {
+				type: "string",
+				required: true,
+				description: "Step-by-step reproduction (steps only, no code)."
+			},
+			poc_script_code: {
+				type: "string",
+				required: true,
+				description: "Working PoC (Python preferred)."
+			},
+			remediation_steps: {
+				type: "string",
+				required: true,
+				description: "Specific, actionable fix (prose, no code)."
+			},
+			evidence: {
+				type: "string",
+				required: true,
+				description: "Concrete proof: request/response excerpts, observed behavior, tool output."
+			},
+			assumptions: {
+				type: "string",
+				required: true,
+				description: "Assumptions/prerequisites that make this finding impactful."
+			},
+			counterevidence: {
+				type: "string",
+				required: true,
+				description: "REQUIRED: the strongest case against this finding, after actively looking for it."
+			},
+			confidence: {
+				type: "string",
+				required: true,
+				enum: [
+					"high",
+					"medium",
+					"low"
+				],
+				description: "Calibrated confidence."
+			},
+			confidence_rationale: {
+				type: "string",
+				description: "Required when confidence is not high: name the specific gap."
+			},
+			severity_change_conditions: {
+				type: "string",
+				required: true,
+				description: "One concrete sentence on what evidence would raise or lower severity."
+			},
+			fix_effort: {
+				type: "string",
+				required: true,
+				enum: [
+					"trivial",
+					"low",
+					"medium",
+					"high"
+				],
+				description: "Estimated fix effort."
+			},
+			cvss_breakdown: {
+				type: "object",
+				required: true,
+				properties: CVSS_METRIC_SCHEMAS,
+				additionalProperties: false,
+				description: "All 8 CVSS v3.1 metrics; score and severity are computed from it."
+			},
+			endpoint: {
+				type: "string",
+				description: "API path / Git path (e.g. /api/login)."
+			},
+			method: {
+				type: "string",
+				description: "HTTP method when relevant."
+			},
+			cve: {
+				type: "string",
+				description: "CVE-YYYY-NNNNN if certain, else omit."
+			},
+			cwe: {
+				type: "string",
+				description: "CWE-NNN (most specific child) if certain, else omit."
+			},
+			code_locations: {
+				type: "array",
+				items: CODE_LOCATION_SCHEMA,
+				description: "White-box findings: file/start_line/end_line/snippet/label/fix_before/fix_after."
+			},
+			fix_verification: {
+				type: "string",
+				description: "Required whenever any code_locations entry carries fix_after: the 4 ordered verification gates."
+			},
+			fix_pr_body: {
+				type: "string",
+				description: "Optional markdown PR-description body proposing the fix."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					message: { type: "string" },
+					report_id: { type: "string" },
+					severity: { type: "string" },
+					cvss_score: { type: "number" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					},
+					duplicate_of: { type: "string" },
+					confidence: { type: "number" },
+					reason: { type: "string" },
+					warning: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (!result.success) return [{
+					type: "text",
+					text: `create_vulnerability_report failed: ${result.error ?? "unknown"}`
+				}];
+				return [{
+					type: "text",
+					text: `filed ${result.report_id} (${String(result.severity)}, CVSS ${String(result.cvss_score)})`
+				}];
+			},
+			presentationMeta: (args, value) => findingPresentationMeta(args, value)
+		},
+		execute: (async (rawArgs, rawExec) => {
+			const args = rawArgs;
+			const errors = [];
+			const breakdown = args.cvss_breakdown;
+			errors.push(...validateCvssBreakdown(breakdown));
+			const confidence = args.confidence.toLowerCase();
+			if (!VALID_CONFIDENCE.has(confidence)) errors.push(`Invalid confidence: ${args.confidence}. Must be one of: [high, low, medium]`);
+			const fixEffort = args.fix_effort.toLowerCase();
+			if (!VALID_FIX_EFFORT.has(fixEffort)) errors.push(`Invalid fix_effort: ${args.fix_effort}. Must be one of: [high, low, medium, trivial]`);
+			const cve = normalizeCve(args.cve);
+			if (args.cve !== void 0 && cve === void 0) errors.push(`Invalid cve: ${args.cve}. Must match CVE-YYYY-NNNNN`);
+			const cwe = normalizeCwe(args.cwe);
+			if (args.cwe !== void 0 && cwe === void 0) errors.push(`Invalid cwe: ${args.cwe}. Must match CWE-NNN`);
+			if (cwe !== void 0 && config.strictCwe === true && BROADCWES.has(cwe)) errors.push(`${cwe} is too broad — file the most specific child CWE`);
+			const locations = normalizeCodeLocations(args.code_locations);
+			errors.push(...locations.errors);
+			if ((locations.locations?.some((location) => typeof location["fix_after"] === "string" && location["fix_after"] !== "") ?? false) && cleanOptional(args.fix_verification) === void 0) errors.push("fix_verification is required when any code_locations entry carries fix_after");
+			if (args.confidence !== "high" && cleanOptional(args.confidence_rationale) === void 0) errors.push("confidence_rationale is required when confidence is not high");
+			if (errors.length > 0) return {
+				success: false,
+				error: "Validation failed",
+				errors
+			};
+			let cvssScore;
+			let severity;
+			try {
+				const computed = calculateCvss(breakdown);
+				cvssScore = computed.score;
+				severity = computed.severity;
+			} catch (error) {
+				return {
+					success: false,
+					error: "Validation failed",
+					errors: [String(error instanceof Error ? error.message : error)]
+				};
+			}
+			const fields = {
+				description: args.description,
+				impact: args.impact,
+				target: args.target,
+				technical_analysis: args.technical_analysis,
+				poc_description: args.poc_description,
+				poc_script_code: args.poc_script_code,
+				remediation_steps: args.remediation_steps,
+				evidence: args.evidence,
+				assumptions: args.assumptions,
+				counterevidence: args.counterevidence,
+				confidence,
+				confidence_rationale: args.confidence_rationale,
+				severity_change_conditions: args.severity_change_conditions,
+				fix_effort: fixEffort,
+				cvss: cvssScore,
+				cvss_breakdown: breakdown,
+				endpoint: args.endpoint,
+				method: args.method,
+				cve,
+				cwe,
+				code_locations: locations.locations,
+				fix_verification: args.fix_verification,
+				fix_pr_body: args.fix_pr_body
+			};
+			return persistCreate({
+				title: args.title,
+				severity,
+				findingClass: "dynamic",
+				fields
+			}, {
+				title: args.title,
+				description: args.description,
+				impact: args.impact,
+				target: args.target,
+				technical_analysis: args.technical_analysis,
+				poc_description: args.poc_description,
+				poc_script_code: args.poc_script_code,
+				endpoint: args.endpoint,
+				method: args.method
+			});
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "update_vulnerability_report",
+		description: "Revise a vulnerability report that is already filed, keeping its id. Pass only the fields to replace; create's reporting rules apply. cvss_breakdown replaces the whole vector (score + severity recomputed). Reports keep their id, author, and filing time; the revision is recorded as update history.",
+		parameters: {
+			report_id: {
+				type: "string",
+				required: true,
+				description: "Id of the report to revise (format vuln-NNNN)."
+			},
+			update_reason: {
+				type: "string",
+				required: true,
+				description: "What you learned that the report does not yet carry (1-2 sentences)."
+			},
+			title: { type: "string" },
+			description: { type: "string" },
+			impact: { type: "string" },
+			target: { type: "string" },
+			technical_analysis: { type: "string" },
+			poc_description: { type: "string" },
+			poc_script_code: { type: "string" },
+			remediation_steps: { type: "string" },
+			evidence: { type: "string" },
+			assumptions: { type: "string" },
+			counterevidence: { type: "string" },
+			confidence: {
+				type: "string",
+				enum: [
+					"high",
+					"medium",
+					"low"
+				]
+			},
+			confidence_rationale: { type: "string" },
+			severity_change_conditions: { type: "string" },
+			fix_effort: {
+				type: "string",
+				enum: [
+					"trivial",
+					"low",
+					"medium",
+					"high"
+				]
+			},
+			cvss_breakdown: {
+				type: "object",
+				properties: CVSS_METRIC_SCHEMAS,
+				additionalProperties: false
+			},
+			endpoint: { type: "string" },
+			method: { type: "string" },
+			cve: { type: "string" },
+			cwe: { type: "string" },
+			code_locations: {
+				type: "array",
+				items: CODE_LOCATION_SCHEMA
+			},
+			fix_verification: { type: "string" },
+			fix_pr_body: { type: "string" },
+			contextual_cvss_reasoning: {
+				type: "string",
+				description: "Dependency findings only: what you observed in this codebase justifying the contextual cvss_breakdown."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					action: { type: "string" },
+					message: { type: "string" },
+					report_id: { type: "string" },
+					updated_fields: {
+						type: "array",
+						items: { type: "string" }
+					},
+					severity: { type: "string" },
+					cvss_score: { type: "number" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					},
+					finding_class: { type: "string" },
+					rejected_fields: {
+						type: "array",
+						items: { type: "string" }
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (!result.success) return [{
+					type: "text",
+					text: `update_vulnerability_report failed: ${result.error ?? "unknown"}`
+				}];
+				return [{
+					type: "text",
+					text: `revised ${result.report_id}`
+				}];
+			},
+			presentationMeta: (args, value) => findingPresentationMeta(args, value)
+		},
+		execute: (async (rawArgs, rawExec) => {
+			const args = rawArgs;
+			const reportId = cleanOptional(args.report_id);
+			const reason = cleanOptional(args.update_reason);
+			if (reportId === void 0 || reason === void 0) return {
+				success: false,
+				error: `${reportId === void 0 ? "report_id" : "update_reason"} cannot be empty - name the report you are revising and state what you learned that it does not yet carry`
+			};
+			const report = state.vulnerabilityReports.find((entry) => entry.id === reportId);
+			if (report === void 0) return {
+				success: false,
+				error: `Report with id '${reportId}' not found`,
+				report_id: reportId
+			};
+			const changes = {};
+			for (const [key, value] of Object.entries(args)) {
+				if (key === "report_id" || key === "update_reason") continue;
+				const cleaned = typeof value === "string" ? cleanOptional(value) : value;
+				if (cleaned === void 0) continue;
+				changes[key] = cleaned;
+			}
+			if (Object.keys(changes).length === 0) return {
+				success: false,
+				error: "No fields to update - pass at least one field you want to replace",
+				report_id: reportId
+			};
+			const findingClass = typeof report.finding_class === "string" ? report.finding_class : report.dependency_metadata !== void 0 ? "dependency_cve" : "dynamic";
+			const rejected = [];
+			if (findingClass === "dependency_cve") {
+				for (const field of DYNAMIC_ONLY_UPDATE_FIELDS) if (changes[field] !== void 0) rejected.push(field);
+			} else for (const field of DEPENDENCY_ONLY_UPDATE_FIELDS) if (changes[field] !== void 0) rejected.push(field);
+			if (rejected.length > 0) return {
+				success: false,
+				error: `Report '${reportId}' is a ${findingClass} finding, so it cannot carry ${rejected.join(", ")}. File your proof as its own vulnerability report instead of writing it onto this one.`,
+				report_id: reportId,
+				finding_class: findingClass,
+				rejected_fields: rejected
+			};
+			if (changes["cvss_breakdown"] !== void 0 && findingClass === "dependency_cve") {
+				if (changes["contextual_cvss_reasoning"] === void 0 && report.dependency_metadata === void 0) return {
+					success: false,
+					error: "Validation failed",
+					errors: ["contextual_cvss_reasoning is required when re-rating a dependency finding"],
+					report_id: reportId
+				};
+				const errors = validateCvssBreakdown(changes["cvss_breakdown"]);
+				if (errors.length > 0) return {
+					success: false,
+					error: "Validation failed",
+					errors,
+					report_id: reportId
+				};
+				const computed = calculateCvss(changes["cvss_breakdown"]);
+				changes["cvss"] = computed.score;
+				changes["severity"] = computed.severity;
+			} else if (changes["cvss_breakdown"] !== void 0) {
+				const errors = validateCvssBreakdown(changes["cvss_breakdown"]);
+				if (errors.length > 0) return {
+					success: false,
+					error: "Validation failed",
+					errors,
+					report_id: reportId
+				};
+				const computed = calculateCvss(changes["cvss_breakdown"]);
+				changes["cvss"] = computed.score;
+				changes["severity"] = computed.severity;
+			}
+			const outcome = state.updateVulnerabilityReport(reportId, changes, reason);
+			if ("noop" in outcome) return {
+				success: false,
+				error: `Report '${reportId}' already says this - nothing in your update changes it`,
+				report_id: reportId
+			};
+			await saveArtifacts();
+			const updated = outcome.report;
+			return {
+				success: true,
+				action: "updated",
+				message: `Report '${reportId}' now carries your revision. Do not file it again.`,
+				report_id: reportId,
+				updated_fields: updated["update_history"]?.at(-1)?.fields ?? [],
+				severity: updated.severity,
+				...updated.cvss !== void 0 ? { cvss_score: updated.cvss } : {}
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "create_dependency_report",
+		description: "File a known-CVE dependency (SCA) finding — one report per CVE x package. For vulnerable third-party package versions pinned in a lockfile/manifest/SBOM; no live PoC needed. Severity comes from the contextual_cvss_breakdown when provided, else the advisory score. Never for dynamically-proven vulnerabilities — use create_vulnerability_report.",
+		parameters: {
+			title: {
+				type: "string",
+				required: true,
+				description: "e.g. \"CVE-2024-1234 in lodash 4.17.20 (prototype pollution)\"."
+			},
+			description: {
+				type: "string",
+				required: true,
+				description: "What the CVE is and why the pinned version is affected."
+			},
+			target: {
+				type: "string",
+				required: true,
+				description: "Affected repository / project / manifest."
+			},
+			cve: {
+				type: "string",
+				required: true,
+				description: "CVE-YYYY-NNNNN — required and verified."
+			},
+			package_name: {
+				type: "string",
+				required: true,
+				description: "Affected package name (e.g. lodash)."
+			},
+			installed_version: {
+				type: "string",
+				required: true,
+				description: "The version currently pinned/installed."
+			},
+			advisory_cvss: {
+				type: "number",
+				required: true,
+				description: "Published advisory base score (0.0-10.0)."
+			},
+			impact: {
+				type: "string",
+				required: true,
+				description: "What the CVE enables; business risk in this context."
+			},
+			remediation_steps: {
+				type: "string",
+				required: true,
+				description: "How to fix (usually upgrade to a fixed version)."
+			},
+			assumptions: {
+				type: "string",
+				required: true,
+				description: "Exploitability/reachability assumptions & confidence."
+			},
+			package_ecosystem: {
+				type: "string",
+				required: true,
+				description: "e.g. npm / pypi / maven / go."
+			},
+			manifest_path: {
+				type: "string",
+				description: "Repo-relative lockfile/manifest path (required)."
+			},
+			fixed_version: {
+				type: "string",
+				description: "First non-vulnerable version, if known."
+			},
+			cwe: {
+				type: "string",
+				description: "CWE-NNN (most specific) if certain."
+			},
+			technical_analysis: {
+				type: "string",
+				description: "Optional deeper mechanism/root-cause detail."
+			},
+			fix_effort: {
+				type: "string",
+				enum: [
+					"trivial",
+					"low",
+					"medium",
+					"high"
+				],
+				description: "Default low."
+			},
+			introduced_by: {
+				type: "string",
+				description: "For a transitive dep, the direct dependency pulling it in (name@version)."
+			},
+			dependency_path: {
+				type: "string",
+				description: "Resolution chain joined with \" > \"."
+			},
+			reachability: {
+				type: "string",
+				enum: [
+					"not_imported",
+					"imported",
+					"vulnerable_symbol_used",
+					"reachable_call_path",
+					"unknown"
+				],
+				description: "Usage-evidence level (default unknown)."
+			},
+			reachability_evidence: {
+				type: "string",
+				description: "Concrete proof for the level (required)."
+			},
+			contextual_cvss_breakdown: {
+				type: "object",
+				properties: CVSS_METRIC_SCHEMAS,
+				additionalProperties: false,
+				description: "Full CVSS v3.1 rating of this CVE in this codebase (required)."
+			},
+			contextual_cvss_reasoning: {
+				type: "string",
+				description: "2-4 verifiable sentences with file:line hops (required)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					message: { type: "string" },
+					report_id: { type: "string" },
+					severity: { type: "string" },
+					cve: { type: "string" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					},
+					duplicate_of: { type: "string" },
+					confidence: { type: "number" },
+					reason: { type: "string" },
+					warning: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (!result.success) return [{
+					type: "text",
+					text: `create_dependency_report failed: ${result.error ?? "unknown"}`
+				}];
+				return [{
+					type: "text",
+					text: `filed ${result.report_id} (${String(result.severity)}) for ${result.cve ?? "CVE"}`
+				}];
+			},
+			presentationMeta: (args, value) => findingPresentationMeta(args, value)
+		},
+		execute: (async (rawArgs, _rawExec) => {
+			const args = rawArgs;
+			const errors = [];
+			const requireText = (value, name) => {
+				const cleaned = cleanOptional(value);
+				if (cleaned === void 0) errors.push(`${name} cannot be empty`);
+				return cleaned;
+			};
+			const packageName = requireText(args.package_name, "package_name");
+			const installedVersion = requireText(args.installed_version, "installed_version");
+			const packageEcosystem = requireText(args.package_ecosystem, "package_ecosystem");
+			const manifestPath = requireText(args.manifest_path, "manifest_path");
+			const reachabilityEvidence = requireText(args.reachability_evidence, "reachability_evidence");
+			const contextualReasoning = requireText(args.contextual_cvss_reasoning, "contextual_cvss_reasoning");
+			const cve = normalizeCve(args.cve);
+			if (cve === void 0) errors.push(`Invalid cve: ${String(args.cve)}. Must match CVE-YYYY-NNNNN`);
+			const cwe = normalizeCwe(args.cwe);
+			if (args.cwe !== void 0 && cwe === void 0) errors.push(`Invalid cwe: ${args.cwe}. Must match CWE-NNN`);
+			const advisory = args.advisory_cvss;
+			if (typeof advisory !== "number" || Number.isNaN(advisory) || advisory < 0 || advisory > 10) errors.push(`Invalid advisory_cvss: ${String(advisory)}. Must be between 0.0 and 10.0`);
+			const reachability = (args.reachability ?? "unknown").toLowerCase();
+			if (!VALID_REACHABILITY.has(reachability)) errors.push(`Invalid reachability: ${String(args.reachability)}. Must be one of: [imported, not_imported, reachable_call_path, unknown, vulnerable_symbol_used]`);
+			const fixEffort = (args.fix_effort ?? "low").toLowerCase();
+			if (!VALID_FIX_EFFORT.has(fixEffort)) errors.push(`Invalid fix_effort: ${String(args.fix_effort)}. Must be one of: [high, low, medium, trivial]`);
+			if (manifestPath !== void 0 && (manifestPath.startsWith("/") || manifestPath.includes("\\") || manifestPath.split("/").some((part) => part === "" || part === "." || part === ".."))) errors.push(`Invalid manifest_path: ${manifestPath}. Must be a repo-relative path without absolute or traversal segments`);
+			let contextual;
+			const hasContextualBreakdown = args.contextual_cvss_breakdown !== void 0;
+			if (hasContextualBreakdown || contextualReasoning !== void 0) {
+				if (!hasContextualBreakdown) errors.push("contextual_cvss_breakdown is required when contextual_cvss_reasoning is given");
+				if (contextualReasoning === void 0) errors.push("contextual_cvss_reasoning is required when contextual_cvss_breakdown is given");
+				if (hasContextualBreakdown && contextualReasoning !== void 0) {
+					const breakdown = args.contextual_cvss_breakdown;
+					errors.push(...validateCvssBreakdown(breakdown));
+					const computed = calculateCvss(breakdown);
+					contextual = {
+						breakdown,
+						score: computed.score,
+						vector: computed.vector,
+						reasoning: contextualReasoning
+					};
+				}
+			}
+			if (errors.length > 0) return {
+				success: false,
+				error: "Validation failed",
+				errors
+			};
+			const severity = contextual !== void 0 ? calculateCvss(contextual.breakdown).severity : dependencySeverity(advisory);
+			const metadata = buildDependencyMetadata({
+				packageName,
+				installedVersion,
+				advisoryCvss: advisory,
+				packageEcosystem,
+				manifestPath,
+				fixedVersion: cleanOptional(args.fixed_version),
+				introducedBy: cleanOptional(args.introduced_by),
+				dependencyPath: cleanOptional(args.dependency_path),
+				reachability,
+				reachabilityEvidence,
+				contextual
+			});
+			const fields = {
+				description: args.description,
+				impact: args.impact,
+				target: args.target,
+				technical_analysis: args.technical_analysis,
+				remediation_steps: args.remediation_steps,
+				assumptions: args.assumptions,
+				fix_effort: fixEffort,
+				cve,
+				cwe,
+				cvss: contextual !== void 0 ? contextual.score : advisory
+			};
+			return persistCreate({
+				title: args.title,
+				severity,
+				findingClass: "dependency_cve",
+				dependencyMetadata: metadata,
+				fields
+			}, {
+				title: args.title,
+				description: args.description,
+				target: args.target,
+				cve,
+				dependency_metadata: metadata,
+				technical_analysis: args.technical_analysis
+			});
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "list_reports",
+		description: "List vulnerability reports filed so far in this scan — metadata-first. Read-only and shared across all agents. Filters compose (AND); compact entries by default, full bodies with include_details.",
+		parameters: {
+			severity: {
+				type: "string",
+				enum: [
+					"critical",
+					"high",
+					"medium",
+					"low",
+					"info",
+					"none"
+				],
+				description: "Filter to one severity."
+			},
+			finding_class: {
+				type: "string",
+				enum: ["dynamic", "dependency_cve"],
+				description: "dynamic or dependency_cve."
+			},
+			target: {
+				type: "string",
+				description: "Substring match against target/endpoint."
+			},
+			search: {
+				type: "string",
+				description: "Substring match against title and description."
+			},
+			include_details: {
+				type: "boolean",
+				description: "Full report bodies instead of compact entries (default false)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					reports: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						}
+					},
+					filtered_count: {
+						type: "integer",
+						required: true
+					},
+					total_count: {
+						type: "integer",
+						required: true
+					},
+					severity_counts: {
+						type: "object",
+						properties: {},
+						additionalProperties: true,
+						required: true
+					},
+					warning: { type: "string" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: `${String(result.reports.length)} of ${String(result.total_count)} report(s)`
+				}];
+			}
+		},
+		execute: (async (rawArgs, rawExec) => {
+			const args = rawArgs;
+			const severityFilter = cleanOptional(args.severity)?.toLowerCase();
+			const classFilter = cleanOptional(args.finding_class)?.toLowerCase();
+			const targetFilter = cleanOptional(args.target)?.toLowerCase();
+			const searchFilter = cleanOptional(args.search)?.toLowerCase();
+			if (severityFilter !== void 0 && !VALID_SEVERITIES.has(severityFilter)) return {
+				success: false,
+				reports: [],
+				filtered_count: 0,
+				total_count: 0,
+				severity_counts: {},
+				error: `Invalid severity: ${severityFilter}. Must be one of: [critical, high, info, low, medium, none]`
+			};
+			if (classFilter !== void 0 && !VALID_FINDING_CLASSES.has(classFilter)) return {
+				success: false,
+				reports: [],
+				filtered_count: 0,
+				total_count: 0,
+				severity_counts: {},
+				error: `Invalid finding_class: ${classFilter}. Must be one of: [dependency_cve, dynamic]`
+			};
+			const severityCounts = {};
+			for (const report of state.vulnerabilityReports) {
+				const key = String(report.severity);
+				severityCounts[key] = (severityCounts[key] ?? 0) + 1;
+			}
+			const filtered = state.vulnerabilityReports.filter((report) => {
+				if (severityFilter !== void 0 && report.severity !== severityFilter) return false;
+				if (classFilter !== void 0 && String(report.finding_class) !== classFilter) return false;
+				if (targetFilter !== void 0) {
+					const target = String(report.target ?? "").toLowerCase();
+					const endpoint = String(report.endpoint ?? "").toLowerCase();
+					if (!target.includes(targetFilter) && !endpoint.includes(targetFilter)) return false;
+				}
+				if (searchFilter !== void 0) {
+					const title = String(report.title ?? "").toLowerCase();
+					const description = String(report.description ?? "").toLowerCase();
+					if (!title.includes(searchFilter) && !description.includes(searchFilter)) return false;
+				}
+				return true;
+			});
+			filtered.sort((a, b) => severityRank(a.severity) - severityRank(b.severity) || a.id.localeCompare(b.id));
+			return {
+				success: true,
+				reports: filtered.map((report) => args.include_details === true ? { ...report } : summarize(report)),
+				filtered_count: filtered.length,
+				total_count: state.vulnerabilityReports.length,
+				severity_counts: severityCounts
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "get_report",
+		description: "Fetch one vulnerability report by its id (e.g. vuln-0001). Read-only; use list_reports to find ids.",
+		parameters: { report_id: {
+			type: "string",
+			required: true,
+			description: "Report id from list_reports or a create response (format 'vuln-NNNN')."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					report: {
+						type: "object",
+						properties: {},
+						additionalProperties: true
+					},
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (!result.success) return [{
+					type: "text",
+					text: `get_report failed: ${result.error ?? "unknown"}`
+				}];
+				return [{
+					type: "text",
+					text: `report ${String(result.report?.id)}`
+				}];
+			}
+		},
+		execute: (async (rawArgs, rawExec) => {
+			const reportId = cleanOptional(rawArgs.report_id);
+			if (reportId === void 0) return {
+				success: false,
+				error: "report_id cannot be empty"
+			};
+			const report = state.vulnerabilityReports.find((entry) => entry.id === reportId);
+			if (report === void 0) return {
+				success: false,
+				error: `Report with id '${reportId}' not found`
+			};
+			return {
+				success: true,
+				report: { ...report }
+			};
+		})
+	}));
+	/** Compact summary entry (tool.py `_to_report_summary_entry` field order). */
+	function summarize(report) {
+		const record = report;
+		const summary = {};
+		for (const field of [
+			"id",
+			"title",
+			"severity",
+			"cvss",
+			"confidence",
+			"finding_class",
+			"cve",
+			"cwe",
+			"target",
+			"endpoint",
+			"method",
+			"fix_effort",
+			"agent_name",
+			"timestamp"
+		]) {
+			const value = record[field];
+			if (value !== null && value !== void 0 && value !== "") summary[field] = value;
+		}
+		const description = record["description"];
+		if (typeof description === "string" && description !== "") summary["description_preview"] = description.length > 280 ? `${description.slice(0, 280)}...` : description;
+		return summary;
+	}
+	/**
+	* Replay-safe toolview meta for finding cards (ui FindingRow consumes
+	* severity/report_id/title from `result.meta`). Pure over (args, value);
+	* undefined keys are omitted so the snapshot stays lossless JSON.
+	*/
+	function findingPresentationMeta(args, value) {
+		const meta = {};
+		const title = args.title;
+		if (title !== void 0) meta["title"] = title;
+		const severity = value.severity;
+		if (severity !== void 0) meta["severity"] = severity;
+		const reportId = value.report_id;
+		if (reportId !== void 0) meta["report_id"] = reportId;
+		return meta;
+	}
+	const composeFinalReport = (sections) => [
+		"# Executive Summary",
+		sections.executiveSummary,
+		"",
+		"# Methodology",
+		sections.methodology,
+		"",
+		"# Technical Analysis",
+		sections.technicalAnalysis,
+		"",
+		"# Recommendations",
+		sections.recommendations
+	].join("\n");
+	const handle = {
+		state,
+		runDir,
+		/** Mark the scan complete and write the final report + artifacts. */
+		async finishScan(sections, status = "completed") {
+			state.finalScanResult = composeFinalReport(sections);
+			state.complete(status);
+			scanResults = {
+				scan_completed: true,
+				executive_summary: sections.executiveSummary,
+				methodology: sections.methodology,
+				technical_analysis: sections.technicalAnalysis,
+				recommendations: sections.recommendations,
+				success: status === "completed"
+			};
+			await writeExecutiveReport(await ensureRunDir(), state.finalScanResult, formatTimestamp(/* @__PURE__ */ new Date()));
+			await saveArtifacts();
+		},
+		/** Dump the current run.json record (golden/test helper). */
+		async writeNow() {
+			await saveArtifacts();
+		},
+		readRaw: async (relative) => readFile(join(runDir, relative), "utf8")
+	};
+	ctx.provide("pentestReporting", handle);
+	return handle;
+}
+//#endregion
+export { Config, ReportState, apply, buildCvssVector, buildDependencyMetadata, buildSarif, calculateCvss, checkDuplicate, classKeyword, cleanTitle, cvssBaseScore, cvssSeverity, dependencyIdentity, dependencySeverity, inject, name, normalizeCodeLocations, normalizeCve, normalizeCwe, renderVulnerabilityMd, ruleIdOf, sarifUri, severityRank, validateCvssBreakdown };
+
+//# sourceMappingURL=index.js.map