@dailephd/my-dev-kit-lab 0.2.1 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dailephd LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,10 @@
 # my-dev-kit-lab
 
-my-dev-kit-lab is the experiment, evidence, reporting, and demo companion for [my-dev-kit](https://github.com/your-org/my-dev-kit). It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, and builds gallery outputs.
+my-dev-kit-lab is the experiment, evidence, reporting, security-validation, and future audit companion for my-dev-kit. It runs reproducible experiments that test whether my-dev-kit's graph-guided retrieval helps coding-agent workflows, collects metrics, renders reports, generates plots, captures screenshots, builds gallery outputs, and performs automated CLI/package security validation.
 
-As of v0.2.1, my-dev-kit-lab also exposes a generic experiment-plugin framework for validating local developer tools, security checks, codebase workflows, retrieval strategies, and experiment outcomes. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
+The current package is v0.2.2, release-prepared but not yet published to npm. Its generic experiment-plugin framework was introduced in v0.2.0. The first plugin is `context-strategy-comparison`, which preserves the existing raw-full-file vs my-dev-kit-guided workflow through the plugin runner.
+
+my-dev-kit is most useful when the repository is larger than the task. It helps coding agents work with large codebases through reusable structural indexing, graph-guided retrieval, targeted source slices, and auditable context selection. Results are scoped evidence; the project does not claim that my-dev-kit always saves tokens.
 
 **my-dev-kit** is the repo indexing and graph-guided retrieval engine.
 **my-dev-kit-lab** is the separate lab layer that feeds it benchmark inputs and records evaluation outputs.
@@ -29,7 +31,7 @@ As of v0.2.1, my-dev-kit-lab also exposes a generic experiment-plugin framework
 - First experiment plugin: `context-strategy-comparison`
 - Target-aware experiment execution for local projects via `experiment:run -- --target <path>`
 - Plugin-aware JSON and HTML reports with plugin, target, variant, metric, artifact, warning, skip, and failure metadata
-- Security validation framework: dependency audit, package tarball inspection, CLI adversarial tests, static scans (CodeQL/Semgrep), bounded fuzz smoke, and release verdict — runnable against any local project via `security:validate --target <path>`
+- Security validation framework: dependency audit, package tarball inspection, CLI adversarial tests, static scans (CodeQL/Semgrep), bounded fuzz smoke, attack-scenario checks, and structured verdict/report output — runnable against any local project via `security:validate --target <path>`
 
 ---
 
@@ -37,19 +39,14 @@ As of v0.2.1, my-dev-kit-lab also exposes a generic experiment-plugin framework
 
 ```mermaid
 flowchart TD
-  A[Benchmark Projects] --> B[Prompt Variants]
-  B --> C[Agent Adapters\nfake-agent / Codex / Claude]
-  C --> D[Controlled Experiment Runner]
-  D --> E[Experiment Artifacts\nJSON]
-  E --> F[Report Renderer]
-  E --> G[Plot Generator]
-  E --> H[Visualization Demos]
-  F --> I[HTML Report + optional PNG]
-  G --> J[SVG Charts]
-  H --> K[Demo Artifacts]
-  I --> L[Gallery]
-  J --> L
-  K --> L
+  A[scripts/experiments] --> B[Experiment plugin registry + runner]
+  B --> C[context-strategy-comparison]
+  C --> D[Controlled experiment foundations]
+  D --> E[Plugin + legacy artifacts]
+  E --> F[Plugin-aware reports]
+  E --> G[Plots / screenshots / gallery]
+  H[scripts/security] --> I[Automated security validation]
+  I --> J[Security reports + verdict]
 ```
 
 ---
@@ -205,7 +202,7 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 
 ## Current baseline release positioning
 
-my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. v0.2.1 keeps the generic experiment-plugin framework, preserves `context-strategy-comparison` as the first plugin, and fixes target-aware security validation so installed-package checks run `npm run test:security` in the external target project root.
+my-dev-kit-lab is at a working baseline. The raw-vs-indexed experiment pipeline is fully implemented and produces reproducible artifacts. Real-agent campaign support exists for Codex and Claude. The current package version is `v0.2.2`, which implements the automated security-validation fortification work described below and has passed pre-release readiness and cross-platform validation. `v0.2.2` has not yet been published to npm.
 
 ---
 
@@ -223,7 +220,7 @@ This is not a web application pentest framework. **my-dev-kit** is a local CLI/p
 - database-free
 - safe to run on local repositories
 
-The release gate is implemented as of v0.1.4. It combines static scans, dependency/package checks, adversarial CLI tests, bounded fuzz smoke tests, and a structured release security report with a four-category verdict.
+The automated validation gate is implemented. It combines static scans, dependency/package checks, adversarial CLI tests, bounded fuzz smoke tests, and attack-scenario checks with structured text/JSON reports and a four-category verdict.
 
 ### Security commands
 
@@ -233,15 +230,23 @@ The release gate is implemented as of v0.1.4. It combines static scans, dependen
 | `npm run security:package` | npm pack --dry-run, forbidden content detection |
 | `npm run security:codeql` | CodeQL CLI availability check; skipped gracefully when absent |
 | `npm run security:semgrep` | Semgrep scan via local binary or npx; skipped gracefully when both absent |
-| `npm run test:security` | 165 adversarial CLI tests (path traversal, read-only boundaries, malformed artifacts, JSON safety, fuzz targets) |
+| `npm run test:security` | Automated security and adversarial CLI tests (path traversal, read-only boundaries, malformed artifacts, JSON safety, and related checks) |
 | `npm run test:fuzz:smoke` | 9 bounded fuzz targets, seeded PRNG, completes in under 1 second |
-| `npm run security:validate` | Full release gate — runs all checks and writes `reports/security/<prefix>-security-validation.{txt,json}` |
+| `npm run security:validate` | Runs selected security checks, applies profile-aware defaults when requested, and writes text/JSON reports according to `--format` |
+
+CodeQL, Semgrep, and OSV-Scanner are optional. When unavailable locally, they are recorded as `skipped` in the report, not as passed. That can lead to `ready except optional manual checks`; it does not silently turn missing tooling into a clean pass.
+
+Each security command can validate my-dev-kit-lab itself or another local project via `--target <path>`. When `--target` is omitted, the framework performs self-validation. Target projects are inspected in place: their source files are not modified by default, generated artifacts stay under `reports/security/` unless `--out` is used, and external-target reports identify the tool root, target root, target package metadata, target git metadata, command cwd, exit code, and stdout/stderr summaries.
+
+`security:validate` supports `--checks`, `--profile`, `--format`, `--fail-on`, `--out`, and `--report-prefix`. The no-flag path remains backward compatible and still runs the classic implemented check groups: `deps`, `package`, `static`, `cli-adversarial`, and `fuzz`. Supplying `--profile` without `--checks` swaps in that profile's default checks; supplying explicit `--checks` always wins over profile defaults.
+
+The current attack-scenario checks cover boundary, subprocess, secrets, and network assumptions. They are automated adversarial checks, not a manual pentest. `verdictImpact` metadata from each registered scenario drives blocker categorization in report reasoning, and narrowed `--checks` runs are labeled as scoped rather than described as a full release gate.
 
-CodeQL, Semgrep, and OSV-Scanner are optional. When unavailable locally, they are recorded as `skipped` in the report — not as failures — and the verdict is `ready except optional manual checks` rather than `not ready`.
+JSON report poisoning/config-injection checks use a baseline-diff schema guard so legitimate additive JSON fields do not fail the guard while payload-created trusted top-level fields still do. Text reports are sanitized to strip ANSI/control-byte payloads before rendering.
 
-Each security command can validate my-dev-kit-lab itself or another local project via `--target <path>`. When `--target` is omitted, the framework performs self-validation. Target projects are inspected in place: their source files are not modified, generated artifacts stay under `reports/security/`, and external-target reports identify the tool root, target root, target package metadata, target git metadata, command cwd, exit code, and stdout/stderr summaries.
-
-For external-target validation, `security:validate` reads the target `package.json`, detects `scripts.test:security`, and runs `npm run test:security` in the target project root when that script exists. This behavior is validated both from the source checkout and from an installed packed tarball because published-package execution differs from local source execution.
+Known limits remain intentionally explicit: secret scanning is bounded rather than exhaustive, the network/local-first check is a bounded static assumption check rather than proof of runtime isolation, package-boundary severity is still result-level rather than per-evidence-item, and profile-specific scenario behavior is limited to profile-based scenario selection/default checks.
+
+For external-target validation, `security:validate` reads the target `package.json`, detects `scripts.test:security`, and runs `npm run test:security` in the target project root when that script exists. This behavior is validated both from the source checkout and from an installed packed tarball because published-package execution differs from local source execution.
 
 Generated security reports under `reports/security/` are excluded from git by default. They are produced locally or in CI as release-gate evidence and are not committed to the repository.
 
@@ -249,6 +254,12 @@ See [docs/COMMANDS.md](docs/COMMANDS.md) for full command options and [docs/secu
 
 ---
 
+## License
+
+MIT License. See [LICENSE](LICENSE) for the full text.
+
+---
+
 ## Support
 
 my-dev-kit-lab is an independent project by dailephd LLC, developed and maintained by Dai Le.

package/dist/scripts/security/validate.js

@@ -4,11 +4,34 @@ import fs from "node:fs";
 import { runSecurityValidation } from "../../src/securityValidation/validate/runSecurityValidation.js";
 import { resolveValidationTarget, reportFilenamePrefix } from "../../src/securityValidation/validate/resolveTarget.js";
 import { renderTextReport, renderJsonReport } from "../../src/securityValidation/report/renderSecurityReport.js";
+import { parseSecurityValidateArgs, normalizeSecurityValidateConfig, applyProfileDefaultChecksIfApplicable, } from "../../src/securityValidation/validate/cliOptions.js";
+import { resolveAttackProfile } from "../../src/securityValidation/attackScenarios/attackProfile.js";
+import { findingsBreachFailOnThreshold } from "../../src/securityValidation/validate/verdict.js";
 import { resolveToolRoot } from "./resolveToolRoot.js";
+const USAGE = "Usage: npm run security:validate -- [--target <path>] [--out <dir>] [--report-prefix <name>] " +
+    "[--checks deps,package,static,cli-adversarial,fuzz,boundary,subprocess,secrets,network] " +
+    "[--profile node-cli-package|local-tool|npm-package] [--format text,json] [--fail-on blocker|high|medium|low]";
 // Parse CLI arguments from process.argv (after the node/tsx and script path).
 const rawArgs = process.argv.slice(2);
-const args = parseArgs(rawArgs);
 const toolRoot = resolveToolRoot(import.meta.url);
+let args;
+let config;
+try {
+    args = parseSecurityValidateArgs(rawArgs);
+    config = normalizeSecurityValidateConfig(args, toolRoot);
+    // v0.2.2 Batch 5: --profile with no --checks uses that profile's declared
+    // default checks. No-op unless the user passed --profile without --checks
+    // (see applyProfileDefaultChecksIfApplicable's guard) — the true no-flag
+    // case and any explicit --checks case are always unaffected.
+    config = applyProfileDefaultChecksIfApplicable(config, resolveAttackProfile(config.profile).defaultCheckIds);
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`\nERROR: ${msg}`);
+    console.error(USAGE);
+    process.exitCode = 1;
+    process.exit(1);
+}
 // Resolve and validate target early so we can fail fast with a clean error.
 let target;
 try {
@@ -17,7 +40,7 @@ try {
 catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`\nERROR: ${msg}`);
-    console.error("Usage: npm run security:validate -- [--target <path>] [--out <dir>] [--report-prefix <name>]");
+    console.error(USAGE);
     process.exitCode = 1;
     process.exit(1);
 }
@@ -33,13 +56,30 @@ if (!target.isSelf) {
 else {
     console.log(`Mode       : self-validation`);
 }
+if (!config.checksWereDefault) {
+    console.log(`Checks     : ${config.checks.join(", ")}`);
+}
+if (config.plannedChecksRequested.length > 0) {
+    console.log(`Note       : ${config.plannedChecksRequested.join(", ")} are routed through the attack-scenario framework rather than the classic check-group runners. Review the attack-scenario section in the report for their concrete results.`);
+}
 console.log("");
 const summary = await runSecurityValidation({
     cwd: toolRoot,
     targetPath: args.target,
     fuzzIterations: parseInt(process.env["FUZZ_ITERATIONS"] ?? "50", 10),
     fuzzSeed: parseInt(process.env["FUZZ_SEED"] ?? "0xDEADBEEF", 16),
+    // Full selection (implemented + planned/attack-scenario ids) — the runner
+    // gates both implemented check groups and attack-scenario checks off the
+    // same selectedChecks set.
+    selectedChecks: config.checks,
+    profile: config.profile,
 });
+// v0.2.2 Batch 5: --fail-on breach is additive to (never a substitute for)
+// the existing verdict-based exit decision below — it can only escalate
+// exit 0 to exit 1 (e.g. --fail-on medium/low catching minor/informational
+// findings the verdict policy doesn't already treat as blocking), never
+// downgrade an existing blocker.
+const failOnBreached = findingsBreachFailOnThreshold(summary.findings, config.failOnThreshold);
 // Build report object
 const report = {
     metadata: {
@@ -55,19 +95,25 @@ const report = {
         isSelf: summary.isSelf,
         generatedAt: summary.finishedAt,
         totalDurationMs: new Date(summary.finishedAt).getTime() - new Date(summary.startedAt).getTime(),
+        profile: config.profile,
+        selectedChecks: config.checks,
+        failOnThreshold: config.failOnThreshold,
+        formats: config.formats,
+        failOnBreached,
+        isFullReleaseGate: summary.isFullReleaseGate,
     },
     sections: [],
     allChecks: summary.checks,
     allFindings: summary.findings,
     verdict: summary.verdict,
     recommendedNextStep: summary.recommendedNextStep,
+    attackResults: summary.attackResults,
+    verdictReasonSummary: summary.verdictReasonSummary,
 };
 const textReport = renderTextReport(report);
 const jsonReport = renderJsonReport(report);
 // Determine output directory
-const reportsDir = args.out
-    ? path.resolve(args.out)
-    : path.join(toolRoot, "reports", "security");
+const reportsDir = config.out;
 if (!fs.existsSync(reportsDir)) {
     fs.mkdirSync(reportsDir, { recursive: true });
 }
@@ -75,14 +121,22 @@ if (!fs.existsSync(reportsDir)) {
 const prefix = args.reportPrefix ?? reportFilenamePrefix(target);
 const txtPath = path.join(reportsDir, `${prefix}-security-validation.txt`);
 const jsonPath = path.join(reportsDir, `${prefix}-security-validation.json`);
-fs.writeFileSync(txtPath, textReport, "utf8");
-fs.writeFileSync(jsonPath, jsonReport, "utf8");
+const writtenPaths = [];
+if (config.formats.includes("text")) {
+    fs.writeFileSync(txtPath, textReport, "utf8");
+    writtenPaths.push(txtPath);
+}
+if (config.formats.includes("json")) {
+    fs.writeFileSync(jsonPath, jsonReport, "utf8");
+    writtenPaths.push(jsonPath);
+}
 // Print report to stdout
 console.log(textReport);
 console.log(`\nReports written:`);
-console.log(`  ${txtPath}`);
-console.log(`  ${jsonPath}`);
-// Exit code based on verdict
+for (const p of writtenPaths) {
+    console.log(`  ${p}`);
+}
+// Exit code based on verdict, escalated (never downgraded) by --fail-on.
 const blockerExists = summary.verdict === "not-ready-security-blocker-remains";
 const inconclusive = summary.verdict === "inconclusive-audit-environment-incomplete";
 if (blockerExists) {
@@ -93,26 +147,11 @@ else if (inconclusive) {
     console.warn("\nExit 2 — audit environment incomplete.");
     process.exitCode = 2;
 }
+else if (failOnBreached) {
+    console.error(`\nExit 1 — --fail-on ${config.failOnThreshold} threshold breached.`);
+    process.exitCode = 1;
+}
 else {
     console.log("\nExit 0 — validation completed.");
     process.exitCode = 0;
 }
-// ---------------------------------------------------------------------------
-// Argument parser
-// ---------------------------------------------------------------------------
-function parseArgs(argv) {
-    const result = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if ((arg === "--target" || arg === "-t") && i + 1 < argv.length) {
-            result.target = argv[++i];
-        }
-        else if (arg === "--out" && i + 1 < argv.length) {
-            result.out = argv[++i];
-        }
-        else if (arg === "--report-prefix" && i + 1 < argv.length) {
-            result.reportPrefix = argv[++i];
-        }
-    }
-    return result;
-}

package/dist/src/securityValidation/attackScenarios/attackProfile.js

@@ -0,0 +1,20 @@
+import { SECURITY_PROFILE_IDS } from "../validate/cliOptions.js";
+import { NODE_CLI_PACKAGE_PROFILE } from "./profiles/nodeCliPackageProfile.js";
+import { LOCAL_TOOL_PROFILE } from "./profiles/localToolProfile.js";
+import { NPM_PACKAGE_PROFILE } from "./profiles/npmPackageProfile.js";
+const PROFILE_REGISTRY = {
+    "node-cli-package": NODE_CLI_PACKAGE_PROFILE,
+    "local-tool": LOCAL_TOOL_PROFILE,
+    "npm-package": NPM_PACKAGE_PROFILE,
+};
+// Resolves a profile id to its definition. Throws a clean, descriptive Error
+// for unknown ids (mirrors Batch 1's --profile validation error style).
+export function resolveAttackProfile(id) {
+    if (!SECURITY_PROFILE_IDS.includes(id)) {
+        throw new Error(`Unknown security profile: "${id}". Valid values are: ${SECURITY_PROFILE_IDS.join(", ")}.`);
+    }
+    return PROFILE_REGISTRY[id];
+}
+export function listAttackProfiles() {
+    return SECURITY_PROFILE_IDS.map((id) => PROFILE_REGISTRY[id]);
+}

package/dist/src/securityValidation/attackScenarios/attackResult.js

@@ -0,0 +1,37 @@
+// Bridges an AttackResult into the existing SecurityCheckResult shape so it
+// can flow through the existing verdict/report pipeline without redesigning
+// either. "blocked" (scenario crashed) maps to a failed check with severity
+// bumped to at least "major" so a scenario crash is never silently invisible.
+export function toSecurityCheckResult(result) {
+    const now = new Date().toISOString();
+    const status = result.status === "blocked" ? "failed" : result.status;
+    const severity = result.status === "blocked" && result.severity === "skipped" ? "major" : result.severity;
+    return {
+        id: result.scenarioId,
+        name: result.scenarioTitle,
+        category: result.category,
+        status,
+        severity,
+        startedAt: now,
+        finishedAt: now,
+        durationMs: 0,
+        findings: result.status === "failed" || result.status === "blocked"
+            ? [
+                {
+                    id: `${result.scenarioId}-finding`,
+                    title: result.scenarioTitle,
+                    severity,
+                    category: result.category,
+                    description: result.status === "blocked"
+                        ? `Scenario execution error: ${result.errorSummary ?? "unknown error"}`
+                        : `Attack scenario detected unsafe behavior for check group '${result.checkId}'.`,
+                    evidence: result.evidence.map((e) => e.redactedPreview).filter(Boolean).join(" | ") || undefined,
+                    recommendation: result.recommendation,
+                    releaseImpact: severity === "blocker" ? "Must fix before release" : "Should fix before release",
+                },
+            ]
+            : [],
+        skippedReason: result.skippedReason,
+        verdictImpact: result.verdictImpact,
+    };
+}

package/dist/src/securityValidation/attackScenarios/attackRunner.js

@@ -0,0 +1,153 @@
+import { CHECK_ID_CATEGORY } from "./attackScenario.js";
+import { TARGET_SANDBOX_SCENARIO } from "./scenarios/targetSandboxScenario.js";
+import { PACKAGE_BOUNDARY_SCENARIO } from "./scenarios/packageBoundaryScenario.js";
+import { OUTPUT_BOUNDARY_SCENARIO } from "./scenarios/outputBoundaryScenario.js";
+import { PATH_TRAVERSAL_SCENARIO } from "./scenarios/pathTraversalScenario.js";
+import { CONFIG_INJECTION_SCENARIO } from "./scenarios/configInjectionScenario.js";
+import { SUBPROCESS_INJECTION_SCENARIO } from "./scenarios/subprocessInjectionScenario.js";
+import { SECRET_LEAKAGE_SCENARIO } from "./scenarios/secretLeakageScenario.js";
+import { REPORT_POISONING_SCENARIO } from "./scenarios/reportPoisoningScenario.js";
+import { NETWORK_ASSUMPTION_SCENARIO } from "./scenarios/networkAssumptionScenario.js";
+import { registerScenarioPayloadGroups } from "./payloadCorpus.js";
+registerScenarioPayloadGroups(OUTPUT_BOUNDARY_SCENARIO.id, ["output-boundary"]);
+registerScenarioPayloadGroups(PATH_TRAVERSAL_SCENARIO.id, ["path-traversal"]);
+registerScenarioPayloadGroups(CONFIG_INJECTION_SCENARIO.id, ["malformed-config", "report-poisoning"]);
+registerScenarioPayloadGroups(SUBPROCESS_INJECTION_SCENARIO.id, ["subprocess-injection"]);
+registerScenarioPayloadGroups(REPORT_POISONING_SCENARIO.id, ["report-poisoning"]);
+// ---------------------------------------------------------------------------
+// v0.2.2 Batch 2/3/4 — attack scenario runner.
+//
+// SCENARIO_REGISTRY was empty in Batch 2. Batch 3 registered the first
+// concrete scenarios (boundary: target sandbox, package boundary, output
+// boundary, path traversal, config injection; subprocess: subprocess
+// injection). Batch 4 adds secret leakage (secrets), report poisoning
+// (boundary — report-rendering safety is a boundary-of-trust concern), and
+// network/local-first assumption (network). All 9 --checks ids now have at
+// least one registered scenario.
+// ---------------------------------------------------------------------------
+export const SCENARIO_REGISTRY = [
+    TARGET_SANDBOX_SCENARIO,
+    PACKAGE_BOUNDARY_SCENARIO,
+    OUTPUT_BOUNDARY_SCENARIO,
+    PATH_TRAVERSAL_SCENARIO,
+    CONFIG_INJECTION_SCENARIO,
+    REPORT_POISONING_SCENARIO,
+    SUBPROCESS_INJECTION_SCENARIO,
+    SECRET_LEAKAGE_SCENARIO,
+    NETWORK_ASSUMPTION_SCENARIO,
+];
+const DEFAULT_SCENARIO_TIMEOUT_MS = 30_000;
+// Selects scenarios whose checkId is in selectedChecks and whose
+// applicableProfiles either is empty (applies to all profiles) or includes
+// the given profile. Preserves registry order (deterministic).
+export function filterScenarios(scenarios, selectedChecks, profile) {
+    const checkSet = new Set(selectedChecks);
+    return scenarios.filter((s) => checkSet.has(s.checkId) && (s.applicableProfiles.length === 0 || s.applicableProfiles.includes(profile)));
+}
+async function withTimeout(promise, timeoutMs, scenarioId) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`Scenario '${scenarioId}' exceeded its ${timeoutMs}ms execution budget.`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+// Runs a single scenario, converting a skip condition, thrown error, or
+// timeout into a structured AttackResult rather than letting exceptions
+// propagate to the caller.
+export async function runScenario(scenario, ctx) {
+    const baseFields = {
+        scenarioId: scenario.id,
+        scenarioTitle: scenario.title,
+        checkId: scenario.checkId,
+        profileId: ctx.profile,
+    };
+    try {
+        const skipReason = scenario.skipCondition?.(ctx);
+        if (skipReason) {
+            return {
+                ...baseFields,
+                status: "skipped",
+                severity: "skipped",
+                confidence: "low",
+                evidence: [],
+                category: CHECK_ID_CATEGORY[scenario.checkId],
+                skippedReason: skipReason,
+            };
+        }
+        const outcome = await withTimeout(scenario.run(ctx), scenario.timeoutMs ?? DEFAULT_SCENARIO_TIMEOUT_MS, scenario.id);
+        return {
+            ...baseFields,
+            status: outcome.status,
+            severity: outcome.severity ?? scenario.severityBaseline,
+            confidence: outcome.confidence,
+            evidence: outcome.evidence,
+            category: outcome.category ?? CHECK_ID_CATEGORY[scenario.checkId],
+            recommendation: outcome.recommendation,
+            verdictImpact: scenario.verdictImpact,
+        };
+    }
+    catch (err) {
+        return {
+            ...baseFields,
+            status: "blocked",
+            severity: scenario.severityBaseline,
+            confidence: "low",
+            evidence: [],
+            category: CHECK_ID_CATEGORY[scenario.checkId],
+            errorSummary: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function unavailableResult(checkId, profile) {
+    return {
+        scenarioId: `${checkId}-no-scenarios-registered`,
+        scenarioTitle: `No attack scenarios registered for '${checkId}'`,
+        checkId,
+        profileId: profile,
+        status: "skipped",
+        severity: "skipped",
+        confidence: "low",
+        evidence: [],
+        category: CHECK_ID_CATEGORY[checkId],
+        skippedReason: `No attack scenarios are registered yet for check group '${checkId}'. ` +
+            `The attack-scenario framework is present (v0.2.2 Batch 2); concrete scenarios are planned for a later v0.2.2 batch. ` +
+            `This must not be treated as evidence that '${checkId}' is safe.`,
+    };
+}
+// Runs all scenarios matching selectedChecks/profile, then appends one
+// explicit "unavailable" placeholder result for every selected check that
+// matched zero scenarios. Safe when the scenario list is empty. Result order
+// is deterministic: matched scenarios in registry order, then unavailable
+// placeholders in selectedChecks order.
+export async function runAttackScenarios(options) {
+    const scenarios = options.scenarios ?? SCENARIO_REGISTRY;
+    const matched = filterScenarios(scenarios, options.selectedChecks, options.profile);
+    const ctx = {
+        toolRoot: options.toolRoot,
+        target: options.target,
+        profile: options.profile,
+        config: options.config,
+        targetSnapshotBefore: options.targetSnapshotBefore,
+    };
+    const results = [];
+    for (const scenario of matched) {
+        results.push(await runScenario(scenario, ctx));
+    }
+    const matchedCheckIds = new Set(matched.map((s) => s.checkId));
+    for (const checkId of options.selectedChecks) {
+        if (!matchedCheckIds.has(checkId)) {
+            results.push(unavailableResult(checkId, options.profile));
+        }
+    }
+    return results;
+}

package/dist/src/securityValidation/attackScenarios/attackScenario.js

@@ -0,0 +1,21 @@
+// ---------------------------------------------------------------------------
+// v0.2.2 Batch 2 — attack scenario contract.
+//
+// This is the shared interface later v0.2.2 batches implement concrete
+// scenarios against. Batch 2 intentionally ships with an empty scenario
+// registry (see attackRunner.ts) — this file only defines the shape.
+// ---------------------------------------------------------------------------
+// Maps a planned/attack-scenario check id to its default report category.
+// Used both when no scenarios are registered yet (placeholder result) and by
+// scenario authors as a sensible default category.
+export const CHECK_ID_CATEGORY = {
+    deps: "dependency-audit",
+    package: "package-content",
+    static: "static-scan",
+    "cli-adversarial": "cli-adversarial",
+    fuzz: "fuzz-smoke",
+    boundary: "artifact-safety",
+    subprocess: "cli-adversarial",
+    secrets: "secret-leakage",
+    network: "network-boundary",
+};

package/dist/src/securityValidation/attackScenarios/boundedSourceScan.js

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import { collectFilesForGlobs } from "../../core/fileGlobs.js";
+// ---------------------------------------------------------------------------
+// v0.2.2 Batch 4 — shared bounded, deterministic source-file scan helper.
+//
+// Reused by secretLeakageScenario and networkAssumptionScenario. Both need
+// "read a bounded, deterministic set of source-ish files, skip large/binary
+// content" and nothing more — collectFilesForGlobs() already provides
+// deterministic ordering and standard exclusions (node_modules, dist, build,
+// coverage, .git, lab-output, .my-dev-kit); this layer adds a size cap and a
+// small file-content allowlist filter for scenario-specific exclusions.
+// ---------------------------------------------------------------------------
+// Default bounded glob set: project manifests/config plus first-party source
+// and scripts. Deliberately excludes tests/, benchmarks/, examples/ — those
+// commonly contain intentionally fake secret-shaped fixtures (including this
+// project's own security payload corpus test suite) that would otherwise be
+// permanent false positives against this project's own repo.
+export const DEFAULT_SOURCE_SCAN_GLOBS = [
+    "package.json",
+    "package-lock.json",
+    "npm-shrinkwrap.json",
+    "tsconfig.json",
+    "tsconfig.*.json",
+    ".env",
+    ".env.*",
+    "src/**/*",
+    "scripts/**/*",
+];
+// Files that are deliberately excluded from scan output even though they
+// match a glob above — e.g. the payload corpus itself, which intentionally
+// contains fake-secret-shaped strings for Batch 2's test corpus.
+const KNOWN_SYNTHETIC_FIXTURE_FILES = new Set(["src/securityValidation/attackScenarios/payloadCorpus.ts"]);
+// Skip files larger than this to keep the scan bounded and fast; source
+// files this large are not expected in this project.
+const MAX_SCANNABLE_FILE_BYTES = 1_000_000;
+// A single NUL character, used as a cheap binary-file heuristic below.
+// Built via fromCharCode rather than a "\0" string escape to avoid any
+// literal control byte ending up in this source file.
+const NUL_CHAR = String.fromCharCode(0);
+// Returns file contents for the bounded glob set, skipping known synthetic
+// fixtures, oversized files, and anything unreadable as UTF-8 text (treated
+// as binary and skipped, not an error). Stable, deterministic order.
+export function collectBoundedSourceFiles(targetRoot, globs = DEFAULT_SOURCE_SCAN_GLOBS) {
+    // collectFilesForGlobs() throws for the *entire* call if any single glob's
+    // base path doesn't exist (e.g. no .env file, no tsconfig.*.json match) —
+    // resolve each glob independently so one missing/inapplicable glob doesn't
+    // silently zero out results for all the others.
+    const candidateMap = new Map();
+    for (const glob of globs) {
+        let matches;
+        try {
+            matches = collectFilesForGlobs(targetRoot, [glob]);
+        }
+        catch {
+            // This glob's base path doesn't exist for this target — a legitimate
+            // "nothing to scan for this pattern" outcome, not an error.
+            continue;
+        }
+        for (const m of matches) {
+            candidateMap.set(m.relativePath, m.absolutePath);
+        }
+    }
+    const candidates = [...candidateMap.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([relativePath, absolutePath]) => ({ relativePath, absolutePath }));
+    const files = [];
+    for (const candidate of candidates) {
+        const normalizedRel = candidate.relativePath.replace(/\\/g, "/");
+        if (KNOWN_SYNTHETIC_FIXTURE_FILES.has(normalizedRel))
+            continue;
+        let stat;
+        try {
+            stat = fs.statSync(candidate.absolutePath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.size > MAX_SCANNABLE_FILE_BYTES)
+            continue;
+        try {
+            const content = fs.readFileSync(candidate.absolutePath, "utf8");
+            if (content.indexOf(NUL_CHAR) !== -1)
+                continue;
+            files.push({ relativePath: normalizedRel, absolutePath: candidate.absolutePath, content });
+        }
+        catch {
+            continue;
+        }
+    }
+    return files;
+}
+// Returns the 1-based line number containing `index` within `content`.
+export function lineNumberAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i++) {
+        if (content[i] === "\n")
+            line++;
+    }
+    return line;
+}