codex-plugin-doctor 1.24.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. 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.
+`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.24.0
+      - uses: Esquetta/CodexPluginDoctor@v1.25.0
         with:
-          version: "1.24.0"
+          version: "1.25.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/validate-plugin.js

@@ -1,5 +1,6 @@
 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, evidence) {
@@ -358,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
@@ -373,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,
@@ -388,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

@@ -8,6 +8,7 @@ export interface Finding {
     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/render-markdown-report.js

@@ -1,4 +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;
@@ -39,6 +40,10 @@ 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}`);

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

@@ -47,6 +47,13 @@ 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,5 +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;
@@ -61,6 +62,10 @@ 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}`);

package/dist/security/security-audit.js

@@ -3,6 +3,7 @@ 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";
+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 {
@@ -310,19 +311,20 @@ 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) {
@@ -331,14 +333,7 @@ export async function buildSecurityAudit(targetPath) {
         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.", { 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."));
@@ -382,6 +377,10 @@ 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}`);

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.24.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",