securl 1.4.1

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+export declare const unique: <T>(values: Array<T | null | undefined | false>) => T[];
+export declare const withTimeout: <T>(promise: Promise<T>, timeoutMs: number, message: string) => Promise<T>;
+export declare const headerValue: (headers: Record<string, string | string[] | undefined>, name: string) => string | null;
+export declare const safeResolve: <T>(operation: () => Promise<T>) => Promise<T | null>;
+export declare const safeResolveWithTimeout: <T>(operation: () => Promise<T>, timeoutMs: number, message?: string) => Promise<T | null>;
+export declare const mapWithConcurrency: <T, R>(items: T[], limit: number, mapper: (item: T, index: number) => Promise<R>) => Promise<R[]>;
+export declare const getSiteDomain: (hostname: string) => string;

package/dist/utils.js

@@ -0,0 +1,66 @@
+export const unique = (values) => [...new Set(values.filter((value) => Boolean(value)))];
+export const withTimeout = async (promise, timeoutMs, message) => {
+    let timeoutId = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+};
+export const headerValue = (headers, name) => {
+    const value = headers[name];
+    if (Array.isArray(value)) {
+        return value.join(", ");
+    }
+    return value ?? null;
+};
+export const safeResolve = async (operation) => {
+    try {
+        return await operation();
+    }
+    catch {
+        return null;
+    }
+};
+export const safeResolveWithTimeout = async (operation, timeoutMs, message = "DNS lookup timed out.") => {
+    try {
+        return await withTimeout(operation(), timeoutMs, message);
+    }
+    catch {
+        return null;
+    }
+};
+export const mapWithConcurrency = async (items, limit, mapper) => {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, () => worker()));
+    return results;
+};
+export const getSiteDomain = (hostname) => {
+    const lower = hostname.toLowerCase();
+    const parts = lower.split(".").filter(Boolean);
+    if (parts.length <= 2) {
+        return lower;
+    }
+    const compoundSuffixes = new Set(["co.uk", "org.uk", "ac.uk", "gov.uk", "com.au", "co.nz"]);
+    const suffix = parts.slice(-2).join(".");
+    if (compoundSuffixes.has(suffix) && parts.length >= 3) {
+        return parts.slice(-3).join(".");
+    }
+    return parts.slice(-2).join(".");
+};

package/dist/wafFingerprint.d.ts

@@ -0,0 +1,5 @@
+import { URL } from "node:url";
+import type { RedirectHop, WafFingerprintInfo } from "./types.js";
+type ResponseHeaders = Record<string, string | string[] | undefined>;
+export declare const analyzeWafFingerprint: (finalUrl: URL, headers: ResponseHeaders, html: string | null, redirects: RedirectHop[]) => WafFingerprintInfo;
+export {};

package/dist/wafFingerprint.js

@@ -0,0 +1,156 @@
+import { URL } from "node:url";
+import { unique } from "./utils.js";
+const headerValue = (headers, name) => {
+    const value = headers[name];
+    if (Array.isArray(value)) {
+        return value.join(", ");
+    }
+    return value ?? null;
+};
+const WAF_DETECTORS = [
+    {
+        name: "Cloudflare",
+        confidence: "high",
+        detection: "observed",
+        test: (headers, body) => Boolean(headerValue(headers, "cf-ray") || headerValue(headers, "cf-cache-status") || /cloudflare/i.test(headerValue(headers, "server") || "") || /attention required|cloudflare/i.test(body)),
+        evidence: (headers) => headerValue(headers, "cf-ray") ? "Observed cf-ray / Cloudflare edge headers." : "Observed Cloudflare-branded edge response markers.",
+    },
+    {
+        name: "Akamai",
+        confidence: "high",
+        detection: "observed",
+        test: (headers, body) => Boolean(headerValue(headers, "x-akamai-transformed") || headerValue(headers, "akamai-cache-status") || /akamai/i.test(headerValue(headers, "server") || "") || /reference #\d+\.[a-z0-9.]+\.akamai/i.test(body)),
+        evidence: () => "Observed Akamai edge headers or block-page signatures.",
+    },
+    {
+        name: "Imperva",
+        confidence: "high",
+        detection: "observed",
+        test: (headers, body) => Boolean(headerValue(headers, "x-iinfo") || /imperva|incapsula/i.test(headerValue(headers, "server") || "") || /incapsula incident id|imperva/i.test(body)),
+        evidence: () => "Observed Imperva/Incapsula response markers.",
+    },
+    {
+        name: "Sucuri",
+        confidence: "high",
+        detection: "observed",
+        test: (headers, body) => Boolean(headerValue(headers, "x-sucuri-id") || headerValue(headers, "x-sucuri-cache") || /sucuri/i.test(headerValue(headers, "server") || "") || /sucuri website firewall/i.test(body)),
+        evidence: () => "Observed Sucuri edge headers or branded error-page markers.",
+    },
+    {
+        name: "Fastly",
+        confidence: "medium",
+        detection: "observed",
+        test: (headers) => Boolean((headerValue(headers, "x-cache") || "").toLowerCase().includes("fastly") || (headerValue(headers, "x-served-by") || "").toLowerCase().includes("cache-")),
+        evidence: () => "Observed Fastly cache headers.",
+    },
+    {
+        name: "AWS CloudFront / WAF",
+        confidence: "medium",
+        detection: "observed",
+        test: (headers) => Boolean(headerValue(headers, "x-amz-cf-id") || /cloudfront/i.test(headerValue(headers, "server") || "")),
+        evidence: () => "Observed CloudFront edge headers.",
+    },
+    {
+        name: "Azure Front Door",
+        confidence: "high",
+        detection: "observed",
+        test: (headers) => Boolean(headerValue(headers, "x-azure-ref")),
+        evidence: () => "Observed x-azure-ref edge headers.",
+    },
+    {
+        name: "F5 BIG-IP ASM",
+        confidence: "medium",
+        detection: "observed",
+        test: (headers, body) => Boolean(headerValue(headers, "x-wa-info") || headerValue(headers, "x-cnection") || /the requested url was rejected/i.test(body)),
+        evidence: () => "Observed F5-style response headers or rejection-body markers.",
+    },
+    {
+        name: "Barracuda",
+        confidence: "high",
+        detection: "observed",
+        test: (headers) => Object.keys(headers).some((key) => key.toLowerCase().startsWith("x-barracuda-")),
+        evidence: () => "Observed Barracuda-branded response headers.",
+    },
+    {
+        name: "Nginx Plus / ModSecurity",
+        confidence: "medium",
+        detection: "observed",
+        test: (headers) => Boolean((headerValue(headers, "server") || "").toLowerCase().includes("mod_security") || headerValue(headers, "x-response-code")),
+        evidence: () => "Observed mod_security or gateway response markers.",
+    },
+    {
+        name: "Palo Alto Prisma WAAS",
+        confidence: "high",
+        detection: "observed",
+        test: (headers) => Boolean(headerValue(headers, "x-pan-request-id")),
+        evidence: () => "Observed x-pan-request-id header.",
+    },
+    {
+        name: "Google Cloud Armor",
+        confidence: "medium",
+        detection: "observed",
+        test: (headers) => Object.keys(headers).some((key) => key.toLowerCase().startsWith("x-goog-")) &&
+            (headerValue(headers, "via") || "").toLowerCase().includes("google"),
+        evidence: () => "Observed x-goog-* headers with Google edge routing markers.",
+    },
+    {
+        name: "Vercel Edge Network",
+        confidence: "high",
+        detection: "observed",
+        test: (headers) => Boolean(headerValue(headers, "x-vercel-id")),
+        evidence: () => "Observed x-vercel-id header.",
+    },
+];
+export const analyzeWafFingerprint = (finalUrl, headers, html, redirects) => {
+    const body = (html || "").toLowerCase();
+    const providers = WAF_DETECTORS
+        .filter((detector) => detector.test(headers, body))
+        .map((detector) => ({
+        name: detector.name,
+        confidence: detector.confidence,
+        detection: detector.detection,
+        evidence: detector.evidence(headers),
+    }));
+    const via = headerValue(headers, "via");
+    const server = headerValue(headers, "server");
+    const xCdn = headerValue(headers, "x-cdn");
+    const edgeSignals = unique([
+        server && /(edge|proxy|gateway|cache|gtm|belfrage|varnish)/i.test(server) ? `Server: ${server}` : null,
+        via ? `Via: ${via}` : null,
+        xCdn ? `X-CDN: ${xCdn}` : null,
+        redirects.some((hop) => {
+            try {
+                return hop.location ? new URL(hop.location, finalUrl).origin !== finalUrl.origin : false;
+            }
+            catch {
+                return false;
+            }
+        })
+            ? "Redirect chain includes a separate edge or identity origin."
+            : null,
+    ]);
+    const strengths = [];
+    const issues = [];
+    if (providers.length) {
+        strengths.push(`Edge protection or delivery signals point to ${providers.map((provider) => provider.name).join(", ")}.`);
+    }
+    else {
+        strengths.push("No branded WAF or edge provider was conclusively identified from passive response evidence.");
+    }
+    if (edgeSignals.length) {
+        strengths.push("Response headers exposed edge-network handling details that help classify the delivery path.");
+    }
+    if (providers.some((provider) => provider.name.includes("CloudFront"))) {
+        issues.push("AWS edge delivery was observed, but passive evidence alone does not confirm whether AWS WAF policies are enforced.");
+    }
+    return {
+        detected: Boolean(providers.length),
+        providers,
+        edgeSignals,
+        issues,
+        strengths,
+        summary: providers.length
+            ? `Passive response evidence suggests ${providers.map((provider) => provider.name).join(", ")} in front of the target.`
+            : "No branded WAF or edge-protection provider was conclusively identified from passive response evidence.",
+    };
+};

package/examples/risk-events.mjs

@@ -0,0 +1,27 @@
+import {
+  buildHistoryDiffFromSnapshots,
+  snapshotFromAnalysis,
+} from "securl/history-diff";
+import {
+  buildPostureRiskEventsFromSnapshots,
+} from "securl/risk-events";
+
+const [currentPath, previousPath] = process.argv.slice(2);
+
+if (!currentPath || !previousPath) {
+  console.error("Usage: node risk-events.mjs current-report.json previous-report.json");
+  process.exit(1);
+}
+
+const current = JSON.parse(await import("node:fs/promises").then((fs) => fs.readFile(currentPath, "utf8")));
+const previous = JSON.parse(await import("node:fs/promises").then((fs) => fs.readFile(previousPath, "utf8")));
+
+const currentSnapshot = snapshotFromAnalysis(current.analysis ?? current);
+const previousSnapshot = snapshotFromAnalysis(previous.analysis ?? previous);
+const diff = buildHistoryDiffFromSnapshots(currentSnapshot, previousSnapshot);
+const riskEvents = buildPostureRiskEventsFromSnapshots(currentSnapshot, previousSnapshot, diff);
+
+console.log(JSON.stringify({
+  diff,
+  riskEvents,
+}, null, 2));

package/examples/scan-url.mjs

@@ -0,0 +1,17 @@
+import { analyzeUrl } from "securl";
+
+const target = process.argv[2] ?? "https://example.com";
+const result = await analyzeUrl(target, {
+  scanMode: "quiet",
+});
+
+console.log(JSON.stringify({
+  url: result.finalUrl,
+  score: result.score,
+  grade: result.grade,
+  mainRisk: result.executiveSummary?.mainRisk ?? null,
+  findings: result.issues.map((issue) => ({
+    severity: issue.severity,
+    title: issue.title,
+  })),
+}, null, 2));

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "securl",
+  "version": "1.4.1",
+  "type": "module",
+  "description": "Passive external security posture analysis engine for SecURL.",
+  "author": {
+    "name": "Keith Batterham",
+    "url": "https://github.com/ktbatterham"
+  },
+  "homepage": "https://securl.online",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/this-is-securl/securl.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/this-is-securl/securl/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "bin": {
+    "securl": "dist/cli.js",
+    "epi": "dist/cli.js",
+    "external-posture-insight": "dist/cli.js"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "default": "./dist/cli.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./history-diff": {
+      "types": "./dist/historyDiff.d.ts",
+      "default": "./dist/historyDiff.js"
+    },
+    "./risk-events": {
+      "types": "./dist/riskEvents.d.ts",
+      "default": "./dist/riskEvents.js"
+    },
+    "./posture-digest": {
+      "types": "./dist/postureDigest.d.ts",
+      "default": "./dist/postureDigest.js"
+    },
+    "./posture-drift": {
+      "types": "./dist/postureDrift.d.ts",
+      "default": "./dist/postureDrift.js"
+    },
+    "./remediation-plan": {
+      "types": "./dist/postureRemediation.d.ts",
+      "default": "./dist/postureRemediation.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "CHANGELOG.md",
+    "README.md",
+    "RELEASING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "security",
+    "security-headers",
+    "headers",
+    "tls",
+    "dns",
+    "dmarc",
+    "owasp",
+    "posture",
+    "scanner",
+    "attack-surface",
+    "external-attack-surface",
+    "defensive-security",
+    "cli",
+    "ci",
+    "monitoring",
+    "supply-chain",
+    "vendor-risk"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "node-html-parser": "^7.1.0"
+  }
+}