securl 1.8.0 → 1.9.0

package/README.md

@@ -194,6 +194,23 @@ console.log({
 
 Action-plan items include owner, effort, impact, confidence, score impact where available, evidence references, and verification guidance.
 
+### 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,
+});
+```
+
 ### 6. Evidence-backed remediation plans
 
 Version `1.4.0+` includes a remediation plan helper that turns score drivers and findings into prioritized, owner-aware fix guidance. Findings can also carry structured evidence references so clients can show why a finding was raised.
@@ -304,6 +321,7 @@ 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.
 - `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 +332,7 @@ Package subpath exports:
 - `securl/history-diff`
 - `securl/posture-digest`
 - `securl/action-plan`
+- `securl/live-certificate`
 - `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

@@ -12,6 +12,7 @@ export declare const analyzeTarget: typeof analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.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

@@ -1040,6 +1040,7 @@ export const analyzeTarget = analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.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/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;

package/package.json

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