securl 1.7.0 → 1.8.0

package/README.md

@@ -174,6 +174,26 @@ console.log({
 });
 ```
 
+### 6. Prioritized action plans
+
+Version `1.8.0+` includes an action-plan helper for client surfaces that need to show what to fix first without reinterpreting the full scan result.
+
+```ts
+import { analyzeUrl, buildActionPlan } from "securl";
+
+const result = await analyzeUrl("https://example.com");
+const actionPlan = buildActionPlan(result);
+
+console.log({
+  grade: actionPlan.posture.grade,
+  mainRisk: actionPlan.posture.mainRisk,
+  highImpactActions: actionPlan.highImpactActions,
+  firstAction: actionPlan.items[0],
+});
+```
+
+Action-plan items include owner, effort, impact, confidence, score impact where available, evidence references, and verification guidance.
+
 ### 6. Evidence-backed remediation plans
 
 Version `1.4.0+` includes a remediation plan helper that turns score drivers and findings into prioritized, owner-aware fix guidance. Findings can also carry structured evidence references so clients can show why a finding was raised.
@@ -283,6 +303,7 @@ Primary exports:
 - `buildHistoryDiffFromSnapshots(current, previous)` - build a structured diff between scans.
 - `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.
 - `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.
@@ -292,6 +313,7 @@ Package subpath exports:
 
 - `securl/history-diff`
 - `securl/posture-digest`
+- `securl/action-plan`
 - `securl/posture-drift`
 - `securl/remediation-plan`
 - `securl/risk-events`

package/dist/actionPlan.d.ts

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

package/dist/actionPlan.js

@@ -0,0 +1,315 @@
+const normalizeArray = (value) => (Array.isArray(value) ? value : []);
+const IMPACT_RANK = {
+    high: 0,
+    medium: 1,
+    low: 2,
+};
+function evidenceFromText(label, observed, kind, source) {
+    return {
+        kind,
+        label,
+        observed,
+        source: source,
+    };
+}
+function evidenceKindForExposure(source) {
+    if (source === "dns") {
+        return "dns";
+    }
+    if (source === "tls") {
+        return "tls";
+    }
+    if (source === "cookies") {
+        return "cookie";
+    }
+    if (source === "headers") {
+        return "header";
+    }
+    if (source === "html" || source === "third_party" || source === "ai") {
+        return "html";
+    }
+    if (source === "public_record" || source === "ct") {
+        return "public_record";
+    }
+    return "probe";
+}
+function ownerForExposure(category) {
+    if (category === "trust_gap") {
+        return "dns";
+    }
+    if (category === "third_party" || category === "ai") {
+        return "third_party";
+    }
+    if (category === "identity") {
+        return "identity";
+    }
+    if (category === "entry_point" || category === "infrastructure") {
+        return "edge";
+    }
+    return "app";
+}
+function themeForOwner(owner, title) {
+    const value = title.toLowerCase();
+    if (owner === "dns") {
+        return "domain_trust";
+    }
+    if (owner === "third_party") {
+        return "vendor_risk";
+    }
+    if (owner === "identity") {
+        return "identity";
+    }
+    if (value.includes("tls") || value.includes("certificate") || value.includes("https") || value.includes("hsts")) {
+        return "transport";
+    }
+    if (value.includes("monitor") || value.includes("rescan")) {
+        return "monitoring";
+    }
+    if (value.includes("unreachable") || value.includes("timeout") || value.includes("service")) {
+        return "availability";
+    }
+    if (value.includes("header") || value.includes("policy") || value.includes("cookie") || value.includes("csp")) {
+        return "browser_hardening";
+    }
+    return "public_exposure";
+}
+function themeForExposure(item) {
+    if (item.category === "trust_gap") {
+        return "domain_trust";
+    }
+    if (item.category === "third_party" || item.category === "ai") {
+        return "vendor_risk";
+    }
+    if (item.category === "identity") {
+        return "identity";
+    }
+    if (item.category === "entry_point" || item.category === "infrastructure") {
+        return "public_exposure";
+    }
+    if (item.source === "tls") {
+        return "transport";
+    }
+    return "public_exposure";
+}
+function impactForExposure(item) {
+    if (item.severity === "critical" || item.severity === "warning") {
+        return "high";
+    }
+    if (item.severity === "watch") {
+        return "medium";
+    }
+    return "low";
+}
+function effortForExposure(item) {
+    if (item.category === "entry_point" || item.category === "trust_gap") {
+        return "low";
+    }
+    if (item.category === "third_party" || item.category === "ai") {
+        return "medium";
+    }
+    return item.severity === "critical" ? "high" : "medium";
+}
+function scoreDriverAction(driver) {
+    if (driver.impact > 0) {
+        return `Review and improve ${driver.label} so this score driver no longer reduces the passive posture score.`;
+    }
+    return `Review ${driver.label} and confirm it is intentionally configured.`;
+}
+function scoreDriverTheme(driver) {
+    if (driver.source === "dns" || driver.areaKey === "domain") {
+        return "domain_trust";
+    }
+    if (driver.source === "tls") {
+        return "transport";
+    }
+    if (driver.source === "cookies" || driver.source === "headers") {
+        return "browser_hardening";
+    }
+    if (driver.source === "third_party" || driver.source === "ai") {
+        return "vendor_risk";
+    }
+    return "public_exposure";
+}
+function scoreDriverOwner(driver) {
+    if (driver.source === "dns" || driver.areaKey === "domain") {
+        return "dns";
+    }
+    if (driver.source === "headers" || driver.source === "tls") {
+        return "edge";
+    }
+    if (driver.source === "third_party" || driver.source === "ai") {
+        return "third_party";
+    }
+    if (driver.source === "cookies") {
+        return "app";
+    }
+    return "app";
+}
+function scoreDriverEvidence(driver) {
+    return [{
+            kind: "score_driver",
+            label: driver.label,
+            observed: driver.detail,
+            source: driver.source,
+        }];
+}
+function vendorEvidence(provider) {
+    return [{
+            kind: "html",
+            label: provider.domain || provider.name,
+            observed: provider.evidence,
+            source: "derived",
+        }];
+}
+function actionKey(item) {
+    return `${item.theme}:${item.title}:${item.action}`.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function dedupeItems(items) {
+    const seen = new Set();
+    const unique = [];
+    for (const item of items) {
+        const key = actionKey(item);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(item);
+    }
+    return unique;
+}
+function sortItems(items) {
+    return [...items].sort((left, right) => {
+        const impactDelta = IMPACT_RANK[left.impact] - IMPACT_RANK[right.impact];
+        if (impactDelta !== 0) {
+            return impactDelta;
+        }
+        const priorityDelta = left.priority - right.priority;
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        return (right.scoreImpact ?? 0) - (left.scoreImpact ?? 0);
+    }).map((item, index) => ({
+        ...item,
+        priority: index + 1,
+    }));
+}
+function buildSummary(analysis, items) {
+    if (analysis.assessmentLimitation?.limited) {
+        return "The assessment was limited, so the first priority is restoring reliable scan coverage before treating the grade as complete.";
+    }
+    if (items.length === 0) {
+        return "No immediate action was identified from the passive evidence. Keep monitoring and rescan after deployment, DNS, or vendor changes.";
+    }
+    const highImpact = items.filter((item) => item.impact === "high").length;
+    if (highImpact > 0) {
+        return `${highImpact} high-impact action${highImpact === 1 ? "" : "s"} should move first because they affect the visible security posture most.`;
+    }
+    return "The next actions are mostly cleanup and monitoring work; no high-impact passive issue is currently leading the posture.";
+}
+export function buildActionPlan(analysis) {
+    const items = [];
+    for (const planItem of normalizeArray(analysis.remediationPlan?.items)) {
+        items.push({
+            id: `remediation:${planItem.id}`,
+            priority: planItem.priority,
+            title: planItem.title,
+            whyNow: planItem.scoreImpact && planItem.scoreImpact > 0
+                ? `This is costing about ${planItem.scoreImpact} point${planItem.scoreImpact === 1 ? "" : "s"} in the passive score.`
+                : planItem.detail,
+            action: planItem.action,
+            verify: planItem.verify,
+            owner: planItem.owner,
+            effort: planItem.effort,
+            impact: planItem.impact,
+            scoreImpact: planItem.scoreImpact,
+            confidence: "high",
+            theme: themeForOwner(planItem.owner, planItem.title),
+            evidence: normalizeArray(planItem.evidence).slice(0, 5),
+            relatedFindings: normalizeArray(planItem.relatedFindings).slice(0, 5),
+            source: "remediation",
+        });
+    }
+    for (const risk of normalizeArray(analysis.exposureBrief?.topRisks)) {
+        if (!risk.action) {
+            continue;
+        }
+        const owner = ownerForExposure(risk.category);
+        items.push({
+            id: `exposure:${risk.category}:${risk.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}`,
+            priority: 50,
+            title: risk.title,
+            whyNow: risk.detail,
+            action: risk.action,
+            verify: "Rescan the target and confirm this exposure brief item is no longer reported as a top risk.",
+            owner,
+            effort: effortForExposure(risk),
+            impact: impactForExposure(risk),
+            scoreImpact: null,
+            confidence: risk.confidence,
+            theme: themeForExposure(risk),
+            evidence: normalizeArray(risk.evidence).map((evidence) => evidenceFromText(risk.title, evidence, evidenceKindForExposure(risk.source), risk.source)).slice(0, 5),
+            relatedFindings: [risk.detail],
+            source: "exposure_brief",
+        });
+    }
+    for (const provider of normalizeArray(analysis.vendorExposure?.highPriorityProviders)) {
+        items.push({
+            id: `vendor:${provider.domain || provider.name}`.toLowerCase(),
+            priority: provider.reviewPriority === "urgent" ? 40 : 60,
+            title: `Review ${provider.name} vendor exposure`,
+            whyNow: `${provider.domain} is visible as a ${provider.risk}-risk ${provider.category} provider with ${provider.dataFlow.replace(/_/g, " ")} data-flow implications.`,
+            action: provider.action,
+            verify: "Rescan the target and confirm the provider remains documented, intentionally loaded, or no longer appears.",
+            owner: "third_party",
+            effort: "medium",
+            impact: provider.reviewPriority === "urgent" || provider.risk === "high" ? "high" : "medium",
+            scoreImpact: null,
+            confidence: "medium",
+            theme: "vendor_risk",
+            evidence: vendorEvidence(provider),
+            relatedFindings: [provider.domain],
+            source: "vendor_exposure",
+        });
+    }
+    if (items.length === 0) {
+        for (const driver of normalizeArray(analysis.scoreDrivers).filter((driver) => driver.impact > 0).slice(0, 5)) {
+            const owner = scoreDriverOwner(driver);
+            items.push({
+                id: `score:${driver.areaKey}:${driver.label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}`,
+                priority: 100 - driver.impact,
+                title: driver.label,
+                whyNow: driver.detail,
+                action: scoreDriverAction(driver),
+                verify: "Rescan and confirm this score driver is no longer reported as missing or warning.",
+                owner,
+                effort: driver.impact >= 8 ? "medium" : "low",
+                impact: driver.impact >= 10 ? "high" : driver.impact >= 4 ? "medium" : "low",
+                scoreImpact: driver.impact,
+                confidence: "medium",
+                theme: scoreDriverTheme(driver),
+                evidence: scoreDriverEvidence(driver),
+                relatedFindings: [driver.detail],
+                source: "score_driver",
+            });
+        }
+    }
+    const sortedItems = sortItems(dedupeItems(items)).slice(0, 8);
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: buildSummary(analysis, sortedItems),
+        posture: {
+            score: analysis.score,
+            grade: analysis.grade,
+            limited: Boolean(analysis.assessmentLimitation?.limited),
+            mainRisk: sortedItems[0]?.title ?? null,
+        },
+        totalActions: sortedItems.length,
+        highImpactActions: sortedItems.filter((item) => item.impact === "high").length,
+        quickWins: sortedItems.filter((item) => item.effort === "low").length,
+        items: sortedItems,
+        nextReview: analysis.assessmentLimitation?.limited
+            ? "Resolve the limited-assessment condition and rerun the scan before relying on the grade."
+            : "Rerun after the high-impact actions are complete, and again after deployment, DNS, or vendor changes.",
+        limitation: analysis.assessmentLimitation?.limited ? analysis.assessmentLimitation : null,
+    };
+}

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export declare function analyzeUrl(input: string, options?: AnalyzeTargetOptions
 export declare const analyzeTarget: typeof analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
+export { buildActionPlan } from "./actionPlan.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";
 export { analyzeInfrastructure } from "./infrastructure.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { URL } from "node:url";
 import { scanTls } from "./certificate.js";
+import { buildActionPlan } from "./actionPlan.js";
 import { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
 import { buildExposureBrief } from "./exposureBrief.js";
 import { buildVendorExposureBrief } from "./vendorExposure.js";
@@ -508,11 +509,15 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    return {
+    const resultWithBriefs = {
         ...resultWithRemediation,
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
+    return {
+        ...resultWithBriefs,
+        actionPlan: buildActionPlan(resultWithBriefs),
+    };
 }
 async function enrichCoreResult(result, profile) {
     const finalUrl = new URL(result.finalUrl);
@@ -943,11 +948,15 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...evidenceResult, remediationPlan }),
     };
-    return {
+    const resultWithBriefs = {
         ...resultWithRemediation,
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
+    return {
+        ...resultWithBriefs,
+        actionPlan: buildActionPlan(resultWithBriefs),
+    };
 }
 export async function analyzeUrl(input, options = {}) {
     const scanStartedAt = Date.now();
@@ -1017,15 +1026,20 @@ export async function analyzeUrl(input, options = {}) {
         remediationPlan,
         evidenceSummary: buildPostureEvidenceSummary({ ...resultWithEvidence, remediationPlan }),
     };
-    return {
+    const resultWithBriefs = {
         ...resultWithRemediation,
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
+    return {
+        ...resultWithBriefs,
+        actionPlan: buildActionPlan(resultWithBriefs),
+    };
 }
 export const analyzeTarget = analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
+export { buildActionPlan } from "./actionPlan.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";
 export { analyzeInfrastructure } from "./infrastructure.js";

package/dist/types.d.ts

@@ -224,6 +224,40 @@ export interface VendorExposureBrief {
     collectionBoundary: string;
     limitation: AssessmentLimitation | null;
 }
+export type ActionPlanTheme = "browser_hardening" | "transport" | "domain_trust" | "public_exposure" | "vendor_risk" | "identity" | "availability" | "monitoring";
+export interface ActionPlanItem {
+    id: string;
+    priority: number;
+    title: string;
+    whyNow: string;
+    action: string;
+    verify: string;
+    owner: RemediationOwner;
+    effort: RemediationEffort;
+    impact: RemediationImpact;
+    scoreImpact: number | null;
+    confidence: IssueConfidence;
+    theme: ActionPlanTheme;
+    evidence: ScanEvidenceReference[];
+    relatedFindings: string[];
+    source: "remediation" | "score_driver" | "exposure_brief" | "vendor_exposure";
+}
+export interface ActionPlan {
+    generatedAt: string;
+    summary: string;
+    posture: {
+        score: number;
+        grade: string;
+        limited: boolean;
+        mainRisk: string | null;
+    };
+    totalActions: number;
+    highImpactActions: number;
+    quickWins: number;
+    items: ActionPlanItem[];
+    nextReview: string;
+    limitation: AssessmentLimitation | null;
+}
 export interface CrawlPageResult {
     label: string;
     path: string;
@@ -791,6 +825,7 @@ export interface AnalysisResult {
     evidenceSummary?: PostureEvidenceSummary;
     exposureBrief?: ExposureBrief;
     vendorExposure?: VendorExposureBrief;
+    actionPlan?: ActionPlan;
     crawl: CrawlSummary;
     securityTxt: SecurityTxtInfo;
     domainSecurity: DomainSecurityInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -73,6 +73,10 @@
     "./vendor-exposure": {
       "types": "./dist/vendorExposure.d.ts",
       "default": "./dist/vendorExposure.js"
+    },
+    "./action-plan": {
+      "types": "./dist/actionPlan.d.ts",
+      "default": "./dist/actionPlan.js"
     }
   },
   "files": [