codex-plugin-doctor 1.50.0 → 1.52.0

package/dist/rules/rule-catalog.js

@@ -161,6 +161,24 @@ export const ruleCatalog = [
         fix: "Add `command` for stdio servers or `url` for remote servers.",
         example: '{ "command": "node", "args": ["server.js"] }'
     },
+    {
+        id: "mcp.server.transport.conflict",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "An MCP server defines both command and URL transports.",
+        why: "Clients cannot select a transport deterministically when a server defines both process and remote connection settings.",
+        fix: "Keep either command for stdio or url for remote MCP, but not both.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.mcp.server.transport.conflict",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A bundled MCP server defines both command and URL transports.",
+        why: "Codex cannot select a transport deterministically when a bundled server defines both process and remote connection settings.",
+        fix: "Keep either command for stdio or url for remote MCP, but not both.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
     {
         id: "plugin.security.path_traversal",
         category: "security",
@@ -245,12 +263,66 @@ export const ruleCatalog = [
     {
         id: "plugin.security.insecure_http_url",
         category: "security",
-        defaultSeverity: "warn",
+        defaultSeverity: "fail",
         summary: "An MCP server uses a plain HTTP URL.",
         why: "Plain HTTP can expose MCP traffic and does not verify endpoint identity on non-local networks.",
         fix: "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints.",
         example: '{ "url": "https://example.com/mcp" }'
     },
+    {
+        id: "plugin.security.remote_mcp_url.invalid",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL is not an absolute HTTP or HTTPS URL.",
+        why: "Clients cannot reliably connect to malformed or relative remote MCP endpoints.",
+        fix: "Use an absolute HTTPS URL, or an explicit localhost HTTP development URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.unsupported_scheme",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL uses an unsupported scheme.",
+        why: "Remote MCP transport supports only HTTP and HTTPS endpoints.",
+        fix: "Use an HTTPS URL, or an explicit localhost HTTP development URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.credentials",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL embeds credentials.",
+        why: "URL credentials can leak through configuration, logs, reports, and package artifacts.",
+        fix: "Remove URL credentials and configure authentication outside the endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.query",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL contains a query string.",
+        why: "Query strings can carry secrets and make endpoint configuration ambiguous.",
+        fix: "Remove the query string from the MCP endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.fragment",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL contains a fragment.",
+        why: "Fragments are not sent to servers and can hide misleading endpoint configuration.",
+        fix: "Remove the fragment from the MCP endpoint URL.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
+    {
+        id: "plugin.security.remote_mcp_url.ip_literal",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server URL uses a numeric IP literal.",
+        why: "Numeric IP endpoints bypass hostname-based endpoint review and are not an accepted remote MCP shape.",
+        fix: "Use a reviewed hostname; use localhost only for local development.",
+        example: '{ "url": "https://example.com/mcp" }'
+    },
     {
         id: "plugin.security.mcp_binds_all_interfaces",
         category: "security",
@@ -278,6 +350,78 @@ export const ruleCatalog = [
         fix: "Remove hidden override or exfiltration instructions and keep descriptions scoped to legitimate behavior.",
         example: "Keep SKILL.md, prompt, resource, and tool descriptions direct and user-facing."
     },
+    {
+        id: "mcp.conformance.protocol.unknown_newer",
+        category: "mcp",
+        defaultSeverity: "warn",
+        summary: "The server advertises a newer MCP protocol version.",
+        why: "The validator applies the 2025-11-25 structural baseline, which may not cover newer protocol requirements.",
+        fix: "Confirm the server's newer protocol changes remain compatible with the 2025-11-25 MCP contract.",
+        example: '{ "protocolVersion": "2026-01-01" }'
+    },
+    {
+        id: "mcp.conformance.tasks.capability_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A Tasks capability declaration is malformed.",
+        why: "Codex cannot safely determine whether the server supports task-aware tool calls.",
+        fix: "Return an object for the affected Tasks capability field, or omit the capability until it is implemented.",
+        example: '{ "capabilities": { "tasks": { "requests": { "tools": { "call": {} } } } } }'
+    },
+    {
+        id: "mcp.conformance.tasks.task_support_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool declares invalid task support.",
+        why: "Codex cannot safely interpret the tool's task support contract.",
+        fix: "Set execution.taskSupport to required, optional, or forbidden.",
+        example: '{ "execution": { "taskSupport": "optional" } }'
+    },
+    {
+        id: "mcp.conformance.tasks.capability_mismatch",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool's task support does not match server capability.",
+        why: "Codex may attempt task-aware tool calls that the server did not advertise as supported.",
+        fix: "Advertise capabilities.tasks.requests.tools.call as an object, or set execution.taskSupport to forbidden.",
+        example: '{ "capabilities": { "tasks": { "requests": { "tools": { "call": {} } } } }, "execution": { "taskSupport": "required" } }'
+    },
+    {
+        id: "mcp.conformance.tasks_list.timeout",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The server did not complete tasks/list in time.",
+        why: "Codex cannot rely on task discovery when tasks/list cannot complete with a valid response.",
+        fix: "Reduce tasks/list latency and verify pagination completes.",
+        example: "Return a valid tasks/list response before the configured runtime timeout."
+    },
+    {
+        id: "mcp.conformance.tasks_list.invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "The server returned an invalid tasks/list response.",
+        why: "Codex cannot rely on task discovery when tasks/list cannot complete with a valid response.",
+        fix: "Return a valid tasks/list response with well-formed task items and pagination.",
+        example: '{ "tasks": [] }'
+    },
+    {
+        id: "mcp.conformance.schema.dialect_invalid",
+        category: "mcp",
+        defaultSeverity: "fail",
+        summary: "A tool schema declares an invalid dialect.",
+        why: "Codex cannot reliably select a schema dialect for this tool.",
+        fix: "Omit $schema or provide an absolute URI in the affected tool schema.",
+        example: '{ "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } }'
+    },
+    {
+        id: "mcp.conformance.schema.dialect_unsupported",
+        category: "mcp",
+        defaultSeverity: "warn",
+        summary: "A tool schema uses a non-canonical dialect.",
+        why: "The schema may be valid, but its dialect is outside the validator's latest compatibility baseline.",
+        fix: "Use https://json-schema.org/draft/2020-12/schema or omit $schema.",
+        example: '{ "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema" } }'
+    },
     {
         id: "plugin.runtime.exited_early",
         category: "runtime",
@@ -304,6 +448,114 @@ export const ruleCatalog = [
         why: "MCP stdio transport requires newline-delimited JSON-RPC messages on stdout.",
         fix: "Send logs to stderr and reserve stdout for JSON-RPC protocol messages only.",
         example: "Use `console.error` for diagnostics in Node stdio servers."
+    },
+    {
+        id: "plugin.runtime.remote.network_not_approved",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote MCP probing was not explicitly approved.",
+        why: "Remote initialization creates outbound network traffic.",
+        fix: "Review the plan, then use --runtime --allow-network; add --allow-local-network only for localhost HTTP.",
+        example: "codex-plugin-doctor mcp . --runtime --allow-network"
+    },
+    {
+        id: "plugin.runtime.remote.url.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "A remote MCP endpoint URL is unsafe or unsupported.",
+        why: "Credentials, queries, fragments, IP literals, and unsupported schemes bypass the remote probe boundary.",
+        fix: "Use an absolute HTTPS URL without credentials, query parameters, fragments, or IP literals.",
+        example: "https://mcp.example/mcp"
+    },
+    {
+        id: "plugin.runtime.remote.transport.timeout",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize request timed out.",
+        why: "A bounded probe cannot safely negotiate an unavailable endpoint.",
+        fix: "Make the endpoint reachable and complete initialize within the configured timeout.",
+        example: "Return a valid initialize response promptly."
+    },
+    {
+        id: "plugin.runtime.remote.transport.response_too_large",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP response exceeded the bounded probe limit.",
+        why: "Unbounded remote responses can exhaust local resources.",
+        fix: "Return a compact initialize response and keep discovery metadata bounded.",
+        example: "Return only the MCP initialize result."
+    },
+    {
+        id: "plugin.runtime.remote.transport.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP transport request failed.",
+        why: "Protocol negotiation cannot proceed without a safe bounded connection.",
+        fix: "Verify endpoint reachability, TLS, and remote network policy eligibility.",
+        example: "Use a public HTTPS endpoint or explicitly approved localhost HTTP."
+    },
+    {
+        id: "plugin.runtime.remote.http_status.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize response used an unexpected HTTP status.",
+        why: "Streamable HTTP initialization requires a successful response before negotiation.",
+        fix: "Return HTTP 200 for initialize or publish valid OAuth discovery metadata for protected endpoints.",
+        example: "HTTP/1.1 200 OK"
+    },
+    {
+        id: "plugin.runtime.remote.content_type.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize response used an unsupported content type.",
+        why: "The probe can only validate JSON or Server-Sent Events protocol responses.",
+        fix: "Return application/json or text/event-stream with a JSON-RPC response.",
+        example: "Content-Type: application/json"
+    },
+    {
+        id: "plugin.runtime.remote.session.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP session header is invalid.",
+        why: "An invalid session identifier cannot be safely replayed on the initialized notification.",
+        fix: "Return MCP-Session-Id only as visible ASCII characters.",
+        example: "MCP-Session-Id: session-123"
+    },
+    {
+        id: "plugin.runtime.remote.initialize.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP initialize JSON-RPC result is invalid.",
+        why: "Invalid negotiation results leave capabilities and protocol version unknown.",
+        fix: "Return a JSON-RPC 2.0 initialize result for protocol version 2025-11-25.",
+        example: '{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-11-25" } }'
+    },
+    {
+        id: "plugin.runtime.remote.initialized.failed",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "The remote MCP server did not acknowledge notifications/initialized.",
+        why: "The session may not be ready for subsequent protocol traffic.",
+        fix: "Accept a successful initialized notification at the configured MCP endpoint.",
+        example: "Return HTTP 204 to notifications/initialized."
+    },
+    {
+        id: "plugin.runtime.remote.authorization.metadata.invalid",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote OAuth discovery metadata is invalid.",
+        why: "Protected MCP endpoints cannot be assessed safely without valid authorization metadata.",
+        fix: "Publish valid HTTPS protected-resource and authorization-server metadata.",
+        example: "https://mcp.example/.well-known/oauth-protected-resource"
+    },
+    {
+        id: "plugin.runtime.remote.authorization.metadata.unavailable",
+        category: "runtime",
+        defaultSeverity: "fail",
+        summary: "Remote OAuth discovery metadata is unavailable.",
+        why: "Authorization readiness cannot be confirmed without bounded metadata responses.",
+        fix: "Make protected-resource and authorization-server metadata available over HTTPS.",
+        example: "Return application/json discovery metadata."
     }
 ];
 export function findRuleDefinition(id) {

package/dist/run-cli.js

@@ -99,8 +99,41 @@ function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
     }
     return value;
 }
+function parseRemoteNetworkFlags(flags, runtime) {
+    let allowNetwork = false;
+    let allowLocalNetwork = false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if (flag === "--allow-network") {
+            if (allowNetwork)
+                return new CliUsageError("Duplicate runtime network flag: --allow-network.");
+            if (flags[index + 1] && !flags[index + 1].startsWith("--")) {
+                return new CliUsageError("--allow-network does not accept a value.");
+            }
+            allowNetwork = true;
+        }
+        else if (flag === "--allow-local-network") {
+            if (allowLocalNetwork)
+                return new CliUsageError("Duplicate runtime network flag: --allow-local-network.");
+            if (flags[index + 1] && !flags[index + 1].startsWith("--")) {
+                return new CliUsageError("--allow-local-network does not accept a value.");
+            }
+            allowLocalNetwork = true;
+        }
+        else if (flag?.startsWith("--allow-network=") || flag?.startsWith("--allow-local-network=")) {
+            return new CliUsageError(`${flag.split("=", 1)[0]} does not accept a value.`);
+        }
+    }
+    if ((allowNetwork || allowLocalNetwork) && !runtime) {
+        return new CliUsageError("--allow-network requires --runtime.");
+    }
+    if (allowLocalNetwork && !allowNetwork) {
+        return new CliUsageError("--allow-local-network requires --allow-network.");
+    }
+    return { allowNetwork, allowLocalNetwork };
+}
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--runtime --sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--runtime --sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime --sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime --sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr("Corpus quality regression: codex-plugin-doctor doctor corpus metrics diff --before <metrics.json> --after <metrics.json> [--fail-on-regression] [--json|--markdown] [--output <path>]");
     io.writeStderr("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
     io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
@@ -647,17 +680,68 @@ async function executeSuppressCommand(command, io, options = {}) {
 }
 function buildGenericMcpDoctorCommandArgs(commandTarget, flags) {
     if (!commandTarget || commandTarget.startsWith("--")) {
-        return "Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]";
+        return "Missing target path. Usage: codex-plugin-doctor mcp <path> [--runtime] [--json] [--output <path>]";
     }
-    const outputIndex = flags.indexOf("--output");
-    const outputPath = outputIndex === -1 ? null : flags[outputIndex + 1];
-    if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
-        return "Missing path after --output.";
+    let jsonOutput = false;
+    let outputPath = null;
+    let runtime = false;
+    let allowNetwork = false;
+    let allowLocalNetwork = false;
+    for (let index = 0; index < flags.length; index += 1) {
+        const flag = flags[index];
+        if (flag === "--runtime") {
+            if (runtime) {
+                return "Duplicate MCP flag: --runtime.";
+            }
+            runtime = true;
+            continue;
+        }
+        if (flag === "--json") {
+            if (jsonOutput) {
+                return "Duplicate MCP flag: --json.";
+            }
+            jsonOutput = true;
+            continue;
+        }
+        if (flag === "--allow-network") {
+            if (allowNetwork)
+                return "Duplicate MCP flag: --allow-network.";
+            allowNetwork = true;
+            continue;
+        }
+        if (flag === "--allow-local-network") {
+            if (allowLocalNetwork)
+                return "Duplicate MCP flag: --allow-local-network.";
+            allowLocalNetwork = true;
+            continue;
+        }
+        if (flag === "--output") {
+            if (outputPath !== null) {
+                return "Duplicate MCP flag: --output.";
+            }
+            const value = flags[index + 1];
+            if (!value || value.startsWith("--")) {
+                return "Missing path after --output.";
+            }
+            outputPath = value;
+            index += 1;
+            continue;
+        }
+        return flag.startsWith("--")
+            ? `Unknown MCP flag: ${flag}.`
+            : `Unexpected MCP argument: ${flag}.`;
+    }
+    const remoteNetwork = parseRemoteNetworkFlags(flags, runtime);
+    if (remoteNetwork instanceof CliUsageError) {
+        return remoteNetwork.message;
     }
     return {
         targetPath: commandTarget,
-        jsonOutput: flags.includes("--json"),
-        outputPath
+        jsonOutput,
+        outputPath,
+        runtime,
+        allowNetwork,
+        allowLocalNetwork
     };
 }
 function parsePerformanceThresholds(flags) {
@@ -944,6 +1028,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
             const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
                 env: terminalContext.env,
                 platform: terminalContext.platform
+            }, {
+                runtime: parsedMcpArgs.runtime,
+                allowNetwork: parsedMcpArgs.allowNetwork,
+                allowLocalNetwork: parsedMcpArgs.allowLocalNetwork
             });
             const renderedReport = parsedMcpArgs.jsonOutput
                 ? renderGenericMcpDoctorJson(report)
@@ -1185,7 +1273,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     ? null
                     : assetFlags[runtimeApprovalDigestIndex + 1];
                 const runtime = assetFlags.includes("--runtime");
+                const remoteNetwork = parseRemoteNetworkFlags(assetFlags, runtime);
                 let runtimeSandbox;
+                if (remoteNetwork instanceof CliUsageError) {
+                    io.writeStderr(remoteNetwork.message);
+                    return 2;
+                }
                 try {
                     runtimeSandbox = parseRuntimeSandbox(assetFlags);
                 }
@@ -1249,6 +1342,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     requireRuntimeApproval,
                     runtimeApprovalDigest,
                     runtime,
+                    ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+                    ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
                     ...(runtimeSandbox ? { sandbox: runtimeSandbox } : {}),
                     environment: {
                         env: terminalContext.env,
@@ -1257,6 +1352,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     runCheck: options.runCheckImpl ?? runCheck,
                     performanceThresholds: parsedThresholds.thresholds
                 });
+                if (!evidence.releaseReady) {
+                    io.writeStdout(jsonOutput ? renderDoctorReleaseEvidenceJson(evidence) : renderDoctorReleaseEvidence(evidence));
+                    return evidence.exitCode;
+                }
                 await writeFile(resolvedOutputPath, renderDoctorReleaseEvidenceJson(evidence), "utf8");
                 let uploaded = false;
                 const uploadArgs = ["release", "upload", tag, resolvedOutputPath, "--clobber"];
@@ -1354,7 +1453,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 ? null
                 : evidenceFlags[runtimeApprovalDigestIndex + 1];
             const runtime = evidenceFlags.includes("--runtime");
+            const remoteNetwork = parseRemoteNetworkFlags(evidenceFlags, runtime);
             let runtimeSandbox;
+            if (remoteNetwork instanceof CliUsageError) {
+                io.writeStderr(remoteNetwork.message);
+                return 2;
+            }
             try {
                 runtimeSandbox = parseRuntimeSandbox(evidenceFlags);
             }
@@ -1401,6 +1505,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 requireRuntimeApproval,
                 runtimeApprovalDigest,
                 runtime,
+                ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+                ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
                 ...(runtimeSandbox ? { sandbox: runtimeSandbox } : {}),
                 environment: {
                     env: terminalContext.env,
@@ -2223,6 +2329,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const report = await buildGenericMcpDoctor(parsedMcpArgs.targetPath, {
             env: terminalContext.env,
             platform: terminalContext.platform
+        }, {
+            runtime: parsedMcpArgs.runtime,
+            allowNetwork: parsedMcpArgs.allowNetwork,
+            allowLocalNetwork: parsedMcpArgs.allowLocalNetwork
         });
         const renderedReport = parsedMcpArgs.jsonOutput
             ? renderGenericMcpDoctorJson(report)
@@ -2499,7 +2609,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
             : remainingArgs.slice(1);
         const jsonOutput = releaseFlags.includes("--json");
         const runtimeProbeEnabled = releaseFlags.includes("--runtime");
+        const remoteNetwork = parseRemoteNetworkFlags(releaseFlags, runtimeProbeEnabled);
         let runtimeSandbox;
+        if (remoteNetwork instanceof CliUsageError) {
+            io.writeStderr(remoteNetwork.message);
+            return 2;
+        }
         try {
             runtimeSandbox = parseRuntimeSandbox(releaseFlags);
         }
@@ -2536,6 +2651,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
             env: terminalContext.env,
             platform: terminalContext.platform,
             runtime: runtimeProbeEnabled,
+            ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+            ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
             ...(runtimeSandbox ? { runtimeSandbox } : {}),
             runCheck: options.runCheckImpl
         });
@@ -2682,6 +2799,11 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const effectiveRuntimeProbeEnabled = runtimeProbeEnabled ||
         checkProfile === "publish" ||
         policyEnablesRuntime(policy);
+    const remoteNetwork = parseRemoteNetworkFlags(normalizedFlags, effectiveRuntimeProbeEnabled);
+    if (remoteNetwork instanceof CliUsageError) {
+        io.writeStderr(remoteNetwork.message);
+        return 2;
+    }
     if (requireRuntimeApproval && !effectiveRuntimeProbeEnabled) {
         io.writeStderr("Runtime approval requires runtime probing. Add --runtime, --profile publish, or a runtime-enabled policy.");
         return 2;
@@ -2743,6 +2865,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 plugin,
                 result: applyDoctorConfig(await runCheckImpl(plugin.rootPath, {
                     runtime: effectiveRuntimeProbeEnabled,
+                    ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+                    ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
                     runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
                         ? (line) => io.writeStderr(line)
                         : undefined
@@ -2812,7 +2936,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     continue;
                 }
                 const pluginResult = applyDoctorConfig(await runCheckImpl(pluginRoot, {
-                    runtime: effectiveRuntimeProbeEnabled
+                    runtime: effectiveRuntimeProbeEnabled,
+                    ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+                    ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {})
                 }), applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(pluginRoot, configPath), checkProfile), policy));
                 io.writeStdout(`\n${pluginResult.targetPath}: ${pluginResult.status.toUpperCase()}`);
                 validatedCount += 1;
@@ -2834,6 +2960,8 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const doctorConfig = applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy);
     const configuredResult = applyDoctorConfig(await runCheckImpl(targetPath, {
         runtime: effectiveRuntimeProbeEnabled,
+        ...(remoteNetwork.allowNetwork ? { allowNetwork: true } : {}),
+        ...(remoteNetwork.allowLocalNetwork ? { allowLocalNetwork: true } : {}),
         ...(runtimeSandbox ? { runtimeSandbox } : {}),
         ...(effectiveRuntimeProbeEnabled && verboseRuntime
             ? { runtimeTranscript: (line) => io.writeStderr(line) }

package/dist/security/security-audit.js

@@ -2,6 +2,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "../core/discover-package.js";
 import { readJsonFile } from "../core/read-json-file.js";
+import { inspectRemoteMcpUrl } from "../core/remote-url-policy.js";
 import { validatePlugin } from "../core/validate-plugin.js";
 import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { formatFindingEvidenceLine } from "../reporting/format-finding-evidence.js";
@@ -18,6 +19,16 @@ function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function remoteUrlIssueFindingId(issue) {
+    return issue === "insecure_non_loopback"
+        ? "plugin.security.insecure_http_url"
+        : `plugin.security.remote_mcp_url.${issue}`;
+}
+function remoteUrlIssueMessage(issue) {
+    return issue === "insecure_non_loopback"
+        ? "uses an insecure public HTTP URL"
+        : `uses a remote MCP URL with ${issue.replaceAll("_", " ")}`;
+}
 function isPathWithinRoot(rootPath, candidatePath) {
     const relativePath = path.relative(rootPath, candidatePath);
     return (relativePath === "" ||
@@ -245,19 +256,33 @@ export function auditMcpServerConfig(rootPath, parsedConfig, options = {}) {
                 }));
             }
         }
-        if (typeof url === "string" && /^http:\/\//i.test(url)) {
-            findings.push(buildFinding("warn", "plugin.security.insecure_http_url", `The MCP server \`${serverName}\` uses an insecure HTTP URL.`, "Plain HTTP transports can expose MCP traffic on non-local networks and make endpoint identity harder to verify.", "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints.", { serverName, configPath, url }));
-        }
-        if (typeof url === "string" && /\/\/0\.0\.0\.0[:/]/i.test(url)) {
-            findings.push(buildFinding("warn", "plugin.security.mcp_binds_all_interfaces", `The MCP server \`${serverName}\` URL binds to \`0.0.0.0\`.`, "Servers that listen on all interfaces can accept connections from external hosts, which is rarely intended for local MCP development.", "Use `127.0.0.1` or `localhost` instead of `0.0.0.0` unless external access is explicitly required.", { serverName, configPath, url }));
+        if (typeof url === "string") {
+            const inspection = inspectRemoteMcpUrl(url);
+            for (const issue of inspection.issues) {
+                findings.push(buildFinding("fail", remoteUrlIssueFindingId(issue), `The MCP server \`${serverName}\` ${remoteUrlIssueMessage(issue)}.`, "Unsafe or ambiguous remote transport configuration can expose credentials or prevent reliable MCP connectivity.", "Use an absolute HTTPS URL without credentials, query parameters, fragments, or numeric IP literals; HTTP is only supported for localhost development.", {
+                    serverName,
+                    configPath,
+                    url: inspection.sanitizedUrl
+                }));
+            }
+            if (inspection.parsedUrl?.hostname === "0.0.0.0") {
+                findings.push(buildFinding("warn", "plugin.security.mcp_binds_all_interfaces", `The MCP server \`${serverName}\` URL binds to \`0.0.0.0\`.`, "Servers that listen on all interfaces can accept connections from external hosts, which is rarely intended for local MCP development.", "Use `127.0.0.1` or `localhost` instead of `0.0.0.0` unless external access is explicitly required.", {
+                    serverName,
+                    configPath,
+                    url: inspection.sanitizedUrl
+                }));
+            }
         }
     }
     return findings;
 }
 const externalUrlPattern = /https?:\/\/[^\s`"'<>)]+/gi;
-async function auditSkillExternalReferences(rootPath) {
+async function auditSkillExternalReferences(rootPath, mcpConfigPath) {
     const findings = [];
     for (const filePath of await collectPromptPoisoningScanFiles(rootPath)) {
+        if (mcpConfigPath !== null && path.resolve(filePath) === mcpConfigPath) {
+            continue;
+        }
         const content = await readFile(filePath, "utf8");
         const matches = content.match(externalUrlPattern);
         if (!matches) {
@@ -422,7 +447,9 @@ export async function buildSecurityAudit(targetPath) {
         ...(await auditMcpCommandSurface(discoveredPackage)),
         ...(await auditChildProcessSourceSurface(discoveredPackage.rootPath)),
         ...(await auditPromptPoisoningSurface(discoveredPackage.rootPath)),
-        ...(await auditSkillExternalReferences(discoveredPackage.rootPath))
+        ...(await auditSkillExternalReferences(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers
+            ? path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers)
+            : null))
     ];
     return buildSecurityAuditFromFindings(discoveredPackage.rootPath, findings);
 }