codex-plugin-doctor 1.23.0 → 1.25.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. Findings also include deterministic SHA-256 fingerprints derived from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. 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.25.0
         with:
-          version: "1.23.0"
+          version: "1.25.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/validate-plugin.js

@@ -1,23 +1,26 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
+import { withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 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 +69,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 +217,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 +288,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 +339,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]"
+                    }));
                 }
             }
         }
@@ -338,7 +359,7 @@ export async function validatePlugin(targetPath, options = {}) {
             targetPath: rootPath,
             status: "fail",
             exitCode: 1,
-            findings: [await buildMissingManifestFailure(rootPath)]
+            findings: withFindingFingerprints([await buildMissingManifestFailure(rootPath)], rootPath)
         };
     }
     const runtimeResult = options.runtime
@@ -353,8 +374,9 @@ export async function validatePlugin(targetPath, options = {}) {
         ...(await validateMcpConfig(discoveredPackage)),
         ...(runtimeResult ? runtimeResult.findings : [])
     ];
-    const hasFailures = findings.some((finding) => finding.severity === "fail");
-    const hasWarnings = findings.some((finding) => finding.severity === "warn");
+    const fingerprintedFindings = withFindingFingerprints(findings, discoveredPackage.rootPath);
+    const hasFailures = fingerprintedFindings.some((finding) => finding.severity === "fail");
+    const hasWarnings = fingerprintedFindings.some((finding) => finding.severity === "warn");
     if (!hasFailures && !hasWarnings) {
         return {
             targetPath: discoveredPackage.rootPath,
@@ -368,7 +390,7 @@ export async function validatePlugin(targetPath, options = {}) {
         targetPath: discoveredPackage.rootPath,
         status: hasFailures ? "fail" : "warn",
         exitCode: hasFailures ? 1 : 0,
-        findings,
+        findings: fingerprintedFindings,
         ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {})
     };
 }

package/dist/domain/types.d.ts

@@ -1,10 +1,14 @@
 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;
+    fingerprint?: string;
 }
 export interface CheckResult {
     targetPath: string;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
+export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, type DoctorSnapshot } from "./core/doctor-snapshot.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 import { validatePlugin } from "./core/validate-plugin.js";
+export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";

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

@@ -2,6 +2,7 @@ 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 { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
 function buildFinding(severity, id, message, impact, suggestedFix) {
     return {
@@ -110,14 +111,15 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}) {
     const security = buildSecurityAuditFromFindings(rootPath, mcpConfigPath && parsedConfig !== null
         ? auditMcpServerConfig(rootPath, parsedConfig)
         : []);
-    const status = mergeReportStatus(staticFindings, security);
+    const fingerprintedStaticFindings = withFindingFingerprints(staticFindings, rootPath);
+    const status = mergeReportStatus(fingerprintedStaticFindings, security);
     return {
         targetPath: rootPath,
         status,
         exitCode: status === "fail" ? 1 : 0,
         mcpConfigPath,
         serverCount,
-        findings: [...staticFindings, ...security.findings],
+        findings: [...fingerprintedStaticFindings, ...security.findings],
         security,
         compatibility
     };
@@ -159,6 +161,10 @@ export function renderGenericMcpDoctor(report) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`  Fingerprint: ${fingerprint}`);
+            }
         }
     };
     appendFindings("Failures", failures, "x");

package/dist/reporting/finding-fingerprint.d.ts

@@ -0,0 +1,5 @@
+import type { Finding } from "../domain/types.js";
+export declare function buildFindingFingerprint(finding: Finding, rootPath: string): string;
+export declare function withFindingFingerprint(finding: Finding, rootPath: string): Finding;
+export declare function withFindingFingerprints(findings: Finding[], rootPath: string): Finding[];
+export declare function formatFindingFingerprintLine(finding: Finding): string | null;

package/dist/reporting/finding-fingerprint.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+const fingerprintVersion = 1;
+function isPathEvidenceKey(key) {
+    return key.toLowerCase().endsWith("path");
+}
+function normalizePathEvidence(value, rootPath) {
+    const windowsPath = /^[a-z]:[\\/]/i.test(value);
+    const windowsRoot = /^[a-z]:[\\/]/i.test(rootPath);
+    if (windowsPath && windowsRoot) {
+        return path.win32.relative(rootPath, value).replaceAll("\\", "/") || ".";
+    }
+    if (value.startsWith("/") && rootPath.startsWith("/")) {
+        return path.posix.relative(rootPath, value) || ".";
+    }
+    return value.replaceAll("\\", "/");
+}
+function canonicalizeEvidenceValue(key, value, rootPath) {
+    return typeof value === "string" && isPathEvidenceKey(key)
+        ? normalizePathEvidence(value, rootPath)
+        : value;
+}
+function canonicalizeEvidence(evidence, rootPath) {
+    return Object.fromEntries(Object.entries(evidence ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => [
+        key,
+        canonicalizeEvidenceValue(key, value, rootPath)
+    ]));
+}
+export function buildFindingFingerprint(finding, rootPath) {
+    const payload = JSON.stringify({
+        version: fingerprintVersion,
+        ruleId: finding.id,
+        evidence: canonicalizeEvidence(finding.evidence, rootPath)
+    });
+    return createHash("sha256").update(payload).digest("hex");
+}
+export function withFindingFingerprint(finding, rootPath) {
+    return {
+        ...finding,
+        fingerprint: buildFindingFingerprint(finding, rootPath)
+    };
+}
+export function withFindingFingerprints(findings, rootPath) {
+    return findings.map((finding) => withFindingFingerprint(finding, rootPath));
+}
+export function formatFindingFingerprintLine(finding) {
+    return finding.fingerprint ?? null;
+}

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,5 @@
+import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
+import { formatFindingFingerprintLine } from "./finding-fingerprint.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 +40,14 @@ export function buildMarkdownReport(result, options) {
         lines.push(`- Message: ${finding.message}`);
         lines.push(`- Impact: ${finding.impact}`);
         lines.push(`- Suggested fix: ${finding.suggestedFix}`);
+        const fingerprint = formatFindingFingerprintLine(finding);
+        if (fingerprint) {
+            lines.push(`- Fingerprint: \`${fingerprint}\``);
+        }
+        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,15 @@ export function renderSarifReport(result) {
                                 }
                             }
                         }
-                    ]
+                    ],
+                    ...(finding.fingerprint
+                        ? {
+                            partialFingerprints: {
+                                "codexPluginDoctor/v1": finding.fingerprint
+                            }
+                        }
+                        : {}),
+                    ...(finding.evidence ? { properties: { evidence: finding.evidence } } : {})
                 }))
             }
         ]

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

@@ -1,4 +1,6 @@
 import { findRuleDefinition } from "../rules/rule-catalog.js";
+import { formatFindingEvidenceLine } from "./format-finding-evidence.js";
+import { formatFindingFingerprintLine } from "./finding-fingerprint.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 +62,14 @@ export function renderTextReport(result, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`  Fingerprint: ${fingerprint}`);
+            }
+            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,16 @@ 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 { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
+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 +23,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 +108,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 +164,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 +183,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 +216,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 +263,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 +282,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();
@@ -286,35 +311,29 @@ 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 rootPath = path.resolve(targetPath);
+    const fingerprintedFindings = withFindingFingerprints(dedupeFindings(findings), rootPath);
+    const findingCounts = buildFindingCounts(fingerprintedFindings);
     const status = findingCounts.fail > 0
         ? "fail"
         : findingCounts.warn > 0
             ? "warn"
             : "pass";
     return {
-        targetPath: path.resolve(targetPath),
+        targetPath: rootPath,
         status,
         score: scoreSecurityAudit(findingCounts),
         findingCounts,
-        findings: dedupedFindings
+        findings: fingerprintedFindings
     };
 }
 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 {
-            targetPath: path.resolve(targetPath),
-            status: "fail",
-            score: scoreSecurityAudit(findingCounts),
-            findingCounts,
-            findings
-        };
+        return buildSecurityAuditFromFindings(targetPath, findings);
     }
     const validationResult = await validatePlugin(discoveredPackage.rootPath);
     const validationSecurityFindings = validationResult.findings.filter((finding) => finding.id.startsWith("plugin.security."));
@@ -358,6 +377,14 @@ export function renderSecurityScorecard(audit, options = {}) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`  Fingerprint: ${fingerprint}`);
+            }
+            const evidence = formatFindingEvidenceLine(finding);
+            if (evidence) {
+                lines.push(`  Evidence: ${evidence}`);
+            }
         }
     };
     appendSection("Failures", audit.findings.filter((finding) => finding.severity === "fail"), "x");

package/dist/security/trust-score.js

@@ -2,6 +2,7 @@ import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { discoverPackage } from "../core/discover-package.js";
 import { parseJsonText } from "../core/read-json-file.js";
+import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { buildSecurityAudit } from "./security-audit.js";
 const lifecycleScripts = new Set([
     "preinstall",
@@ -130,11 +131,11 @@ export async function buildTrustScore(targetPath, options = {}) {
         : await discoverPackage(rootPath)
             ? await buildSecurityAudit(rootPath)
             : null;
-    const findings = dedupeFindings([
+    const findings = withFindingFingerprints(dedupeFindings([
         ...scriptAudit.findings,
         ...dependencyAudit.findings,
         ...(securityAudit?.findings ?? [])
-    ]);
+    ]), rootPath);
     const fail = findings.filter((finding) => finding.severity === "fail").length;
     const warn = findings.filter((finding) => finding.severity === "warn").length;
     const score = scoreFindings(findings);
@@ -189,6 +190,10 @@ export function renderTrustScore(report) {
             lines.push(`  Message: ${finding.message}`);
             lines.push(`  Impact: ${finding.impact}`);
             lines.push(`  Suggested fix: ${finding.suggestedFix}`);
+            const fingerprint = formatFindingFingerprintLine(finding);
+            if (fingerprint) {
+                lines.push(`  Fingerprint: ${fingerprint}`);
+            }
         }
     };
     appendSection("Failures", report.findings.filter((finding) => finding.severity === "fail"), "x");

package/package.json

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