@quantakrypto/mcp 0.4.4 → 0.5.1

package/dist/tools.js

@@ -824,6 +824,58 @@ const checkDependencyTool = {
         };
     },
 };
+/**
+ * JSON-schema shape of one finding from `scan_path --format json` (mirrors the
+ * core {@link Finding} type). Used as the `items` schema for every findings
+ * array below so MCP clients/inspectors get a described element shape instead of
+ * a bare `type: "array"`. Extra finding fields are allowed (no
+ * additionalProperties:false), only ruleId + location.file are required — which
+ * is exactly what {@link areFindings} enforces.
+ */
+const FINDING_ITEM_SCHEMA = {
+    type: "object",
+    description: "A single finding from `scan_path --format json`.",
+    properties: {
+        ruleId: { type: "string", description: 'Stable rule id, e.g. "rsa-keygen".' },
+        title: { type: "string" },
+        category: { type: "string" },
+        severity: { type: "string", description: "critical | high | medium | low | info." },
+        confidence: { type: "string" },
+        algorithm: { type: "string", description: "Classical algorithm family, when applicable." },
+        hndl: { type: "boolean", description: "Exposed to harvest-now-decrypt-later." },
+        message: { type: "string" },
+        remediation: { type: "string" },
+        cwe: { type: "string", description: 'e.g. "CWE-327".' },
+        location: {
+            type: "object",
+            description: "Where the finding is.",
+            properties: {
+                file: { type: "string" },
+                line: { type: "number" },
+            },
+            required: ["file"],
+        },
+    },
+    required: ["ruleId", "location"],
+};
+/** JSON-schema shape of one triage verdict for `apply_triage`. */
+const VERDICT_ITEM_SCHEMA = {
+    type: "object",
+    description: "A triage verdict for one finding.",
+    properties: {
+        fingerprint: {
+            type: "string",
+            description: "Fingerprint of the finding this verdict applies to.",
+        },
+        exposureScore: {
+            type: "number",
+            description: "Real-world exposure (higher = more exposed).",
+        },
+        priority: { type: "string", enum: ["now", "soon", "later"] },
+        rationale: { type: "string", description: "Why this exposure score / priority." },
+    },
+    required: ["fingerprint", "exposureScore", "priority", "rationale"],
+};
 const scoreDeltaTool = {
     name: "score_delta",
     description: "Compute the readiness-score and HNDL change between two finding sets (e.g. before " +
@@ -834,9 +886,14 @@ const scoreDeltaTool = {
         properties: {
             before: {
                 type: "array",
+                items: FINDING_ITEM_SCHEMA,
                 description: "Findings before the change (from a scan's JSON findings).",
             },
-            after: { type: "array", description: "Findings after the change." },
+            after: {
+                type: "array",
+                items: FINDING_ITEM_SCHEMA,
+                description: "Findings after the change.",
+            },
         },
         required: ["before", "after"],
         additionalProperties: false,
@@ -918,7 +975,11 @@ const triageFindingsTool = {
     inputSchema: {
         type: "object",
         properties: {
-            findings: { type: "array", description: "Findings from a scan's JSON output." },
+            findings: {
+                type: "array",
+                items: FINDING_ITEM_SCHEMA,
+                description: "Findings from a scan's JSON output.",
+            },
         },
         required: ["findings"],
         additionalProperties: false,
@@ -988,8 +1049,16 @@ const applyTriageTool = {
     inputSchema: {
         type: "object",
         properties: {
-            findings: { type: "array", description: "The findings that were triaged." },
-            verdicts: { type: "array", description: "One verdict per finding, keyed by fingerprint." },
+            findings: {
+                type: "array",
+                items: FINDING_ITEM_SCHEMA,
+                description: "The findings that were triaged.",
+            },
+            verdicts: {
+                type: "array",
+                items: VERDICT_ITEM_SCHEMA,
+                description: "One verdict per finding, keyed by fingerprint.",
+            },
         },
         required: ["findings", "verdicts"],
         additionalProperties: false,
@@ -1053,7 +1122,11 @@ const remediateFindingsTool = {
     inputSchema: {
         type: "object",
         properties: {
-            findings: { type: "array", description: "Findings from a scan's JSON output." },
+            findings: {
+                type: "array",
+                items: FINDING_ITEM_SCHEMA,
+                description: "Findings from a scan's JSON output.",
+            },
         },
         required: ["findings"],
         additionalProperties: false,
@@ -1142,6 +1215,100 @@ const applyVerifiedPatchTool = {
         }, null, 2));
     },
 };
+/**
+ * `probe_endpoint` — actively probe ONE live TLS/SSH endpoint the caller OWNS for
+ * post-quantum readiness. This is the ONLY MCP tool that opens a network socket;
+ * the qprobe plane is loaded via dynamic import so the server stays offline until
+ * the tool is actually invoked, and the ownership attestation gate is enforced in
+ * qProbe's `runProbe` before any connection. On the HTTP transport it is OFF by
+ * default (see {@link NETWORK_TOOL_NAMES}) — a hosted endpoint should not probe
+ * arbitrary hosts — but a trusted operator can opt in with
+ * QUANTAKRYPTO_MCP_ALLOW_NETWORK=1.
+ */
+const probeEndpointTool = {
+    name: "probe_endpoint",
+    description: "Actively probe ONE live TLS/SSH endpoint YOU OWN for post-quantum readiness " +
+        "(PQC-hybrid key exchange X25519MLKEM768, classical certificate posture). REQUIRES " +
+        "an ownership attestation: set i_own_this=true to confirm you are authorized to test " +
+        "the target. Refuses CIDR ranges / wildcards / lists — one host at a time. Performs " +
+        "only a benign, unauthenticated handshake and never modifies the endpoint. NOTE: this " +
+        "is the ONLY quantakrypto MCP tool that opens a network connection; the server is " +
+        "otherwise offline. Over HTTP it is disabled unless the operator sets " +
+        "QUANTAKRYPTO_MCP_ALLOW_NETWORK=1.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            target: {
+                type: "string",
+                description: "A single host or host:port you own (no ranges/CIDRs/wildcards).",
+            },
+            mode: {
+                type: "string",
+                enum: ["tls", "ssh", "auto"],
+                description: "Probe mode (default: auto — SSH on :22, TLS otherwise).",
+            },
+            i_own_this: {
+                type: "boolean",
+                description: "Attestation that you are authorized to probe this endpoint. Must be true; the probe is refused otherwise.",
+            },
+            timeout_ms: { type: "number", description: "Per-connection timeout in ms (default 8000)." },
+        },
+        required: ["target", "i_own_this"],
+        additionalProperties: false,
+    },
+    async handler(args) {
+        const target = args.target;
+        if (typeof target !== "string" || target.length === 0) {
+            return errorResult("probe_endpoint requires a non-empty 'target' string.");
+        }
+        if (args.i_own_this !== true) {
+            return errorResult("probe_endpoint refused: set i_own_this=true to attest you are authorized to probe this endpoint. Active probing of endpoints you do not own may be unlawful.");
+        }
+        const mode = args.mode === "tls" || args.mode === "ssh" ? args.mode : "auto";
+        const timeoutMs = typeof args.timeout_ms === "number" ? args.timeout_ms : undefined;
+        // Dynamic import keeps the networked qprobe plane out of the server process
+        // until this tool is actually used; runProbe enforces the attestation gate.
+        const qprobe = await import("@quantakrypto/qprobe");
+        // Parse the target explicitly so a CIDR/range/list refusal returns a helpful
+        // message rather than a scrubbed internal error.
+        let parsed;
+        try {
+            parsed = qprobe.parseTarget(target, mode === "ssh" ? 22 : 443);
+        }
+        catch (e) {
+            return errorResult(`probe_endpoint: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const probed = await safe("probe_endpoint", () => qprobe.runProbe({ targets: [parsed], mode, attest: { iOwnThis: true }, timeoutMs }));
+        if (!probed.ok)
+            return probed.result;
+        const { reports, findings, inventory } = probed.value;
+        const lines = [];
+        let unreachable = 0;
+        for (const r of reports) {
+            lines.push(`${r.target.host}:${r.target.port} [${r.mode}]`);
+            const err = r.ssh?.error ?? r.tls?.error ?? r.hybrid?.error;
+            if (err && r.findings.length === 0) {
+                unreachable++;
+                // Do NOT let an unreachable/errored endpoint read as a clean 100/100.
+                lines.push(`  ⚠ probe error: ${err} — endpoint NOT assessed (not a clean result)`);
+            }
+            for (const p of r.positives)
+                lines.push(`  ✓ ${p}`);
+            for (const f of r.findings)
+                lines.push(`  [${f.severity}] ${f.title} — ${f.message}`);
+        }
+        const note = unreachable > 0
+            ? " — NOTE: an endpoint could not be reached/handshaken, so this is NOT a clean bill of health"
+            : "";
+        lines.push(`\n${findings.length} finding${findings.length === 1 ? "" : "s"} · ${inventory.hndlCount} HNDL-exposed · readiness ${inventory.readinessScore}/100${note}`);
+        return {
+            content: [
+                { type: "text", text: lines.join("\n") },
+                { type: "text", text: JSON.stringify({ findings, inventory }, null, 2) },
+            ],
+        };
+    },
+};
 /**
  * Tools that read arbitrary filesystem paths. Disabled by default on the HTTP
  * transport (see {@link ./http.ts}) because a hosted endpoint must not be an
@@ -1154,6 +1321,13 @@ export const FS_TOOL_NAMES = [
     "generate_cbom",
     "plan_migration",
 ];
+/**
+ * Tools that open network connections. On the HTTP transport they are OFF by
+ * default — a hosted MCP should not probe arbitrary hosts — but a trusted operator
+ * can opt in with QUANTAKRYPTO_MCP_ALLOW_NETWORK=1 (mirroring the FS-tools opt-in).
+ * Always available on the local stdio transport, which trusts the local user.
+ */
+export const NETWORK_TOOL_NAMES = ["probe_endpoint"];
 /** All quantakrypto MCP tools, in a stable order. */
 export const quantakryptoTools = [
     scanPathTool,
@@ -1173,6 +1347,8 @@ export const quantakryptoTools = [
     applyTriageTool,
     remediateFindingsTool,
     applyVerifiedPatchTool,
+    // The only networked tool — offline until invoked; refused on the HTTP transport.
+    probeEndpointTool,
 ];
 /** The core version these tools are built against (re-exported for diagnostics). */
 export const CORE_VERSION = VERSION;