securl 1.9.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

@@ -211,7 +211,23 @@ console.log({
 });
 ```
 
-### 6. Evidence-backed remediation plans
+### 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.
 
@@ -322,6 +338,7 @@ Primary exports:
 - `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.
@@ -333,6 +350,7 @@ Package subpath exports:
 - `securl/posture-digest`
 - `securl/action-plan`
 - `securl/live-certificate`
+- `securl/observations`
 - `securl/posture-drift`
 - `securl/remediation-plan`
 - `securl/risk-events`

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 { buildObservationLedger } from "./observations.js";
 export { buildActionPlan } from "./actionPlan.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.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,14 +1040,19 @@ 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";

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

@@ -815,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;
@@ -862,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.9.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -81,6 +81,10 @@
     "./live-certificate": {
       "types": "./dist/certificate.d.ts",
       "default": "./dist/certificate.js"
+    },
+    "./observations": {
+      "types": "./dist/observations.d.ts",
+      "default": "./dist/observations.js"
     }
   },
   "files": [