securl 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-06-14
+
+### Added
+- Added `buildPostureEvidenceSummary()` for compact, API/mobile-friendly evidence metadata that explains score drivers and findings without requiring clients to inspect the full scan payload.
+- Added the `securl/evidence-summary` package export for consumers that want the evidence summary helper directly.
+- Added `evidenceSummary` to completed analysis results and posture digests.
+
 ## [1.4.1] - 2026-06-14
 
 ### Changed

package/README.md

@@ -193,6 +193,20 @@ console.log(remediationPlan.items.map((item) => ({
 })));
 ```
 
+Version `1.5.0+` includes a compact evidence summary for API, mobile, and report clients that need to explain why a scan scored the way it did without walking the full result object.
+
+```js
+import { buildPostureEvidenceSummary } from "securl/evidence-summary";
+
+const evidenceSummary = buildPostureEvidenceSummary(resultWithEvidence);
+
+console.log({
+  total: evidenceSummary.totalEvidenceReferences,
+  observed: evidenceSummary.observedCount,
+  topEvidence: evidenceSummary.topEvidence,
+});
+```
+
 ## Package trust and release signals
 
 - public source repository with package code under `packages/core`
@@ -270,6 +284,7 @@ Primary exports:
 - `buildPostureDriftReportFromSnapshots(current, previous)` - produce a complete scan-to-scan drift report for monitoring, alerting, and history views.
 - `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.
 
 Package subpath exports:
 

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import type { AnalysisResult, AnalyzeTargetOptions, HtmlSecurityInfo } from "./t
 export { buildPostureRiskEventsFromDiff, buildPostureRiskEventsFromSnapshots } from "./riskEvents.js";
 export { buildPostureDigest } from "./postureDigest.js";
 export { buildPostureDriftReport, buildPostureDriftReportFromDiff, buildPostureDriftReportFromSnapshots, } from "./postureDrift.js";
-export { attachIssueEvidence, buildIssueEvidence, buildPostureRemediationPlan, } from "./postureRemediation.js";
+export { attachIssueEvidence, buildIssueEvidence, buildPostureEvidenceSummary, buildPostureRemediationPlan, } from "./postureRemediation.js";
 export type { PostureRiskEvent, PostureRiskEventSeverity } from "./types.js";
 declare function formatErrorMessage(error: any): string;
 export declare function analyzeHtmlDocument(input: string | URL, html: string): HtmlSecurityInfo;

package/dist/index.js

@@ -18,7 +18,7 @@ import { fetchWithRedirects, requestJson, requestOnce, requestText, requestWithH
 import { normalizeDiscoveredPath, rankDiscoveredPaths } from "./path-discovery.js";
 import { buildPassiveIntelligence, emptyPassiveIntelligence } from "./passive-intelligence.js";
 import { analyzeRedirectChain } from "./redirectChain.js";
-import { attachIssueEvidence, buildPostureRemediationPlan } from "./postureRemediation.js";
+import { attachIssueEvidence, buildPostureEvidenceSummary, buildPostureRemediationPlan } from "./postureRemediation.js";
 import { scoreAnalysis, scorePostureAnalysis, summarizePostureGrade } from "./scoring.js";
 import { fetchSecurityTxt } from "./security-txt.js";
 import { detectTechnologies } from "./technology-detection.js";
@@ -27,7 +27,7 @@ import { analyzeWafFingerprint } from "./wafFingerprint.js";
 export { buildPostureRiskEventsFromDiff, buildPostureRiskEventsFromSnapshots } from "./riskEvents.js";
 export { buildPostureDigest } from "./postureDigest.js";
 export { buildPostureDriftReport, buildPostureDriftReportFromDiff, buildPostureDriftReportFromSnapshots, } from "./postureDrift.js";
-export { attachIssueEvidence, buildIssueEvidence, buildPostureRemediationPlan, } from "./postureRemediation.js";
+export { attachIssueEvidence, buildIssueEvidence, buildPostureEvidenceSummary, buildPostureRemediationPlan, } from "./postureRemediation.js";
 function buildScanProfile(mode, requestedTimeoutMs) {
     const deepPassive = mode === "deep-passive";
     const scanTimeoutMs = requestedTimeoutMs ?? (deepPassive ? DEEP_PASSIVE_SCAN_TIMEOUT_MS : MAX_SCAN_DURATION_MS);
@@ -500,9 +500,11 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         },
     };
     const evidenceResult = attachIssueEvidence(limitedResult);
+    const remediationPlan = buildPostureRemediationPlan(evidenceResult);
     return {
         ...evidenceResult,
-        remediationPlan: buildPostureRemediationPlan(evidenceResult),
+        remediationPlan,
+        evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
 }
 async function enrichCoreResult(result, profile) {
@@ -928,9 +930,11 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         executiveSummary: buildExecutiveSummary(timedOutResult),
     };
     const evidenceResult = attachIssueEvidence(timedOutResultWithSummary);
+    const remediationPlan = buildPostureRemediationPlan(evidenceResult);
     return {
         ...evidenceResult,
-        remediationPlan: buildPostureRemediationPlan(evidenceResult),
+        remediationPlan,
+        evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
 }
 export async function analyzeUrl(input, options = {}) {
@@ -995,9 +999,11 @@ export async function analyzeUrl(input, options = {}) {
         executiveSummary: buildExecutiveSummary(scoredResult),
     };
     const resultWithEvidence = attachIssueEvidence(resultWithSummary);
+    const remediationPlan = buildPostureRemediationPlan(resultWithEvidence);
     return {
         ...resultWithEvidence,
-        remediationPlan: buildPostureRemediationPlan(resultWithEvidence),
+        remediationPlan,
+        evidenceSummary: buildPostureEvidenceSummary({ ...resultWithEvidence, remediationPlan }),
     };
 }
 export const analyzeTarget = analyzeUrl;

package/dist/postureDigest.d.ts

@@ -41,6 +41,24 @@ export declare function buildPostureDigest(analysis: AnalysisResult, { findingLi
             mitre: import("./types.js").MitreRelevance[];
         }[];
     };
+    evidence: {
+        summary: string;
+        totalEvidenceReferences: number;
+        byKind: Partial<Record<import("./types.js").ScanEvidenceKind, number>>;
+        observedCount: number;
+        derivedCount: number;
+        topEvidence: {
+            kind: import("./types.js").ScanEvidenceKind;
+            label: string;
+            observed: string;
+            expected: string;
+            source: import("./types.js").IssueSource | "headers" | "cookies" | "tls" | "dns" | "html" | "public_record" | "third_party" | "ai" | "availability" | "breadth" | "assessment_limit" | "derived";
+            areaLabel: string;
+            relatedFinding: string;
+            severity: "info" | "warning" | "critical";
+            scoreImpact: number;
+        }[];
+    };
     remediationPlan: {
         summary: string;
         totalActions: number;

package/dist/postureDigest.js

@@ -59,6 +59,24 @@ export function buildPostureDigest(analysis, { findingLimit = 8 } = {}) {
             bySeverity: countIssuesBySeverity(issues),
             top: topIssues(issues, findingLimit),
         },
+        evidence: analysis.evidenceSummary ? {
+            summary: analysis.evidenceSummary.summary,
+            totalEvidenceReferences: analysis.evidenceSummary.totalEvidenceReferences,
+            byKind: analysis.evidenceSummary.byKind,
+            observedCount: analysis.evidenceSummary.observedCount,
+            derivedCount: analysis.evidenceSummary.derivedCount,
+            topEvidence: normalizeArray(analysis.evidenceSummary.topEvidence).slice(0, 5).map((reference) => ({
+                kind: reference.kind,
+                label: reference.label,
+                observed: reference.observed,
+                expected: reference.expected,
+                source: reference.source,
+                areaLabel: reference.areaLabel,
+                relatedFinding: reference.relatedFinding,
+                severity: reference.severity,
+                scoreImpact: reference.scoreImpact,
+            })),
+        } : null,
         remediationPlan: analysis.remediationPlan ? {
             summary: analysis.remediationPlan.summary,
             totalActions: analysis.remediationPlan.totalActions,

package/dist/postureRemediation.d.ts

@@ -1,6 +1,10 @@
 import type { AnalysisResult, RemediationPlan, ScanEvidenceReference, ScanIssue } from "./types.js";
+import type { PostureEvidenceSummary } from "./types.js";
 export declare function buildIssueEvidence(issue: ScanIssue, analysis: AnalysisResult): ScanEvidenceReference[];
 export declare function attachIssueEvidence(analysis: AnalysisResult): AnalysisResult;
+export declare function buildPostureEvidenceSummary(analysis: AnalysisResult, { limit }?: {
+    limit?: number;
+}): PostureEvidenceSummary;
 export declare function buildPostureRemediationPlan(analysis: AnalysisResult, { limit }?: {
     limit?: number;
 }): RemediationPlan;

package/dist/postureRemediation.js

@@ -73,6 +73,9 @@ function evidenceKindForScoreSource(source) {
         return "public_record";
     return "score_driver";
 }
+function incrementCount(counts, key) {
+    counts[key] = (counts[key] ?? 0) + 1;
+}
 function headerEvidenceForIssue(issue, headers) {
     const issueText = `${issue.title} ${issue.detail}`.toLowerCase();
     const matched = headers.find((header) => issueText.includes(header.label.toLowerCase()) || issueText.includes(header.key.toLowerCase()));
@@ -165,6 +168,65 @@ export function attachIssueEvidence(analysis) {
         })),
     };
 }
+function rankEvidence(left, right) {
+    const impactDelta = (right.scoreImpact ?? -1) - (left.scoreImpact ?? -1);
+    if (impactDelta !== 0)
+        return impactDelta;
+    const severityRank = { critical: 0, warning: 1, info: 2 };
+    const severityDelta = (severityRank[left.severity ?? "info"] ?? 2) - (severityRank[right.severity ?? "info"] ?? 2);
+    if (severityDelta !== 0)
+        return severityDelta;
+    return left.label.localeCompare(right.label);
+}
+export function buildPostureEvidenceSummary(analysis, { limit = 12 } = {}) {
+    const scoreDriverEvidence = normalizeArray(analysis.scoreDrivers)
+        .filter((driver) => driver.impact > 0)
+        .map((driver) => ({
+        kind: evidenceKindForScoreSource(driver.source),
+        label: driver.label,
+        observed: driver.detail,
+        source: driver.source,
+        areaLabel: driver.areaLabel,
+        scoreImpact: driver.impact,
+    }));
+    const findingEvidence = normalizeArray(analysis.issues).flatMap((issue) => {
+        const evidence = normalizeArray(issue.evidence).length ? normalizeArray(issue.evidence) : buildIssueEvidence(issue, analysis);
+        return evidence.map((reference) => ({
+            ...reference,
+            relatedFinding: issue.title,
+            severity: issue.severity,
+            scoreImpact: null,
+        }));
+    });
+    const allEvidence = [
+        ...scoreDriverEvidence,
+        ...findingEvidence,
+    ];
+    const byKind = {};
+    const bySource = {};
+    for (const reference of allEvidence) {
+        incrementCount(byKind, reference.kind);
+        incrementCount(bySource, String(reference.source ?? "unknown"));
+    }
+    const observedKinds = new Set(["header", "tls", "cookie", "redirect", "dns", "html", "public_record"]);
+    const observedCount = allEvidence.filter((reference) => observedKinds.has(reference.kind)).length;
+    const derivedCount = allEvidence.length - observedCount;
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: allEvidence.length
+            ? `${allEvidence.length} evidence reference${allEvidence.length === 1 ? "" : "s"} explain the main score drivers and findings.`
+            : "No structured evidence references were generated for this scan.",
+        totalEvidenceReferences: allEvidence.length,
+        byKind,
+        bySource,
+        observedCount,
+        derivedCount,
+        topEvidence: [...allEvidence].sort(rankEvidence).slice(0, limit),
+        scoreDriverEvidence: scoreDriverEvidence.slice(0, limit),
+        findingEvidence: findingEvidence.sort(rankEvidence).slice(0, limit),
+        limitation: analysis.assessmentLimitation ?? null,
+    };
+}
 function relatedFindingsForDriver(driver, issues) {
     const driverText = `${driver.areaKey} ${driver.label} ${driver.detail}`.toLowerCase();
     return issues

package/dist/types.d.ts

@@ -137,6 +137,25 @@ export interface RemediationPlan {
     quickWins: number;
     items: RemediationPlanItem[];
 }
+export interface PostureEvidenceSummaryReference extends ScanEvidenceReference {
+    areaLabel?: string;
+    relatedFinding?: string;
+    severity?: Exclude<Severity, "good">;
+    scoreImpact?: number | null;
+}
+export interface PostureEvidenceSummary {
+    generatedAt: string;
+    summary: string;
+    totalEvidenceReferences: number;
+    byKind: Partial<Record<ScanEvidenceKind, number>>;
+    bySource: Record<string, number>;
+    observedCount: number;
+    derivedCount: number;
+    topEvidence: PostureEvidenceSummaryReference[];
+    scoreDriverEvidence: PostureEvidenceSummaryReference[];
+    findingEvidence: PostureEvidenceSummaryReference[];
+    limitation: AssessmentLimitation | null;
+}
 export interface CrawlPageResult {
     label: string;
     path: string;
@@ -701,6 +720,7 @@ export interface AnalysisResult {
     strengths: string[];
     remediation: RemediationSnippet[];
     remediationPlan?: RemediationPlan;
+    evidenceSummary?: PostureEvidenceSummary;
     crawl: CrawlSummary;
     securityTxt: SecurityTxtInfo;
     domainSecurity: DomainSecurityInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "description": "Passive external security posture analysis engine for SecURL.",
   "author": {
@@ -61,6 +61,10 @@
     "./remediation-plan": {
       "types": "./dist/postureRemediation.d.ts",
       "default": "./dist/postureRemediation.js"
+    },
+    "./evidence-summary": {
+      "types": "./dist/postureRemediation.d.ts",
+      "default": "./dist/postureRemediation.js"
     }
   },
   "files": [