codex-plugin-doctor 1.21.0 → 1.23.0

package/README.md

@@ -298,7 +298,7 @@ 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 contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `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.
+`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 contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `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. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
@@ -370,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.21.0
+      - uses: Esquetta/CodexPluginDoctor@v1.23.0
         with:
-          version: "1.21.0"
+          version: "1.23.0"
           path: .
           runtime: "true"
           policy: codex-publish

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

@@ -13,6 +13,18 @@ export interface DoctorNpmPackageReport {
         version: string | null;
         fileCount: number | null;
     };
+    tarball: {
+        filename: string;
+        path: string;
+        integrity: string | null;
+        shasum: string | null;
+        size: number | null;
+        unpackedSize: number | null;
+        fileCount: number | null;
+        packageRoot: string;
+        packageName: string | null;
+        packageVersion: string | null;
+    };
     summary: {
         status: "pass" | "warn" | "fail";
         exitCode: 0 | 1;

package/dist/core/npm-package-doctor.js

@@ -119,6 +119,9 @@ export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
         const packageRoot = await directoryExists(path.join(extractPath, "package"))
             ? path.join(extractPath, "package")
             : extractPath;
+        const packageName = typeof metadata.name === "string" ? metadata.name : null;
+        const packageVersion = typeof metadata.version === "string" ? metadata.version : null;
+        const fileCount = Array.isArray(metadata.files) ? metadata.files.length : null;
         const analysis = await buildPackageAnalysis(packageRoot, {
             environment: options.environment
         });
@@ -129,9 +132,21 @@ export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
             kind: "doctor.npm",
             packageSpec,
             package: {
-                name: typeof metadata.name === "string" ? metadata.name : null,
-                version: typeof metadata.version === "string" ? metadata.version : null,
-                fileCount: Array.isArray(metadata.files) ? metadata.files.length : null
+                name: packageName,
+                version: packageVersion,
+                fileCount
+            },
+            tarball: {
+                filename: path.basename(tarballPath),
+                path: tarballPath,
+                integrity: typeof metadata.integrity === "string" ? metadata.integrity : null,
+                shasum: typeof metadata.shasum === "string" ? metadata.shasum : null,
+                size: typeof metadata.size === "number" ? metadata.size : null,
+                unpackedSize: typeof metadata.unpackedSize === "number" ? metadata.unpackedSize : null,
+                fileCount,
+                packageRoot,
+                packageName,
+                packageVersion
             },
             summary: {
                 status: recommendations.status,
@@ -160,6 +175,7 @@ export function renderDoctorNpmPackageReport(report, options = {}) {
         "==========================",
         `Package: ${packageLabel}`,
         `Spec: ${report.packageSpec}`,
+        `Tarball: ${report.tarball.filename}`,
         `Status: ${report.summary.status.toUpperCase()}`,
         `Safe to install: ${report.summary.safeToInstall ? "yes" : "no"}`,
         `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,

package/dist/core/output-contract.js

@@ -157,7 +157,7 @@ const publicSchemaDefinitions = [
         id: "doctor.npm.json",
         command: "codex-plugin-doctor doctor npm <package> --json",
         outputKind: "doctor.npm",
-        required: ["schemaVersion", "kind", "generatedAt", "package", "summary", "validation", "security", "trust", "recommendations"]
+        required: ["schemaVersion", "kind", "generatedAt", "package", "tarball", "summary", "validation", "security", "trust", "recommendations"]
     },
     {
         id: "doctor.risk.diff.json",

package/dist/rules/rule-catalog.js

@@ -197,6 +197,24 @@ export const ruleCatalog = [
         fix: "Pin dependencies through a package manager or check in a reviewed setup script.",
         example: '{ "command": "npx", "args": ["-y", "@scope/server"] }'
     },
+    {
+        id: "plugin.security.path_traversal_risk",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server passes a package-external path to a path-like runtime argument.",
+        why: "Runtime file arguments outside the plugin root can load code or configuration that was not included in the reviewed package.",
+        fix: "Keep runtime file arguments inside the plugin package root, or package the referenced file with the plugin.",
+        example: '{ "command": "node", "args": ["server.js", "--config", "config/server.json"] }'
+    },
+    {
+        id: "plugin.security.dangerous_env_usage",
+        category: "security",
+        defaultSeverity: "fail",
+        summary: "An MCP server sets an environment variable that can alter code loading.",
+        why: "Variables such as NODE_OPTIONS, NODE_PATH, PYTHONPATH, LD_PRELOAD, or DYLD_INSERT_LIBRARIES can inject imports, preload native libraries, or load modules outside the reviewed package.",
+        fix: "Remove code-loading environment overrides, or keep referenced modules and preload files inside the reviewed plugin package.",
+        example: '{ "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }'
+    },
     {
         id: "plugin.security.cwd_outside_root",
         category: "security",

package/dist/security/security-audit.js

@@ -41,6 +41,104 @@ function containsPipeInstaller(args) {
         /\b(iwr|irm|invoke-webrequest|invoke-restmethod)\b[^|]*\|\s*(iex|invoke-expression)\b/.test(joinedArgs) ||
         /\binvoke-expression\b/.test(joinedArgs));
 }
+const pathLikeArgFlags = new Set([
+    "--config",
+    "--config-path",
+    "--cwd",
+    "--dir",
+    "--directory",
+    "--file",
+    "--import",
+    "--loader",
+    "--path",
+    "--project",
+    "--require",
+    "--root",
+    "--script",
+    "--tsconfig",
+    "--workspace"
+]);
+const codeLoadingEnvKeys = new Set([
+    "LD_PRELOAD",
+    "DYLD_INSERT_LIBRARIES"
+]);
+const modulePathEnvKeys = new Set([
+    "NODE_PATH",
+    "PYTHONPATH",
+    "RUBYLIB"
+]);
+function looksLikeEnvReference(value) {
+    return /^\$\{?[A-Z0-9_]+\}?$/i.test(value.trim());
+}
+function looksLikePathValue(value) {
+    const trimmed = value.trim();
+    return (trimmed.includes("..") ||
+        trimmed.includes("/") ||
+        trimmed.includes("\\") ||
+        trimmed.startsWith(".") ||
+        trimmed.startsWith("~") ||
+        path.isAbsolute(trimmed));
+}
+function isEscapingPathValue(rootPath, value) {
+    const trimmed = value.trim();
+    if (!trimmed ||
+        looksLikeEnvReference(trimmed) ||
+        /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ||
+        !looksLikePathValue(trimmed)) {
+        return false;
+    }
+    return !isPathWithinRoot(rootPath, path.resolve(rootPath, trimmed));
+}
+function collectEscapingPathArgs(rootPath, args) {
+    if (!Array.isArray(args)) {
+        return [];
+    }
+    const stringArgs = args.filter((arg) => typeof arg === "string");
+    const findings = [];
+    for (let index = 0; index < stringArgs.length; index += 1) {
+        const arg = stringArgs[index];
+        const equalsIndex = arg.indexOf("=");
+        if (equalsIndex > 0) {
+            const flag = arg.slice(0, equalsIndex).toLowerCase();
+            const value = arg.slice(equalsIndex + 1);
+            if (pathLikeArgFlags.has(flag) && isEscapingPathValue(rootPath, value)) {
+                findings.push({ flag, value });
+            }
+            continue;
+        }
+        const flag = arg.toLowerCase();
+        const value = stringArgs[index + 1];
+        if (pathLikeArgFlags.has(flag) && value && isEscapingPathValue(rootPath, value)) {
+            findings.push({ flag, value });
+            index += 1;
+        }
+    }
+    return findings;
+}
+function splitModulePathEnvValue(value) {
+    const trimmed = value.trim();
+    if (/^[a-z]:[\\/]/i.test(trimmed)) {
+        return trimmed.includes(";") ? trimmed.split(";") : [trimmed];
+    }
+    return trimmed.includes(";") ? trimmed.split(";") : trimmed.split(":");
+}
+function hasEscapingModulePath(rootPath, value) {
+    return splitModulePathEnvValue(value).some((entry) => isEscapingPathValue(rootPath, entry));
+}
+function isDangerousEnvUsage(rootPath, envKey, envValue) {
+    if (typeof envValue !== "string" || looksLikeEnvReference(envValue)) {
+        return false;
+    }
+    const normalizedKey = envKey.toUpperCase();
+    if (codeLoadingEnvKeys.has(normalizedKey)) {
+        return true;
+    }
+    if (normalizedKey === "NODE_OPTIONS" &&
+        /(?:^|\s)--(?:require|import|loader|experimental-loader)(?:=|\s+)/i.test(envValue)) {
+        return true;
+    }
+    return modulePathEnvKeys.has(normalizedKey) && hasEscapingModulePath(rootPath, envValue);
+}
 const poisonScanExtensions = new Set([
     ".json",
     ".md",
@@ -84,12 +182,23 @@ export function auditMcpServerConfig(rootPath, parsedConfig) {
         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."));
         }
+        for (const riskyArg of collectEscapingPathArgs(rootPath, args)) {
+            findings.push(buildFinding("fail", "plugin.security.path_traversal_risk", `The MCP server \`${serverName}\` passes \`${riskyArg.value}\` to path-like arg \`${riskyArg.flag}\`, which escapes the plugin root.`, "Path-like runtime arguments that point outside the package can make startup depend on unreviewed local files or load code outside the reviewed tarball.", "Keep runtime file arguments inside the plugin package root, or package the referenced file with the plugin."));
+        }
         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 (isPlainObject(serverConfig.env)) {
+            for (const [envKey, envValue] of Object.entries(serverConfig.env)) {
+                if (!isDangerousEnvUsage(rootPath, envKey, envValue)) {
+                    continue;
+                }
+                findings.push(buildFinding("fail", "plugin.security.dangerous_env_usage", `The MCP server \`${serverName}\` sets dangerous code-loading env variable \`${envKey}\`.`, "Environment variables that alter module lookup, preload native libraries, or inject runtime imports can execute code outside the reviewed package.", "Remove code-loading environment overrides, or keep referenced modules and preload files inside the reviewed plugin package."));
+            }
+        }
         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."));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",