@dailephd/my-dev-kit-lab 0.9.1 → 0.9.3

package/dist/src/securityValidation/attackScenarios/scenarios/subprocessInjectionScenario.js

@@ -1,9 +1,6 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { makeEvidence } from "../exploitEvidence.js";
 import { getPayloadsForGroup } from "../payloadCorpus.js";
-import { runSecurityCommand } from "../../commandRunner.js";
+import { buildSecurityCommandSpawnOptions, runSecurityCommand } from "../../commandRunner.js";
 // ---------------------------------------------------------------------------
 // v0.2.2 Batch 3 — subprocess injection scenario.
 //
@@ -15,31 +12,60 @@ import { runSecurityCommand } from "../../commandRunner.js";
 // that no shell re-interpreted it (splitting it into multiple commands via
 // `;`, `&&`, backticks, `$()`, or `|`).
 //
-// Also does a bounded static check that the command-execution helpers this
-// scenario exercises are built with `shell: false` (source inspection of a
-// known-small file, not a general code scanner).
+// Also verifies at runtime, through the compiled command runner's own
+// spawn-options builder (the exact value runSecurityCommand() spawns with),
+// that the runner does not enable a shell. No TypeScript source is read, so
+// the proof works from an installed package.
 // ---------------------------------------------------------------------------
 const ECHO_ARGV_SCRIPT = "process.stdout.write(JSON.stringify(process.argv.slice(1)))";
-function commandRunnerSourcePath() {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    return path.resolve(here, "..", "..", "commandRunner.ts");
+const DEFAULT_DEPS = {
+    runCommand: runSecurityCommand,
+    readSpawnOptions: (cwd) => buildSecurityCommandSpawnOptions({ cwd, env: process.env }),
+};
+// Runtime proof that the applicable runner's spawn path does not use a shell.
+// A strict `shell === false` is the only accepted safe value; a truthy shell
+// is demonstrated unsafe; a missing/malformed/throwing proof is unavailable.
+function proveShellDisabled(deps, cwd) {
+    let options;
+    try {
+        options = deps.readSpawnOptions(cwd);
+    }
+    catch (error) {
+        return {
+            state: "unavailable",
+            detail: `Spawn options could not be obtained from the command runner: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (typeof options !== "object" || options === null || !("shell" in options)) {
+        return { state: "unavailable", detail: "Command runner spawn options did not declare a shell setting." };
+    }
+    const shell = options.shell;
+    if (shell === false)
+        return { state: "safe" };
+    if (shell === true || typeof shell === "string") {
+        return { state: "unsafe", detail: "Command runner spawn options enable a shell." };
+    }
+    return { state: "unavailable", detail: "Command runner spawn options declared a malformed shell setting." };
 }
 export const SUBPROCESS_INJECTION_SCENARIO = {
     id: "subprocess-injection-safety",
     title: "Subprocess injection: shell metacharacter payloads are passed as literal arguments",
-    description: "Runs a benign argv-echoing Node script with each subprocess-injection payload as a single spawn argument and confirms it round-trips as exactly one literal string, proving no shell re-interpretation. Also checks that commandRunner.ts constructs subprocess calls with shell:false.",
+    description: "Runs a benign argv-echoing Node script with each subprocess-injection payload as a single spawn argument and confirms it round-trips as exactly one literal string, proving no shell re-interpretation. Also verifies at runtime that the command runner constructs subprocess calls with shell:false.",
     checkId: "subprocess",
     applicableProfiles: [],
     severityBaseline: "blocker",
     verdictImpact: "tool-framework-blocker",
-    expectedSafeBehavior: "Every subprocess-injection payload round-trips as a single literal argv element; commandRunner.ts uses shell:false.",
+    expectedSafeBehavior: "Every subprocess-injection payload round-trips as a single literal argv element; the command runner uses shell:false.",
     evidenceRequirements: ["command", "observation"],
-    run: async (ctx) => {
+    run: (ctx) => runSubprocessInjectionScenario(ctx, DEFAULT_DEPS),
+};
+export async function runSubprocessInjectionScenario(ctx, deps) {
+    {
         const evidence = [];
         const notLiteral = [];
         const payloads = getPayloadsForGroup("subprocess-injection");
         for (const p of payloads) {
-            const cmd = await runSecurityCommand({
+            const cmd = await deps.runCommand({
                 command: process.execPath,
                 args: ["-e", ECHO_ARGV_SCRIPT, p.value],
                 cwd: ctx.toolRoot,
@@ -70,42 +96,34 @@ export const SUBPROCESS_INJECTION_SCENARIO = {
                 rawPreview: p.value,
             }));
         }
-        let shellFalseConfirmed = false;
-        let sourceReadable = true;
-        try {
-            const source = fs.readFileSync(commandRunnerSourcePath(), "utf8");
-            shellFalseConfirmed = /shell:\s*false/.test(source);
-        }
-        catch {
-            sourceReadable = false;
-        }
+        const proof = proveShellDisabled(deps, ctx.toolRoot);
         evidence.push(makeEvidence({
             kind: "observation",
-            source: "static check: src/securityValidation/commandRunner.ts",
-            confidence: sourceReadable ? "high" : "low",
+            source: "runtime check: buildSecurityCommandSpawnOptions() used by runSecurityCommand()",
+            confidence: proof.state === "unavailable" ? "low" : "high",
             expectedBehavior: "Subprocess calls should be constructed with shell:false.",
-            observedBehavior: sourceReadable
-                ? shellFalseConfirmed
-                    ? "shell:false found in commandRunner.ts."
-                    : "shell:false NOT found in commandRunner.ts."
-                : "Could not read commandRunner.ts source for static confirmation.",
+            observedBehavior: proof.state === "safe"
+                ? "Command runner spawn options declare shell:false."
+                : proof.state === "unsafe"
+                    ? proof.detail
+                    : `Could not verify shell:false: ${proof.detail}`,
         }));
-        if (notLiteral.length > 0 || (sourceReadable && !shellFalseConfirmed)) {
+        if (notLiteral.length > 0 || proof.state === "unsafe") {
             return {
                 status: "failed",
                 confidence: "high",
                 evidence,
                 recommendation: notLiteral.length > 0
                     ? `Investigate argument construction — payload(s) did not round-trip literally: ${notLiteral.join(", ")}.`
-                    : "commandRunner.ts must construct child_process.spawn calls with shell:false.",
+                    : "The command runner must construct child_process.spawn calls with shell:false.",
             };
         }
-        if (!sourceReadable) {
+        if (proof.state === "unavailable") {
             return {
                 status: "blocked",
                 confidence: "low",
                 evidence,
-                recommendation: "Could not statically confirm shell:false; argv round-trip evidence is still valid.",
+                recommendation: "Could not verify shell:false for the command runner; argv round-trip evidence alone is not sufficient.",
             };
         }
         return {
@@ -113,5 +131,5 @@ export const SUBPROCESS_INJECTION_SCENARIO = {
             confidence: "high",
             evidence,
         };
-    },
-};
+    }
+}

package/dist/src/securityValidation/commandRunner.js

@@ -5,6 +5,18 @@ import { resolveCommand } from "../core/resolveCommand.js";
 export function resolveNpmCommand() {
     return "npm";
 }
+// The single place the spawn options for security commands are constructed.
+// runSecurityCommand() spawns with exactly this result, so the subprocess
+// injection scenario can verify `shell: false` at runtime from the compiled
+// module instead of reading unshipped TypeScript source.
+export function buildSecurityCommandSpawnOptions(options) {
+    return {
+        cwd: options.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: options.env,
+    };
+}
 // Runs a security check command with an argument array (no shell interpolation).
 // npm audit returns exit code 1 on vulnerabilities; that is not treated as a
 // spawn failure here — the caller inspects the output and exit code separately.
@@ -52,12 +64,7 @@ export async function runSecurityCommand(options) {
         let timeout;
         let child;
         try {
-            child = spawn(command, args, {
-                cwd: options.cwd,
-                shell: false,
-                stdio: ["ignore", "pipe", "pipe"],
-                env,
-            });
+            child = spawn(command, args, buildSecurityCommandSpawnOptions({ cwd: options.cwd, env }));
         }
         catch (spawnErr) {
             resolve({

package/dist/src/securityValidation/packageChecks/parseNpmPackDryRun.js

@@ -13,6 +13,29 @@ export function parseNpmPackDryRun(stdout) {
     if (!stdout.trim()) {
         return { files: [], parseError: "npm pack --dry-run produced no output" };
     }
+    if (/^[\[{]/.test(stdout.trim())) {
+        try {
+            const inventory = JSON.parse(stdout);
+            if (!Array.isArray(inventory) || inventory.length !== 1 ||
+                !inventory[0] || !Array.isArray(inventory[0].files) || !inventory[0].files.length) {
+                return { files: [], parseError: "npm pack JSON must contain exactly one nonempty package inventory" };
+            }
+            const files = [];
+            for (const file of inventory[0].files) {
+                if (!file || typeof file.path !== "string" || !safeInventoryPath(file.path)) {
+                    return { files: [], parseError: "npm pack JSON contains a malformed or unsafe file path" };
+                }
+                // JSON paths are package-relative, unlike text tarball paths. Add the
+                // archive root exactly once so a real nested package/ directory cannot
+                // masquerade as a root entrypoint in the existing detectors.
+                files.push(`package/${file.path.replace(/\\/g, "/").replace(/^(\.\/)+/, "")}`);
+            }
+            return { files };
+        }
+        catch {
+            return { files: [], parseError: "npm pack JSON is unparseable" };
+        }
+    }
     const files = [];
     let inContents = false;
     let totalSize;
@@ -35,10 +58,8 @@ export function parseNpmPackDryRun(stdout) {
             if (match?.[1]) {
                 files.push(match[1].trim());
             }
-            else {
-                // Fallback: take the whole line if size pattern doesn't match
-                files.push(line);
-            }
+            else
+                return { files: [], parseError: "Malformed npm tarball contents line" };
         }
         const totalMatch = line.match(/total files\s*:\s*(\d+)/i) ?? line.match(/unpacked size\s*:\s*([\d.]+\s*[kKmMgGbB]+)/i);
         if (totalMatch?.[1]) {
@@ -52,5 +73,14 @@ export function parseNpmPackDryRun(stdout) {
             parseError: "npm pack --dry-run: no files detected in tarball contents section",
         };
     }
+    if (files.some((file) => !safeInventoryPath(file))) {
+        return { files: [], parseError: "npm pack contains an unsafe file path" };
+    }
     return { files, totalSize };
 }
+function safeInventoryPath(file) {
+    const normalized = file.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
+    return Boolean(normalized) && !normalized.startsWith("/") &&
+        !/[\x00-\x1f\x7f:]/.test(normalized) &&
+        normalized.split("/").every((part) => Boolean(part) && part !== "." && part !== "..");
+}

package/dist/src/securityValidation/packageChecks/requiredPackageContents.js

@@ -1,3 +1,5 @@
+import fs from "node:fs/promises";
+import path from "node:path";
 export const REQUIRED_PACKAGE_CONTENTS = [
     "CHANGELOG.md",
     "LICENSE",
@@ -20,15 +22,117 @@ export const REQUIRED_PACKAGE_CONTENTS = [
     "examples/token-savings-cases.json",
 ];
 function normalizeTarballPath(file) {
-    const normalized = file.replace(/\\/g, "/");
+    const normalized = file.replace(/\\/g, "/").replace(/^(\.\/)+/, "");
     return normalized.startsWith("package/")
         ? normalized.slice("package/".length)
         : normalized;
 }
+// Policy belongs beside the existing required-file detector. Identity is
+// supplied by the existing target resolver, never inferred from package name.
+export async function requiredContentsForTarget(target) {
+    const required = new Set(target.isSelf ? REQUIRED_PACKAGE_CONTENTS : ["package.json"]);
+    const findings = [];
+    function invalid(field, reason) {
+        findings.push({
+            id: `npm-pack-metadata-${findings.length}`,
+            title: `Package metadata cannot be validated: ${field}`,
+            severity: "blocker",
+            category: "package-content",
+            description: reason,
+            evidence: `package.json field: ${field}; ${reason}`,
+            affectedFiles: ["package.json"],
+            recommendation: "Provide readable package metadata with supported, safe package-relative entrypoint paths and rerun validation.",
+            releaseImpact: "Blocker: required package evidence is incomplete",
+        });
+    }
+    function entry(value, field, exportsPath = false) {
+        if (typeof value !== "string") {
+            invalid(field, "Malformed entrypoint: expected a nonempty string.");
+            return;
+        }
+        const normalized = value.replace(/\\/g, "/");
+        const relative = normalized.replace(/^(\.\/)+/, "");
+        if (!relative || normalized !== normalized.trim() ||
+            /[\x00-\x1f\x7f:*?#%]/.test(normalized) || normalized.startsWith("/") ||
+            relative.split("/").some((part) => !part || part === ".." || part === "." || part === "node_modules") ||
+            (exportsPath && !normalized.startsWith("./"))) {
+            invalid(field, "Unsafe or unsupported entrypoint path (absolute, escaping, pattern, URL, or ambiguous path).");
+            return;
+        }
+        required.add(relative);
+    }
+    try {
+        const metadata = JSON.parse(await fs.readFile(path.join(target.targetRoot, "package.json"), "utf8"));
+        if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+            invalid("package.json", "Malformed package metadata: expected an object.");
+        }
+        else if (!target.isSelf) {
+            const pkg = metadata;
+            if ("bin" in pkg) {
+                if (typeof pkg.bin === "string")
+                    entry(pkg.bin, "bin");
+                else if (pkg.bin && typeof pkg.bin === "object" && !Array.isArray(pkg.bin)) {
+                    for (const key of Object.keys(pkg.bin).sort()) {
+                        if (!key || key === "." || key === ".." || /[\\/:\x00-\x1f\x7f]/.test(key)) {
+                            invalid("bin", "Unsafe or unsupported executable name in bin map.");
+                        }
+                        else
+                            entry(pkg.bin[key], `bin.${key}`);
+                    }
+                }
+                else
+                    invalid("bin", "Malformed bin: expected a string or object map.");
+            }
+            if ("main" in pkg) {
+                if (typeof pkg.main === "string" && pkg.main && !path.posix.extname(pkg.main.replace(/\\/g, "/"))) {
+                    invalid("main", "Unsupported or ambiguous main: extensionless or directory resolution is not validated; declare an exact runtime file.");
+                }
+                else
+                    entry(pkg.main, "main");
+            }
+            if ("exports" in pkg && pkg.exports !== null) {
+                if (typeof pkg.exports === "string")
+                    entry(pkg.exports, "exports", true);
+                else if (pkg.exports && typeof pkg.exports === "object" && !Array.isArray(pkg.exports)) {
+                    const exports = pkg.exports;
+                    const keys = Object.keys(exports).sort();
+                    if (!keys.length || keys.some((key) => key !== "." && (!key.startsWith("./") || /[\\:*?#%\x00-\x1f\x7f]/.test(key) ||
+                        key.slice(2).split("/").some((part) => !part || part === "." || part === "..")))) {
+                        invalid("exports", "Unsupported or ambiguous exports: conditional or pattern mappings require additional evidence.");
+                    }
+                    else
+                        for (const key of keys) {
+                            if (exports[key] === null)
+                                continue; // Explicitly excluded subpath.
+                            if (typeof exports[key] !== "string") {
+                                invalid(`exports.${key}`, "Unsupported exports shape: conditional objects and fallback arrays are not validated.");
+                            }
+                            else
+                                entry(exports[key], `exports.${key}`, true);
+                        }
+                }
+                else
+                    invalid("exports", "Unsupported exports shape: expected an exact string or subpath map.");
+            }
+            // npm automatically ships existing root README and license files. Do not
+            // invent a documentation requirement for packages without those files.
+            for (const file of (await fs.readdir(target.targetRoot, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+                if (file.isFile() && /^(readme|licen[cs]e)(\..*)?$/i.test(file.name))
+                    required.add(file.name);
+            }
+        }
+    }
+    catch {
+        invalid("package.json", "Package metadata is missing, unreadable, or unparseable.");
+    }
+    return { requiredFiles: [...required].sort(), findings };
+}
 export function detectMissingRequiredContents(options) {
     const present = new Set(options.files.map(normalizeTarballPath));
     const required = [...(options.requiredFiles ?? REQUIRED_PACKAGE_CONTENTS)]
-        .map(normalizeTarballPath)
+        // Requirements are package-relative declarations, not archive paths. A
+        // literal package/ directory in an entrypoint must not be stripped.
+        .map((file) => file.replace(/\\/g, "/").replace(/^(\.\/)+/, ""))
         .sort((left, right) => left.localeCompare(right));
     const missing = required.filter((file) => !present.has(file));
     const findings = missing.map((file, index) => ({

package/dist/src/securityValidation/packageChecks/runPackageChecks.js

@@ -3,7 +3,9 @@ import { runSecurityCommand, resolveNpmCommand } from "../commandRunner.js";
 import { writeCheckResult } from "../artifacts.js";
 import { parseNpmPackDryRun } from "./parseNpmPackDryRun.js";
 import { detectForbiddenContents } from "./forbiddenPackageContents.js";
-import { detectMissingRequiredContents } from "./requiredPackageContents.js";
+import { detectMissingRequiredContents, requiredContentsForTarget } from "./requiredPackageContents.js";
+import { resolveValidationTarget } from "../validate/resolveTarget.js";
+import { discoverPackageRoot } from "../../runtime/packageRoot.js";
 // Run npm pack --dry-run and inspect the resulting file list for forbidden contents.
 // Does not publish anything.
 export async function runPackageChecks(options) {
@@ -12,20 +14,23 @@ export async function runPackageChecks(options) {
     const allFindings = [];
     const checks = [];
     const npm = resolveNpmCommand();
+    const target = options.target ?? resolveValidationTarget(path.resolve(cwd), discoverPackageRoot());
+    if (path.resolve(target.targetRoot) !== path.resolve(cwd)) {
+        throw new Error("Package check cwd does not match the resolved target root");
+    }
+    const policy = await requiredContentsForTarget(target);
     // npm pack --dry-run to get the tarball file list
     const startedAt = new Date().toISOString();
     const cmd = await runSecurityCommand({
         command: npm,
-        args: ["pack", "--dry-run"],
+        args: ["pack", "--dry-run", "--json", "--ignore-scripts", "--cache", path.resolve(rawOutputDir, "npm-cache")],
         cwd,
         timeoutMs: commandTimeoutMs,
     });
     const finishedAt = new Date().toISOString();
-    // npm pack --dry-run writes the tarball filename to stdout on some npm
-    // versions and the detailed file list to stderr. Prefer whichever stream
-    // contains the tarball contents section, then fall back to combined output.
-    const packOutput = [cmd.stdout, cmd.stderr].find((stream) => /tarball contents/i.test(stream)) ??
-        [cmd.stdout, cmd.stderr].filter(Boolean).join("\n");
+    // Supported npm versions emit JSON on stdout. Lifecycle scripts are disabled
+    // so inspection cannot build, install, or rewrite the target.
+    const packOutput = cmd.stdout;
     const parsed = parseNpmPackDryRun(packOutput);
     const { findings: contentFindings } = detectForbiddenContents({
         files: parsed.files,
@@ -36,20 +41,28 @@ export async function runPackageChecks(options) {
     const { findings: missingRequiredFindings } = detectMissingRequiredContents({
         files: parsed.files,
         checkId: "npm-pack",
+        requiredFiles: policy.requiredFiles,
     });
-    const packageFindings = [...contentFindings, ...missingRequiredFindings];
+    const evidenceFindings = [];
+    if (cmd.exitCode !== 0 || cmd.timedOut || cmd.skipped || parsed.parseError || parsed.files.length === 0) {
+        evidenceFindings.push({
+            id: "npm-pack-evidence-invalid",
+            title: "npm package inventory could not be validated",
+            severity: "blocker",
+            category: "package-content",
+            description: "A successful npm pack operation and a nonempty, parseable inventory are required.",
+            evidence: `exitCode=${String(cmd.exitCode)}; timedOut=${cmd.timedOut}; skipped=${cmd.skipped}; ${parsed.parseError ?? ""}; ${cmd.stderr.slice(0, 500)}`,
+            recommendation: "Resolve the package command or inventory failure and rerun validation.",
+            releaseImpact: "Blocker: required package evidence is unavailable",
+        });
+    }
+    const packageFindings = [...policy.findings, ...evidenceFindings, ...contentFindings, ...missingRequiredFindings];
     allFindings.push(...packageFindings);
     const packCheck = {
         id: "npm-pack-dry-run",
         name: "npm pack --dry-run (tarball file list)",
         category: "package-content",
-        status: cmd.timedOut
-            ? "failed"
-            : parsed.parseError && parsed.files.length === 0
-                ? "warning"
-                : packageFindings.length > 0
-                    ? "failed"
-                    : "passed",
+        status: packageFindings.length > 0 ? "failed" : "passed",
         severity: packageFindings.length > 0
             ? packageFindings.some((f) => f.severity === "blocker")
                 ? "blocker"
@@ -60,7 +73,9 @@ export async function runPackageChecks(options) {
         durationMs: cmd.durationMs,
         findings: packageFindings,
         skippedReason: undefined,
-        command: "npm pack --dry-run",
+        command: "npm pack --dry-run --json --ignore-scripts",
+        commandCwd: cwd,
+        exitCode: cmd.exitCode,
     };
     await writeCheckResult({
         result: packCheck,

package/dist/src/securityValidation/staticScans/semgrep.js

@@ -5,16 +5,35 @@ import { resolveCommand } from "../../core/resolveCommand.js";
 import { skippedCheck } from "../cliAdversarial/runAdversarialCheck.js";
 export function parseSemgrepJson(raw) {
     if (!raw.trim()) {
-        return { findings: [], rawOutput: raw };
+        return { findings: [], parseError: "Semgrep produced no JSON scan evidence", rawOutput: raw };
     }
     try {
         const parsed = JSON.parse(raw);
-        const results = Array.isArray(parsed["results"]) ? parsed["results"] : [];
-        const findings = results.map((r) => {
+        if (!isRecord(parsed) || !Array.isArray(parsed.results)) {
+            return { findings: [], parseError: "Semgrep JSON requires a results array", rawOutput: raw };
+        }
+        const findings = [];
+        let parseError = !Array.isArray(parsed.errors) || !isRecord(parsed.paths) ||
+            !Array.isArray(parsed.paths.scanned) || parsed.paths.scanned.some((file) => typeof file !== "string")
+            ? "Semgrep JSON requires errors and paths.scanned arrays" : undefined;
+        for (const [index, r] of parsed.results.entries()) {
+            if (!isRecord(r) || typeof r.check_id !== "string" || !r.check_id ||
+                typeof r.path !== "string" || !r.path || !isRecord(r.start) ||
+                !Number.isInteger(r.start.line) || Number(r.start.line) < 1 || !isRecord(r.extra) ||
+                (r.extra.message !== undefined && typeof r.extra.message !== "string") ||
+                (r.extra.metadata !== undefined && !isRecord(r.extra.metadata))) {
+                parseError ??= `Malformed Semgrep result at index ${index}`;
+                continue;
+            }
             const item = r;
             const checkId = typeof item["check_id"] === "string" ? item["check_id"] : "unknown";
             const extra = item["extra"] ?? {};
             const metadata = extra["metadata"] ?? {};
+            if ((extra.severity !== undefined && (typeof extra.severity !== "string" || !extra.severity.trim())) ||
+                (extra.severity === undefined && (typeof metadata.severity !== "string" || !metadata.severity.trim()))) {
+                parseError ??= `Missing or malformed Semgrep severity at index ${index}`;
+                continue;
+            }
             const severity = typeof extra["severity"] === "string"
                 ? extra["severity"]
                 : typeof metadata["severity"] === "string"
@@ -24,9 +43,14 @@ export function parseSemgrepJson(raw) {
             const filePath = typeof item["path"] === "string" ? item["path"] : "";
             const startObj = item["start"] ?? {};
             const line = typeof startObj["line"] === "number" ? startObj["line"] : 0;
-            return { ruleId: checkId, severity, message, path: filePath, line };
-        });
-        return { findings, rawOutput: raw };
+            findings.push({ ruleId: checkId, severity, message, path: filePath, line });
+        }
+        // Semgrep's CLI contract reports partial/fatal analysis in errors even
+        // when the process exits zero. Retain matches, but never call this clean.
+        const analysisError = Array.isArray(parsed.errors) && parsed.errors.length > 0
+            ? `Semgrep reported ${parsed.errors.length} analysis error(s): ${JSON.stringify(parsed.errors).slice(0, 500)}`
+            : undefined;
+        return { findings, parseError, analysisError, rawOutput: raw };
     }
     catch (err) {
         return {
@@ -36,6 +60,9 @@ export function parseSemgrepJson(raw) {
         };
     }
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function semgrepSeverityToSecurity(semgrepSeverity) {
     switch (semgrepSeverity.toUpperCase()) {
         case "ERROR":
@@ -88,67 +115,25 @@ export async function runSemgrepCheck(options) {
         "--quiet",
         scanTarget,
     ];
-    const cmd = await runSecurityCommand({
-        command,
-        args: scanArgs,
-        cwd: targetRoot,
-        timeoutMs,
-    });
+    let cmd;
+    try {
+        cmd = await runSecurityCommand({ command, args: scanArgs, cwd: targetRoot, timeoutMs });
+    }
+    catch (error) {
+        cmd = { command, args: scanArgs, cwd: targetRoot, exitCode: null, durationMs: 0,
+            stdout: "", stderr: error instanceof Error ? error.message : String(error), timedOut: false, skipped: false };
+    }
     const finishedAt = new Date().toISOString();
-    // Semgrep exits 0 = no findings, 1 = findings found, other = error.
-    const isError = cmd.exitCode !== 0 && cmd.exitCode !== 1;
-    const isTimedOut = cmd.timedOut;
-    if (isTimedOut || (isError && !cmd.stdout.trim())) {
-        return {
-            id: "semgrep-scan",
-            name: "Semgrep static analysis",
-            category: "static-scan",
-            status: "failed",
-            severity: "major",
-            startedAt,
-            finishedAt,
-            durationMs: cmd.durationMs,
-            findings: [
-                {
-                    id: "semgrep-execution-error",
-                    title: "Semgrep execution failed",
-                    severity: "major",
-                    category: "static-scan",
-                    description: isTimedOut
-                        ? "Semgrep timed out."
-                        : `Semgrep exited with code ${String(cmd.exitCode)}. stderr: ${cmd.stderr.slice(0, 500)}`,
-                    recommendation: "Check semgrep installation and .semgrep.yml config.",
-                    releaseImpact: "Review before release",
-                },
-            ],
-            command: [command, ...scanArgs].join(" "),
-        };
+    // Distinguish positively established absence from a failed attempted scan.
+    // Network, permission, generic npm, or native spawn errors are not absence.
+    const unavailable = !cmd.timedOut && cmd.exitCode !== 0 && !cmd.stdout.trim() && ((cmd.skipped && cmd.exitCode === null && Boolean(cmd.skippedReason?.match(/\b(semgrep|scanner|cli)\b.*(unavailable|not installed|not found|not on PATH)/i))) ||
+        (useNpx && !cmd.skipped && cmd.exitCode === 1 && /could not determine executable to run/i.test(cmd.stderr)));
+    if (unavailable) {
+        return { ...skippedCheck({ id: "semgrep-scan", name: "Semgrep static analysis", category: "static-scan",
+                reason: cmd.skippedReason ?? "Semgrep CLI is unavailable; the npx fallback package provides no executable." }),
+            command: [command, ...scanArgs].join(" "), commandCwd: targetRoot, exitCode: cmd.exitCode };
     }
     const parsed = parseSemgrepJson(cmd.stdout);
-    if (parsed.parseError) {
-        return {
-            id: "semgrep-scan",
-            name: "Semgrep static analysis",
-            category: "static-scan",
-            status: "warning",
-            severity: "minor",
-            startedAt,
-            finishedAt,
-            durationMs: cmd.durationMs,
-            findings: [
-                {
-                    id: "semgrep-parse-error",
-                    title: "Could not parse Semgrep output",
-                    severity: "minor",
-                    category: "static-scan",
-                    description: `JSON parse error: ${parsed.parseError}`,
-                    recommendation: "Verify semgrep version produces valid JSON output.",
-                    releaseImpact: "Review before release",
-                },
-            ],
-            command: [command, ...scanArgs].join(" "),
-        };
-    }
     const securityFindings = parsed.findings.map((f) => ({
         id: `semgrep-${f.ruleId.replace(/[^a-z0-9-]/gi, "-")}`,
         title: f.ruleId,
@@ -160,6 +145,23 @@ export async function runSemgrepCheck(options) {
             ? "Should fix before release"
             : "Review before release",
     }));
+    const executionFailed = cmd.timedOut || cmd.skipped || (cmd.exitCode !== 0 && cmd.exitCode !== 1) ||
+        (cmd.exitCode === 1 && parsed.findings.length === 0);
+    const evidenceError = executionFailed
+        ? `Semgrep execution failed: exitCode=${String(cmd.exitCode)}, timedOut=${cmd.timedOut}, skipped=${cmd.skipped}. ${cmd.stderr.slice(0, 500)}`
+        : parsed.parseError ?? parsed.analysisError;
+    if (evidenceError) {
+        securityFindings.push({
+            id: executionFailed ? "semgrep-execution-error" : parsed.parseError ? "semgrep-parse-error" : "semgrep-analysis-error",
+            title: "Semgrep scan evidence is incomplete or unsuccessful",
+            severity: "major",
+            category: "static-scan",
+            description: evidenceError,
+            evidence: `exitCode=${String(cmd.exitCode)}; ${parsed.parseError ?? parsed.analysisError ?? ""}`,
+            recommendation: "Resolve the scanner execution or analysis error and rerun with valid JSON scan evidence.",
+            releaseImpact: "Review before release",
+        });
+    }
     const hasBlockerOrMajor = securityFindings.some((f) => f.severity === "blocker" || f.severity === "major");
     return {
         id: "semgrep-scan",
@@ -176,5 +178,7 @@ export async function runSemgrepCheck(options) {
         durationMs: cmd.durationMs,
         findings: securityFindings,
         command: [command, ...scanArgs].join(" "),
+        commandCwd: targetRoot,
+        exitCode: cmd.exitCode,
     };
 }

package/dist/src/securityValidation/types.js

@@ -1,7 +1,3 @@
-// Core types for the my-dev-kit-lab security-validation framework.
-// These types describe the vocabulary for checks, findings, results, and verdicts
-// used by dependency checks (Prompt 3), CLI adversarial tests (Prompts 4–5),
-// static scans (Prompt 6), fuzz smoke tests (Prompt 7), and the release report (Prompt 8).
 export const SECURITY_SEVERITIES = [
     "blocker",
     "major",