@quantakrypto/qprobe 0.4.4

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * qprobe CLI — a thin shell over the programmatic API: parse argv, authorize,
+ * probe, print, and set an exit code. It never throws to the top level.
+ * Exit codes mirror qScan: 0 OK, 1 findings, 2 error/usage.
+ */
+import { readFileSync } from "node:fs";
+import { parseArgs, HELP } from "./args.js";
+import { parseTarget, TargetError } from "./target.js";
+import { parseOwnedHosts, AttestationError } from "./attest.js";
+import { runProbe } from "./index.js";
+import { toJsonReport, toSarifReport, toCbomReport } from "./report.js";
+import { VERSION } from "./version.js";
+const EXIT = { OK: 0, FINDINGS: 1, ERROR: 2 };
+function endpointLine(r) {
+    const t = `${r.target.host}:${r.target.port}`;
+    const lines = [`\n${t}  [${r.mode}]`];
+    if ((r.mode === "tls" || r.mode === "smtp") && r.tls) {
+        if (r.tls.error)
+            lines.push(`  ${r.mode}: ${r.tls.error}`);
+        else
+            lines.push(`  ${r.tls.protocol ?? "?"} · ${r.tls.cipher ?? "?"} · KEX ${r.tls.kexGroup ?? "?"} · cert ${r.tls.certKeyType ?? "?"}${r.tls.certKeyBits ? `-${r.tls.certKeyBits}` : ""}${r.tls.certSigFamily ? ` (sig ${r.tls.certSigFamily})` : ""}`);
+        if (r.hybrid && !r.hybrid.error)
+            lines.push(`  PQC-hybrid (X25519MLKEM768): ${r.hybrid.hybridSelected ? "SUPPORTED ✓" : "not negotiated"}`);
+    }
+    if (r.mode === "ssh" && r.ssh) {
+        if (r.ssh.error)
+            lines.push(`  ssh: ${r.ssh.error}`);
+        else
+            lines.push(`  ${r.ssh.banner ?? ""} · PQC KEX: ${r.ssh.pqKexOffered ? "offered ✓" : "none"}`);
+    }
+    for (const p of r.positives)
+        lines.push(`  ✓ ${p}`);
+    for (const f of r.findings)
+        lines.push(`  [${f.severity}] ${f.title} — ${f.message}`);
+    return lines.join("\n");
+}
+function formatHuman(result) {
+    const out = [`qProbe — live post-quantum readiness · qprobe v${VERSION}`];
+    for (const r of result.reports)
+        out.push(endpointLine(r));
+    const f = result.findings;
+    out.push(`\n${f.length} finding${f.length === 1 ? "" : "s"} · ${result.inventory.hndlCount} HNDL-exposed · readiness ${result.inventory.readinessScore}/100`);
+    return out.join("\n") + "\n";
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(HELP);
+        return EXIT.OK;
+    }
+    if (args.targets.length === 0) {
+        console.error(HELP);
+        return EXIT.ERROR;
+    }
+    const defaultPort = args.mode === "ssh" ? 22 : args.mode === "smtp" ? 587 : 443;
+    let targets;
+    try {
+        targets = args.targets.map((t) => parseTarget(t, defaultPort));
+    }
+    catch (e) {
+        if (e instanceof TargetError) {
+            console.error(`qprobe: ${e.message}`);
+            return EXIT.ERROR;
+        }
+        throw e;
+    }
+    let ownedHosts;
+    if (args.ownedHostsFile) {
+        try {
+            ownedHosts = parseOwnedHosts(readFileSync(args.ownedHostsFile, "utf8"));
+        }
+        catch {
+            console.error(`qprobe: cannot read ownership manifest ${args.ownedHostsFile}`);
+            return EXIT.ERROR;
+        }
+    }
+    const startedAt = new Date().toISOString();
+    let result;
+    try {
+        result = await runProbe({
+            targets,
+            mode: args.mode,
+            attest: { iOwnThis: args.iOwnThis, ownedHosts },
+            servername: args.servername,
+            timeoutMs: args.timeoutMs,
+        });
+    }
+    catch (e) {
+        if (e instanceof AttestationError) {
+            console.error(`qprobe: ${e.message}`);
+            return EXIT.ERROR;
+        }
+        throw e;
+    }
+    const finishedAt = new Date().toISOString();
+    switch (args.format) {
+        case "json":
+            console.log(JSON.stringify(toJsonReport(result, startedAt, finishedAt), null, 2));
+            break;
+        case "sarif":
+            console.log(JSON.stringify(toSarifReport(result, startedAt, finishedAt), null, 2));
+            break;
+        case "cbom":
+            console.log(JSON.stringify(toCbomReport(result, startedAt, finishedAt), null, 2));
+            break;
+        default:
+            process.stdout.write(formatHuman(result));
+    }
+    return result.findings.length > 0 ? EXIT.FINDINGS : EXIT.OK;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((e) => {
+    console.error(`qprobe: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(EXIT.ERROR);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n/**\n * qprobe CLI — a thin shell over the programmatic API: parse argv, authorize,\n * probe, print, and set an exit code. It never throws to the top level.\n * Exit codes mirror qScan: 0 OK, 1 findings, 2 error/usage.\n */\nimport { readFileSync } from \"node:fs\";\nimport { parseArgs, HELP } from \"./args.js\";\nimport { parseTarget, TargetError } from \"./target.js\";\nimport { parseOwnedHosts, AttestationError } from \"./attest.js\";\nimport { runProbe, type RunResult, type EndpointReport } from \"./index.js\";\nimport { toJsonReport, toSarifReport, toCbomReport } from \"./report.js\";\nimport { VERSION } from \"./version.js\";\n\nconst EXIT = { OK: 0, FINDINGS: 1, ERROR: 2 } as const;\n\nfunction endpointLine(r: EndpointReport): string {\n  const t = `${r.target.host}:${r.target.port}`;\n  const lines: string[] = [`\\n${t}  [${r.mode}]`];\n  if ((r.mode === \"tls\" || r.mode === \"smtp\") && r.tls) {\n    if (r.tls.error) lines.push(`  ${r.mode}: ${r.tls.error}`);\n    else\n      lines.push(\n        `  ${r.tls.protocol ?? \"?\"} · ${r.tls.cipher ?? \"?\"} · KEX ${r.tls.kexGroup ?? \"?\"} · cert ${\n          r.tls.certKeyType ?? \"?\"\n        }${r.tls.certKeyBits ? `-${r.tls.certKeyBits}` : \"\"}${\n          r.tls.certSigFamily ? ` (sig ${r.tls.certSigFamily})` : \"\"\n        }`,\n      );\n    if (r.hybrid && !r.hybrid.error)\n      lines.push(\n        `  PQC-hybrid (X25519MLKEM768): ${r.hybrid.hybridSelected ? \"SUPPORTED ✓\" : \"not negotiated\"}`,\n      );\n  }\n  if (r.mode === \"ssh\" && r.ssh) {\n    if (r.ssh.error) lines.push(`  ssh: ${r.ssh.error}`);\n    else\n      lines.push(`  ${r.ssh.banner ?? \"\"} · PQC KEX: ${r.ssh.pqKexOffered ? \"offered ✓\" : \"none\"}`);\n  }\n  for (const p of r.positives) lines.push(`  ✓ ${p}`);\n  for (const f of r.findings) lines.push(`  [${f.severity}] ${f.title} — ${f.message}`);\n  return lines.join(\"\\n\");\n}\n\nfunction formatHuman(result: RunResult): string {\n  const out: string[] = [`qProbe — live post-quantum readiness · qprobe v${VERSION}`];\n  for (const r of result.reports) out.push(endpointLine(r));\n  const f = result.findings;\n  out.push(\n    `\\n${f.length} finding${f.length === 1 ? \"\" : \"s\"} · ${result.inventory.hndlCount} HNDL-exposed · readiness ${\n      result.inventory.readinessScore\n    }/100`,\n  );\n  return out.join(\"\\n\") + \"\\n\";\n}\n\nasync function main(): Promise<number> {\n  const args = parseArgs(process.argv.slice(2));\n  if (args.help) {\n    console.log(HELP);\n    return EXIT.OK;\n  }\n  if (args.targets.length === 0) {\n    console.error(HELP);\n    return EXIT.ERROR;\n  }\n\n  const defaultPort = args.mode === \"ssh\" ? 22 : args.mode === \"smtp\" ? 587 : 443;\n  let targets;\n  try {\n    targets = args.targets.map((t) => parseTarget(t, defaultPort));\n  } catch (e) {\n    if (e instanceof TargetError) {\n      console.error(`qprobe: ${e.message}`);\n      return EXIT.ERROR;\n    }\n    throw e;\n  }\n\n  let ownedHosts: string[] | undefined;\n  if (args.ownedHostsFile) {\n    try {\n      ownedHosts = parseOwnedHosts(readFileSync(args.ownedHostsFile, \"utf8\"));\n    } catch {\n      console.error(`qprobe: cannot read ownership manifest ${args.ownedHostsFile}`);\n      return EXIT.ERROR;\n    }\n  }\n\n  const startedAt = new Date().toISOString();\n  let result: RunResult;\n  try {\n    result = await runProbe({\n      targets,\n      mode: args.mode,\n      attest: { iOwnThis: args.iOwnThis, ownedHosts },\n      servername: args.servername,\n      timeoutMs: args.timeoutMs,\n    });\n  } catch (e) {\n    if (e instanceof AttestationError) {\n      console.error(`qprobe: ${e.message}`);\n      return EXIT.ERROR;\n    }\n    throw e;\n  }\n  const finishedAt = new Date().toISOString();\n\n  switch (args.format) {\n    case \"json\":\n      console.log(JSON.stringify(toJsonReport(result, startedAt, finishedAt), null, 2));\n      break;\n    case \"sarif\":\n      console.log(JSON.stringify(toSarifReport(result, startedAt, finishedAt), null, 2));\n      break;\n    case \"cbom\":\n      console.log(JSON.stringify(toCbomReport(result, startedAt, finishedAt), null, 2));\n      break;\n    default:\n      process.stdout.write(formatHuman(result));\n  }\n\n  return result.findings.length > 0 ? EXIT.FINDINGS : EXIT.OK;\n}\n\nmain()\n  .then((code) => process.exit(code))\n  .catch((e: unknown) => {\n    console.error(`qprobe: ${e instanceof Error ? e.message : String(e)}`);\n    process.exit(EXIT.ERROR);\n  });\n"]}

package/dist/clienthello.d.ts

@@ -0,0 +1,40 @@
+export declare const GROUP_X25519 = 29;
+export declare const GROUP_X25519MLKEM768 = 4588;
+export declare const GROUP_SECP256R1 = 23;
+/**
+ * Build a raw ClientHello TLS record advertising the hybrid group. `keyShareGroup`
+ * is the group we actually send a key_share for (default x25519), while
+ * `supportedGroups` is what we advertise (hybrid first).
+ */
+export declare function buildClientHello(opts: {
+    serverName?: string;
+    supportedGroups?: number[];
+    keyShareGroup?: number;
+}): Buffer;
+/** A parsed TLS record. */
+export interface TlsRecord {
+    type: number;
+    fragment: Buffer;
+}
+/** Split a buffer into TLS records. Stops at the first truncated record. */
+export declare function parseRecords(buf: Buffer): TlsRecord[];
+/** The result of reading a ServerHello / HelloRetryRequest. */
+export interface ServerHelloInfo {
+    isHelloRetryRequest: boolean;
+    /** Group named in the key_share extension (selected group), if present. */
+    selectedGroup?: number;
+    /** Negotiated version from supported_versions (0x0304 for TLS 1.3), if present. */
+    negotiatedVersion?: number;
+    cipherSuite?: number;
+}
+/**
+ * Parse a ServerHello handshake message body (the bytes AFTER the 4-byte handshake
+ * header) and extract the selected group + negotiated version. Handles both a
+ * normal ServerHello (key_share carries group + key) and a HelloRetryRequest
+ * (key_share carries just the selected group) — in both the first 2 bytes of the
+ * key_share body are the group.
+ */
+export declare function parseServerHelloBody(body: Buffer): ServerHelloInfo;
+/** Read the first ServerHello/HRR out of a raw response buffer, if any. */
+export declare function readServerHello(raw: Buffer): ServerHelloInfo | undefined;
+//# sourceMappingURL=clienthello.d.ts.map

package/dist/clienthello.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clienthello.d.ts","sourceRoot":"","sources":["../src/clienthello.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,YAAY,KAAS,CAAC;AACnC,eAAO,MAAM,oBAAoB,OAAS,CAAC;AAC3C,eAAO,MAAM,eAAe,KAAS,CAAC;AAuCtC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAkDT;AAED,2BAA2B;AAC3B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,CAWrD;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAyClE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAWxE"}

package/dist/clienthello.js

@@ -0,0 +1,182 @@
+/**
+ * Minimal, hand-rolled TLS 1.3 ClientHello builder + ServerHello/HelloRetryRequest
+ * parser — just enough to detect whether a server supports the post-quantum hybrid
+ * key-exchange group X25519MLKEM768 (codepoint 0x11EC, RFC 9370 / draft-kwiatkowski
+ * -tls-ecdhe-mlkem). Node's bundled OpenSSL does not offer this group, so it cannot
+ * be detected through `node:tls`; we advertise it in a raw ClientHello and read the
+ * group the server selects.
+ *
+ * Detection trick (no ML-KEM keygen needed): we send `supported_groups =
+ * [X25519MLKEM768, x25519]` but a `key_share` ONLY for x25519. A server that
+ * supports and prefers the hybrid group answers with a HelloRetryRequest selecting
+ * 0x11EC (asking us to resend with that share) — which is proof of support without
+ * us performing any ML-KEM. A server that does not proceeds with our x25519 share.
+ *
+ * This module is pure byte manipulation over Buffers; the socket I/O lives in
+ * tls.ts. Every function here is unit-tested with crafted bytes.
+ */
+import { randomBytes } from "node:crypto";
+// TLS constants.
+export const GROUP_X25519 = 0x001d;
+export const GROUP_X25519MLKEM768 = 0x11ec;
+export const GROUP_SECP256R1 = 0x0017;
+const TLS13_VERSION = 0x0304;
+const HS_CLIENT_HELLO = 0x01;
+const HS_SERVER_HELLO = 0x02;
+const REC_HANDSHAKE = 0x16;
+const EXT_SERVER_NAME = 0x0000;
+const EXT_SUPPORTED_GROUPS = 0x000a;
+const EXT_SIGNATURE_ALGORITHMS = 0x000d;
+const EXT_SUPPORTED_VERSIONS = 0x002b;
+const EXT_KEY_SHARE = 0x0033;
+/** The special ServerHello.random that marks a HelloRetryRequest (RFC 8446 §4.1.3). */
+const HRR_RANDOM = Buffer.from("cf21ad74e59a6111be1d8c021e65b891c2a211167abb8c5e079e09e2c8a8339c", "hex");
+function u16(n) {
+    const b = Buffer.alloc(2);
+    b.writeUInt16BE(n, 0);
+    return b;
+}
+/** Prefix `body` with a length field of `bytes` width (1, 2, or 3 bytes). */
+function withLen(bytes, body) {
+    const len = Buffer.alloc(bytes);
+    if (bytes === 1)
+        len.writeUInt8(body.length, 0);
+    else if (bytes === 2)
+        len.writeUInt16BE(body.length, 0);
+    else
+        len.writeUIntBE(body.length, 0, 3);
+    return Buffer.concat([len, body]);
+}
+/** Build a single extension (type + 2-byte-length body). */
+function ext(type, body) {
+    return Buffer.concat([u16(type), withLen(2, body)]);
+}
+/**
+ * Build a raw ClientHello TLS record advertising the hybrid group. `keyShareGroup`
+ * is the group we actually send a key_share for (default x25519), while
+ * `supportedGroups` is what we advertise (hybrid first).
+ */
+export function buildClientHello(opts) {
+    const supportedGroups = opts.supportedGroups ?? [
+        GROUP_X25519MLKEM768,
+        GROUP_X25519,
+        GROUP_SECP256R1,
+    ];
+    const keyShareGroup = opts.keyShareGroup ?? GROUP_X25519;
+    const extensions = [];
+    if (opts.serverName &&
+        opts.serverName.length > 0 &&
+        !/^\d+\.\d+\.\d+\.\d+$/.test(opts.serverName)) {
+        // server_name: ServerNameList { name_type(0=host_name), HostName }
+        const name = Buffer.from(opts.serverName, "ascii");
+        const entry = Buffer.concat([Buffer.from([0x00]), withLen(2, name)]);
+        extensions.push(ext(EXT_SERVER_NAME, withLen(2, entry)));
+    }
+    // supported_versions: TLS 1.3 only.
+    extensions.push(ext(EXT_SUPPORTED_VERSIONS, withLen(1, u16(TLS13_VERSION))));
+    // supported_groups (named_group list).
+    extensions.push(ext(EXT_SUPPORTED_GROUPS, withLen(2, Buffer.concat(supportedGroups.map(u16)))));
+    // signature_algorithms (a standard modern set).
+    const sigAlgs = [0x0403, 0x0804, 0x0807, 0x0401, 0x0805, 0x0806];
+    extensions.push(ext(EXT_SIGNATURE_ALGORITHMS, withLen(2, Buffer.concat(sigAlgs.map(u16)))));
+    // key_share: one entry for keyShareGroup with a 32-byte X25519-sized public.
+    // (We never complete the handshake, so the value need not be a real key.)
+    const share = Buffer.concat([u16(keyShareGroup), withLen(2, randomBytes(32))]);
+    extensions.push(ext(EXT_KEY_SHARE, withLen(2, share)));
+    const cipherSuites = Buffer.concat([u16(0x1301), u16(0x1302), u16(0x1303)]);
+    const helloBody = Buffer.concat([
+        u16(0x0303), // legacy_version TLS 1.2
+        randomBytes(32), // random
+        withLen(1, randomBytes(32)), // legacy_session_id (non-empty → "middlebox compat")
+        withLen(2, cipherSuites), // cipher_suites
+        withLen(1, Buffer.from([0x00])), // compression_methods: null
+        withLen(2, Buffer.concat(extensions)), // extensions
+    ]);
+    const handshake = Buffer.concat([Buffer.from([HS_CLIENT_HELLO]), withLen(3, helloBody)]);
+    // TLS record: handshake, legacy record version 0x0301.
+    return Buffer.concat([Buffer.from([REC_HANDSHAKE]), u16(0x0301), withLen(2, handshake)]);
+}
+/** Split a buffer into TLS records. Stops at the first truncated record. */
+export function parseRecords(buf) {
+    const out = [];
+    let off = 0;
+    while (off + 5 <= buf.length) {
+        const type = buf[off];
+        const len = buf.readUInt16BE(off + 3);
+        if (off + 5 + len > buf.length)
+            break;
+        out.push({ type, fragment: buf.subarray(off + 5, off + 5 + len) });
+        off += 5 + len;
+    }
+    return out;
+}
+/**
+ * Parse a ServerHello handshake message body (the bytes AFTER the 4-byte handshake
+ * header) and extract the selected group + negotiated version. Handles both a
+ * normal ServerHello (key_share carries group + key) and a HelloRetryRequest
+ * (key_share carries just the selected group) — in both the first 2 bytes of the
+ * key_share body are the group.
+ */
+export function parseServerHelloBody(body) {
+    let off = 0;
+    const need = (n) => {
+        if (off + n > body.length)
+            throw new RangeError("truncated ServerHello");
+    };
+    need(2);
+    off += 2; // legacy_version
+    need(32);
+    const random = body.subarray(off, off + 32);
+    off += 32;
+    const isHRR = random.equals(HRR_RANDOM);
+    need(1);
+    const sidLen = body[off];
+    off += 1;
+    need(sidLen);
+    off += sidLen; // legacy_session_id_echo
+    need(2);
+    const cipherSuite = body.readUInt16BE(off);
+    off += 2;
+    need(1);
+    off += 1; // legacy_compression_method
+    const info = { isHelloRetryRequest: isHRR, cipherSuite };
+    if (off + 2 > body.length)
+        return info; // no extensions
+    const extTotal = body.readUInt16BE(off);
+    off += 2;
+    const extEnd = Math.min(off + extTotal, body.length);
+    while (off + 4 <= extEnd) {
+        const extType = body.readUInt16BE(off);
+        const extLen = body.readUInt16BE(off + 2);
+        const start = off + 4;
+        if (start + extLen > body.length)
+            break;
+        const extBody = body.subarray(start, start + extLen);
+        if (extType === EXT_KEY_SHARE && extBody.length >= 2) {
+            info.selectedGroup = extBody.readUInt16BE(0);
+        }
+        else if (extType === EXT_SUPPORTED_VERSIONS && extBody.length >= 2) {
+            info.negotiatedVersion = extBody.readUInt16BE(0);
+        }
+        off = start + extLen;
+    }
+    return info;
+}
+/** Read the first ServerHello/HRR out of a raw response buffer, if any. */
+export function readServerHello(raw) {
+    for (const rec of parseRecords(raw)) {
+        if (rec.type !== REC_HANDSHAKE)
+            continue;
+        const f = rec.fragment;
+        if (f.length < 4)
+            continue;
+        if (f[0] !== HS_SERVER_HELLO)
+            continue;
+        const len = f.readUIntBE(1, 3);
+        if (4 + len > f.length)
+            continue;
+        return parseServerHelloBody(f.subarray(4, 4 + len));
+    }
+    return undefined;
+}
+//# sourceMappingURL=clienthello.js.map

package/dist/clienthello.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clienthello.js","sourceRoot":"","sources":["../src/clienthello.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Minimal, hand-rolled TLS 1.3 ClientHello builder + ServerHello/HelloRetryRequest\n * parser — just enough to detect whether a server supports the post-quantum hybrid\n * key-exchange group X25519MLKEM768 (codepoint 0x11EC, RFC 9370 / draft-kwiatkowski\n * -tls-ecdhe-mlkem). Node's bundled OpenSSL does not offer this group, so it cannot\n * be detected through `node:tls`; we advertise it in a raw ClientHello and read the\n * group the server selects.\n *\n * Detection trick (no ML-KEM keygen needed): we send `supported_groups =\n * [X25519MLKEM768, x25519]` but a `key_share` ONLY for x25519. A server that\n * supports and prefers the hybrid group answers with a HelloRetryRequest selecting\n * 0x11EC (asking us to resend with that share) — which is proof of support without\n * us performing any ML-KEM. A server that does not proceeds with our x25519 share.\n *\n * This module is pure byte manipulation over Buffers; the socket I/O lives in\n * tls.ts. Every function here is unit-tested with crafted bytes.\n */\nimport { randomBytes } from \"node:crypto\";\n\n// TLS constants.\nexport const GROUP_X25519 = 0x001d;\nexport const GROUP_X25519MLKEM768 = 0x11ec;\nexport const GROUP_SECP256R1 = 0x0017;\nconst TLS13_VERSION = 0x0304;\n\nconst HS_CLIENT_HELLO = 0x01;\nconst HS_SERVER_HELLO = 0x02;\nconst REC_HANDSHAKE = 0x16;\n\nconst EXT_SERVER_NAME = 0x0000;\nconst EXT_SUPPORTED_GROUPS = 0x000a;\nconst EXT_SIGNATURE_ALGORITHMS = 0x000d;\nconst EXT_SUPPORTED_VERSIONS = 0x002b;\nconst EXT_KEY_SHARE = 0x0033;\n\n/** The special ServerHello.random that marks a HelloRetryRequest (RFC 8446 §4.1.3). */\nconst HRR_RANDOM = Buffer.from(\n  \"cf21ad74e59a6111be1d8c021e65b891c2a211167abb8c5e079e09e2c8a8339c\",\n  \"hex\",\n);\n\nfunction u16(n: number): Buffer {\n  const b = Buffer.alloc(2);\n  b.writeUInt16BE(n, 0);\n  return b;\n}\n\n/** Prefix `body` with a length field of `bytes` width (1, 2, or 3 bytes). */\nfunction withLen(bytes: 1 | 2 | 3, body: Buffer): Buffer {\n  const len = Buffer.alloc(bytes);\n  if (bytes === 1) len.writeUInt8(body.length, 0);\n  else if (bytes === 2) len.writeUInt16BE(body.length, 0);\n  else len.writeUIntBE(body.length, 0, 3);\n  return Buffer.concat([len, body]);\n}\n\n/** Build a single extension (type + 2-byte-length body). */\nfunction ext(type: number, body: Buffer): Buffer {\n  return Buffer.concat([u16(type), withLen(2, body)]);\n}\n\n/**\n * Build a raw ClientHello TLS record advertising the hybrid group. `keyShareGroup`\n * is the group we actually send a key_share for (default x25519), while\n * `supportedGroups` is what we advertise (hybrid first).\n */\nexport function buildClientHello(opts: {\n  serverName?: string;\n  supportedGroups?: number[];\n  keyShareGroup?: number;\n}): Buffer {\n  const supportedGroups = opts.supportedGroups ?? [\n    GROUP_X25519MLKEM768,\n    GROUP_X25519,\n    GROUP_SECP256R1,\n  ];\n  const keyShareGroup = opts.keyShareGroup ?? GROUP_X25519;\n\n  const extensions: Buffer[] = [];\n\n  if (\n    opts.serverName &&\n    opts.serverName.length > 0 &&\n    !/^\\d+\\.\\d+\\.\\d+\\.\\d+$/.test(opts.serverName)\n  ) {\n    // server_name: ServerNameList { name_type(0=host_name), HostName }\n    const name = Buffer.from(opts.serverName, \"ascii\");\n    const entry = Buffer.concat([Buffer.from([0x00]), withLen(2, name)]);\n    extensions.push(ext(EXT_SERVER_NAME, withLen(2, entry)));\n  }\n\n  // supported_versions: TLS 1.3 only.\n  extensions.push(ext(EXT_SUPPORTED_VERSIONS, withLen(1, u16(TLS13_VERSION))));\n\n  // supported_groups (named_group list).\n  extensions.push(ext(EXT_SUPPORTED_GROUPS, withLen(2, Buffer.concat(supportedGroups.map(u16)))));\n\n  // signature_algorithms (a standard modern set).\n  const sigAlgs = [0x0403, 0x0804, 0x0807, 0x0401, 0x0805, 0x0806];\n  extensions.push(ext(EXT_SIGNATURE_ALGORITHMS, withLen(2, Buffer.concat(sigAlgs.map(u16)))));\n\n  // key_share: one entry for keyShareGroup with a 32-byte X25519-sized public.\n  // (We never complete the handshake, so the value need not be a real key.)\n  const share = Buffer.concat([u16(keyShareGroup), withLen(2, randomBytes(32))]);\n  extensions.push(ext(EXT_KEY_SHARE, withLen(2, share)));\n\n  const cipherSuites = Buffer.concat([u16(0x1301), u16(0x1302), u16(0x1303)]);\n\n  const helloBody = Buffer.concat([\n    u16(0x0303), // legacy_version TLS 1.2\n    randomBytes(32), // random\n    withLen(1, randomBytes(32)), // legacy_session_id (non-empty → \"middlebox compat\")\n    withLen(2, cipherSuites), // cipher_suites\n    withLen(1, Buffer.from([0x00])), // compression_methods: null\n    withLen(2, Buffer.concat(extensions)), // extensions\n  ]);\n\n  const handshake = Buffer.concat([Buffer.from([HS_CLIENT_HELLO]), withLen(3, helloBody)]);\n  // TLS record: handshake, legacy record version 0x0301.\n  return Buffer.concat([Buffer.from([REC_HANDSHAKE]), u16(0x0301), withLen(2, handshake)]);\n}\n\n/** A parsed TLS record. */\nexport interface TlsRecord {\n  type: number;\n  fragment: Buffer;\n}\n\n/** Split a buffer into TLS records. Stops at the first truncated record. */\nexport function parseRecords(buf: Buffer): TlsRecord[] {\n  const out: TlsRecord[] = [];\n  let off = 0;\n  while (off + 5 <= buf.length) {\n    const type = buf[off];\n    const len = buf.readUInt16BE(off + 3);\n    if (off + 5 + len > buf.length) break;\n    out.push({ type, fragment: buf.subarray(off + 5, off + 5 + len) });\n    off += 5 + len;\n  }\n  return out;\n}\n\n/** The result of reading a ServerHello / HelloRetryRequest. */\nexport interface ServerHelloInfo {\n  isHelloRetryRequest: boolean;\n  /** Group named in the key_share extension (selected group), if present. */\n  selectedGroup?: number;\n  /** Negotiated version from supported_versions (0x0304 for TLS 1.3), if present. */\n  negotiatedVersion?: number;\n  cipherSuite?: number;\n}\n\n/**\n * Parse a ServerHello handshake message body (the bytes AFTER the 4-byte handshake\n * header) and extract the selected group + negotiated version. Handles both a\n * normal ServerHello (key_share carries group + key) and a HelloRetryRequest\n * (key_share carries just the selected group) — in both the first 2 bytes of the\n * key_share body are the group.\n */\nexport function parseServerHelloBody(body: Buffer): ServerHelloInfo {\n  let off = 0;\n  const need = (n: number) => {\n    if (off + n > body.length) throw new RangeError(\"truncated ServerHello\");\n  };\n  need(2);\n  off += 2; // legacy_version\n  need(32);\n  const random = body.subarray(off, off + 32);\n  off += 32;\n  const isHRR = random.equals(HRR_RANDOM);\n  need(1);\n  const sidLen = body[off];\n  off += 1;\n  need(sidLen);\n  off += sidLen; // legacy_session_id_echo\n  need(2);\n  const cipherSuite = body.readUInt16BE(off);\n  off += 2;\n  need(1);\n  off += 1; // legacy_compression_method\n\n  const info: ServerHelloInfo = { isHelloRetryRequest: isHRR, cipherSuite };\n  if (off + 2 > body.length) return info; // no extensions\n  const extTotal = body.readUInt16BE(off);\n  off += 2;\n  const extEnd = Math.min(off + extTotal, body.length);\n  while (off + 4 <= extEnd) {\n    const extType = body.readUInt16BE(off);\n    const extLen = body.readUInt16BE(off + 2);\n    const start = off + 4;\n    if (start + extLen > body.length) break;\n    const extBody = body.subarray(start, start + extLen);\n    if (extType === EXT_KEY_SHARE && extBody.length >= 2) {\n      info.selectedGroup = extBody.readUInt16BE(0);\n    } else if (extType === EXT_SUPPORTED_VERSIONS && extBody.length >= 2) {\n      info.negotiatedVersion = extBody.readUInt16BE(0);\n    }\n    off = start + extLen;\n  }\n  return info;\n}\n\n/** Read the first ServerHello/HRR out of a raw response buffer, if any. */\nexport function readServerHello(raw: Buffer): ServerHelloInfo | undefined {\n  for (const rec of parseRecords(raw)) {\n    if (rec.type !== REC_HANDSHAKE) continue;\n    const f = rec.fragment;\n    if (f.length < 4) continue;\n    if (f[0] !== HS_SERVER_HELLO) continue;\n    const len = f.readUIntBE(1, 3);\n    if (4 + len > f.length) continue;\n    return parseServerHelloBody(f.subarray(4, 4 + len));\n  }\n  return undefined;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @quantakrypto/qprobe — active post-quantum readiness probing of live TLS/SSH
+ * endpoints you OWN. The programmatic API. See THREAT-MODEL.md for the
+ * authorization model; {@link runProbe} refuses to touch the network until
+ * {@link authorizeTargets} passes.
+ *
+ * Findings are `@quantakrypto/core` Findings, so they compose with qScan output
+ * and score through the same `buildInventory`.
+ */
+import type { CryptoInventory, Finding } from "@quantakrypto/core";
+import type { Target } from "./target.js";
+import { type AttestationInput } from "./attest.js";
+import { type TlsNegotiated, type HybridSupport } from "./tls.js";
+import { type SshProbeResult } from "./ssh.js";
+export type { Target } from "./target.js";
+export { parseTarget, TargetError } from "./target.js";
+export { authorizeTargets, parseOwnedHosts, AttestationError, type AttestationInput, } from "./attest.js";
+export type { TlsNegotiated, HybridSupport } from "./tls.js";
+export type { SshProbeResult, KexInit } from "./ssh.js";
+export { PQ_SSH_KEX } from "./ssh.js";
+export * from "./clienthello.js";
+export { certSignatureAlgorithm, decodeOid, oidToSignatureFamily } from "./x509.js";
+export { smtpAdvertisesStartTls, smtpReplyComplete } from "./smtp.js";
+export { classifyTls, classifySsh } from "./classify.js";
+export { toScanResult, toSarifReport, toCbomReport, toJsonReport } from "./report.js";
+export type ProbeMode = "tls" | "ssh" | "smtp";
+export interface EndpointReport {
+    target: Target;
+    mode: ProbeMode;
+    tls?: TlsNegotiated;
+    hybrid?: HybridSupport;
+    ssh?: SshProbeResult;
+    /** Human-readable positive signals (good news), e.g. hybrid TLS selected. */
+    positives: string[];
+    findings: Finding[];
+}
+/** Choose a probe mode for "auto": SSH on 22, SMTP STARTTLS on 25/587, TLS otherwise. */
+export declare function resolveMode(target: Target, mode: ProbeMode | "auto"): ProbeMode;
+export interface RunOptions {
+    targets: Target[];
+    mode: ProbeMode | "auto";
+    attest: AttestationInput;
+    servername?: string;
+    timeoutMs?: number;
+    /** Minimum spacing between endpoint connections (politeness / rate-limit). */
+    minIntervalMs?: number;
+}
+export interface RunResult {
+    reports: EndpointReport[];
+    findings: Finding[];
+    inventory: CryptoInventory;
+}
+/**
+ * Authorize (throws {@link AttestationError} / {@link TargetError} on failure — no
+ * network I/O happens before a successful authorization) then probe every target
+ * sequentially with a minimum interval between connections.
+ */
+export declare function runProbe(opts: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAIzD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AAMrB,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7D,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtF,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAK/E;AAkCD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,eAAe,CAAC;CAC5B;AAID;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAenE"}

package/dist/index.js

@@ -0,0 +1,74 @@
+import { buildInventory } from "@quantakrypto/core";
+import { authorizeTargets } from "./attest.js";
+import { probeTlsNegotiated, probeHybridSupport, } from "./tls.js";
+import { probeSsh } from "./ssh.js";
+import { probeSmtpStartTls } from "./smtp.js";
+import { classifyTls, classifySsh } from "./classify.js";
+export { parseTarget, TargetError } from "./target.js";
+export { authorizeTargets, parseOwnedHosts, AttestationError, } from "./attest.js";
+export { PQ_SSH_KEX } from "./ssh.js";
+export * from "./clienthello.js"; // pure byte codec — no network
+export { certSignatureAlgorithm, decodeOid, oidToSignatureFamily } from "./x509.js"; // pure DER parse
+export { smtpAdvertisesStartTls, smtpReplyComplete } from "./smtp.js"; // pure SMTP reply framing
+export { classifyTls, classifySsh } from "./classify.js";
+export { toScanResult, toSarifReport, toCbomReport, toJsonReport } from "./report.js";
+/** Choose a probe mode for "auto": SSH on 22, SMTP STARTTLS on 25/587, TLS otherwise. */
+export function resolveMode(target, mode) {
+    if (mode !== "auto")
+        return mode;
+    if (target.port === 22)
+        return "ssh";
+    if (target.port === 25 || target.port === 587)
+        return "smtp";
+    return "tls";
+}
+/**
+ * Probe a single endpoint. INTERNAL — not exported, because it performs network
+ * I/O without checking authorization; only {@link runProbe} (which authorizes
+ * first) may reach it. Assumes authorization has already been granted.
+ */
+async function probeEndpoint(target, mode, opts = {}) {
+    const positives = [];
+    if (mode === "ssh") {
+        const ssh = await probeSsh(target.host, target.port, opts.timeoutMs);
+        if (ssh.pqKexOffered)
+            positives.push("PQC SSH key exchange offered");
+        return { target, mode, ssh, positives, findings: classifySsh(target, ssh) };
+    }
+    if (mode === "smtp") {
+        // STARTTLS upgrade, then the same negotiated inspection (no hybrid probe over
+        // STARTTLS): classify with an "inconclusive" hybrid result so we don't claim to
+        // have tested for a hybrid group we never advertised.
+        const tls = await probeSmtpStartTls(target.host, target.port, opts);
+        const hybrid = { hybridSelected: false, error: "not probed (SMTP)" };
+        return { target, mode, tls, hybrid, positives, findings: classifyTls(target, tls, hybrid) };
+    }
+    const [tls, hybrid] = await Promise.all([
+        probeTlsNegotiated(target.host, target.port, opts),
+        probeHybridSupport(target.host, target.port, opts),
+    ]);
+    if (hybrid.hybridSelected)
+        positives.push("PQC-hybrid TLS (X25519MLKEM768) selected");
+    return { target, mode, tls, hybrid, positives, findings: classifyTls(target, tls, hybrid) };
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Authorize (throws {@link AttestationError} / {@link TargetError} on failure — no
+ * network I/O happens before a successful authorization) then probe every target
+ * sequentially with a minimum interval between connections.
+ */
+export async function runProbe(opts) {
+    authorizeTargets(opts.targets, opts.attest); // gate — throws before any connection
+    const reports = [];
+    const interval = opts.minIntervalMs ?? 250;
+    for (let i = 0; i < opts.targets.length; i++) {
+        if (i > 0 && interval > 0)
+            await delay(interval);
+        const target = opts.targets[i];
+        const mode = resolveMode(target, opts.mode);
+        reports.push(await probeEndpoint(target, mode, { servername: opts.servername, timeoutMs: opts.timeoutMs }));
+    }
+    const findings = reports.flatMap((r) => r.findings);
+    return { reports, findings, inventory: buildInventory(findings) };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAyB,MAAM,aAAa,CAAC;AACtE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GAGnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,QAAQ,EAAuB,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAGzD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GAEjB,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,cAAc,kBAAkB,CAAC,CAAC,+BAA+B;AACjE,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC,CAAC,iBAAiB;AACtG,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC,CAAC,0BAA0B;AACjG,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAetF,yFAAyF;AACzF,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAwB;IAClE,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,MAAM,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,MAAM,CAAC,IAAI,KAAK,EAAE,IAAI,MAAM,CAAC,IAAI,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IAC7D,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAC1B,MAAc,EACd,IAAe,EACf,OAAoD,EAAE;IAEtD,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACrE,IAAI,GAAG,CAAC,YAAY;YAAE,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;QACrE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAC9E,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,8EAA8E;QAC9E,gFAAgF;QAChF,sDAAsD;QACtD,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpE,MAAM,MAAM,GAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;QACpF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC;IAC9F,CAAC;IACD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACtC,kBAAkB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;QAClD,kBAAkB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;KACnD,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,cAAc;QAAE,SAAS,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACtF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC;AAC9F,CAAC;AAkBD,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAgB;IAC7C,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,sCAAsC;IAEnF,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,IAAI,GAAG,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,OAAO,CAAC,IAAI,CACV,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAC9F,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACpD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;AACpE,CAAC","sourcesContent":["/**\n * @quantakrypto/qprobe — active post-quantum readiness probing of live TLS/SSH\n * endpoints you OWN. The programmatic API. See THREAT-MODEL.md for the\n * authorization model; {@link runProbe} refuses to touch the network until\n * {@link authorizeTargets} passes.\n *\n * Findings are `@quantakrypto/core` Findings, so they compose with qScan output\n * and score through the same `buildInventory`.\n */\nimport type { CryptoInventory, Finding } from \"@quantakrypto/core\";\nimport { buildInventory } from \"@quantakrypto/core\";\nimport type { Target } from \"./target.js\";\nimport { authorizeTargets, type AttestationInput } from \"./attest.js\";\nimport {\n  probeTlsNegotiated,\n  probeHybridSupport,\n  type TlsNegotiated,\n  type HybridSupport,\n} from \"./tls.js\";\nimport { probeSsh, type SshProbeResult } from \"./ssh.js\";\nimport { probeSmtpStartTls } from \"./smtp.js\";\nimport { classifyTls, classifySsh } from \"./classify.js\";\n\nexport type { Target } from \"./target.js\";\nexport { parseTarget, TargetError } from \"./target.js\";\nexport {\n  authorizeTargets,\n  parseOwnedHosts,\n  AttestationError,\n  type AttestationInput,\n} from \"./attest.js\";\n// Only TYPES from the network modules are public — the socket-opening functions\n// (probeTlsNegotiated / probeHybridSupport / probeSsh) are intentionally NOT\n// re-exported, so `runProbe` (which authorizes first) is the sole public entry\n// that performs network I/O. This keeps the THREAT-MODEL invariant true at the\n// package API boundary, not just in the CLI.\nexport type { TlsNegotiated, HybridSupport } from \"./tls.js\";\nexport type { SshProbeResult, KexInit } from \"./ssh.js\";\nexport { PQ_SSH_KEX } from \"./ssh.js\";\nexport * from \"./clienthello.js\"; // pure byte codec — no network\nexport { certSignatureAlgorithm, decodeOid, oidToSignatureFamily } from \"./x509.js\"; // pure DER parse\nexport { smtpAdvertisesStartTls, smtpReplyComplete } from \"./smtp.js\"; // pure SMTP reply framing\nexport { classifyTls, classifySsh } from \"./classify.js\";\nexport { toScanResult, toSarifReport, toCbomReport, toJsonReport } from \"./report.js\";\n\nexport type ProbeMode = \"tls\" | \"ssh\" | \"smtp\";\n\nexport interface EndpointReport {\n  target: Target;\n  mode: ProbeMode;\n  tls?: TlsNegotiated;\n  hybrid?: HybridSupport;\n  ssh?: SshProbeResult;\n  /** Human-readable positive signals (good news), e.g. hybrid TLS selected. */\n  positives: string[];\n  findings: Finding[];\n}\n\n/** Choose a probe mode for \"auto\": SSH on 22, SMTP STARTTLS on 25/587, TLS otherwise. */\nexport function resolveMode(target: Target, mode: ProbeMode | \"auto\"): ProbeMode {\n  if (mode !== \"auto\") return mode;\n  if (target.port === 22) return \"ssh\";\n  if (target.port === 25 || target.port === 587) return \"smtp\";\n  return \"tls\";\n}\n\n/**\n * Probe a single endpoint. INTERNAL — not exported, because it performs network\n * I/O without checking authorization; only {@link runProbe} (which authorizes\n * first) may reach it. Assumes authorization has already been granted.\n */\nasync function probeEndpoint(\n  target: Target,\n  mode: ProbeMode,\n  opts: { servername?: string; timeoutMs?: number } = {},\n): Promise<EndpointReport> {\n  const positives: string[] = [];\n  if (mode === \"ssh\") {\n    const ssh = await probeSsh(target.host, target.port, opts.timeoutMs);\n    if (ssh.pqKexOffered) positives.push(\"PQC SSH key exchange offered\");\n    return { target, mode, ssh, positives, findings: classifySsh(target, ssh) };\n  }\n  if (mode === \"smtp\") {\n    // STARTTLS upgrade, then the same negotiated inspection (no hybrid probe over\n    // STARTTLS): classify with an \"inconclusive\" hybrid result so we don't claim to\n    // have tested for a hybrid group we never advertised.\n    const tls = await probeSmtpStartTls(target.host, target.port, opts);\n    const hybrid: HybridSupport = { hybridSelected: false, error: \"not probed (SMTP)\" };\n    return { target, mode, tls, hybrid, positives, findings: classifyTls(target, tls, hybrid) };\n  }\n  const [tls, hybrid] = await Promise.all([\n    probeTlsNegotiated(target.host, target.port, opts),\n    probeHybridSupport(target.host, target.port, opts),\n  ]);\n  if (hybrid.hybridSelected) positives.push(\"PQC-hybrid TLS (X25519MLKEM768) selected\");\n  return { target, mode, tls, hybrid, positives, findings: classifyTls(target, tls, hybrid) };\n}\n\nexport interface RunOptions {\n  targets: Target[];\n  mode: ProbeMode | \"auto\";\n  attest: AttestationInput;\n  servername?: string;\n  timeoutMs?: number;\n  /** Minimum spacing between endpoint connections (politeness / rate-limit). */\n  minIntervalMs?: number;\n}\n\nexport interface RunResult {\n  reports: EndpointReport[];\n  findings: Finding[];\n  inventory: CryptoInventory;\n}\n\nconst delay = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/**\n * Authorize (throws {@link AttestationError} / {@link TargetError} on failure — no\n * network I/O happens before a successful authorization) then probe every target\n * sequentially with a minimum interval between connections.\n */\nexport async function runProbe(opts: RunOptions): Promise<RunResult> {\n  authorizeTargets(opts.targets, opts.attest); // gate — throws before any connection\n\n  const reports: EndpointReport[] = [];\n  const interval = opts.minIntervalMs ?? 250;\n  for (let i = 0; i < opts.targets.length; i++) {\n    if (i > 0 && interval > 0) await delay(interval);\n    const target = opts.targets[i];\n    const mode = resolveMode(target, opts.mode);\n    reports.push(\n      await probeEndpoint(target, mode, { servername: opts.servername, timeoutMs: opts.timeoutMs }),\n    );\n  }\n  const findings = reports.flatMap((r) => r.findings);\n  return { reports, findings, inventory: buildInventory(findings) };\n}\n"]}

package/dist/report.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reporting: turn a qProbe {@link RunResult} into `@quantakrypto/core`'s shared
+ * output formats, so live-endpoint findings emit the SAME SARIF 2.1.0 and
+ * CycloneDX 1.6 CBOM as qScan (code) and the infra detectors (config). This is
+ * what lets the three planes compose into one post-quantum posture: a qScan CBOM
+ * and a qProbe CBOM are both CycloneDX 1.6 documents and merge cleanly.
+ *
+ * The core reporters are findings-based (they derive SARIF `rules[]` and CBOM
+ * crypto-assets from the findings themselves), so no registry entry is needed for
+ * the `qprobe-*` rules.
+ */
+import type { ScanResult, SarifLog, CycloneDxBom } from "@quantakrypto/core";
+import type { RunResult } from "./index.js";
+/**
+ * Adapt a {@link RunResult} to a {@link ScanResult}. `filesScanned` is the number
+ * of endpoints probed; `root` is the probed target list.
+ */
+export declare function toScanResult(run: RunResult, startedAt: string, finishedAt: string): ScanResult;
+export declare function toSarifReport(run: RunResult, startedAt: string, finishedAt: string): SarifLog;
+export declare function toCbomReport(run: RunResult, startedAt: string, finishedAt: string): CycloneDxBom;
+export declare function toJsonReport(run: RunResult, startedAt: string, finishedAt: string): Record<string, unknown>;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAU9F;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,QAAQ,CAE7F;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAQhG;AAED,wBAAgB,YAAY,CAC1B,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}

package/dist/report.js

@@ -0,0 +1,51 @@
+import { toSarif, toJson, toCbom } from "@quantakrypto/core";
+import { VERSION } from "./version.js";
+/**
+ * Adapt a {@link RunResult} to a {@link ScanResult}. `filesScanned` is the number
+ * of endpoints probed; `root` is the probed target list.
+ */
+export function toScanResult(run, startedAt, finishedAt) {
+    return {
+        root: run.reports.map((r) => `${r.target.host}:${r.target.port}`).join(", ") || "(no targets)",
+        findings: run.findings,
+        filesScanned: run.reports.length,
+        inventory: run.inventory,
+        startedAt,
+        finishedAt,
+        toolVersion: `qprobe ${VERSION}`,
+    };
+}
+export function toSarifReport(run, startedAt, finishedAt) {
+    return toSarif(toScanResult(run, startedAt, finishedAt));
+}
+export function toCbomReport(run, startedAt, finishedAt) {
+    const bom = toCbom(toScanResult(run, startedAt, finishedAt));
+    // core's toCbom labels the producing tool "qScan"; correct it for qProbe so a
+    // merged code+endpoints CBOM attributes each plane to the right tool.
+    const tools = bom.metadata.tools
+        ?.components;
+    if (Array.isArray(tools))
+        for (const t of tools)
+            if (t.name === "qScan")
+                t.name = "qProbe";
+    return bom;
+}
+export function toJsonReport(run, startedAt, finishedAt) {
+    // Core's structured JSON (findings + inventory), augmented with the per-endpoint
+    // probe detail qProbe uniquely carries (negotiated params, hybrid result).
+    const base = toJson(toScanResult(run, startedAt, finishedAt));
+    return {
+        ...base,
+        endpoints: run.reports.map((r) => ({
+            target: `${r.target.host}:${r.target.port}`,
+            mode: r.mode,
+            positives: r.positives,
+            tls: r.tls,
+            hybrid: r.hybrid,
+            ssh: r.ssh
+                ? { banner: r.ssh.banner, pqKexOffered: r.ssh.pqKexOffered, error: r.ssh.error }
+                : undefined,
+        })),
+    };
+}
+//# sourceMappingURL=report.js.map