securl 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -6,9 +6,38 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-06-20
+
+### Added
+- Added a bounded declarative observation policy engine, maintained baseline policy, validation helper, and `securl/observation-policy` export.
+- Added `diffObservationLedgers()` and `securl/observation-drift` for deterministic observation-level regression and improvement classification.
+
+## [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.9.0] - 2026-06-15
+
+### Added
+- Added `scanLiveCertificate()` and the `securl/live-certificate` package export for bounded TLS handshake-only certificate reads.
+- Added certificate chain, protocol, key-strength, and expiry metadata for lightweight certificate clients.
+
+## [1.8.0] - 2026-06-15
+
+### Added
+- Added `buildActionPlan()` and the `securl/action-plan` package export for prioritized owner, effort, and impact-ranked remediation actions.
+
+## [1.7.0] - 2026-06-15
+
 ### Added
 - Added `buildVendorExposureBrief()` for compact vendor and supply-chain exposure summaries covering visible third-party providers, data-flow categories, SRI gaps, priority vendors, and next actions.
 - Added `vendorExposure` to analysis results and the `securl/vendor-exposure` package export for SDK consumers.
+
+## [1.6.0] - 2026-06-15
+
+### Added
 - 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.
 

package/README.md

@@ -211,7 +211,27 @@ 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.
+
+Version `1.11.0+` adds `diffObservationLedgers(current, previous)` from `securl/observation-drift` to classify observation-level regressions, improvements, and neutral changes.
+
+Use `evaluateObservationPolicy({ ledger, drift, policy })` from `securl/observation-policy` to apply bounded declarative rules. Rules can select an exact observation kind, kind prefix, or category, then assert equality, membership, or numeric thresholds against current observations or changes. `DEFAULT_OBSERVATION_POLICY` provides a maintained baseline for certificate validity/window, HSTS, CSP, DMARC, and critical regressions.
+
+### 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 +342,9 @@ 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.
+- `diffObservationLedgers(current, previous)` - compare stable observations and classify their operational impact.
+- `evaluateObservationPolicy({ ledger, drift, policy })` - evaluate bounded declarative posture and change rules.
 - `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 +356,9 @@ Package subpath exports:
 - `securl/posture-digest`
 - `securl/action-plan`
 - `securl/live-certificate`
+- `securl/observations`
+- `securl/observation-drift`
+- `securl/observation-policy`
 - `securl/posture-drift`
 - `securl/remediation-plan`
 - `securl/risk-events`

package/dist/index.d.ts

@@ -11,6 +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 { diffObservationLedgers } from "./observationDrift.js";
+export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.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,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 { diffObservationLedgers } from "./observationDrift.js";
+export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";

package/dist/observationDrift.d.ts

@@ -0,0 +1,2 @@
+import type { ObservationDriftReport, ObservationLedger } from "./types.js";
+export declare function diffObservationLedgers(current: ObservationLedger, previous: ObservationLedger): ObservationDriftReport;

package/dist/observationDrift.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+const STATUS_RANK = {
+    unavailable: 0,
+    missing: 1,
+    inferred: 2,
+    observed: 3,
+};
+const CRITICAL_KINDS = new Set([
+    "tls.certificate.valid",
+    "email.dmarc",
+    "http.header.strict-transport-security",
+    "http.header.content-security-policy",
+]);
+function equalValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function certificateBand(days) {
+    if (days < 0)
+        return 0;
+    if (days <= 7)
+        return 1;
+    if (days <= 14)
+        return 2;
+    if (days <= 30)
+        return 3;
+    return 4;
+}
+function impactFor(previous, current) {
+    if (!previous && current) {
+        return current.status === "missing" || current.status === "unavailable" ? "regression" : "change";
+    }
+    if (previous && !current) {
+        return previous.status === "missing" || previous.status === "unavailable" ? "improvement" : "regression";
+    }
+    if (!previous || !current)
+        return "change";
+    if (STATUS_RANK[current.status] < STATUS_RANK[previous.status])
+        return "regression";
+    if (STATUS_RANK[current.status] > STATUS_RANK[previous.status])
+        return "improvement";
+    if (current.kind === "tls.certificate.days_remaining"
+        && typeof previous.value === "number"
+        && typeof current.value === "number") {
+        const previousBand = certificateBand(previous.value);
+        const currentBand = certificateBand(current.value);
+        if (currentBand < previousBand)
+            return "regression";
+        if (currentBand > previousBand || current.value > previous.value + 7)
+            return "improvement";
+        return "change";
+    }
+    if (current.kind === "tls.certificate.valid"
+        && typeof previous.value === "boolean"
+        && typeof current.value === "boolean") {
+        return current.value ? "improvement" : "regression";
+    }
+    return "change";
+}
+function severityFor(kind, impact, current) {
+    if (impact !== "regression")
+        return "info";
+    if (kind === "tls.certificate.valid" && current?.value === false)
+        return "critical";
+    if (CRITICAL_KINDS.has(kind) && (current?.status === "missing" || current?.status === "unavailable"))
+        return "critical";
+    if (kind === "tls.certificate.days_remaining" && typeof current?.value === "number" && current.value <= 14)
+        return "critical";
+    return "warning";
+}
+function changeId(observationId, type) {
+    return `chg_${createHash("sha256").update(`${observationId}\u0000${type}`).digest("hex").slice(0, 20)}`;
+}
+function summaryFor(type, previous, current) {
+    const label = current?.kind ?? previous?.kind ?? "observation";
+    if (type === "added")
+        return `${label} was newly detected.`;
+    if (type === "removed")
+        return `${label} is no longer detected.`;
+    if (type === "status_changed")
+        return `${label} changed from ${previous?.status} to ${current?.status}.`;
+    if (type === "confidence_changed")
+        return `${label} confidence changed from ${previous?.confidence} to ${current?.confidence}.`;
+    return `${label} changed from ${JSON.stringify(previous?.value)} to ${JSON.stringify(current?.value)}.`;
+}
+function buildChange(type, previous, current) {
+    const observation = current ?? previous;
+    if (!observation)
+        throw new Error("Observation change requires a current or previous value.");
+    const impact = impactFor(previous, current);
+    return {
+        id: changeId(observation.id, type),
+        observationId: observation.id,
+        type,
+        impact,
+        severity: severityFor(observation.kind, impact, current),
+        category: observation.category,
+        kind: observation.kind,
+        subject: observation.subject,
+        previous,
+        current,
+        summary: summaryFor(type, previous, current),
+    };
+}
+export function diffObservationLedgers(current, previous) {
+    const currentById = new Map(current.observations.map((observation) => [observation.id, observation]));
+    const previousById = new Map(previous.observations.map((observation) => [observation.id, observation]));
+    const changes = [];
+    for (const observation of current.observations) {
+        const before = previousById.get(observation.id) ?? null;
+        if (!before) {
+            changes.push(buildChange("added", null, observation));
+            continue;
+        }
+        if (before.status !== observation.status)
+            changes.push(buildChange("status_changed", before, observation));
+        if (!equalValue(before.value, observation.value))
+            changes.push(buildChange("value_changed", before, observation));
+        if (before.confidence !== observation.confidence)
+            changes.push(buildChange("confidence_changed", before, observation));
+    }
+    for (const observation of previous.observations) {
+        if (!currentById.has(observation.id))
+            changes.push(buildChange("removed", observation, null));
+    }
+    const severityRank = { critical: 3, warning: 2, info: 1 };
+    changes.sort((left, right) => severityRank[right.severity] - severityRank[left.severity] || left.id.localeCompare(right.id));
+    const regressions = changes.filter((change) => change.impact === "regression").length;
+    const improvements = changes.filter((change) => change.impact === "improvement").length;
+    const bySeverity = { info: 0, warning: 0, critical: 0 };
+    const byCategory = {};
+    for (const change of changes) {
+        bySeverity[change.severity] += 1;
+        byCategory[change.category] = (byCategory[change.category] ?? 0) + 1;
+    }
+    return {
+        version: "1.0",
+        target: current.target,
+        comparedAt: current.generatedAt,
+        previousObservedAt: previous.generatedAt,
+        currentObservedAt: current.generatedAt,
+        changes,
+        summary: {
+            direction: regressions ? "regressed" : improvements ? "improved" : changes.length ? "changed" : "unchanged",
+            total: changes.length,
+            regressions,
+            improvements,
+            neutralChanges: changes.length - regressions - improvements,
+            bySeverity,
+            byCategory,
+        },
+    };
+}

package/dist/observationPolicy.d.ts

@@ -0,0 +1,8 @@
+import type { ObservationDriftReport, ObservationLedger, ObservationPolicy, ObservationPolicyEvaluation } from "./types.js";
+export declare const DEFAULT_OBSERVATION_POLICY: ObservationPolicy;
+export declare function validateObservationPolicy(value: unknown): ObservationPolicy;
+export declare function evaluateObservationPolicy({ ledger, drift, policy, }: {
+    ledger: ObservationLedger;
+    drift?: ObservationDriftReport | null;
+    policy?: ObservationPolicy;
+}): ObservationPolicyEvaluation;

package/dist/observationPolicy.js

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+const MAX_RULES = 25;
+const VALID_OPERATORS = new Set(["eq", "neq", "in", "gte", "lte"]);
+const VALID_SEVERITIES = new Set(["info", "warning", "critical"]);
+const VALID_SCOPES = new Set(["observation", "change"]);
+const VALID_FIELDS = new Set(["status", "value", "confidence", "impact", "severity", "type"]);
+const VALID_CATEGORIES = new Set(["transport", "header", "certificate", "dns", "email", "infrastructure", "technology", "trust", "availability"]);
+export const DEFAULT_OBSERVATION_POLICY = {
+    id: "securl-baseline-v1",
+    name: "SecURL baseline",
+    version: "1.0",
+    rules: [
+        {
+            id: "certificate-valid",
+            title: "Certificate must remain valid",
+            severity: "critical",
+            scope: "observation",
+            selector: { kind: "tls.certificate.valid" },
+            assertion: { field: "value", operator: "eq", value: true },
+            requireMatch: true,
+        },
+        {
+            id: "certificate-window",
+            title: "Certificate must have at least 14 days remaining",
+            severity: "critical",
+            scope: "observation",
+            selector: { kind: "tls.certificate.days_remaining" },
+            assertion: { field: "value", operator: "gte", value: 14 },
+            requireMatch: true,
+        },
+        {
+            id: "hsts-present",
+            title: "HSTS must be present",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "http.header.strict-transport-security" },
+            assertion: { field: "status", operator: "eq", value: "observed" },
+            requireMatch: true,
+        },
+        {
+            id: "csp-present",
+            title: "Content Security Policy must be present",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "http.header.content-security-policy" },
+            assertion: { field: "status", operator: "eq", value: "observed" },
+            requireMatch: true,
+        },
+        {
+            id: "dmarc-enforced",
+            title: "DMARC should be strong or monitored",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "email.dmarc" },
+            assertion: { field: "value", operator: "in", value: ["strong", "watch"] },
+            requireMatch: true,
+        },
+        {
+            id: "critical-regression",
+            title: "Critical observation regressions are not allowed",
+            severity: "critical",
+            scope: "change",
+            selector: {},
+            assertion: { field: "severity", operator: "neq", value: "critical" },
+            requireMatch: false,
+        },
+    ],
+};
+function boundedText(value, field, max) {
+    if (typeof value !== "string" || !value.trim() || value.length > max) {
+        throw new Error(`Observation policy ${field} must be a non-empty string up to ${max} characters.`);
+    }
+    return value.trim();
+}
+export function validateObservationPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Observation policy must be an object.");
+    const input = value;
+    if (!Array.isArray(input.rules) || input.rules.length === 0 || input.rules.length > MAX_RULES) {
+        throw new Error(`Observation policy must contain between 1 and ${MAX_RULES} rules.`);
+    }
+    const seen = new Set();
+    const rules = input.rules.map((rawRule) => {
+        if (!rawRule || typeof rawRule !== "object" || Array.isArray(rawRule))
+            throw new Error("Each observation policy rule must be an object.");
+        const rule = rawRule;
+        const id = boundedText(rule.id, "rule id", 64);
+        if (!/^[a-z0-9][a-z0-9._-]*$/i.test(id) || seen.has(id))
+            throw new Error(`Observation policy rule id is invalid or duplicated: ${id}.`);
+        seen.add(id);
+        if (!VALID_SEVERITIES.has(String(rule.severity)))
+            throw new Error(`Observation policy rule ${id} has an invalid severity.`);
+        if (!VALID_SCOPES.has(String(rule.scope)))
+            throw new Error(`Observation policy rule ${id} has an invalid scope.`);
+        const selector = rule.selector && typeof rule.selector === "object" && !Array.isArray(rule.selector)
+            ? rule.selector
+            : {};
+        const assertion = rule.assertion && typeof rule.assertion === "object" && !Array.isArray(rule.assertion)
+            ? rule.assertion
+            : null;
+        if (!assertion || !VALID_FIELDS.has(String(assertion.field)) || !VALID_OPERATORS.has(String(assertion.operator))) {
+            throw new Error(`Observation policy rule ${id} has an invalid assertion.`);
+        }
+        if (selector.category !== undefined && !VALID_CATEGORIES.has(String(selector.category))) {
+            throw new Error(`Observation policy rule ${id} has an invalid selector category.`);
+        }
+        if (rule.scope === "observation" && ["impact", "severity", "type"].includes(String(assertion.field))) {
+            throw new Error(`Observation policy rule ${id} uses a change-only field for an observation rule.`);
+        }
+        if (rule.scope === "change" && ["status", "confidence"].includes(String(assertion.field))) {
+            throw new Error(`Observation policy rule ${id} uses an observation-only field for a change rule.`);
+        }
+        if (assertion.operator === "in" && !Array.isArray(assertion.value))
+            throw new Error(`Observation policy rule ${id} requires an array value for in.`);
+        if ((assertion.operator === "gte" || assertion.operator === "lte") && typeof assertion.value !== "number") {
+            throw new Error(`Observation policy rule ${id} requires a numeric assertion value.`);
+        }
+        return {
+            id,
+            title: boundedText(rule.title, `rule ${id} title`, 160),
+            ...(typeof rule.description === "string" ? { description: rule.description.trim().slice(0, 500) } : {}),
+            enabled: rule.enabled !== false,
+            severity: rule.severity,
+            scope: rule.scope,
+            selector: {
+                ...(typeof selector.kind === "string" ? { kind: selector.kind.slice(0, 160) } : {}),
+                ...(typeof selector.kindPrefix === "string" ? { kindPrefix: selector.kindPrefix.slice(0, 160) } : {}),
+                ...(typeof selector.category === "string" ? { category: selector.category } : {}),
+            },
+            assertion: {
+                field: assertion.field,
+                operator: assertion.operator,
+                value: assertion.value,
+            },
+            requireMatch: rule.requireMatch === true,
+        };
+    });
+    return {
+        id: boundedText(input.id, "id", 64),
+        name: boundedText(input.name, "name", 120),
+        version: boundedText(input.version, "version", 32),
+        rules,
+    };
+}
+function matchesSelector(entity, rule) {
+    const { selector } = rule;
+    return (!selector.kind || entity.kind === selector.kind)
+        && (!selector.kindPrefix || entity.kind.startsWith(selector.kindPrefix))
+        && (!selector.category || entity.category === selector.category);
+}
+function actualValue(entity, field) {
+    if (field === "value")
+        return "current" in entity ? entity.current?.value ?? null : entity.value;
+    return entity[field] ?? null;
+}
+function assertionPasses(actual, rule) {
+    const { operator, value } = rule.assertion;
+    if (operator === "eq")
+        return JSON.stringify(actual) === JSON.stringify(value);
+    if (operator === "neq")
+        return JSON.stringify(actual) !== JSON.stringify(value);
+    if (operator === "in")
+        return Array.isArray(value) && value.some((candidate) => JSON.stringify(candidate) === JSON.stringify(actual));
+    if (operator === "gte")
+        return typeof actual === "number" && typeof value === "number" && actual >= value;
+    if (operator === "lte")
+        return typeof actual === "number" && typeof value === "number" && actual <= value;
+    return false;
+}
+function violationId(ruleId, entityId) {
+    return `pol_${createHash("sha256").update(`${ruleId}\u0000${entityId}`).digest("hex").slice(0, 20)}`;
+}
+function violationFor(rule, entity) {
+    const actual = entity ? actualValue(entity, rule.assertion.field) : null;
+    const isChange = entity && "observationId" in entity;
+    const entityId = entity?.id ?? "missing";
+    return {
+        id: violationId(rule.id, entityId),
+        ruleId: rule.id,
+        title: rule.title,
+        severity: rule.severity,
+        scope: rule.scope,
+        observationId: isChange ? entity.observationId : entity?.id ?? null,
+        changeId: isChange ? entity.id : null,
+        kind: entity?.kind ?? rule.selector.kind ?? rule.selector.kindPrefix ?? null,
+        subject: entity?.subject ?? null,
+        expected: rule.assertion,
+        actual: actual,
+        summary: entity
+            ? `${rule.title}: ${rule.assertion.field} ${rule.assertion.operator} ${JSON.stringify(rule.assertion.value)} was not satisfied.`
+            : `${rule.title}: no matching observation was available.`,
+    };
+}
+export function evaluateObservationPolicy({ ledger, drift = null, policy = DEFAULT_OBSERVATION_POLICY, }) {
+    const normalized = validateObservationPolicy(policy);
+    const violations = [];
+    const enabledRules = normalized.rules.filter((rule) => rule.enabled !== false);
+    for (const rule of enabledRules) {
+        const source = rule.scope === "change" ? drift?.changes ?? [] : ledger.observations;
+        const matches = source.filter((entity) => matchesSelector(entity, rule));
+        if (!matches.length && rule.requireMatch)
+            violations.push(violationFor(rule, null));
+        for (const entity of matches) {
+            if (!assertionPasses(actualValue(entity, rule.assertion.field), rule))
+                violations.push(violationFor(rule, entity));
+        }
+    }
+    const bySeverity = { info: 0, warning: 0, critical: 0 };
+    for (const violation of violations)
+        bySeverity[violation.severity] += 1;
+    const highestSeverity = bySeverity.critical ? "critical" : bySeverity.warning ? "warning" : bySeverity.info ? "info" : null;
+    return {
+        version: "1.0",
+        policy: { id: normalized.id, name: normalized.name, version: normalized.version },
+        target: ledger.target,
+        evaluatedAt: ledger.generatedAt,
+        passed: violations.length === 0,
+        violations,
+        summary: {
+            rulesEvaluated: enabledRules.length,
+            violations: violations.length,
+            bySeverity,
+            highestSeverity,
+        },
+    };
+}

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,128 @@ 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 type ObservationChangeType = "added" | "removed" | "status_changed" | "value_changed" | "confidence_changed";
+export type ObservationChangeImpact = "regression" | "improvement" | "change";
+export type ObservationChangeSeverity = "info" | "warning" | "critical";
+export interface ObservationChange {
+    id: string;
+    observationId: string;
+    type: ObservationChangeType;
+    impact: ObservationChangeImpact;
+    severity: ObservationChangeSeverity;
+    category: ObservationCategory;
+    kind: string;
+    subject: string;
+    previous: PostureObservation | null;
+    current: PostureObservation | null;
+    summary: string;
+}
+export interface ObservationDriftReport {
+    version: "1.0";
+    target: string;
+    comparedAt: string;
+    previousObservedAt: string;
+    currentObservedAt: string;
+    changes: ObservationChange[];
+    summary: {
+        direction: "regressed" | "improved" | "changed" | "unchanged";
+        total: number;
+        regressions: number;
+        improvements: number;
+        neutralChanges: number;
+        bySeverity: Record<ObservationChangeSeverity, number>;
+        byCategory: Partial<Record<ObservationCategory, number>>;
+    };
+}
+export type ObservationPolicySeverity = "info" | "warning" | "critical";
+export type ObservationPolicyScope = "observation" | "change";
+export type ObservationPolicyField = "status" | "value" | "confidence" | "impact" | "severity" | "type";
+export type ObservationPolicyOperator = "eq" | "neq" | "in" | "gte" | "lte";
+export interface ObservationPolicyRule {
+    id: string;
+    title: string;
+    description?: string;
+    enabled?: boolean;
+    severity: ObservationPolicySeverity;
+    scope: ObservationPolicyScope;
+    selector: {
+        kind?: string;
+        kindPrefix?: string;
+        category?: ObservationCategory;
+    };
+    assertion: {
+        field: ObservationPolicyField;
+        operator: ObservationPolicyOperator;
+        value: ObservationValue | ObservationChangeImpact | ObservationChangeSeverity | ObservationChangeType;
+    };
+    requireMatch?: boolean;
+}
+export interface ObservationPolicy {
+    id: string;
+    name: string;
+    version: string;
+    rules: ObservationPolicyRule[];
+}
+export interface ObservationPolicyViolation {
+    id: string;
+    ruleId: string;
+    title: string;
+    severity: ObservationPolicySeverity;
+    scope: ObservationPolicyScope;
+    observationId: string | null;
+    changeId: string | null;
+    kind: string | null;
+    subject: string | null;
+    expected: ObservationPolicyRule["assertion"];
+    actual: ObservationValue;
+    summary: string;
+}
+export interface ObservationPolicyEvaluation {
+    version: "1.0";
+    policy: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    target: string;
+    evaluatedAt: string;
+    passed: boolean;
+    violations: ObservationPolicyViolation[];
+    summary: {
+        rulesEvaluated: number;
+        violations: number;
+        bySeverity: Record<ObservationPolicySeverity, number>;
+        highestSeverity: ObservationPolicySeverity | null;
+    };
+}
 export interface AnalysisResult {
     inputUrl: string;
     normalizedUrl: string;
@@ -862,6 +984,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.11.0",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -81,6 +81,18 @@
     "./live-certificate": {
       "types": "./dist/certificate.d.ts",
       "default": "./dist/certificate.js"
+    },
+    "./observations": {
+      "types": "./dist/observations.d.ts",
+      "default": "./dist/observations.js"
+    },
+    "./observation-drift": {
+      "types": "./dist/observationDrift.d.ts",
+      "default": "./dist/observationDrift.js"
+    },
+    "./observation-policy": {
+      "types": "./dist/observationPolicy.d.ts",
+      "default": "./dist/observationPolicy.js"
     }
   },
   "files": [