@securecode-ai/mcp 0.5.4 → 0.5.6

package/dist/utils/verificationSandbox.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Verification sandbox — the real security boundary for LLM-generated tests.
+ *
+ * Phase 2 of the agent scan pipeline takes an LLM-generated test script and
+ * executes it on the user's machine. The previous implementation ran the
+ * script via `execFileSync` with the full `process.env` spread and only a
+ * decorative blocklist (`checkTestSafety`) in front. Prompt-injected code
+ * in the scanned source could ride into the verify-generate prompt and
+ * produce a test script that exfiltrated secrets, hit the network, or
+ * spawned processes — `checkTestSafety` missed `fetch`, `http`, `https`,
+ * `fs`, `dns`, `eval`, `new Function`, dynamic imports, and `process.env`
+ * access.
+ *
+ * This module replaces that with a real isolation boundary. Pluggable
+ * backends provide kernel-enforced isolation:
+ *
+ *   - DockerSandbox: `docker run --network=none --cpus=1
+ *     --memory=256m --pids-limit=64 --user 1000:1000 -v <workspace>:/workspace:ro`
+ *     — network disabled at the kernel level, workspace read-only, temp
+ *     dir as tmpfs, no host env, non-root user. Works for any Node/Python
+ *     test script unchanged.
+ *   - DenoSandbox: `deno run --allow-read=<workspace> --allow-write=<tmp>
+ *     --allow-env=NODE_ENV --no-prompt --no-remote` — real permission
+ *     model, no network, no arbitrary fs, no arbitrary env. Only works
+ *     for test scripts that don't use `require()` (Deno is ESM-only by
+ *     default); the verify-generate prompt must be told to emit
+ *     Deno-compatible code when Deno is the backend.
+ *
+ * If neither backend is available, `detectSandbox()` returns null and the
+ * caller MUST return INCONCLUSIVE. Never fall back to unrestricted
+ * `execFileSync` — that is the bug this module exists to fix.
+ *
+ * `checkTestSafety()` remains as defense-in-depth (it can reject scripts
+ * before we pay for a container start), but it is NOT the security
+ * boundary. The sandbox is.
+ */
+export interface SandboxExecuteOptions {
+    /** Execution mode: 'script' (default) runs a script via runner; 'command' runs a validated executable+args. */
+    mode?: 'script' | 'command';
+    /** Test script source code (required for mode='script'). */
+    script?: string;
+    /** Runner: 'node' | 'tsx' | 'bun' | 'python' | 'python3' | 'deno' | ... (required for mode='script'). */
+    runner?: string;
+    /** Validated executable (required for mode='command'). Passed as argv[0] — never via shell. */
+    executable?: string;
+    /** Validated args array (required for mode='command'). Each arg passed as a separate argv element. */
+    args?: string[];
+    /** Workspace root — mounted read-only into the sandbox. */
+    workspaceRoot: string;
+    /** Optional setup script run before the test (same sandbox). */
+    setupScript?: string | null;
+    /** Hard wall-clock timeout in ms. The sandbox kills the process at this boundary. */
+    timeoutMs: number;
+    /** AbortSignal — if aborted, the sandbox must kill the process and return. */
+    signal?: AbortSignal;
+}
+export interface SandboxExecuteResult {
+    verdict: 'pass' | 'fail' | 'error' | 'timeout' | 'blocked' | 'sandbox-unavailable' | 'cancelled';
+    output: string;
+    exitCode: number;
+    /** Identifier of the backend that ran the test (for logging). */
+    backend: string;
+}
+export interface SandboxBackend {
+    readonly name: string;
+    readonly available: boolean;
+    execute(opts: SandboxExecuteOptions): Promise<SandboxExecuteResult>;
+}
+/**
+ * Command-mode verdict: no PASS:/FAIL: markers. Exit code 0 = pass, nonzero = fail.
+ * This is the standard semantics for `npm test`, `pytest`, etc.
+ */
+export declare function parseVerdictCommandMode(exitCode: number, timedOut: boolean): SandboxExecuteResult['verdict'];
+/**
+ * Pick the Docker image for a command-mode executable. Returns null if no
+ * suitable image is configured — the caller returns sandbox-unavailable.
+ */
+export declare function pickImageForCommand(executable: string): {
+    image: string | null;
+    reason?: string;
+};
+/**
+ * Pick the Docker image for a script-mode runner. Returns null if no suitable
+ * image is configured — the caller returns sandbox-unavailable so the user
+ * gets a clear "install X / set ENV to enable" message rather than a crash.
+ */
+export declare function pickImageForRunner(runner: string): {
+    image: string | null;
+    reason?: string;
+};
+/**
+ * Build the in-container command string for a runner + script path.
+ * The path is generated by us (unique suffix), so shell quoting is not
+ * required for safety; we still quote defensively in case the workspace
+ * path contains spaces.
+ */
+export declare function runnerInvocation(runner: string, scriptPath: string): string;
+/**
+ * Detect the best available sandbox backend. Docker is preferred (runs any
+ * Node/Python test unchanged); Deno is a fallback for TS/JS tests only.
+ * Returns null if neither is available — the caller MUST return INCONCLUSIVE.
+ */
+export declare function detectSandbox(): SandboxBackend | null;
+/** Reset the cached backend selection. Used by tests. */
+export declare function _resetSandboxCacheForTests(): void;
+/** Force a specific backend (for tests). Pass null to simulate "no sandbox". */
+export declare function _setSandboxForTests(backend: SandboxBackend | null): void;
+export declare class __UnsafeHostSandboxForTests implements SandboxBackend {
+    readonly name = "unsafe-host-tests-only";
+    constructor();
+    get available(): boolean;
+    execute(opts: SandboxExecuteOptions): Promise<SandboxExecuteResult>;
+}