codex-plugin-doctor 1.23.0 → 1.24.0

package/README.md

@@ -314,7 +314,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `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.
+`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. Security findings include structured evidence where available, such as server names, config paths, env keys, arg flags, and escaped paths. 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.
 
@@ -370,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.23.0
+      - uses: Esquetta/CodexPluginDoctor@v1.24.0
         with:
-          version: "1.23.0"
+          version: "1.24.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/validate-plugin.js

@@ -2,22 +2,24 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "./discover-package.js";
 import { probeRuntime } from "./runtime-probe.js";
-function buildFailure(id, message, impact, suggestedFix) {
+function buildFailure(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "fail",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
-function buildWarning(id, message, impact, suggestedFix) {
+function buildWarning(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "warn",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 async function directoryExists(targetPath) {
@@ -66,6 +68,9 @@ function isPathWithinRoot(rootPath, candidatePath) {
     return (relativePath === "" ||
         (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
 }
+function relativePackagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).replace(/\\/g, "/") || ".";
+}
 function isSensitiveKey(key) {
     return /(token|secret|password|api[_-]?key|private[_-]?key)/i.test(key);
 }
@@ -211,7 +216,12 @@ async function validateSkillsDirectory(discoveredPackage) {
     const skillsPath = path.resolve(rootPath, manifest.skills);
     if (!isPathWithinRoot(rootPath, skillsPath)) {
         return [
-            buildFailure("plugin.security.path_traversal", "The plugin manifest points the skills path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `skills` path inside the plugin root.")
+            buildFailure("plugin.security.path_traversal", "The plugin manifest points the skills path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `skills` path inside the plugin root.", {
+                manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+                field: "skills",
+                configuredPath: manifest.skills,
+                resolvedPath: skillsPath
+            })
         ];
     }
     const exists = await directoryExists(skillsPath);
@@ -277,7 +287,12 @@ async function validateMcpConfig(discoveredPackage) {
     const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
     if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
         return [
-            buildFailure("plugin.security.path_traversal", "The plugin manifest points the MCP config path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `mcpServers` path inside the plugin root.")
+            buildFailure("plugin.security.path_traversal", "The plugin manifest points the MCP config path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `mcpServers` path inside the plugin root.", {
+                manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+                field: "mcpServers",
+                configuredPath: manifest.mcpServers,
+                resolvedPath: mcpConfigPath
+            })
         ];
     }
     const mcpConfigExists = await fileExists(mcpConfigPath);
@@ -323,7 +338,12 @@ async function validateMcpConfig(discoveredPackage) {
                 if (isSensitiveKey(envKey) &&
                     typeof envValue === "string" &&
                     looksLikeLiteralSecret(envValue)) {
-                    findings.push(buildFailure("plugin.security.hard_coded_secret", `The MCP server \`${serverName}\` contains a hard-coded secret-like env value for \`${envKey}\`.`, "Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.", `Replace the literal value for \`${envKey}\` with an environment reference or injected secret outside the package.`));
+                    findings.push(buildFailure("plugin.security.hard_coded_secret", `The MCP server \`${serverName}\` contains a hard-coded secret-like env value for \`${envKey}\`.`, "Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.", `Replace the literal value for \`${envKey}\` with an environment reference or injected secret outside the package.`, {
+                        serverName,
+                        configPath: relativePackagePath(rootPath, mcpConfigPath),
+                        envKey,
+                        envValue: "[REDACTED]"
+                    }));
                 }
             }
         }

package/dist/domain/types.d.ts

@@ -1,10 +1,13 @@
 export type FindingSeverity = "warn" | "fail";
+export type FindingEvidenceValue = string | number | boolean | null;
+export type FindingEvidence = Record<string, FindingEvidenceValue>;
 export interface Finding {
     id: string;
     severity: FindingSeverity;
     message: string;
     impact: string;
     suggestedFix: string;
+    evidence?: FindingEvidence;
 }
 export interface CheckResult {
     targetPath: string;

package/dist/reporting/format-finding-evidence.d.ts

@@ -0,0 +1,3 @@
+import type { Finding, FindingEvidence } from "../domain/types.js";
+export declare function formatFindingEvidence(evidence: FindingEvidence): string;
+export declare function formatFindingEvidenceLine(finding: Finding): string | null;

package/dist/reporting/format-finding-evidence.js

@@ -0,0 +1,8 @@
+export function formatFindingEvidence(evidence) {
+    return Object.entries(evidence)
+        .map(([key, value]) => `${key}=${String(value)}`)
+        .join(", ");
+}
+export function formatFindingEvidenceLine(finding) {
+    return finding.evidence ? formatFindingEvidence(finding.evidence) : null;
+}

package/dist/reporting/render-markdown-report.js

@@ -1,3 +1,4 @@
+import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
 export function buildMarkdownReport(result, options) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -38,6 +39,10 @@ export function buildMarkdownReport(result, options) {
         lines.push(`- Message: ${finding.message}`);
         lines.push(`- Impact: ${finding.impact}`);
         lines.push(`- Suggested fix: ${finding.suggestedFix}`);
+        const evidence = formatFindingEvidenceLine(finding);
+        if (evidence) {
+            lines.push(`- Evidence: ${evidence}`);
+        }
         lines.push("");
     }
     return lines.join("\n");

package/dist/reporting/render-sarif-report.js

@@ -46,7 +46,8 @@ export function renderSarifReport(result) {
                                 }
                             }
                         }
-                    ]
+                    ],
+                    ...(finding.evidence ? { properties: { evidence: finding.evidence } } : {})
                 }))
             }
         ]

package/dist/reporting/render-text-report.js

@@ -1,4 +1,5 @@
 import { findRuleDefinition } from "../rules/rule-catalog.js";
+import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
 function getCounts(result) {
     const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
     const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
@@ -60,6 +61,10 @@ export function renderTextReport(result, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const evidence = formatFindingEvidenceLine(finding);
+            if (evidence) {
+                lines.push(`  Evidence: ${evidence}`);
+            }
             if (explain) {
                 const rule = findRuleDefinition(finding.id);
                 if (rule) {

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

@@ -10,7 +10,9 @@ export interface SecurityAudit {
     };
     findings: Finding[];
 }
-export declare function auditMcpServerConfig(rootPath: string, parsedConfig: unknown): Finding[];
+export declare function auditMcpServerConfig(rootPath: string, parsedConfig: unknown, options?: {
+    configPath?: string;
+}): 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;

package/dist/security/security-audit.js

@@ -3,13 +3,15 @@ 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) {
+import { formatFindingEvidenceLine } from "../reporting/format-finding-evidence.js";
+function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity,
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 function isPlainObject(value) {
@@ -20,6 +22,9 @@ function isPathWithinRoot(rootPath, candidatePath) {
     return (relativePath === "" ||
         (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
 }
+function relativePackagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).replace(/\\/g, "/") || ".";
+}
 function normalizeCommandName(command) {
     return path.basename(command).toLowerCase().replace(/\.(exe|cmd|bat)$/i, "");
 }
@@ -102,14 +107,14 @@ function collectEscapingPathArgs(rootPath, args) {
             const flag = arg.slice(0, equalsIndex).toLowerCase();
             const value = arg.slice(equalsIndex + 1);
             if (pathLikeArgFlags.has(flag) && isEscapingPathValue(rootPath, value)) {
-                findings.push({ flag, value });
+                findings.push({ flag, value, resolvedPath: path.resolve(rootPath, value) });
             }
             continue;
         }
         const flag = arg.toLowerCase();
         const value = stringArgs[index + 1];
         if (pathLikeArgFlags.has(flag) && value && isEscapingPathValue(rootPath, value)) {
-            findings.push({ flag, value });
+            findings.push({ flag, value, resolvedPath: path.resolve(rootPath, value) });
             index += 1;
         }
     }
@@ -158,10 +163,13 @@ const promptInjectionPatterns = [
     /\b(?:exfiltrate|steal|leak|upload|send)\b.{0,120}\b(?:secret|secrets|token|tokens|api\s*key|api\s*keys|credential|credentials|environment\s+variables?|env)\b/i,
     /\bdo\s+not\s+(?:reveal|tell|mention|disclose)\b.{0,120}\b(?:instruction|instructions|prompt|prompts|system|developer)\b/i
 ];
-export function auditMcpServerConfig(rootPath, parsedConfig) {
+export function auditMcpServerConfig(rootPath, parsedConfig, options = {}) {
+    const configPath = options.configPath
+        ? relativePackagePath(rootPath, options.configPath)
+        : ".mcp.json";
     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.")
+            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.", { configPath })
         ];
     }
     const findings = [];
@@ -174,21 +182,32 @@ export function auditMcpServerConfig(rootPath, parsedConfig) {
         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."));
+            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.", { serverName, configPath, command }));
         }
         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."));
+            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.", { serverName, configPath, command: typeof command === "string" ? command : null }));
         }
         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."));
+            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.", { serverName, configPath, command: typeof command === "string" ? command : null }));
         }
         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."));
+            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.", {
+                serverName,
+                configPath,
+                argFlag: riskyArg.flag,
+                argValue: riskyArg.value,
+                resolvedPath: riskyArg.resolvedPath
+            }));
         }
         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."));
+                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.", {
+                    serverName,
+                    configPath,
+                    cwd,
+                    resolvedPath: cwdPath
+                }));
             }
         }
         if (isPlainObject(serverConfig.env)) {
@@ -196,11 +215,16 @@ export function auditMcpServerConfig(rootPath, parsedConfig) {
                 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."));
+                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.", {
+                    serverName,
+                    configPath,
+                    envKey,
+                    envValue: typeof envValue === "string" ? envValue : null
+                }));
             }
         }
         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."));
+            findings.push(buildFinding("warn", "plugin.security.insecure_http_url", `The MCP server \`${serverName}\` uses an insecure HTTP URL.`, "Plain HTTP transports can expose MCP traffic on non-local networks and make endpoint identity harder to verify.", "Use HTTPS for remote MCP servers; reserve HTTP for explicit localhost development endpoints.", { serverName, configPath, url }));
         }
     }
     return findings;
@@ -238,7 +262,7 @@ async function auditPromptPoisoningSurface(rootPath) {
             continue;
         }
         const relativeFilePath = path.relative(rootPath, filePath).replace(/\\/g, "/");
-        findings.push(buildFinding("fail", "plugin.security.prompt_injection_text", `The packaged text file \`${relativeFilePath}\` contains prompt-injection or secret-exfiltration style instructions.`, "Malicious or poisoned tool, prompt, resource, or skill text can instruct an agent to ignore higher-priority instructions or leak secrets when loaded into context.", "Remove hidden override or exfiltration instructions, then keep tool/prompt/resource descriptions scoped to the legitimate user-facing behavior."));
+        findings.push(buildFinding("fail", "plugin.security.prompt_injection_text", `The packaged text file \`${relativeFilePath}\` contains prompt-injection or secret-exfiltration style instructions.`, "Malicious or poisoned tool, prompt, resource, or skill text can instruct an agent to ignore higher-priority instructions or leak secrets when loaded into context.", "Remove hidden override or exfiltration instructions, then keep tool/prompt/resource descriptions scoped to the legitimate user-facing behavior.", { filePath: relativeFilePath }));
     }
     return findings;
 }
@@ -257,10 +281,10 @@ async function auditMcpCommandSurface(discoveredPackage) {
     }
     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>`.")
+            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>`.", { configPath: relativePackagePath(rootPath, mcpConfigPath) })
         ];
     }
-    return auditMcpServerConfig(rootPath, parsedConfig);
+    return auditMcpServerConfig(rootPath, parsedConfig, { configPath: mcpConfigPath });
 }
 function dedupeFindings(findings) {
     const seen = new Set();
@@ -305,7 +329,7 @@ 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.")
+            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.", { targetPath: path.resolve(targetPath) })
         ];
         const findingCounts = buildFindingCounts(findings);
         return {
@@ -358,6 +382,10 @@ export function renderSecurityScorecard(audit, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const evidence = formatFindingEvidenceLine(finding);
+            if (evidence) {
+                lines.push(`  Evidence: ${evidence}`);
+            }
         }
     };
     appendSection("Failures", audit.findings.filter((finding) => finding.severity === "fail"), "x");

package/package.json

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