codex-plugin-doctor 0.10.1 → 0.12.0

package/README.md

@@ -33,7 +33,7 @@ This tool gives plugin authors a repeatable preflight check before distribution.
 
 ## What It Checks
 
-Static validation:
+Static validation:
 
 - required `.codex-plugin/plugin.json`
 - manifest fields: `name`, `version`, `description`
@@ -42,10 +42,18 @@ Static validation:
 - YAML single-line and block-scalar skill descriptions
 - `.mcp.json` structure
 - path traversal risks
-- hard-coded secret-like env values
-- description quality heuristics tuned against real plugin packages
-
-Runtime MCP validation with `--runtime`:
+- hard-coded secret-like env values
+- description quality heuristics tuned against real plugin packages
+
+Security scorecard with `security`:
+
+- shell wrapper command warnings for MCP servers
+- encoded shell command failures
+- remote content piped into shell failures
+- MCP server `cwd` paths that escape the package root
+- plain HTTP remote transport warnings
+
+Runtime MCP validation with `--runtime`:
 
 - `initialize`
 - `notifications/initialized`
@@ -90,9 +98,12 @@ codex-plugin-doctor list --installed
 codex-plugin-doctor check --installed
 codex-plugin-doctor check --installed --all-summary
 codex-plugin-doctor check --installed --compat --all-summary
+codex-plugin-doctor audit --installed --security --compat
+codex-plugin-doctor audit --installed --security --compat --policy security
+codex-plugin-doctor mcp path/to/mcp-package
 codex-plugin-doctor check --installed github
-codex-plugin-doctor explain plugin.manifest.missing
-```
+codex-plugin-doctor explain plugin.manifest.missing
+```
 
 Run from source:
 
@@ -165,12 +176,25 @@ Run these from a Codex plugin package root:
 codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+codex-plugin-doctor doctor snapshot
+codex-plugin-doctor doctor snapshot --json
+codex-plugin-doctor doctor snapshot --output doctor-snapshot.json
 codex-plugin-doctor doctor clients
 codex-plugin-doctor doctor --update-check
+codex-plugin-doctor audit --installed
+codex-plugin-doctor audit --installed --security --compat
+codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
+codex-plugin-doctor mcp .
+codex-plugin-doctor mcp . --json
+codex-plugin-doctor mcp . --json --output mcp-doctor.json
 codex-plugin-doctor init my-plugin
 codex-plugin-doctor init my-mcp --template mcp-stdio
 codex-plugin-doctor init remote-mcp --template mcp-http
 codex-plugin-doctor init runtime-demo --template full-runtime
+codex-plugin-doctor security .
+codex-plugin-doctor security . --scorecard
+codex-plugin-doctor security . --json
+codex-plugin-doctor security . --policy security
 codex-plugin-doctor compat .
 codex-plugin-doctor compat . --all --scorecard
 codex-plugin-doctor compat . --client codex
@@ -190,6 +214,9 @@ codex-plugin-doctor check .
 codex-plugin-doctor check . --profile ci
 codex-plugin-doctor check . --profile strict
 codex-plugin-doctor check . --profile publish
+codex-plugin-doctor check . --policy codex-publish
+codex-plugin-doctor check . --policy mcp-strict
+codex-plugin-doctor check . --policy security
 codex-plugin-doctor check . --json
 codex-plugin-doctor check . --explain
 codex-plugin-doctor check . --json --output report.json
@@ -213,10 +240,18 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+
+`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report.
+
+`--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
+
+`mcp <path>` diagnoses generic MCP packages that may not have a Codex plugin manifest. It looks for `.mcp.json` or a manifest `mcpServers` reference, validates the top-level `mcpServers` object and server transports, adds MCP command-surface security findings, and includes the all-client compatibility matrix in the same report.
 
 `init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
+`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Use `--json` for automation or `--scorecard` for a compact status view.
+
 `compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
 
 `compat --client cursor` checks whether the MCP package can be added to Cursor. It prefers a project-level `.cursor/mcp.json` when one already exists in the target package, then falls back to the global `~/.cursor/mcp.json` path. A valid existing config returns `PASS`, a missing Cursor config returns `WARN`, malformed JSON returns `FAIL`, and duplicate MCP server names return `WARN`. Add `--install-preview` to print the JSON snippet that should be merged into Cursor's `mcp.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.

package/dist/audit/ecosystem-audit.d.ts

@@ -0,0 +1,36 @@
+import type { CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+import type { CheckResult } from "../domain/types.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+export interface EcosystemAuditOptions {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    filter?: string | null;
+    includeSecurity?: boolean;
+    includeCompatibility?: boolean;
+    failOnWarnings?: boolean;
+    validatePlugin: (targetPath: string) => Promise<CheckResult>;
+}
+export interface EcosystemAuditPluginResult {
+    plugin: InstalledPlugin;
+    status: "pass" | "warn" | "fail";
+    validation: CheckResult;
+    security?: SecurityAudit;
+    compatibility?: CompatibilityMatrix;
+}
+export interface EcosystemAuditReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    status: "pass" | "warn" | "fail";
+    summary: {
+        totalPlugins: number;
+        pass: number;
+        warn: number;
+        fail: number;
+    };
+    plugins: EcosystemAuditPluginResult[];
+    priorityActions: string[];
+}
+export declare function buildEcosystemAudit(options: EcosystemAuditOptions): Promise<EcosystemAuditReport>;
+export declare function renderEcosystemAuditJson(report: EcosystemAuditReport): string;
+export declare function renderEcosystemAudit(report: EcosystemAuditReport): string;

package/dist/audit/ecosystem-audit.js

@@ -0,0 +1,135 @@
+import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { discoverInstalledPlugins, filterInstalledPlugins } from "../core/discover-installed-plugins.js";
+import { buildSecurityAudit } from "../security/security-audit.js";
+function mergeStatus(statuses) {
+    if (statuses.includes("fail")) {
+        return "fail";
+    }
+    if (statuses.includes("warn")) {
+        return "warn";
+    }
+    return "pass";
+}
+function compatibilityStatus(matrix) {
+    if (!matrix) {
+        return "pass";
+    }
+    if (matrixExitCode(matrix) === 1) {
+        return "fail";
+    }
+    return matrix.results.some((result) => result.status === "warn") ? "warn" : "pass";
+}
+function summarizePlugins(plugins) {
+    return {
+        totalPlugins: plugins.length,
+        pass: plugins.filter((plugin) => plugin.status === "pass").length,
+        warn: plugins.filter((plugin) => plugin.status === "warn").length,
+        fail: plugins.filter((plugin) => plugin.status === "fail").length
+    };
+}
+function buildPriorityActions(plugins) {
+    const actions = [];
+    const cleanReason = (reason) => reason.replace(/[.。]+$/u, "");
+    for (const plugin of plugins.filter((item) => item.status === "fail")) {
+        const validationFinding = plugin.validation.findings[0];
+        const securityFinding = plugin.security?.findings[0];
+        const compatibilityFinding = plugin.compatibility?.results.find((result) => result.status === "fail");
+        const reason = validationFinding?.id ??
+            securityFinding?.id ??
+            compatibilityFinding?.summary ??
+            "unknown failure";
+        actions.push(`${plugin.plugin.name}: fix ${cleanReason(reason)}.`);
+    }
+    for (const plugin of plugins.filter((item) => item.status === "warn")) {
+        const securityFinding = plugin.security?.findings[0];
+        const compatibilityFinding = plugin.compatibility?.results.find((result) => result.status === "warn");
+        const reason = securityFinding?.id ??
+            compatibilityFinding?.summary ??
+            plugin.validation.findings[0]?.id ??
+            "warning";
+        actions.push(`${plugin.plugin.name}: review ${cleanReason(reason)}.`);
+    }
+    return actions;
+}
+export async function buildEcosystemAudit(options) {
+    const installedPlugins = filterInstalledPlugins(await discoverInstalledPlugins({ env: options.env }), options.filter ?? null);
+    const environment = {
+        env: options.env,
+        platform: options.platform
+    };
+    const plugins = [];
+    for (const plugin of installedPlugins) {
+        const validation = await options.validatePlugin(plugin.rootPath);
+        const security = options.includeSecurity
+            ? await buildSecurityAudit(plugin.rootPath)
+            : undefined;
+        const compatibility = options.includeCompatibility
+            ? await buildCompatibilityMatrix(plugin.rootPath, environment)
+            : undefined;
+        const rawStatus = mergeStatus([
+            validation.status,
+            security?.status ?? "pass",
+            compatibilityStatus(compatibility)
+        ]);
+        const status = options.failOnWarnings && rawStatus === "warn"
+            ? "fail"
+            : rawStatus;
+        plugins.push({
+            plugin,
+            status,
+            validation,
+            ...(security ? { security } : {}),
+            ...(compatibility ? { compatibility } : {})
+        });
+    }
+    const summary = summarizePlugins(plugins);
+    const status = summary.fail > 0
+        ? "fail"
+        : summary.warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        status,
+        summary,
+        plugins,
+        priorityActions: buildPriorityActions(plugins)
+    };
+}
+export function renderEcosystemAuditJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderEcosystemAudit(report) {
+    const lines = [
+        "Local Ecosystem Audit",
+        "=====================",
+        `Status: ${report.status.toUpperCase()}`,
+        `Installed plugins: ${report.summary.totalPlugins}`,
+        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`
+    ];
+    if (report.plugins.length === 0) {
+        lines.push("", "No installed Codex plugins found.");
+        return lines.join("\n");
+    }
+    lines.push("", "Plugins", "-------");
+    for (const item of report.plugins) {
+        const version = item.plugin.version ? `@${item.plugin.version}` : "";
+        lines.push(`- ${item.plugin.name}${version}: ${item.status.toUpperCase()}`);
+        lines.push(`  Validation: ${item.validation.status.toUpperCase()}`);
+        if (item.security) {
+            lines.push(`  Security: ${item.security.status.toUpperCase()} (${item.security.score}/100)`);
+        }
+        if (item.compatibility) {
+            const compatibilitySummary = item.compatibility.results
+                .map((result) => `${result.client}=${result.status}`)
+                .join(", ");
+            lines.push(`  Compatibility: ${compatibilitySummary}`);
+        }
+    }
+    if (report.priorityActions.length > 0) {
+        lines.push("", "Priority Actions", "----------------");
+        lines.push(...report.priorityActions.map((action) => `- ${action}`));
+    }
+    return lines.join("\n");
+}

package/dist/core/doctor-snapshot.d.ts

@@ -0,0 +1,20 @@
+import type { CliTerminalContext } from "../run-cli.js";
+import { type ClientDoctorResult, type EnvironmentDoctorReport } from "./environment-doctor.js";
+import { type InstalledPlugin } from "./discover-installed-plugins.js";
+export interface DoctorSnapshot {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    version: string;
+    environment: EnvironmentDoctorReport;
+    clients: ClientDoctorResult[];
+    installedPlugins: {
+        count: number;
+        plugins: InstalledPlugin[];
+    };
+    recommendations: string[];
+}
+export declare function buildDoctorSnapshot(terminalContext: CliTerminalContext): Promise<DoctorSnapshot>;
+export declare function renderDoctorSnapshotJson(snapshot: DoctorSnapshot): string;
+export declare function renderDoctorSnapshot(snapshot: DoctorSnapshot, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/doctor-snapshot.js

@@ -0,0 +1,66 @@
+import { buildClientDoctorReport, buildEnvironmentDoctorReport } from "./environment-doctor.js";
+import { discoverInstalledPlugins } from "./discover-installed-plugins.js";
+import { packageVersion } from "../version.js";
+export async function buildDoctorSnapshot(terminalContext) {
+    const [environment, clients, installedPlugins] = await Promise.all([
+        buildEnvironmentDoctorReport(terminalContext),
+        buildClientDoctorReport(terminalContext),
+        discoverInstalledPlugins({ env: terminalContext.env })
+    ]);
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        version: packageVersion,
+        environment,
+        clients,
+        installedPlugins: {
+            count: installedPlugins.length,
+            plugins: installedPlugins
+        },
+        recommendations: [
+            "codex-plugin-doctor self-test",
+            "codex-plugin-doctor list --installed",
+            "codex-plugin-doctor check --installed --all-summary",
+            "codex-plugin-doctor compat . --all --scorecard"
+        ]
+    };
+}
+export function renderDoctorSnapshotJson(snapshot) {
+    return JSON.stringify(snapshot, null, 2);
+}
+export function renderDoctorSnapshot(snapshot, options = {}) {
+    const passClients = snapshot.clients.filter((client) => client.status === "pass").length;
+    const warnClients = snapshot.clients.filter((client) => client.status === "warn").length;
+    const lines = [
+        "Codex Plugin Doctor Snapshot",
+        "============================",
+        `Generated: ${snapshot.generatedAt}`,
+        `Version: ${snapshot.version}`,
+        `Platform: ${snapshot.environment.platform}`,
+        `Node: ${snapshot.environment.node}`,
+        `Codex home: ${snapshot.environment.codexHome.status.toUpperCase()}${snapshot.environment.codexHome.path ? ` (${snapshot.environment.codexHome.path})` : ""}`,
+        `Codex plugin cache: ${snapshot.environment.codexPluginCache.status.toUpperCase()}${snapshot.environment.codexPluginCache.path ? ` (${snapshot.environment.codexPluginCache.path})` : ""}`,
+        `Installed plugins: ${snapshot.installedPlugins.count}`,
+        `Clients: ${passClients} pass, ${warnClients} warn`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Clients", "-------");
+    for (const client of snapshot.clients) {
+        lines.push(`${client.client}: ${client.status.toUpperCase()} - ${client.summary}`);
+    }
+    lines.push("", "Installed Plugins", "-----------------");
+    if (snapshot.installedPlugins.plugins.length === 0) {
+        lines.push("No installed Codex plugins found.");
+    }
+    else {
+        for (const plugin of snapshot.installedPlugins.plugins) {
+            const version = plugin.version ? `@${plugin.version}` : "";
+            lines.push(`- ${plugin.name}${version} (${plugin.relativePath})`);
+        }
+    }
+    lines.push("", "Recommended Next Commands", "-------------------------");
+    lines.push(...snapshot.recommendations);
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -1,2 +1,7 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
+export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
+export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, type DoctorSnapshot } from "./core/doctor-snapshot.js";
+export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, type EcosystemAuditReport } from "./audit/ecosystem-audit.js";
+export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
+export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -1,4 +1,9 @@
 import { validatePlugin } from "./core/validate-plugin.js";
+export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
+export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
+export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
+export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
+export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

package/dist/mcp/generic-mcp-doctor.d.ts

@@ -0,0 +1,16 @@
+import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { Finding } from "../domain/types.js";
+import { type SecurityAudit } from "../security/security-audit.js";
+export interface GenericMcpDoctorReport {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    mcpConfigPath: string | null;
+    serverCount: number;
+    findings: Finding[];
+    security: SecurityAudit;
+    compatibility: CompatibilityMatrix;
+}
+export declare function buildGenericMcpDoctor(targetPath: string, environment?: CompatibilityEnvironment): Promise<GenericMcpDoctorReport>;
+export declare function renderGenericMcpDoctorJson(report: GenericMcpDoctorReport): string;
+export declare function renderGenericMcpDoctor(report: GenericMcpDoctorReport): string;

package/dist/mcp/generic-mcp-doctor.js

@@ -0,0 +1,166 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/compatibility-matrix.js";
+import { readJsonFile } from "../core/read-json-file.js";
+import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
+function buildFinding(severity, id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity,
+        message,
+        impact,
+        suggestedFix
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
+    if (!mcpConfigPath) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.")
+            ]
+        };
+    }
+    if (!isPlainObject(parsedConfig)) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${mcpConfigPath}\`.`)
+            ]
+        };
+    }
+    const servers = parsedConfig.mcpServers;
+    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+        return {
+            serverCount: 0,
+            findings: [
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+            ]
+        };
+    }
+    const findings = [];
+    for (const [serverName, serverConfig] of Object.entries(servers)) {
+        if (!isPlainObject(serverConfig)) {
+            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            continue;
+        }
+        if (typeof serverConfig.command !== "string" && typeof serverConfig.url !== "string") {
+            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+        }
+    }
+    return {
+        serverCount: Object.keys(servers).length,
+        findings
+    };
+}
+function mergeReportStatus(staticFindings, security) {
+    if (staticFindings.some((finding) => finding.severity === "fail") || security.status === "fail") {
+        return "fail";
+    }
+    if (staticFindings.some((finding) => finding.severity === "warn") || security.status === "warn") {
+        return "warn";
+    }
+    return "pass";
+}
+export async function buildGenericMcpDoctor(targetPath, environment = {}) {
+    const rootPath = path.resolve(targetPath);
+    const compatibility = await buildCompatibilityMatrix(rootPath, environment);
+    const mcpConfigPath = await readMcpConfigPath(rootPath);
+    let parsedConfig = null;
+    let staticFindings = [];
+    let serverCount = 0;
+    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+        staticFindings = buildStaticMcpFindings(null, null).findings;
+    }
+    else if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        staticFindings = [
+            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.")
+        ];
+    }
+    else {
+        try {
+            parsedConfig = await readJsonFile(mcpConfigPath);
+            const staticResult = buildStaticMcpFindings(mcpConfigPath, parsedConfig);
+            staticFindings = staticResult.findings;
+            serverCount = staticResult.serverCount;
+        }
+        catch {
+            staticFindings = [
+                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+            ];
+        }
+    }
+    const security = buildSecurityAuditFromFindings(rootPath, mcpConfigPath && parsedConfig !== null
+        ? auditMcpServerConfig(rootPath, parsedConfig)
+        : []);
+    const status = mergeReportStatus(staticFindings, security);
+    return {
+        targetPath: rootPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        mcpConfigPath,
+        serverCount,
+        findings: [...staticFindings, ...security.findings],
+        security,
+        compatibility
+    };
+}
+export function renderGenericMcpDoctorJson(report) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        ...report
+    }, null, 2);
+}
+export function renderGenericMcpDoctor(report) {
+    const lines = [
+        "Generic MCP Doctor",
+        "==================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `MCP config: ${report.mcpConfigPath ?? "not found"}`,
+        `Servers: ${report.serverCount}`,
+        `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,
+        `Compatibility: ${report.compatibility.results
+            .map((result) => `${result.client}=${result.status}`)
+            .join(", ")}`
+    ];
+    if (report.findings.length === 0) {
+        lines.push("", "No findings.");
+        return lines.join("\n");
+    }
+    const failures = report.findings.filter((finding) => finding.severity === "fail");
+    const warnings = report.findings.filter((finding) => finding.severity === "warn");
+    const appendFindings = (title, findings, marker) => {
+        if (findings.length === 0) {
+            return;
+        }
+        lines.push("", title, "--------");
+        for (const finding of findings) {
+            lines.push(`${marker} ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Impact: ${finding.impact}`);
+            lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+        }
+    };
+    appendFindings("Failures", failures, "x");
+    appendFindings("Warnings", warnings, "!");
+    return lines.join("\n");
+}

package/dist/policy/policy-packs.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorConfig } from "../core/doctor-config.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+export declare const policyPackNames: readonly ["codex-publish", "mcp-strict", "security"];
+export type PolicyPackName = (typeof policyPackNames)[number];
+export declare function parsePolicyPack(value: string | null): PolicyPackName | null;
+export declare function policyEnablesRuntime(policy: PolicyPackName | null): boolean;
+export declare function policyFailsOnWarnings(policy: PolicyPackName | null): boolean;
+export declare function applyPolicyToDoctorConfig(config: DoctorConfig, policy: PolicyPackName | null): DoctorConfig;
+export declare function applyPolicyToSecurityAudit(audit: SecurityAudit, policy: PolicyPackName | null): SecurityAudit;

package/dist/policy/policy-packs.js

@@ -0,0 +1,33 @@
+export const policyPackNames = ["codex-publish", "mcp-strict", "security"];
+export function parsePolicyPack(value) {
+    if (!value) {
+        return null;
+    }
+    return policyPackNames.includes(value)
+        ? value
+        : null;
+}
+export function policyEnablesRuntime(policy) {
+    return policy === "codex-publish" || policy === "mcp-strict";
+}
+export function policyFailsOnWarnings(policy) {
+    return policy !== null;
+}
+export function applyPolicyToDoctorConfig(config, policy) {
+    if (!policyFailsOnWarnings(policy)) {
+        return config;
+    }
+    return {
+        ...config,
+        failOnWarnings: true
+    };
+}
+export function applyPolicyToSecurityAudit(audit, policy) {
+    if (!policyFailsOnWarnings(policy) || audit.status !== "warn") {
+        return audit;
+    }
+    return {
+        ...audit,
+        status: "fail"
+    };
+}

package/dist/release/release-sync.d.ts

@@ -0,0 +1,24 @@
+export interface GitHubReleaseSyncState {
+    tagName: string;
+    isDraft: boolean;
+    isPrerelease: boolean;
+}
+export interface ReleaseSyncEvaluationInput {
+    version: string;
+    npmVersion: string;
+    remoteTagOutput: string;
+    githubRelease: GitHubReleaseSyncState | null;
+    latestReleaseTag: string;
+}
+export interface ReleaseSyncCheck {
+    id: string;
+    status: "pass" | "fail";
+    message: string;
+}
+export interface ReleaseSyncReport {
+    version: string;
+    status: "pass" | "fail";
+    checks: ReleaseSyncCheck[];
+}
+export declare function evaluateReleaseSync(input: ReleaseSyncEvaluationInput): ReleaseSyncReport;
+export declare function renderReleaseSyncReport(report: ReleaseSyncReport): string;

package/dist/release/release-sync.js

@@ -0,0 +1,46 @@
+function buildCheck(id, status, message) {
+    return {
+        id,
+        status,
+        message
+    };
+}
+export function evaluateReleaseSync(input) {
+    const expectedTag = `v${input.version}`;
+    const checks = [];
+    checks.push(input.npmVersion === input.version
+        ? buildCheck("npm.version", "pass", `npm latest is ${input.version}.`)
+        : buildCheck("npm.version", "fail", `npm latest is ${input.npmVersion || "missing"}, expected ${input.version}.`));
+    checks.push(input.remoteTagOutput.includes(`refs/tags/${expectedTag}`)
+        ? buildCheck("git.remote_tag", "pass", `Remote tag ${expectedTag} exists.`)
+        : buildCheck("git.remote_tag", "fail", `Remote tag ${expectedTag} is missing.`));
+    const releaseMatches = input.githubRelease?.tagName === expectedTag &&
+        !input.githubRelease.isDraft &&
+        !input.githubRelease.isPrerelease;
+    checks.push(releaseMatches
+        ? buildCheck("github.release", "pass", `GitHub release ${expectedTag} is published.`)
+        : buildCheck("github.release", "fail", input.githubRelease
+            ? `GitHub release state is tag=${input.githubRelease.tagName}, draft=${input.githubRelease.isDraft}, prerelease=${input.githubRelease.isPrerelease}; expected published ${expectedTag}.`
+            : `GitHub release ${expectedTag} is missing.`));
+    checks.push(input.latestReleaseTag === expectedTag
+        ? buildCheck("github.latest_release", "pass", `GitHub latest release is ${expectedTag}.`)
+        : buildCheck("github.latest_release", "fail", `GitHub latest release is ${input.latestReleaseTag || "missing"}, expected ${expectedTag}.`));
+    return {
+        version: input.version,
+        status: checks.some((check) => check.status === "fail") ? "fail" : "pass",
+        checks
+    };
+}
+export function renderReleaseSyncReport(report) {
+    const lines = [
+        "Release Sync Verification",
+        "=========================",
+        `Version: ${report.version}`,
+        `Status: ${report.status.toUpperCase()}`
+    ];
+    for (const check of report.checks) {
+        lines.push("", `${check.status === "pass" ? "ok" : "x"} ${check.id}`);
+        lines.push(`  ${check.message}`);
+    }
+    return lines.join("\n");
+}

package/dist/rules/rule-catalog.js

@@ -161,6 +161,60 @@ export const ruleCatalog = [
         fix: "Replace literal secrets with environment references or externally injected secrets.",
         example: '{ "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }'
     },
+    {
+        id: "plugin.security.audit_unavailable",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "The security audit could not inspect the package surface.",
+        why: "A missing manifest or unreadable MCP configuration prevents the tool from evaluating package-local execution risks.",
+        fix: "Run against a valid Codex plugin root and fix `.mcp.json` syntax or shape errors before auditing.",
+        example: "codex-plugin-doctor security examples/codex-doctor-runtime"
+    },
+    {
+        id: "plugin.security.command_shell_wrapper",
+        category: "security",
+        defaultSeverity: "warn",
+        summary: "An MCP server starts through a shell wrapper.",
+        why: "Shell wrappers can hide quoting, pipes, aliases, and platform-specific execution behavior from reviewers.",
+        fix: "Launch the concrete executable directly with explicit args.",
+        example: '{ "command": "node", "args": ["server.js"] }'
+    },
+    {
+        id: "plugin.security.encoded_command",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server uses an encoded shell command.",
+        why: "Encoded payloads hide the executed script and make supply-chain review unreliable.",
+        fix: "Replace encoded command payloads with a checked-in script or direct executable plus readable args.",
+        example: '{ "command": "node", "args": ["scripts/server.js"] }'
+    },
+    {
+        id: "plugin.security.remote_pipe_install",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server pipes remote content into a shell.",
+        why: "Download-and-execute startup patterns can run unreviewed remote code as soon as a client starts the server.",
+        fix: "Pin dependencies through a package manager or check in a reviewed setup script.",
+        example: '{ "command": "npx", "args": ["-y", "@scope/server"] }'
+    },
+    {
+        id: "plugin.security.cwd_outside_root",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server sets `cwd` outside the plugin root.",
+        why: "External working directories make startup depend on local files that are not part of the reviewed package.",
+        fix: "Keep `cwd` inside the plugin root or remove it.",
+        example: '{ "cwd": "." }'
+    },
+    {
+        id: "plugin.security.insecure_http_url",
+        category: "security",
+        defaultSeverity: "warn",
+        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.runtime.exited_early",
         category: "runtime",

package/dist/run-cli.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
+import { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 import { appendValidationHistoryEntry, readValidationHistory, summarizeValidationHistory } from "./core/validation-history.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
 import { applyInstallPreview, renderApplyInstallResult } from "./compatibility/apply-install-preview.js";
@@ -12,11 +13,13 @@ import { buildCursorInstallPreview, renderCursorInstallPreview } from "./compati
 import { buildClineInstallPreview, renderClineInstallPreview } from "./compatibility/cline-install-preview.js";
 import { buildWindsurfInstallPreview, renderWindsurfInstallPreview } from "./compatibility/windsurf-install-preview.js";
 import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
+import { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
 import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { initCiWorkflow } from "./core/init-ci.js";
 import { initPluginPackage, initPluginTemplates, isInitPluginTemplate } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
+import { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
 import { renderInstalledSummary } from "./reporting/render-installed-summary.js";
 import { renderBadgeJson, renderBadgeMarkdown } from "./reporting/render-badge-report.js";
 import { renderCompatibilityScorecard } from "./reporting/render-compatibility-scorecard.js";
@@ -27,7 +30,9 @@ import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
 import { renderSarifReport } from "./reporting/render-sarif-report.js";
 import { renderTextReport } from "./reporting/render-text-report.js";
+import { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 import { findRuleDefinition } from "./rules/rule-catalog.js";
+import { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
 import { determineOutputPolicy } from "./terminal/output-policy.js";
 import { getSpinner } from "./terminal/spinner-registry.js";
@@ -53,7 +58,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\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 doctor [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 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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [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 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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -186,6 +191,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const doctorFlags = maybePath?.startsWith("--")
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
+        if (maybePath === "snapshot") {
+            const jsonOutput = doctorFlags.includes("--json");
+            const outputIndex = doctorFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : doctorFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const snapshot = await buildDoctorSnapshot(terminalContext);
+            const snapshotJson = renderDoctorSnapshotJson(snapshot);
+            if (outputPath) {
+                await writeFile(outputPath, snapshotJson, "utf8");
+            }
+            io.writeStdout(jsonOutput
+                ? snapshotJson
+                : renderDoctorSnapshot(snapshot, { outputPath }));
+            return 0;
+        }
         if (doctorFlags.includes("--update-check")) {
             const latestVersion = await (options.resolveLatestVersion ?? resolveLatestNpmVersion)();
             io.writeStdout(renderUpdateCheck(latestVersion));
@@ -352,6 +375,114 @@ export async function runCli(args, io = defaultIo, options = {}) {
             : renderApplyFixResult(result));
         return 0;
     }
+    if (command === "security") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing target path. Usage: codex-plugin-doctor security <path> [--json|--scorecard]");
+            return 2;
+        }
+        const jsonOutput = remainingArgs.includes("--json");
+        const scorecardOutput = remainingArgs.includes("--scorecard");
+        const policyIndex = remainingArgs.indexOf("--policy");
+        const policyName = policyIndex === -1 ? null : remainingArgs[policyIndex + 1];
+        const policy = parsePolicyPack(policyName);
+        if (jsonOutput && scorecardOutput) {
+            io.writeStderr("Use either --json or --scorecard, not both.");
+            return 2;
+        }
+        if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+            io.writeStderr("Missing policy after --policy.");
+            return 2;
+        }
+        if (policyIndex !== -1 && !policy) {
+            io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+            return 2;
+        }
+        const audit = applyPolicyToSecurityAudit(await buildSecurityAudit(maybePath), policy);
+        io.writeStdout(jsonOutput
+            ? renderSecurityAuditJson(audit)
+            : renderSecurityScorecard(audit, { includeFindings: !scorecardOutput }));
+        return audit.status === "fail" ? 1 : 0;
+    }
+    if (command === "mcp") {
+        if (!maybePath || maybePath.startsWith("--")) {
+            io.writeStderr("Missing target path. Usage: codex-plugin-doctor mcp <path> [--json] [--output <path>]");
+            return 2;
+        }
+        const jsonOutput = remainingArgs.includes("--json");
+        const outputIndex = remainingArgs.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        const report = await buildGenericMcpDoctor(maybePath, {
+            env: terminalContext.env,
+            platform: terminalContext.platform
+        });
+        const renderedReport = jsonOutput
+            ? renderGenericMcpDoctorJson(report)
+            : renderGenericMcpDoctor(report);
+        if (outputPath) {
+            await writeFile(outputPath, renderedReport, "utf8");
+        }
+        io.writeStdout(renderedReport);
+        return report.exitCode;
+    }
+    if (command === "audit") {
+        const auditFlags = maybePath ? [maybePath, ...remainingArgs] : remainingArgs;
+        const installed = auditFlags.includes("--installed");
+        if (!installed) {
+            io.writeStderr("Usage: codex-plugin-doctor audit --installed [filter] [--security] [--compat] [--json] [--output <path>]");
+            return 2;
+        }
+        const installedIndex = auditFlags.indexOf("--installed");
+        const installedFilter = auditFlags[installedIndex + 1] && !auditFlags[installedIndex + 1].startsWith("--")
+            ? auditFlags[installedIndex + 1]
+            : null;
+        const jsonOutput = auditFlags.includes("--json");
+        const includeSecurity = auditFlags.includes("--security");
+        const includeCompatibility = auditFlags.includes("--compat");
+        const outputIndex = auditFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : auditFlags[outputIndex + 1];
+        const policyIndex = auditFlags.indexOf("--policy");
+        const policyName = policyIndex === -1 ? null : auditFlags[policyIndex + 1];
+        const policy = parsePolicyPack(policyName);
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+            io.writeStderr("Missing policy after --policy.");
+            return 2;
+        }
+        if (policyIndex !== -1 && !policy) {
+            io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+            return 2;
+        }
+        const report = await buildEcosystemAudit({
+            env: terminalContext.env,
+            platform: terminalContext.platform,
+            filter: installedFilter,
+            includeSecurity,
+            includeCompatibility,
+            failOnWarnings: policyFailsOnWarnings(policy),
+            validatePlugin: options.runCheckImpl ?? runCheck
+        });
+        if (report.summary.totalPlugins === 0) {
+            io.writeStderr(installedFilter
+                ? `No installed Codex plugins matched '${installedFilter}'.`
+                : "No installed Codex plugins found.");
+            return 1;
+        }
+        const renderedReport = jsonOutput
+            ? renderEcosystemAuditJson(report)
+            : renderEcosystemAudit(report);
+        if (outputPath) {
+            await writeFile(outputPath, renderedReport, "utf8");
+        }
+        io.writeStdout(renderedReport);
+        return report.status === "fail" ? 1 : 0;
+    }
     if (command === "compat") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
         const compatFlags = maybePath && maybePath.startsWith("--")
@@ -503,6 +634,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
     const profileIndex = normalizedFlags.indexOf("--profile");
     const profileName = profileIndex === -1 ? null : normalizedFlags[profileIndex + 1];
     const checkProfile = parseCheckProfile(profileName);
+    const policyIndex = normalizedFlags.indexOf("--policy");
+    const policyName = policyIndex === -1 ? null : normalizedFlags[policyIndex + 1];
+    const policy = parsePolicyPack(policyName);
     const historyIndex = normalizedFlags.indexOf("--history");
     const historyPath = historyIndex === -1 ? null : normalizedFlags[historyIndex + 1];
     if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
@@ -521,6 +655,14 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Unknown profile. Supported profiles: ci, strict, publish.");
         return 2;
     }
+    if (policyIndex !== -1 && (!policyName || policyName.startsWith("--"))) {
+        io.writeStderr("Missing policy after --policy.");
+        return 2;
+    }
+    if (policyIndex !== -1 && !policy) {
+        io.writeStderr(`Unknown policy: ${policyName}. Supported policies: ${policyPackNames.join(", ")}.`);
+        return 2;
+    }
     if (historyIndex !== -1 && (!historyPath || historyPath.startsWith("--"))) {
         io.writeStderr("Missing path after --history.");
         return 2;
@@ -533,7 +675,9 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("History output requires a single package target.");
         return 2;
     }
-    const effectiveRuntimeProbeEnabled = runtimeProbeEnabled || checkProfile === "publish";
+    const effectiveRuntimeProbeEnabled = runtimeProbeEnabled ||
+        checkProfile === "publish" ||
+        policyEnablesRuntime(policy);
     const outputPolicy = determineOutputPolicy({
         jsonOutput: jsonOutput || badgeJsonOutput,
         markdownOutput: markdownOutput || badgeMarkdownOutput,
@@ -569,7 +713,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
                     runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
                         ? (line) => io.writeStderr(line)
                         : undefined
-                }), applyCheckProfile(config, checkProfile)),
+                }), applyPolicyToDoctorConfig(applyCheckProfile(config, checkProfile), policy)),
                 compatibilityMatrix
             });
         }
@@ -606,7 +750,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
         runtimeTranscript: effectiveRuntimeProbeEnabled && verboseRuntime
             ? (line) => io.writeStderr(line)
             : undefined
-    }), applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile));
+    }), applyPolicyToDoctorConfig(applyCheckProfile(await loadDoctorConfig(targetPath, configPath), checkProfile), policy));
     if (renderer) {
         if (result.status === "fail") {
             renderer.stopFailure("Validation failed");

package/dist/security/security-audit.d.ts

@@ -0,0 +1,19 @@
+import type { Finding } from "../domain/types.js";
+export interface SecurityAudit {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    score: number;
+    findingCounts: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+    findings: Finding[];
+}
+export declare function auditMcpServerConfig(rootPath: string, parsedConfig: unknown): Finding[];
+export declare function buildSecurityAuditFromFindings(targetPath: string, findings: Finding[]): SecurityAudit;
+export declare function buildSecurityAudit(targetPath: string): Promise<SecurityAudit>;
+export declare function renderSecurityAuditJson(audit: SecurityAudit): string;
+export declare function renderSecurityScorecard(audit: SecurityAudit, options?: {
+    includeFindings?: boolean;
+}): string;

package/dist/security/security-audit.js

@@ -0,0 +1,199 @@
+import path from "node:path";
+import { discoverPackage } from "../core/discover-package.js";
+import { readJsonFile } from "../core/read-json-file.js";
+import { validatePlugin } from "../core/validate-plugin.js";
+function buildFinding(severity, id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity,
+        message,
+        impact,
+        suggestedFix
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function normalizeCommandName(command) {
+    return path.basename(command).toLowerCase().replace(/\.(exe|cmd|bat)$/i, "");
+}
+function isShellWrapperCommand(command) {
+    return new Set(["cmd", "powershell", "pwsh", "bash", "sh"]).has(normalizeCommandName(command));
+}
+function containsEncodedCommandFlag(args) {
+    return Array.isArray(args) && args.some((arg) => typeof arg === "string" && /^[-/]enc(odedcommand)?$/i.test(arg));
+}
+function containsPipeInstaller(args) {
+    if (!Array.isArray(args)) {
+        return false;
+    }
+    const joinedArgs = args
+        .filter((arg) => typeof arg === "string")
+        .join(" ")
+        .toLowerCase();
+    return (/\b(curl|wget)\b[^|]*\|\s*(sh|bash)\b/.test(joinedArgs) ||
+        /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
+        /\binvoke-expression\b/.test(joinedArgs));
+}
+export function auditMcpServerConfig(rootPath, parsedConfig) {
+    if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
+        return [
+            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not find a valid `mcpServers` object.", "Without server entries, the audit cannot evaluate command execution or remote transport risk.", "Define MCP servers under a top-level `mcpServers` object.")
+        ];
+    }
+    const findings = [];
+    for (const [serverName, serverConfig] of Object.entries(parsedConfig.mcpServers)) {
+        if (!isPlainObject(serverConfig)) {
+            continue;
+        }
+        const command = serverConfig.command;
+        const args = serverConfig.args;
+        const cwd = serverConfig.cwd;
+        const url = serverConfig.url;
+        if (typeof command === "string" && isShellWrapperCommand(command)) {
+            findings.push(buildFinding("warn", "plugin.security.command_shell_wrapper", `The MCP server \`${serverName}\` starts through shell wrapper \`${command}\`.`, "Shell wrappers expand quoting, pipes, aliases, and platform-specific behavior, which makes the real execution path harder to audit.", "Prefer launching the concrete executable directly with explicit args."));
+        }
+        if (containsEncodedCommandFlag(args)) {
+            findings.push(buildFinding("fail", "plugin.security.encoded_command", `The MCP server \`${serverName}\` uses an encoded shell command flag.`, "Encoded command payloads hide the executed script from reviewers and increase supply-chain risk.", "Replace encoded shell payloads with a checked-in script or direct executable plus readable args."));
+        }
+        if (containsPipeInstaller(args)) {
+            findings.push(buildFinding("fail", "plugin.security.remote_pipe_install", `The MCP server \`${serverName}\` appears to pipe remote content into a shell.`, "Download-and-execute install patterns can run unreviewed remote code during plugin startup.", "Pin dependencies through the package manager or check in a reviewed setup script instead of piping remote content to a shell."));
+        }
+        if (typeof cwd === "string") {
+            const cwdPath = path.resolve(rootPath, cwd);
+            if (!isPathWithinRoot(rootPath, cwdPath)) {
+                findings.push(buildFinding("fail", "plugin.security.cwd_outside_root", `The MCP server \`${serverName}\` sets cwd outside the plugin root.`, "A working directory outside the package root can make server startup depend on unreviewed local files.", "Keep MCP server `cwd` inside the plugin package root or remove it."));
+            }
+        }
+        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."));
+        }
+    }
+    return findings;
+}
+async function auditMcpCommandSurface(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (!manifest.mcpServers) {
+        return [];
+    }
+    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        return [];
+    }
+    let parsedConfig;
+    try {
+        parsedConfig = await readJsonFile(mcpConfigPath);
+    }
+    catch {
+        return [
+            buildFinding("fail", "plugin.security.audit_unavailable", "The MCP security audit could not parse the referenced MCP config.", "Unreadable MCP configuration prevents review of server commands, URLs, and working directories before install.", "Fix the `.mcp.json` syntax, then rerun `codex-plugin-doctor security <path>`.")
+        ];
+    }
+    return auditMcpServerConfig(rootPath, parsedConfig);
+}
+function dedupeFindings(findings) {
+    const seen = new Set();
+    return findings.filter((finding) => {
+        const key = `${finding.id}\n${finding.message}`;
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+function buildFindingCounts(findings) {
+    const fail = findings.filter((finding) => finding.severity === "fail").length;
+    const warn = findings.filter((finding) => finding.severity === "warn").length;
+    return {
+        fail,
+        warn,
+        total: findings.length
+    };
+}
+function scoreSecurityAudit(findingCounts) {
+    return Math.max(0, 100 - (findingCounts.fail * 35) - (findingCounts.warn * 10));
+}
+export function buildSecurityAuditFromFindings(targetPath, findings) {
+    const dedupedFindings = dedupeFindings(findings);
+    const findingCounts = buildFindingCounts(dedupedFindings);
+    const status = findingCounts.fail > 0
+        ? "fail"
+        : findingCounts.warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        targetPath: path.resolve(targetPath),
+        status,
+        score: scoreSecurityAudit(findingCounts),
+        findingCounts,
+        findings: dedupedFindings
+    };
+}
+export async function buildSecurityAudit(targetPath) {
+    const discoveredPackage = await discoverPackage(targetPath);
+    if (!discoveredPackage) {
+        const findings = [
+            buildFinding("fail", "plugin.security.audit_unavailable", "The target directory is missing `.codex-plugin/plugin.json`, so the package security audit cannot run.", "Without a Codex plugin manifest, the audit cannot resolve packaged skills or MCP server configuration safely.", "Run the audit against a Codex plugin package root.")
+        ];
+        const findingCounts = buildFindingCounts(findings);
+        return {
+            targetPath: path.resolve(targetPath),
+            status: "fail",
+            score: scoreSecurityAudit(findingCounts),
+            findingCounts,
+            findings
+        };
+    }
+    const validationResult = await validatePlugin(discoveredPackage.rootPath);
+    const validationSecurityFindings = validationResult.findings.filter((finding) => finding.id.startsWith("plugin.security."));
+    const findings = [
+        ...validationSecurityFindings,
+        ...(await auditMcpCommandSurface(discoveredPackage))
+    ];
+    return buildSecurityAuditFromFindings(discoveredPackage.rootPath, findings);
+}
+export function renderSecurityAuditJson(audit) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        ...audit
+    }, null, 2);
+}
+export function renderSecurityScorecard(audit, options = {}) {
+    const lines = [
+        "Security Scorecard",
+        "==================",
+        `Target: ${audit.targetPath}`,
+        `Status: ${audit.status.toUpperCase()}`,
+        `Score: ${audit.score}/100`,
+        `Summary: ${audit.findingCounts.fail} fail, ${audit.findingCounts.warn} warn, ${audit.findingCounts.total} total`
+    ];
+    if (audit.findings.length === 0) {
+        lines.push("", "No security findings.");
+        return lines.join("\n");
+    }
+    if (options.includeFindings === false) {
+        return lines.join("\n");
+    }
+    const appendSection = (title, findings, marker) => {
+        if (findings.length === 0) {
+            return;
+        }
+        lines.push("", title, "--------");
+        for (const finding of findings) {
+            lines.push(`${marker} ${finding.id}`);
+            lines.push(`  Message: ${finding.message}`);
+            lines.push(`  Impact: ${finding.impact}`);
+            lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+        }
+    };
+    appendSection("Failures", audit.findings.filter((finding) => finding.severity === "fail"), "x");
+    appendSection("Warnings", audit.findings.filter((finding) => finding.severity === "warn"), "!");
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,6 +27,7 @@
     "prepare-rc": "tsx scripts/prepare-release-candidate.ts",
     "prepare-release": "npm test && npm run build && npm pack --dry-run",
     "release-check": "node scripts/release-check.mjs",
+    "verify-release-sync": "node scripts/verify-release-sync.mjs",
     "prepublishOnly": "npm test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest"