codex-plugin-doctor 0.10.0 → 0.11.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`
@@ -165,12 +173,18 @@ 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 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 compat .
 codex-plugin-doctor compat . --all --scorecard
 codex-plugin-doctor compat . --client codex
@@ -213,10 +227,12 @@ 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.
 
 `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/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/core/fix-plan.js

@@ -4,6 +4,11 @@ import { validatePlugin } from "./validate-plugin.js";
 function relativeToTarget(targetPath, candidatePath) {
     return path.relative(targetPath, candidatePath).replace(/\\/g, "/");
 }
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
 export async function buildFixPlan(targetPath) {
     const result = await validatePlugin(targetPath);
     const rootPath = result.targetPath;
@@ -38,6 +43,12 @@ export async function buildFixPlan(targetPath) {
         .catch(() => ({}));
     if (typeof manifest.skills === "string") {
         const skillsPath = path.resolve(rootPath, manifest.skills);
+        if (!isPathWithinRoot(rootPath, skillsPath)) {
+            return {
+                targetPath: rootPath,
+                actions
+            };
+        }
         if (await directoryExists(skillsPath)) {
             for (const entry of await readdir(skillsPath, { withFileTypes: true })) {
                 if (!entry.isDirectory()) {
@@ -70,6 +81,12 @@ export async function buildFixPlan(targetPath) {
     }
     if (typeof manifest.mcpServers === "string") {
         const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+        if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+            return {
+                targetPath: rootPath,
+                actions
+            };
+        }
         if (!(await fileExists(mcpConfigPath))) {
             actions.push({
                 id: "mcp.scaffold_config",

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 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 declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -1,4 +1,6 @@
 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 async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

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

@@ -12,6 +12,7 @@ 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";
@@ -28,6 +29,7 @@ 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 { 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 +55,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] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor security <path> [--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 +188,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 +372,23 @@ 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");
+        if (jsonOutput && scorecardOutput) {
+            io.writeStderr("Use either --json or --scorecard, not both.");
+            return 2;
+        }
+        const audit = await buildSecurityAudit(maybePath);
+        io.writeStdout(jsonOutput
+            ? renderSecurityAuditJson(audit)
+            : renderSecurityScorecard(audit, { includeFindings: !scorecardOutput }));
+        return audit.status === "fail" ? 1 : 0;
+    }
     if (command === "compat") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
         const compatFlags = maybePath && maybePath.startsWith("--")

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

@@ -0,0 +1,17 @@
+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 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,192 @@
+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));
+}
+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>`.")
+        ];
+    }
+    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;
+}
+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 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 = dedupeFindings([
+        ...validationSecurityFindings,
+        ...(await auditMcpCommandSurface(discoveredPackage))
+    ]);
+    const findingCounts = buildFindingCounts(findings);
+    const status = findingCounts.fail > 0
+        ? "fail"
+        : findingCounts.warn > 0
+            ? "warn"
+            : "pass";
+    return {
+        targetPath: discoveredPackage.rootPath,
+        status,
+        score: scoreSecurityAudit(findingCounts),
+        findingCounts,
+        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.0",
+  "version": "0.11.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"