securl 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -12,6 +12,12 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 - Added `buildExposureBrief()` for compact outside-observer action briefs covering public entry points, sensitive exposures, trust gaps, abuse indicators, third-party risk, AI surface signals, and next actions.
 - Added `exposureBrief` to analysis results and the `securl/exposure-brief` package export for SDK consumers.
 
+## [1.10.0] - 2026-06-20
+
+### Added
+- Added `buildObservationLedger()` and the `securl/observations` package export for stable, source-aware posture observations.
+- Added `observationLedger` to completed analysis results with deterministic IDs, confidence, status, and freshness metadata.
+
 ## [1.5.1] - 2026-06-15
 
 ### Changed

package/README.md

@@ -194,7 +194,40 @@ console.log({
 
 Action-plan items include owner, effort, impact, confidence, score impact where available, evidence references, and verification guidance.
 
-### 6. Evidence-backed remediation plans
+### 7. 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.
+
+```ts
+import { scanLiveCertificate } from "securl/live-certificate";
+
+const certificate = await scanLiveCertificate(new URL("https://example.com"));
+
+console.log({
+  issuer: certificate.issuer,
+  daysRemaining: certificate.daysRemaining,
+  protocol: certificate.protocol,
+  chainLength: certificate.chain.length,
+});
+```
+
+### 8. Machine-readable observation ledger
+
+Version `1.10.0+` adds stable posture observations for monitoring, inventory, policy, and future SaaS integrations. Each observation records what was seen, whether it was observed, inferred, missing, or unavailable, its confidence and source, and when that evidence should be refreshed.
+
+```ts
+import { analyzeUrl } from "securl";
+import { buildObservationLedger } from "securl/observations";
+
+const result = await analyzeUrl("https://example.com");
+const ledger = result.observationLedger ?? buildObservationLedger(result);
+
+console.log(ledger.summary, ledger.observations);
+```
+
+Observation IDs are deterministic across scans for the same subject and signal, making the ledger suitable for change detection without exposing backend job metadata.
+
+### 9. 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.
 
@@ -304,6 +337,8 @@ 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.
+- `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.
 - `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.
@@ -314,6 +349,8 @@ Package subpath exports:
 - `securl/history-diff`
 - `securl/posture-digest`
 - `securl/action-plan`
+- `securl/live-certificate`
+- `securl/observations`
 - `securl/posture-drift`
 - `securl/remediation-plan`
 - `securl/risk-events`

package/dist/certificate.d.ts

@@ -1,5 +1,6 @@
-import type { CertificateResult } from "./types.js";
+import type { CertificateResult, LiveCertificateResult } from "./types.js";
 export declare const OBSERVATIONAL_TLS_OPTIONS: {
     rejectUnauthorized: boolean;
 };
 export declare const scanTls: (targetUrl: URL) => Promise<CertificateResult>;
+export declare const scanLiveCertificate: (targetUrl: URL) => Promise<LiveCertificateResult>;

package/dist/certificate.js

@@ -16,6 +16,48 @@ export const OBSERVATIONAL_TLS_OPTIONS = {
     // Set EXTERNAL_POSTURE_ALLOW_INSECURE_TLS=1 only for controlled observational runs.
     rejectUnauthorized: !allowInsecureTls,
 };
+function certificateName(certificate, field) {
+    return firstStringValue(certificate?.[field]?.O) ?? firstStringValue(certificate?.[field]?.CN);
+}
+function chainFromCertificate(certificate) {
+    const chain = [];
+    const seen = new Set();
+    let current = certificate;
+    while (current && Object.keys(current).length > 0) {
+        const fingerprint = current.fingerprint256 || current.fingerprint || null;
+        const key = fingerprint || `${current.subject?.CN || ""}:${current.issuer?.CN || ""}:${current.valid_to || ""}`;
+        if (seen.has(key)) {
+            break;
+        }
+        seen.add(key);
+        chain.push({
+            subject: certificateName(current, "subject"),
+            issuer: certificateName(current, "issuer"),
+            validFrom: current.valid_from || null,
+            validTo: current.valid_to || null,
+            fingerprint,
+        });
+        if (!current.issuerCertificate || current.issuerCertificate === current) {
+            break;
+        }
+        current = current.issuerCertificate;
+    }
+    return chain;
+}
+function keyBitsFromCertificate(certificate) {
+    const value = certificate?.bits;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function keyTypeFromCertificate(certificate) {
+    const value = certificate?.asn1Curve || certificate?.nistCurve;
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    if (typeof certificate?.bits === "number") {
+        return "rsa";
+    }
+    return null;
+}
 export const scanTls = (targetUrl) => {
     if (targetUrl.protocol !== "https:") {
         return Promise.resolve({
@@ -71,8 +113,89 @@ export const scanTls = (targetUrl) => {
                 available: true,
                 valid: Boolean(socket.authorized),
                 authorized: Boolean(socket.authorized),
-                issuer: firstStringValue(certificate?.issuer?.O) ?? firstStringValue(certificate?.issuer?.CN),
-                subject: firstStringValue(certificate?.subject?.CN),
+                issuer: certificateName(certificate, "issuer"),
+                subject: certificateName(certificate, "subject"),
+                validFrom,
+                validTo,
+                daysRemaining,
+                protocol,
+                cipher: cipherInfo?.name || null,
+                fingerprint: certificate?.fingerprint256 || null,
+                subjectAltName,
+                issues,
+            });
+            socket.end();
+        });
+        socket.once("timeout", () => {
+            socket.destroy(new Error("TLS handshake timed out."));
+        });
+        socket.once("error", reject);
+    });
+};
+export const scanLiveCertificate = (targetUrl) => {
+    if (targetUrl.protocol !== "https:") {
+        return Promise.resolve({
+            available: false,
+            valid: false,
+            authorized: false,
+            issuer: null,
+            subject: null,
+            validFrom: null,
+            validTo: null,
+            daysRemaining: null,
+            protocol: null,
+            cipher: null,
+            fingerprint: null,
+            subjectAltName: [],
+            issues: ["TLS certificate data is only available for HTTPS targets."],
+            host: targetUrl.hostname,
+            port: Number(targetUrl.port || 443),
+            checkedAt: new Date().toISOString(),
+            serialNumber: null,
+            keyBits: null,
+            keyType: null,
+            chain: [],
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const socket = tls.connect({
+            host: targetUrl.hostname,
+            port: Number(targetUrl.port || 443),
+            servername: targetUrl.hostname,
+            ...OBSERVATIONAL_TLS_OPTIONS,
+            timeout: TLS_HANDSHAKE_TIMEOUT_MS,
+        });
+        socket.once("secureConnect", () => {
+            const certificate = socket.getPeerCertificate(true);
+            const protocol = socket.getProtocol?.() || null;
+            const cipherInfo = socket.getCipher?.();
+            const validTo = certificate?.valid_to || null;
+            const validFrom = certificate?.valid_from || null;
+            const daysRemaining = validTo
+                ? Math.ceil((new Date(validTo).getTime() - Date.now()) / (1000 * 60 * 60 * 24))
+                : null;
+            const subjectAltName = typeof certificate?.subjectaltname === "string"
+                ? certificate.subjectaltname.split(",").map((entry) => entry.trim().replace(/^DNS:/, ""))
+                : [];
+            const issues = [];
+            if (!socket.authorized) {
+                issues.push(typeof socket.authorizationError === "string"
+                    ? socket.authorizationError
+                    : "Certificate is not trusted.");
+            }
+            if (allowInsecureTls) {
+                issues.push("Insecure TLS observation mode is enabled via EXTERNAL_POSTURE_ALLOW_INSECURE_TLS.");
+            }
+            if (daysRemaining !== null && daysRemaining <= 14)
+                issues.push("Certificate expires very soon.");
+            if (protocol && /tlsv1(\.0|\.1)?$/i.test(protocol))
+                issues.push("TLS protocol is outdated.");
+            resolve({
+                available: true,
+                valid: Boolean(socket.authorized),
+                authorized: Boolean(socket.authorized),
+                issuer: certificateName(certificate, "issuer"),
+                subject: certificateName(certificate, "subject"),
                 validFrom,
                 validTo,
                 daysRemaining,
@@ -81,6 +204,13 @@ export const scanTls = (targetUrl) => {
                 fingerprint: certificate?.fingerprint256 || null,
                 subjectAltName,
                 issues,
+                host: targetUrl.hostname,
+                port: Number(targetUrl.port || 443),
+                checkedAt: new Date().toISOString(),
+                serialNumber: certificate?.serialNumber || null,
+                keyBits: keyBitsFromCertificate(certificate),
+                keyType: keyTypeFromCertificate(certificate),
+                chain: chainFromCertificate(certificate),
             });
             socket.end();
         });

package/dist/index.d.ts

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

package/dist/index.js

@@ -19,6 +19,7 @@ import { analyzeApiSurface, analyzeCorsSecurity, analyzeExposure, fetchPublicSig
 import { fetchLibraryRiskSignals } from "./libraryRisk.js";
 import { fetchWithRedirects, requestJson, requestOnce, requestText, requestWithHeaders, } from "./network.js";
 import { normalizeDiscoveredPath, rankDiscoveredPaths } from "./path-discovery.js";
+import { buildObservationLedger } from "./observations.js";
 import { buildPassiveIntelligence, emptyPassiveIntelligence } from "./passive-intelligence.js";
 import { analyzeRedirectChain } from "./redirectChain.js";
 import { attachIssueEvidence, buildPostureEvidenceSummary, buildPostureRemediationPlan } from "./postureRemediation.js";
@@ -514,10 +515,14 @@ async function buildLimitedResult(input, normalizedInput, failure, scanTiming) {
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
-    return {
+    const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
+    return {
+        ...resultWithActions,
+        observationLedger: buildObservationLedger(resultWithActions),
+    };
 }
 async function enrichCoreResult(result, profile) {
     const finalUrl = new URL(result.finalUrl);
@@ -953,10 +958,14 @@ function buildTimedOutEnrichmentResult(result, pageAnalysisEnabled, timeoutMs, c
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
-    return {
+    const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
+    return {
+        ...resultWithActions,
+        observationLedger: buildObservationLedger(resultWithActions),
+    };
 }
 export async function analyzeUrl(input, options = {}) {
     const scanStartedAt = Date.now();
@@ -1031,15 +1040,21 @@ export async function analyzeUrl(input, options = {}) {
         exposureBrief: buildExposureBrief(resultWithRemediation),
         vendorExposure: buildVendorExposureBrief(resultWithRemediation),
     };
-    return {
+    const resultWithActions = {
         ...resultWithBriefs,
         actionPlan: buildActionPlan(resultWithBriefs),
     };
+    return {
+        ...resultWithActions,
+        observationLedger: buildObservationLedger(resultWithActions),
+    };
 }
 export const analyzeTarget = analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
+export { buildObservationLedger } from "./observations.js";
 export { buildActionPlan } from "./actionPlan.js";
+export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";
 export { buildVendorExposureBrief } from "./vendorExposure.js";
 export { analyzeInfrastructure } from "./infrastructure.js";

package/dist/observations.d.ts

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

package/dist/observations.js

@@ -0,0 +1,203 @@
+import { createHash } from "node:crypto";
+const HOUR = 60 * 60 * 1000;
+const categoryTtl = {
+    transport: HOUR,
+    header: HOUR,
+    certificate: 6 * HOUR,
+    dns: 24 * HOUR,
+    email: 24 * HOUR,
+    infrastructure: 24 * HOUR,
+    technology: 24 * HOUR,
+    trust: 24 * HOUR,
+    availability: HOUR,
+};
+function kindToken(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "unknown";
+}
+function observationId(category, kind, subject, source) {
+    const fingerprint = createHash("sha256")
+        .update(`${category}\u0000${kind}\u0000${subject.toLowerCase()}\u0000${source}`)
+        .digest("hex")
+        .slice(0, 20);
+    return `obs_${fingerprint}`;
+}
+function evidence(kind, label, observed, source = "observed") {
+    return [{
+            kind,
+            label,
+            observed: Array.isArray(observed) ? observed.join(", ") : observed === null ? null : String(observed),
+            source,
+        }];
+}
+export function buildObservationLedger(result) {
+    const generatedAt = result.scannedAt || new Date().toISOString();
+    const observedAtMs = new Date(generatedAt).getTime();
+    const baseMs = Number.isFinite(observedAtMs) ? observedAtMs : Date.now();
+    const observations = [];
+    const add = (input) => {
+        observations.push({
+            ...input,
+            id: observationId(input.category, input.kind, input.subject, input.source),
+            observedAt: generatedAt,
+            freshUntil: new Date(baseMs + (input.ttlMs ?? categoryTtl[input.category])).toISOString(),
+        });
+    };
+    add({
+        category: "transport",
+        kind: "http.status",
+        subject: result.finalUrl,
+        status: result.statusCode > 0 ? "observed" : "unavailable",
+        value: result.statusCode > 0 ? result.statusCode : null,
+        confidence: "high",
+        source: "probe",
+        evidence: evidence("probe", "HTTP response status", result.statusCode > 0 ? result.statusCode : null),
+    });
+    for (const header of result.headers) {
+        add({
+            category: "header",
+            kind: `http.header.${header.key.toLowerCase()}`,
+            subject: result.finalUrl,
+            status: header.status === "missing" ? "missing" : "observed",
+            value: header.value,
+            confidence: "high",
+            source: "header",
+            evidence: evidence("header", header.label, header.value),
+        });
+    }
+    const certificate = result.certificate;
+    add({
+        category: "certificate",
+        kind: "tls.certificate.valid",
+        subject: result.host,
+        status: certificate.available ? "observed" : "unavailable",
+        value: certificate.available ? certificate.valid && certificate.authorized : null,
+        confidence: "high",
+        source: "tls",
+        evidence: evidence("tls", "Certificate validity", certificate.available ? certificate.valid && certificate.authorized : null),
+    });
+    add({
+        category: "certificate",
+        kind: "tls.certificate.days_remaining",
+        subject: result.host,
+        status: certificate.daysRemaining === null ? "unavailable" : "observed",
+        value: certificate.daysRemaining,
+        confidence: "high",
+        source: "tls",
+        evidence: evidence("tls", "Certificate days remaining", certificate.daysRemaining),
+    });
+    add({
+        category: "transport",
+        kind: "tls.protocol",
+        subject: result.host,
+        status: certificate.protocol ? "observed" : "unavailable",
+        value: certificate.protocol,
+        confidence: "high",
+        source: "tls",
+        evidence: evidence("tls", "Negotiated TLS protocol", certificate.protocol),
+    });
+    const domain = result.domainSecurity;
+    add({
+        category: "dns",
+        kind: "dns.dnssec",
+        subject: domain.host,
+        status: domain.dnssec.status === "unknown" ? "unavailable" : domain.dnssec.enabled ? "observed" : "missing",
+        value: domain.dnssec.status,
+        confidence: domain.dnssec.status === "unknown" ? "low" : "high",
+        source: "dns",
+        evidence: evidence("dns", "DNSSEC status", domain.dnssec.status),
+    });
+    for (const [kind, policy] of [["email.spf", domain.emailPolicy.spf], ["email.dmarc", domain.emailPolicy.dmarc]]) {
+        add({
+            category: "email",
+            kind,
+            subject: domain.host,
+            status: policy.status === "missing" ? "missing" : "observed",
+            value: policy.status,
+            confidence: "high",
+            source: "dns",
+            evidence: evidence("dns", kind === "email.spf" ? "SPF policy" : "DMARC policy", policy.status),
+        });
+    }
+    add({
+        category: "trust",
+        kind: "public.security_txt",
+        subject: result.host,
+        status: result.securityTxt.status === "missing" ? "missing" : "observed",
+        value: result.securityTxt.status,
+        confidence: "high",
+        source: "public_record",
+        evidence: evidence("public_record", "security.txt status", result.securityTxt.status),
+    });
+    for (const provider of result.infrastructure.providers) {
+        add({
+            category: "infrastructure",
+            kind: `infrastructure.provider.${provider.category}.${kindToken(provider.provider)}`,
+            subject: result.host,
+            status: provider.source === "technology" ? "inferred" : "observed",
+            value: provider.provider,
+            confidence: provider.confidence,
+            source: "infrastructure",
+            evidence: evidence(provider.source === "dns" || provider.source === "reverse_dns" ? "dns" : "header", provider.provider, provider.evidence, provider.source === "technology" ? "inferred" : "observed"),
+        });
+    }
+    for (const technology of result.technologies) {
+        add({
+            category: "technology",
+            kind: `technology.${technology.category}.${kindToken(technology.name)}`,
+            subject: result.host,
+            status: technology.detection === "inferred" ? "inferred" : "observed",
+            value: technology.version ? `${technology.name}@${technology.version}` : technology.name,
+            confidence: technology.confidence,
+            source: "technology",
+            evidence: evidence("html", technology.name, technology.evidence, technology.detection),
+        });
+    }
+    for (const provider of result.wafFingerprint.providers) {
+        add({
+            category: "infrastructure",
+            kind: `infrastructure.waf.${kindToken(provider.name)}`,
+            subject: result.host,
+            status: provider.detection === "inferred" ? "inferred" : "observed",
+            value: provider.name,
+            confidence: provider.confidence,
+            source: "infrastructure",
+            evidence: evidence("header", `${provider.name} WAF`, provider.evidence, provider.detection),
+        });
+    }
+    if (result.assessmentLimitation.limited) {
+        add({
+            category: "availability",
+            kind: "assessment.limitation",
+            subject: result.finalUrl,
+            status: "unavailable",
+            value: result.assessmentLimitation.kind,
+            confidence: "high",
+            source: "availability",
+            evidence: evidence("score_driver", "Assessment limitation", result.assessmentLimitation.detail),
+        });
+    }
+    observations.sort((left, right) => left.id.localeCompare(right.id));
+    const byStatus = {
+        observed: 0,
+        inferred: 0,
+        missing: 0,
+        unavailable: 0,
+    };
+    const byCategory = {};
+    for (const observation of observations) {
+        byStatus[observation.status] += 1;
+        byCategory[observation.category] = (byCategory[observation.category] ?? 0) + 1;
+    }
+    return {
+        version: "1.0",
+        target: result.finalUrl,
+        generatedAt,
+        observations,
+        summary: {
+            total: observations.length,
+            byStatus,
+            byCategory,
+            highConfidence: observations.filter((observation) => observation.confidence === "high").length,
+        },
+    };
+}

package/dist/types.d.ts

@@ -67,6 +67,22 @@ export interface CertificateResult {
     subjectAltName: string[];
     issues: string[];
 }
+export interface LiveCertificateChainEntry {
+    subject: string | null;
+    issuer: string | null;
+    validFrom: string | null;
+    validTo: string | null;
+    fingerprint: string | null;
+}
+export interface LiveCertificateResult extends CertificateResult {
+    host: string;
+    port: number;
+    checkedAt: string;
+    serialNumber: string | null;
+    keyBits: number | null;
+    keyType: string | null;
+    chain: LiveCertificateChainEntry[];
+}
 export interface RedirectHop {
     url: string;
     status: number;
@@ -799,6 +815,34 @@ export interface PublicSignalsInfo {
     issues: string[];
     strengths: string[];
 }
+export type ObservationCategory = "transport" | "header" | "certificate" | "dns" | "email" | "infrastructure" | "technology" | "trust" | "availability";
+export type ObservationStatus = "observed" | "inferred" | "missing" | "unavailable";
+export type ObservationValue = string | number | boolean | null | string[];
+export interface PostureObservation {
+    id: string;
+    category: ObservationCategory;
+    kind: string;
+    subject: string;
+    status: ObservationStatus;
+    value: ObservationValue;
+    confidence: IssueConfidence;
+    source: ScanEvidenceKind | "availability" | "technology" | "infrastructure";
+    observedAt: string;
+    freshUntil: string;
+    evidence: ScanEvidenceReference[];
+}
+export interface ObservationLedger {
+    version: "1.0";
+    target: string;
+    generatedAt: string;
+    observations: PostureObservation[];
+    summary: {
+        total: number;
+        byStatus: Record<ObservationStatus, number>;
+        byCategory: Partial<Record<ObservationCategory, number>>;
+        highConfidence: number;
+    };
+}
 export interface AnalysisResult {
     inputUrl: string;
     normalizedUrl: string;
@@ -846,6 +890,7 @@ export interface AnalysisResult {
     publicSignals: PublicSignalsInfo;
     wafFingerprint: WafFingerprintInfo;
     scanTiming?: ScanTimingInfo;
+    observationLedger?: ObservationLedger;
 }
 export interface AnalyzeTargetOptions {
     includeCertificate?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -77,6 +77,14 @@
     "./action-plan": {
       "types": "./dist/actionPlan.d.ts",
       "default": "./dist/actionPlan.js"
+    },
+    "./live-certificate": {
+      "types": "./dist/certificate.d.ts",
+      "default": "./dist/certificate.js"
+    },
+    "./observations": {
+      "types": "./dist/observations.d.ts",
+      "default": "./dist/observations.js"
     }
   },
   "files": [