securl 1.11.0 → 1.12.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.12.0] - 2026-06-27
+
+### Added
+- Added `buildPostureInsights()` and the `securl/posture-insights` package export for display-ready risk themes, top insights, and next-best actions.
+- Added `postureInsights` to completed analysis results so API, mobile, and CLI clients can render security judgement without reinterpreting raw findings.
+
+## [1.11.1] - 2026-06-24
+
+### Changed
+- Updated `node-html-parser` to 8.0.3, replacing the retired entity decoder while preserving the existing parsing API and Node 22 runtime floor.
+
 ## [1.11.0] - 2026-06-20
 
 ### Added

package/README.md

@@ -194,7 +194,28 @@ console.log({
 
 Action-plan items include owner, effort, impact, confidence, score impact where available, evidence references, and verification guidance.
 
-### 7. Live certificate checks
+### 7. Posture insights
+
+Version `1.12.0+` includes a posture-insights helper for client surfaces that need display-ready risk themes and next-best actions.
+
+```ts
+import { analyzeUrl } from "securl";
+import { buildPostureInsights } from "securl/posture-insights";
+
+const result = await analyzeUrl("https://example.com");
+const insights = buildPostureInsights(result);
+
+console.log({
+  summary: insights.summary,
+  themes: insights.themes,
+  topInsights: insights.topInsights,
+  nextBestActions: insights.nextBestActions,
+});
+```
+
+Posture insights are derived from the action plan, so clients can render security judgement without reinterpreting raw findings, score drivers, exposure details, or vendor context.
+
+### 8. Live certificate checks
 
 Version `1.9.0+` includes a lightweight certificate helper for Cert Watch-style clients that only need the currently served TLS certificate.
 
@@ -313,7 +334,7 @@ It is also used by the SecURL app from the local workspace during development.
 - local package check: `npm run pack:core`
 - CI verification: `.github/workflows/core-package-checks.yml`
 - publish workflow: `.github/workflows/publish-core-package.yml`
-- publish requires an `NPM_TOKEN` repository secret
+- publish uses npm Trusted Publishing through GitHub Actions OIDC
 - publish uses npm provenance (`npm publish --provenance`)
 
 Recommended release flow:
@@ -341,6 +362,7 @@ Primary exports:
 - `buildPostureRiskEventsFromSnapshots(current, previous, diff)` - classify scan changes into alert-friendly risk events.
 - `buildPostureDigest(result)` - reduce a full scan result to a compact API/mobile-friendly digest.
 - `buildActionPlan(result)` - turn remediation, score drivers, exposure, and vendor context into prioritized fix actions.
+- `buildPostureInsights(result)` - summarize risk themes, top insights, and next-best actions for client surfaces.
 - `scanLiveCertificate(url)` - perform a TLS handshake-only certificate read for lightweight cert monitoring.
 - `buildObservationLedger(result)` - produce stable source, confidence, status, and freshness-aware posture observations.
 - `diffObservationLedgers(current, previous)` - compare stable observations and classify their operational impact.
@@ -355,6 +377,7 @@ Package subpath exports:
 - `securl/history-diff`
 - `securl/posture-digest`
 - `securl/action-plan`
+- `securl/posture-insights`
 - `securl/live-certificate`
 - `securl/observations`
 - `securl/observation-drift`

package/RELEASING.md

@@ -21,14 +21,21 @@ git diff --name-status securl-v$(node -p "require('./packages/core/package.json'
 3. Run:
    - `npm run release:core:check`
 4. Review the dry-run tarball contents.
-5. Confirm `NPM_TOKEN` is present in GitHub repository secrets.
+5. Confirm npm Trusted Publishing is configured for this package:
+   - provider: GitHub Actions
+   - organization: `this-is-securl`
+   - repository: `securl`
+   - workflow filename: `publish-core-package.yml`
+   - allowed action: `npm publish`
 
 ## Release steps
 
 1. Commit the version/changelog update.
 2. Tag the release using `securl-v<version>`, for example `securl-v1.4.1`.
 3. Push the tag.
-4. Let `.github/workflows/publish-core-package.yml` publish the package.
+4. Let `.github/workflows/publish-core-package.yml` publish the package through short-lived npm OIDC credentials.
+
+The publish workflow verifies that the release commit is already contained in `origin/main` with `git merge-base --is-ancestor`. If a manual workflow dispatch is needed after a tag publish failure, run it from `main`; the package version comes from `packages/core/package.json`.
 
 ## Post-release
 

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 { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";

package/dist/index.js

@@ -3,6 +3,7 @@ import { scanTls } from "./certificate.js";
 import { buildActionPlan } from "./actionPlan.js";
 import { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
 import { buildExposureBrief } from "./exposureBrief.js";
+import { buildPostureInsights } from "./postureInsights.js";
 import { buildVendorExposureBrief } from "./vendorExposure.js";
 import { parseSetCookie } from "./cookie-analysis.js";
 import { analyzeCookieHeaders } from "./cookieAnalysis.js";
@@ -519,9 +520,13 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 async function enrichCoreResult(result, profile) {
@@ -962,9 +967,13 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 export async function analyzeUrl(input, options = {}) {
@@ -1044,9 +1053,13 @@ export async function analyzeUrl(input, options = {}) {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
-    return {
+    const resultWithInsights = {
         ...resultWithActions,
-        observationLedger: buildObservationLedger(resultWithActions),
+        postureInsights: buildPostureInsights(resultWithActions),
+    };
+    return {
+        ...resultWithInsights,
+        observationLedger: buildObservationLedger(resultWithInsights),
     };
 }
 export const analyzeTarget = analyzeUrl;
@@ -1056,6 +1069,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 { buildPostureInsights } from "./postureInsights.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";

package/dist/postureInsights.d.ts

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

package/dist/postureInsights.js

@@ -0,0 +1,127 @@
+import { buildActionPlan } from "./actionPlan.js";
+const SEVERITY_RANK = {
+    critical: 3,
+    warning: 2,
+    info: 1,
+};
+const THEME_LABELS = {
+    browser_hardening: "Browser hardening",
+    transport: "Transport security",
+    domain_trust: "Domain trust",
+    public_exposure: "Public exposure",
+    vendor_risk: "Vendor risk",
+    identity: "Identity surface",
+    availability: "Availability",
+    monitoring: "Monitoring",
+};
+function severityForAction(item) {
+    if (item.impact === "high" || (item.scoreImpact ?? 0) >= 10) {
+        return "critical";
+    }
+    if (item.impact === "medium" || (item.scoreImpact ?? 0) >= 4) {
+        return "warning";
+    }
+    return "info";
+}
+function highestSeverity(left, right) {
+    return SEVERITY_RANK[right] > SEVERITY_RANK[left] ? right : left;
+}
+function buildSummary(analysis, insights) {
+    if (analysis.assessmentLimitation?.limited) {
+        return "The scan was limited, so restore complete scan coverage before treating the posture read as final.";
+    }
+    if (!insights.length) {
+        return "No immediate posture action stands out from the passive evidence. Keep monitoring and rescan after meaningful changes.";
+    }
+    const critical = insights.filter((insight) => insight.severity === "critical").length;
+    if (critical > 0) {
+        return `${critical} critical insight${critical === 1 ? "" : "s"} should be reviewed first because ${critical === 1 ? "it carries" : "they carry"} the highest posture impact.`;
+    }
+    return `${insights.length} actionable insight${insights.length === 1 ? "" : "s"} ${insights.length === 1 ? "is" : "are"} available for follow-up.`;
+}
+function buildThemeSummaries(items) {
+    const themes = new Map();
+    for (const item of items) {
+        const severity = severityForAction(item);
+        const existing = themes.get(item.theme);
+        if (!existing) {
+            themes.set(item.theme, {
+                theme: item.theme,
+                label: THEME_LABELS[item.theme],
+                count: 1,
+                highestSeverity: severity,
+                highImpactActions: item.impact === "high" ? 1 : 0,
+                quickWins: item.effort === "low" ? 1 : 0,
+                owners: [item.owner],
+                scoreImpact: item.scoreImpact ?? 0,
+            });
+            continue;
+        }
+        existing.count += 1;
+        existing.highestSeverity = highestSeverity(existing.highestSeverity, severity);
+        existing.highImpactActions += item.impact === "high" ? 1 : 0;
+        existing.quickWins += item.effort === "low" ? 1 : 0;
+        existing.scoreImpact += item.scoreImpact ?? 0;
+        if (!existing.owners.includes(item.owner)) {
+            existing.owners.push(item.owner);
+        }
+    }
+    return [...themes.values()].sort((left, right) => {
+        const severityDelta = SEVERITY_RANK[right.highestSeverity] - SEVERITY_RANK[left.highestSeverity];
+        if (severityDelta !== 0)
+            return severityDelta;
+        const impactDelta = right.highImpactActions - left.highImpactActions;
+        if (impactDelta !== 0)
+            return impactDelta;
+        return right.scoreImpact - left.scoreImpact;
+    });
+}
+function toInsight(item) {
+    return {
+        id: `insight:${item.id}`,
+        title: item.title,
+        summary: item.whyNow,
+        severity: severityForAction(item),
+        theme: item.theme,
+        owner: item.owner,
+        effort: item.effort,
+        impact: item.impact,
+        confidence: item.confidence,
+        scoreImpact: item.scoreImpact,
+        nextAction: item.action,
+        verify: item.verify,
+        evidence: item.evidence,
+        relatedFindings: item.relatedFindings,
+        source: item.source,
+    };
+}
+function toNextBestAction(item) {
+    return {
+        id: item.id,
+        label: item.action,
+        theme: item.theme,
+        owner: item.owner,
+        effort: item.effort,
+        impact: item.impact,
+        severity: severityForAction(item),
+        verify: item.verify,
+    };
+}
+export function buildPostureInsights(analysis) {
+    const actionPlan = analysis.actionPlan ?? buildActionPlan(analysis);
+    const topItems = actionPlan.items.slice(0, 6);
+    const topInsights = topItems.map(toInsight);
+    const ownerOrder = ["edge", "app", "dns", "identity", "third_party"];
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: buildSummary(analysis, topInsights),
+        posture: actionPlan.posture,
+        themes: buildThemeSummaries(actionPlan.items).map((theme) => ({
+            ...theme,
+            owners: [...theme.owners].sort((left, right) => ownerOrder.indexOf(left) - ownerOrder.indexOf(right)),
+        })),
+        topInsights,
+        nextBestActions: topItems.slice(0, 3).map(toNextBestAction),
+        limitation: actionPlan.limitation,
+    };
+}

package/dist/types.d.ts

@@ -274,6 +274,53 @@ export interface ActionPlan {
     nextReview: string;
     limitation: AssessmentLimitation | null;
 }
+export type PostureInsightSeverity = "info" | "warning" | "critical";
+export interface PostureInsightThemeSummary {
+    theme: ActionPlanTheme;
+    label: string;
+    count: number;
+    highestSeverity: PostureInsightSeverity;
+    highImpactActions: number;
+    quickWins: number;
+    owners: RemediationOwner[];
+    scoreImpact: number;
+}
+export interface PostureInsightItem {
+    id: string;
+    title: string;
+    summary: string;
+    severity: PostureInsightSeverity;
+    theme: ActionPlanTheme;
+    owner: RemediationOwner;
+    effort: RemediationEffort;
+    impact: RemediationImpact;
+    confidence: IssueConfidence;
+    scoreImpact: number | null;
+    nextAction: string;
+    verify: string;
+    evidence: ScanEvidenceReference[];
+    relatedFindings: string[];
+    source: ActionPlanItem["source"];
+}
+export interface PostureInsightAction {
+    id: string;
+    label: string;
+    theme: ActionPlanTheme;
+    owner: RemediationOwner;
+    effort: RemediationEffort;
+    impact: RemediationImpact;
+    severity: PostureInsightSeverity;
+    verify: string;
+}
+export interface PostureInsights {
+    generatedAt: string;
+    summary: string;
+    posture: ActionPlan["posture"];
+    themes: PostureInsightThemeSummary[];
+    topInsights: PostureInsightItem[];
+    nextBestActions: PostureInsightAction[];
+    limitation: AssessmentLimitation | null;
+}
 export interface CrawlPageResult {
     label: string;
     path: string;
@@ -964,6 +1011,7 @@ export interface AnalysisResult {
     exposureBrief?: ExposureBrief;
     vendorExposure?: VendorExposureBrief;
     actionPlan?: ActionPlan;
+    postureInsights?: PostureInsights;
     crawl: CrawlSummary;
     securityTxt: SecurityTxtInfo;
     domainSecurity: DomainSecurityInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -78,6 +78,10 @@
       "types": "./dist/actionPlan.d.ts",
       "default": "./dist/actionPlan.js"
     },
+    "./posture-insights": {
+      "types": "./dist/postureInsights.d.ts",
+      "default": "./dist/postureInsights.js"
+    },
     "./live-certificate": {
       "types": "./dist/certificate.d.ts",
       "default": "./dist/certificate.js"
@@ -129,6 +133,6 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "node-html-parser": "^7.1.0"
+    "node-html-parser": "^8.0.3"
   }
 }