securl 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-06-28
+
+### Added
+- Added `buildEvidenceQualitySummary()` and the `securl/evidence-quality` package export for scan confidence, coverage gaps, and recommended follow-up.
+- Added `evidenceQuality` to completed analysis results and compact posture digests so API, mobile, and CLI clients can explain how trustworthy a scan read is.
+
 ## [1.12.0] - 2026-06-27
 
 ### Added

package/README.md

@@ -287,6 +287,23 @@ console.log({
 });
 ```
 
+Version `1.13.0+` includes an evidence-quality helper for client surfaces that need to explain how much confidence to place in a scan result.
+
+```js
+import { buildEvidenceQualitySummary } from "securl/evidence-quality";
+
+const quality = buildEvidenceQualitySummary(resultWithEvidence);
+
+console.log({
+  level: quality.level,
+  score: quality.score,
+  gaps: quality.gaps,
+  followUp: quality.recommendedFollowUp,
+});
+```
+
+Evidence quality is also included in `buildPostureDigest()` output, so mobile and API clients can display scan confidence without loading the full result.
+
 ## Package trust and release signals
 
 - public source repository with package code under `packages/core`
@@ -371,6 +388,7 @@ Primary exports:
 - `buildPostureRemediationPlan(result)` - generate prioritized, owner-aware remediation actions from findings and score drivers.
 - `attachIssueEvidence(result)` - add structured evidence references to findings without changing their existing fields.
 - `buildPostureEvidenceSummary(result)` - produce compact evidence metadata for API, mobile, report, and explainability surfaces.
+- `buildEvidenceQualitySummary(result)` - summarize scan confidence, collection gaps, and recommended follow-up.
 
 Package subpath exports:
 
@@ -384,6 +402,7 @@ Package subpath exports:
 - `securl/observation-policy`
 - `securl/posture-drift`
 - `securl/remediation-plan`
+- `securl/evidence-quality`
 - `securl/risk-events`
 - `securl/types`
 

package/dist/evidenceQuality.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult, EvidenceQualitySummary } from "./types.js";
+export declare function buildEvidenceQualitySummary(analysis: AnalysisResult): EvidenceQualitySummary;

package/dist/evidenceQuality.js

@@ -0,0 +1,154 @@
+const OBSERVED_KINDS = new Set(["header", "tls", "cookie", "redirect", "dns", "html", "public_record"]);
+const normalizeArray = (value) => (Array.isArray(value) ? value : []);
+function clampScore(score) {
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+function levelForScore(score) {
+    if (score >= 80)
+        return "high";
+    if (score >= 55)
+        return "medium";
+    return "low";
+}
+function pushSignal(signals, id, label, detail, impact) {
+    signals.push({ id, label, detail, impact });
+}
+function buildSummary(level, analysis, gaps) {
+    if (analysis.assessmentLimitation?.limited) {
+        return "Evidence quality is limited because the target did not return a complete posture read.";
+    }
+    if (level === "high") {
+        return "Evidence quality is high enough to treat the posture result as a solid outside-in read.";
+    }
+    if (level === "medium") {
+        return "Evidence quality is usable, but a few collection gaps should be considered before treating the result as final.";
+    }
+    if (gaps.length > 0) {
+        return "Evidence quality is low, so treat this result as directional until the collection gaps are resolved.";
+    }
+    return "Evidence quality is low because the scan produced too little structured support for the result.";
+}
+export function buildEvidenceQualitySummary(analysis) {
+    const evidenceSummary = analysis.evidenceSummary;
+    const issues = normalizeArray(analysis.issues);
+    const timing = analysis.scanTiming;
+    const totalReferences = evidenceSummary?.totalEvidenceReferences ?? 0;
+    const observedReferences = evidenceSummary?.observedCount ?? 0;
+    const derivedReferences = evidenceSummary?.derivedCount ?? 0;
+    const observedRatio = totalReferences > 0 ? observedReferences / totalReferences : 0;
+    const kinds = Object.keys(evidenceSummary?.byKind ?? {});
+    const lowConfidence = issues.filter((issue) => issue.confidence === "low").length;
+    const mediumConfidence = issues.filter((issue) => issue.confidence === "medium").length;
+    const highConfidence = issues.filter((issue) => issue.confidence === "high").length;
+    const strengths = [];
+    const gaps = [];
+    let score = 50;
+    if (totalReferences >= 12) {
+        score += 18;
+        pushSignal(strengths, "evidence_volume", "Evidence volume", "The scan produced a broad set of structured evidence references.", "positive");
+    }
+    else if (totalReferences >= 5) {
+        score += 10;
+        pushSignal(strengths, "evidence_volume", "Evidence volume", "The scan produced enough structured evidence for a useful posture read.", "positive");
+    }
+    else {
+        score -= 18;
+        pushSignal(gaps, "low_evidence_volume", "Low evidence volume", "The scan produced fewer structured evidence references than expected.", "negative");
+    }
+    if (observedRatio >= 0.7) {
+        score += 16;
+        pushSignal(strengths, "observed_evidence", "Observed evidence", "Most evidence came from directly observed target data rather than derived context.", "positive");
+    }
+    else if (observedRatio >= 0.45) {
+        score += 6;
+    }
+    else {
+        score -= 14;
+        pushSignal(gaps, "derived_heavy", "Derived-heavy evidence", "The result relies heavily on derived evidence, so direct verification is thinner.", "negative");
+    }
+    if (kinds.length >= 5) {
+        score += 12;
+        pushSignal(strengths, "evidence_breadth", "Evidence breadth", "The scan collected evidence across several posture areas.", "positive");
+    }
+    else if (kinds.length <= 2) {
+        score -= 12;
+        pushSignal(gaps, "narrow_evidence", "Narrow evidence", "Evidence came from a small number of source types.", "negative");
+    }
+    if (analysis.assessmentLimitation?.limited) {
+        score -= 35;
+        pushSignal(gaps, "limited_assessment", "Limited assessment", analysis.assessmentLimitation.detail ?? "The target response limited collection.", "negative");
+    }
+    if (timing?.timedOut) {
+        score -= 18;
+        pushSignal(gaps, "scan_timeout", "Scan timeout", "The scan timed out before all enrichment completed.", "negative");
+    }
+    if (analysis.statusCode >= 500 || analysis.statusCode === 0) {
+        score -= 14;
+        pushSignal(gaps, "availability_status", "Availability status", `The target returned HTTP ${analysis.statusCode}, reducing confidence in the observed posture.`, "negative");
+    }
+    else if (analysis.statusCode >= 200 && analysis.statusCode < 400) {
+        score += 8;
+        pushSignal(strengths, "normal_response", "Normal response", `The target returned HTTP ${analysis.statusCode}, supporting a normal posture read.`, "positive");
+    }
+    if (lowConfidence > 0) {
+        score -= Math.min(14, lowConfidence * 4);
+        pushSignal(gaps, "low_confidence_findings", "Low-confidence findings", `${lowConfidence} finding${lowConfidence === 1 ? "" : "s"} had low confidence.`, "negative");
+    }
+    if (highConfidence > 0 && highConfidence >= lowConfidence + mediumConfidence) {
+        score += 8;
+        pushSignal(strengths, "high_confidence_findings", "High-confidence findings", "Most findings were supported with high-confidence evidence.", "positive");
+    }
+    if (!normalizeArray(analysis.headers).length) {
+        score -= 10;
+        pushSignal(gaps, "missing_header_set", "Missing header set", "No response header set was available for the scan.", "negative");
+    }
+    if (!analysis.certificate?.available) {
+        score -= 8;
+        pushSignal(gaps, "certificate_unavailable", "Certificate unavailable", "The scan could not read a served TLS certificate.", "negative");
+    }
+    else if (analysis.certificate.authorized !== false) {
+        score += 6;
+        pushSignal(strengths, "certificate_observed", "Certificate observed", "A served TLS certificate was observed during the scan.", "positive");
+    }
+    const finalScore = clampScore(score);
+    const level = levelForScore(finalScore);
+    const recommendedFollowUp = [
+        ...(analysis.assessmentLimitation?.limited ? ["Restore complete scan coverage and rescan before treating the grade as final."] : []),
+        ...(timing?.timedOut ? ["Rerun the scan with a longer timeout or narrower mode to complete enrichment."] : []),
+        ...(observedRatio < 0.45 ? ["Verify the top findings manually because direct observed evidence is thin."] : []),
+        ...(kinds.length <= 2 ? ["Collect another scan after the target returns normal headers, TLS, DNS, and HTML evidence."] : []),
+    ];
+    if (recommendedFollowUp.length === 0) {
+        recommendedFollowUp.push("Use the score drivers and top insights as the primary follow-up path.");
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        level,
+        score: finalScore,
+        summary: buildSummary(level, analysis, gaps),
+        evidence: {
+            totalReferences,
+            observedReferences,
+            derivedReferences,
+            observedRatio: Number(observedRatio.toFixed(2)),
+            kinds: kinds.filter((kind) => OBSERVED_KINDS.has(kind) || kind === "probe" || kind === "score_driver"),
+        },
+        scan: {
+            limited: Boolean(analysis.assessmentLimitation?.limited),
+            limitedKind: analysis.assessmentLimitation?.kind ?? null,
+            timedOut: Boolean(timing?.timedOut),
+            statusCode: analysis.statusCode,
+            responseTimeMs: analysis.responseTimeMs,
+        },
+        findings: {
+            total: issues.length,
+            lowConfidence,
+            mediumConfidence,
+            highConfidence,
+        },
+        strengths: strengths.slice(0, 5),
+        gaps: gaps.slice(0, 5),
+        recommendedFollowUp: recommendedFollowUp.slice(0, 4),
+        limitation: analysis.assessmentLimitation?.limited ? analysis.assessmentLimitation : null,
+    };
+}

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { buildObservationLedger } from "./observations.js";
 export { diffObservationLedgers } from "./observationDrift.js";
 export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
+export { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 export { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";

package/dist/index.js

@@ -2,6 +2,7 @@ import { URL } from "node:url";
 import { scanTls } from "./certificate.js";
 import { buildActionPlan } from "./actionPlan.js";
 import { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
+import { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 import { buildExposureBrief } from "./exposureBrief.js";
 import { buildPostureInsights } from "./postureInsights.js";
 import { buildVendorExposureBrief } from "./vendorExposure.js";
@@ -511,10 +512,14 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
@@ -958,10 +963,14 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
@@ -1044,10 +1053,14 @@ export async function analyzeUrl(input, options = {}) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...resultWithEvidence, remediationPlan }),
     };
-    const resultWithBriefs = {
+    const resultWithQuality = {
         ...resultWithRemediation,
-        exposureBrief: buildExposureBrief(resultWithRemediation),
-        vendorExposure: buildVendorExposureBrief(resultWithRemediation),
+        evidenceQuality: buildEvidenceQualitySummary(resultWithRemediation),
+    };
+    const resultWithBriefs = {
+        ...resultWithQuality,
+        exposureBrief: buildExposureBrief(resultWithQuality),
+        vendorExposure: buildVendorExposureBrief(resultWithQuality),
     };
     const resultWithActions = {
         ...resultWithBriefs,
@@ -1069,6 +1082,7 @@ export { buildObservationLedger } from "./observations.js";
 export { diffObservationLedgers } from "./observationDrift.js";
 export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
+export { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 export { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";

package/dist/postureDigest.d.ts

@@ -20,7 +20,7 @@ export declare function buildPostureDigest(analysis: AnalysisResult, { findingLi
         posture: "strong" | "weak" | "mixed";
         takeaways: string[];
         limited: boolean;
-        limitedKind: "other" | "blocked_edge_response" | "auth_required" | "rate_limited" | "service_unavailable";
+        limitedKind: "blocked_edge_response" | "auth_required" | "rate_limited" | "service_unavailable" | "other";
         limitation: import("./types.js").AssessmentLimitation;
         scoreDrivers: import("./types.js").ScoreDriver[];
     };
@@ -59,6 +59,34 @@ export declare function buildPostureDigest(analysis: AnalysisResult, { findingLi
             scoreImpact: number;
         }[];
     };
+    evidenceQuality: {
+        level: import("./types.js").EvidenceQualityLevel;
+        score: number;
+        summary: string;
+        evidence: {
+            totalReferences: number;
+            observedReferences: number;
+            derivedReferences: number;
+            observedRatio: number;
+            kinds: import("./types.js").ScanEvidenceKind[];
+        };
+        scan: {
+            limited: boolean;
+            limitedKind: import("./types.js").AssessmentLimitation["kind"];
+            timedOut: boolean;
+            statusCode: number;
+            responseTimeMs: number;
+        };
+        findings: {
+            total: number;
+            lowConfidence: number;
+            mediumConfidence: number;
+            highConfidence: number;
+        };
+        strengths: import("./types.js").EvidenceQualitySignal[];
+        gaps: import("./types.js").EvidenceQualitySignal[];
+        recommendedFollowUp: string[];
+    };
     remediationPlan: {
         summary: string;
         totalActions: number;

package/dist/postureDigest.js

@@ -1,3 +1,4 @@
+import { buildEvidenceQualitySummary } from "./evidenceQuality.js";
 const SEVERITY_ORDER = {
     critical: 0,
     warning: 1,
@@ -31,6 +32,7 @@ export function buildPostureDigest(analysis, { findingLimit = 8 } = {}) {
     const issues = normalizeArray(analysis.issues);
     const compromiseIndicators = normalizeArray(analysis.compromiseSignals?.indicators);
     const riskIndicators = compromiseIndicators.filter((indicator) => ["warning", "critical"].includes(indicator.severity));
+    const evidenceQuality = analysis.evidenceQuality ?? buildEvidenceQualitySummary(analysis);
     return {
         generatedAt: new Date().toISOString(),
         target: {
@@ -77,6 +79,17 @@ export function buildPostureDigest(analysis, { findingLimit = 8 } = {}) {
                 scoreImpact: reference.scoreImpact,
             })),
         } : null,
+        evidenceQuality: {
+            level: evidenceQuality.level,
+            score: evidenceQuality.score,
+            summary: evidenceQuality.summary,
+            evidence: evidenceQuality.evidence,
+            scan: evidenceQuality.scan,
+            findings: evidenceQuality.findings,
+            strengths: normalizeArray(evidenceQuality.strengths).slice(0, 5),
+            gaps: normalizeArray(evidenceQuality.gaps).slice(0, 5),
+            recommendedFollowUp: normalizeArray(evidenceQuality.recommendedFollowUp).slice(0, 4),
+        },
         remediationPlan: analysis.remediationPlan ? {
             summary: analysis.remediationPlan.summary,
             totalActions: analysis.remediationPlan.totalActions,

package/dist/types.d.ts

@@ -172,6 +172,43 @@ export interface PostureEvidenceSummary {
     findingEvidence: PostureEvidenceSummaryReference[];
     limitation: AssessmentLimitation | null;
 }
+export type EvidenceQualityLevel = "high" | "medium" | "low";
+export interface EvidenceQualitySignal {
+    id: string;
+    label: string;
+    detail: string;
+    impact: "positive" | "negative" | "neutral";
+}
+export interface EvidenceQualitySummary {
+    generatedAt: string;
+    level: EvidenceQualityLevel;
+    score: number;
+    summary: string;
+    evidence: {
+        totalReferences: number;
+        observedReferences: number;
+        derivedReferences: number;
+        observedRatio: number;
+        kinds: ScanEvidenceKind[];
+    };
+    scan: {
+        limited: boolean;
+        limitedKind: AssessmentLimitation["kind"];
+        timedOut: boolean;
+        statusCode: number;
+        responseTimeMs: number;
+    };
+    findings: {
+        total: number;
+        lowConfidence: number;
+        mediumConfidence: number;
+        highConfidence: number;
+    };
+    strengths: EvidenceQualitySignal[];
+    gaps: EvidenceQualitySignal[];
+    recommendedFollowUp: string[];
+    limitation: AssessmentLimitation | null;
+}
 export type ExposureBriefLevel = "low" | "medium" | "high" | "critical" | "unknown";
 export type ExposureBriefCategory = "entry_point" | "trust_gap" | "abuse_signal" | "sensitive_exposure" | "third_party" | "identity" | "ai" | "infrastructure";
 export type ExposureBriefSource = "headers" | "tls" | "cookies" | "dns" | "html" | "public_record" | "third_party" | "ai" | "ct" | "api" | "exposure" | "derived";
@@ -1008,6 +1045,7 @@ export interface AnalysisResult {
     remediation: RemediationSnippet[];
     remediationPlan?: RemediationPlan;
     evidenceSummary?: PostureEvidenceSummary;
+    evidenceQuality?: EvidenceQualitySummary;
     exposureBrief?: ExposureBrief;
     vendorExposure?: VendorExposureBrief;
     actionPlan?: ActionPlan;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -66,6 +66,10 @@
       "types": "./dist/postureRemediation.d.ts",
       "default": "./dist/postureRemediation.js"
     },
+    "./evidence-quality": {
+      "types": "./dist/evidenceQuality.d.ts",
+      "default": "./dist/evidenceQuality.js"
+    },
     "./exposure-brief": {
       "types": "./dist/exposureBrief.d.ts",
       "default": "./dist/exposureBrief.js"