gstack/lib/cso/scanner-executor.ts

/** Scanner orchestration is helper-owned; target/scanner commands only enter DockerGroup. */
import * as fs from 'node:fs';
import { randomBytes } from 'node:crypto';
import { join } from 'node:path';
import { Command, CoverageRecord, CsoError, HttpAssertion, RunPolicy, SnapshotManifest, canonical, object, relativePath, sha256, snapshotPathHandleId, snapshotReference, string, strings, validateCommand, validateVerificationObservation, type ErrorCode } from './contracts';
import { DockerEndpoint, DockerGroup, dockerEndpoint } from './docker';
import { inspectPreparation, type CsoStack } from './preparation';
import { redact } from './process';
import { QualifiedRuntime, RUNTIME_CATALOG, RuntimeCatalog, RuntimePlatform, assertRuntimeCompatible, selectRuntime } from './runtime-catalog';
import { QualifiedScanner, SCANNER_CATALOG, ScannerCatalog, assertScannerVersionOutput, scannerVersionHash, selectScanner } from './scanner-catalog';
import { ScannerExecution, ScannerGap, ScannerId, ScannerOutcome, ScannerPlan, parseScannerOutput, scannerPlans } from './scanners';
import { assertSnapshot } from './snapshot';
import { hasPendingWatchdogCleanup, secureDirectory } from './state';
import { PublicArchiveCache, publicArchiveCacheRoot } from './cache';
import { admitPreparationRuntime, admitPreparationSidecar, PreparationExecutor, type PreparationSandboxRunner, type RailsDatabaseSelection } from './preparation-executor';
import type { PreparedDatabaseContract } from './preparation-executor';
import { DockerPreparationSandboxRunner } from './preparation-docker';
import { canonicalStartPlan, type CanonicalStartPlan } from './verification';

export interface ScannerRequest {
  profile?: string;
  api?: {
    runtimeProfile: string;
    port: number;
    start: Command;
    control: HttpAssertion;
    boundaryFiles: string[];
    schema: Record<string, unknown>;
    operationIds: string[];
    seed?: number;
    maxExamples?: number;
  };
}
export interface ScannerRunInput {
  id: ScannerId;
  runId: string;
  runDir: string;
  manifest: SnapshotManifest;
  policy: RunPolicy;
  executionDeadline: number;
  platform: RuntimePlatform;
  request?: ScannerRequest;
  watchdogPath: string;
}
export interface ScannerRunRecord {
  outcome: ScannerOutcome;
  coverage: CoverageRecord;
  provenance: {
    scannerCatalog: string;
    profile: string | null;
    image: string | null;
    platform: RuntimePlatform;
    isolationPolicyHash: string | null;
    sourceHash: string;
    requestHash: string;
    versionOutputSha256: string | null;
    assets: QualifiedScanner['assets'] | null;
    network: 'none' | 'isolated-loopback';
    preparation: ScannerApplicationPreparation['proof'] | null;
  };
}
export interface ScannerApplicationPreparation {
  sourceRoot: string;
  environment: Record<string, string>;
  database?: PreparedDatabaseContract;
  proof: {
    dependencyClosureHash: string;
    preparedManifestHash: string;
    sourceProjectionHash: string;
    receiptHash: string;
    executionEnvironmentHash: string;
    databaseHash: string;
  };
  cleanup(): Promise<void>;
}
export interface ScannerRunner {
  version(): Promise<ScannerExecution>;
  scan(): Promise<ScannerExecution>;
  cleanup(): Promise<void>;
}
/** The trusted HTTP control probe is always the bounded verifier process. */
export function schemathesisControlRole(): 'verifier' { return 'verifier'; }
export interface ScannerRunnerContext {
  input: ScannerRunInput;
  plan: ScannerPlan;
  profile: QualifiedScanner;
  runtime?: QualifiedRuntime;
  application?: ScannerApplicationPreparation;
  deadline: number;
}
export type ScannerRunnerFactory = (context: ScannerRunnerContext) => Promise<ScannerRunner>;
export type ScannerApplicationPreparer = (context: {
  input: ScannerRunInput;
  runtime: QualifiedRuntime;
  stack: CsoStack;
  startPlan: CanonicalStartPlan;
  deadline: number;
  catalog: RuntimeCatalog;
}) => Promise<ScannerApplicationPreparation>;
export interface ScannerRunDependencies {
  catalog?: ScannerCatalog;
  runtimes?: RuntimeCatalog;
  /** Unit tests inject a runner to check dispatch/claims; this does not attest containment. */
  runnerFactory?: ScannerRunnerFactory;
  /** Unit tests may inject a materializer; production always uses the qualified offline preparation path. */
  applicationPreparer?: ScannerApplicationPreparer;
}

function exact(v: Record<string, unknown>, allowed: string[], name: string): void {
  for (const key of Object.keys(v)) if (!allowed.includes(key)) throw new CsoError('INVALID_SCHEMA', `Unexpected ${name} field: ${key}`);
}
function boundedInt(v: unknown, min: number, max: number, name: string): number {
  if (!Number.isSafeInteger(v) || (v as number) < min || (v as number) > max) throw new CsoError('INVALID_SCHEMA', `${name} must be ${min}..${max}`);
  return v as number;
}
function control(value: unknown): HttpAssertion {
  const v = object(value, 'API control'), expected = object(v.expected, 'API control expected');
  exact(v, ['name', 'path', 'method', 'headers', 'body', 'expected'], 'API control');
  exact(expected, ['status', 'includes', 'excludes'], 'API control expected');
  const path = string(v.path, 'API control path', 4096);
  if (!path.startsWith('/') || path.startsWith('//') || /[\r\n\\]/.test(path)) throw new CsoError('INVALID_SCHEMA', 'API control path must remain on numeric loopback');
  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(v.method)) throw new CsoError('INVALID_SCHEMA', 'Invalid API control method');
  const headers: Record<string, string> = {};
  for (const [key, value] of Object.entries(v.headers === undefined ? {} : object(v.headers, 'API control headers'))) {
    if (!/^[A-Za-z0-9-]{1,100}$/.test(key) || typeof value !== 'string' || value.length > 8192 || /[\r\n]/.test(value)) throw new CsoError('INVALID_SCHEMA', 'Invalid API control header');
    headers[key] = value;
  }
  return { name: string(v.name, 'API control name', 200), path, method: v.method, headers,
    ...(v.body === undefined ? {} : { body: string(v.body, 'API control body', 65536) }),
    expected: { status: boundedInt(expected.status, 100, 599, 'API control status'),
      ...(expected.includes === undefined ? {} : { includes: string(expected.includes, 'API control includes', 8192) }),
      ...(expected.excludes === undefined ? {} : { excludes: string(expected.excludes, 'API control excludes', 8192) }) } };
}
/** Accept a bounded OpenAPI document, with internal references and selected path operations only. */
export function validateScannerRequest(value: unknown, id: ScannerId): ScannerRequest {
  const v = object(value, 'scanner request');
  exact(v, ['profile', 'api'], 'scanner request');
  const request: ScannerRequest = v.profile === undefined ? {} : { profile: string(v.profile, 'scanner profile', 100) };
  if (v.api === undefined) return request;
  if (id !== 'schemathesis') throw new CsoError('INVALID_SCHEMA', 'Only Schemathesis accepts application execution inputs');
  const api = object(v.api, 'API scan');
  exact(api, ['runtimeProfile', 'port', 'start', 'control', 'boundaryFiles', 'schema', 'operationIds', 'seed', 'maxExamples'], 'API scan');
  const schema = object(api.schema, 'OpenAPI schema'), operations = strings(api.operationIds, 'operation IDs');
  if (operations.length < 1 || operations.length > 20 || new Set(operations).size !== operations.length || operations.some(x => x.length > 200 || /[\x00-\x1f]/.test(x))) throw new CsoError('INVALID_SCHEMA', 'Declare 1..20 unique bounded operation IDs');
  if (typeof schema.openapi !== 'string' || !/^3\.[01]\.\d+$/.test(schema.openapi)) throw new CsoError('PREREQUISITE', 'Schemathesis requires a reviewed OpenAPI 3.0/3.1 JSON document');
  if (Buffer.byteLength(JSON.stringify(schema)) > 262144) throw new CsoError('INVALID_SCHEMA', 'OpenAPI schema exceeds 256 KiB');
  let nodes = 0;
  const inspect = (x: unknown, depth: number): void => {
    if (++nodes > 50_000 || depth > 32) throw new CsoError('INVALID_SCHEMA', 'OpenAPI schema exceeds structural bounds');
    if (!x || typeof x !== 'object') return;
    for (const [key, value] of Object.entries(x)) {
      if (['__proto__', 'prototype', 'constructor', 'externalValue', 'callbacks', 'webhooks'].includes(key) || /hooks?/i.test(key)) throw new CsoError('PREREQUISITE', 'OpenAPI external examples, callbacks, webhooks, and hooks are not admitted');
      if (key === '$ref' && (typeof value !== 'string' || !value.startsWith('#/'))) throw new CsoError('PREREQUISITE', 'OpenAPI references must be internal JSON pointers');
      if (key === 'servers' && (!Array.isArray(value) || value.length)) throw new CsoError('PREREQUISITE', 'Remove server overrides from the reviewed API harness; its target is the isolated loopback application');
      inspect(value, depth + 1);
    }
  };
  inspect(schema, 0);
  const declared: string[] = [];
  for (const [path, item] of Object.entries(object(schema.paths, 'OpenAPI paths'))) {
    if (!path.startsWith('/') || path.startsWith('//') || /[\r\n\\?#]/.test(path)) throw new CsoError('INVALID_SCHEMA', 'OpenAPI paths must be relative to the loopback target');
    const methods = object(item, 'OpenAPI path');
    for (const method of ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace']) {
      if (methods[method] === undefined) continue;
      const op = object(methods[method], 'OpenAPI operation');
      if (typeof op.operationId === 'string') declared.push(op.operationId);
    }
  }
  if (operations.some(op => declared.filter(x => x === op).length !== 1)) throw new CsoError('INVALID_SCHEMA', 'Every selected operation must identify exactly one declared OpenAPI path operation');
  const boundaries = strings(api.boundaryFiles, 'API boundary files').map(snapshotReference);
  if (!boundaries.length || new Set(boundaries).size !== boundaries.length) throw new CsoError('INVALID_SCHEMA', 'API scan needs unique security-boundary source paths');
  request.api = { runtimeProfile: string(api.runtimeProfile, 'API runtime profile', 100), port: boundedInt(api.port, 1024, 65535, 'API port'), start: validateCommand(api.start, 'API start'), control: control(api.control), boundaryFiles: boundaries, schema, operationIds: operations,
    ...(api.seed === undefined ? {} : { seed: boundedInt(api.seed, 1, 2147483647, 'API seed') }),
    ...(api.maxExamples === undefined ? {} : { maxExamples: boundedInt(api.maxExamples, 1, 100, 'API maxExamples') }) };
  const raw = JSON.stringify(request);
  if (redact(raw) !== raw) throw new CsoError('REDACTION_FAILED', 'Scanner harness contains secret-bearing material; use synthetic inputs');
  return request;
}

/** Resolve only helper-issued path references before any application command reaches containment. */
export function resolveScannerRequestPaths(manifest:SnapshotManifest,request:ScannerRequest):ScannerRequest{
  if(!request.api)return request;
  const resolve=(reference:string):string=>{const id=snapshotPathHandleId(reference);if(!id)return relativePath(reference);const entry=manifest.entries.find(item=>item.pathId===id);if(!entry)throw new CsoError('INVALID_SCHEMA',`API path handle is outside the retained snapshot: ${reference}`);return entry.path;};
  const argument=(value:string):string=>{if(snapshotPathHandleId(value))return resolve(value);if(value.startsWith('./')&&snapshotPathHandleId(value.slice(2)))return `./${resolve(value.slice(2))}`;return value;};
  return{...request,api:{...request.api,start:{...request.api.start,args:request.api.start.args.map(argument)},boundaryFiles:request.api.boundaryFiles.map(resolve)}};
}

export function scannerCoverage(outcome: ScannerOutcome, scope: string): CoverageRecord {
  return { domain: `scanner:${outcome.tool}`, scope, status: outcome.status === 'complete' ? 'assessed' : outcome.status,
    method: outcome.tool === 'sarif' ? 'bounded untrusted SARIF import' : 'qualified offline Docker scanner; candidate evidence only',
    gaps: outcome.gaps.map(g => g.message), exclusions: outcome.exclusions,
    evidence: [`${outcome.candidates.length} scanner candidates; plan ${outcome.planSha256}`],
    tool: { name: outcome.tool, version: outcome.version ?? 'unavailable', freshness: outcome.databaseUpdatedAt ?? 'not reported', outcome: outcome.status } };
}
function failure(plan: ScannerPlan, error: unknown, version?: string): ScannerOutcome {
  const e = error instanceof CsoError ? error : new CsoError('ISOLATION_FAILED', 'Scanner execution failed before bounded evidence was established');
  const codes: Record<ErrorCode, ScannerGap['code']> = {
    INVALID_ARGUMENT: 'INVALID_OUTPUT', INVALID_SCHEMA: 'INVALID_OUTPUT', MISSING_INPUT: 'MISSING_INPUT', SNAPSHOT_RACE: 'SNAPSHOT_RACE',
    UNSAFE_PATH: 'UNSAFE_PATH', REDACTION_FAILED: 'REDACTION_FAILED', PERSISTENCE_FAILED: 'PERSISTENCE_FAILED', TOOL_UNAVAILABLE: 'UNAVAILABLE',
    TOOL_FAILED: 'TOOL_FAILED', ISOLATION_FAILED: 'ISOLATION_FAILED', INSUFFICIENT_CAPACITY: 'INSUFFICIENT_CAPACITY', DEADLINE: 'TIMEOUT',
    CANCELLED: 'CANCELLED', PREREQUISITE: 'PREREQUISITE', INCOMPATIBLE_INPUT: 'PREREQUISITE', ASSERTION_FAILED: 'TOOL_FAILED',
  };
  const code = codes[e.code];
  return { ...parseScannerOutput(plan, { stdout: '', exitCode: null, version }), status: 'not_assessed', candidates: [], gaps: [{ code, message: e.message }] };
}

/** Empty catalogs and missing assets produce coverage gaps without opening Docker. */
export async function executeScanner(input: ScannerRunInput, dependencies: ScannerRunDependencies = {}): Promise<ScannerRunRecord> {
  const identityRequest = validateScannerRequest(input.request ?? {}, input.id), catalog = dependencies.catalog ?? SCANNER_CATALOG;
  const timeout = Math.min(300, Math.floor((input.executionDeadline - Date.now()) / 1000));
  let profile: QualifiedScanner | undefined, runtime: QualifiedRuntime | undefined, observedVersion: string | undefined, versionHash: string | null = null;
  let application: ScannerApplicationPreparation | undefined,request=identityRequest;
  let plan = scannerPlans({ snapshotRoot: '/source', offline: input.policy.offline, selected: [input.id], deadlineSeconds: Math.max(1, timeout) })[0];
  let outcome: ScannerOutcome, runner: ScannerRunner | undefined;
  try {
    if (timeout < 1) throw new CsoError('DEADLINE', 'No scanner time remains before the reporting reserve');
    assertSnapshot(input.runDir, input.manifest);
    request=resolveScannerRequestPaths(input.manifest,identityRequest);
    if (input.id === 'schemathesis' && input.policy.mode !== 'comprehensive') throw new CsoError('PREREQUISITE', 'Schemathesis requires comprehensive mode; daily audits do not execute applications');
    profile = selectScanner(input.id, input.platform, request.profile, catalog);
    const api = request.api;
    plan = scannerPlans({ snapshotRoot: '/source', offline: input.policy.offline, selected: [input.id], deadlineSeconds: timeout,
      tools: { [input.id]: { available: true, version: profile.version, capabilities: profile.capabilities } },
      semgrepRules: profile.assets?.semgrepRules?.path, advisoryCache: profile.assets?.advisoryDatabase?.path,
      ...(api ? { schemaPath: '/policy/openapi.json', baseUrl: `http://127.0.0.1:${api.port}/`, operationIds: api.operationIds, seed: api.seed, maxExamples: api.maxExamples } : {}) })[0];
    if (plan.prerequisites.length) throw new CsoError('PREREQUISITE', plan.prerequisites.join('; '));
    if (input.id === 'schemathesis') {
      if (!api) throw new CsoError('PREREQUISITE', 'Schemathesis requires a reviewed API harness and legitimate control');
      for (const file of api.boundaryFiles) {
        const entry = input.manifest.entries.find(e => e.path === file);
        if (!entry || !entry.executionHash || entry.transformation) throw new CsoError('INCOMPATIBLE_INPUT', `API security boundary is missing or transformed: ${file}`);
      }
      try { runtime = selectRuntime(api.runtimeProfile, input.platform, dependencies.runtimes ?? RUNTIME_CATALOG); }
      catch { throw new CsoError('PREREQUISITE', `Qualified application runtime is unavailable: ${api.runtimeProfile}`); }
      if (!['node', 'bun', 'python', 'rails'].includes(runtime.stack)) throw new CsoError('INCOMPATIBLE_INPUT', 'Schemathesis requires a qualified application runtime');
      const stack = runtime.stack as CsoStack, sourceRoot = join(input.runDir, 'snapshot');
      const preparation = inspectPreparation(sourceRoot, stack);
      assertRuntimeCompatible(preparation, runtime);
      const startPlan = canonicalStartPlan(sourceRoot, stack, api.port);
      if (canonical(api.start) !== canonical(startPlan.command)) throw new CsoError('INVALID_SCHEMA', `API start must use the helper-derived ${startPlan.kind} command`);
      for (const file of startPlan.entrypointFiles) if (!api.boundaryFiles.includes(file))
        throw new CsoError('INVALID_SCHEMA', `API boundary files must include canonical startup input: ${file}`);
      application = await (dependencies.applicationPreparer ?? prepareDockerScannerApplication)({
        input: { ...input, request }, runtime, stack, startPlan,
        deadline: Math.min(input.executionDeadline, Date.now() + timeout * 1000), catalog: dependencies.runtimes ?? RUNTIME_CATALOG,
      });
      const preparedStart = canonicalStartPlan(application.sourceRoot, stack, api.port);
      if (preparedStart.signature !== startPlan.signature || canonical(preparedStart.command) !== canonical(startPlan.command))
        throw new CsoError('ISOLATION_FAILED', 'Offline API preparation changed the canonical application startup inputs');
    }
    runner = await (dependencies.runnerFactory ?? createDockerScannerRunner)({ input: { ...input, request }, plan, profile, runtime, application, deadline: Math.min(input.executionDeadline, Date.now() + timeout * 1000) });
    const version = await runner.version();
    if (version.exitCode !== 0 || version.timedOut || version.truncated || version.unavailable || Buffer.byteLength(version.stdout) + Buffer.byteLength(version.stderr ?? '') > 8192) throw new CsoError('TOOL_UNAVAILABLE', 'Scanner version probe did not complete within the qualified sandbox');
    assertScannerVersionOutput(profile.scanner,profile.version,version.stdout,version.stderr);
    versionHash = scannerVersionHash(version.stdout, version.stderr);
    if (versionHash !== profile.versionOutputSha256) throw new CsoError('INCOMPATIBLE_INPUT', 'Scanner version output does not match its reviewed image profile');
    observedVersion = profile.version;
    const execution = await runner.scan();
    assertSnapshot(input.runDir, input.manifest);
    outcome = parseScannerOutput(plan, { ...execution, version: profile.version, databaseUpdatedAt: profile.assets?.advisoryDatabase?.updatedAt });
  } catch (error) { outcome = failure(plan, error, observedVersion); }
  finally {
    let cleanupError: unknown;
    if (runner) try { await runner.cleanup(); } catch (error) { cleanupError = error; }
    if (application) try { await application.cleanup(); } catch (error) { cleanupError ??= error; }
    if (cleanupError) outcome = failure(plan, cleanupError, observedVersion);
  }
  return { outcome: outcome!, coverage: scannerCoverage(outcome!, input.policy.scope), provenance: {
    scannerCatalog: catalog.revision, profile: profile?.id ?? null, image: profile?.image ?? null, platform: input.platform,
    isolationPolicyHash: profile?.isolationPolicyHash ?? null, sourceHash: input.manifest.executionHash, requestHash: sha256(canonical(identityRequest)), versionOutputSha256: versionHash,
    assets: profile?.assets ?? null, network: plan.network === 'loopback' ? 'isolated-loopback' : 'none', preparation: application?.proof ?? null } };
}

export async function prepareDockerScannerApplication(context: Parameters<ScannerApplicationPreparer>[0],dependencies:{endpoint?:DockerEndpoint;runnerFactory?:(options:ConstructorParameters<typeof DockerPreparationSandboxRunner>[0])=>PreparationSandboxRunner;cacheRoot?:string}={}): Promise<ScannerApplicationPreparation> {
  const { input, runtime, stack, deadline, catalog } = context;
  const root = secureDirectory(join(input.runDir, 'supervision', `scanner-preparation-${randomBytes(12).toString('hex')}`));
  let executor: PreparationExecutor | undefined, prepared: Awaited<ReturnType<PreparationExecutor['prepareOffline']>> | undefined;
  try {
    const plan = inspectPreparation(join(input.runDir, 'snapshot'), stack);
    const admission = admitPreparationRuntime({ plan, platform: input.platform, profile: runtime.id, catalog });
    const endpoint = dependencies.endpoint??await dockerEndpoint(root),runnerOptions={ endpoint, watchdogPath: input.watchdogPath,
      runRoot: root, controlRoot: secureDirectory(join(root, 'execution')), admission },runner=dependencies.runnerFactory?dependencies.runnerFactory(runnerOptions):new DockerPreparationSandboxRunner(runnerOptions);
    executor = new PreparationExecutor({ cache: new PublicArchiveCache({ root: dependencies.cacheRoot??publicArchiveCacheRoot(), stagingRoot: secureDirectory(join(root, 'staging')) }),
      runner, materializationRoot: secureDirectory(join(root, 'materializations')) });
    const closure = await executor.acquire({ plan, admission, snapshot: join(input.runDir, 'snapshot'), deadline, offline: input.policy.offline });
    let database:RailsDatabaseSelection|undefined;
    if(stack==='rails'){
      if(!plan.database?.selected)throw new CsoError('PREREQUISITE','Rails API preparation could not select one locked database adapter');
      database=plan.database.selected==='postgresql'
        ?{adapter:'postgresql',sidecar:admitPreparationSidecar({platform:input.platform,catalog})}:{adapter:'sqlite'};
    }
    prepared = await executor.prepareOffline({ plan, admission, snapshot: join(input.runDir, 'snapshot'), closure, deadline, database });
    const proof = { dependencyClosureHash: prepared.dependencyClosureHash, preparedManifestHash: prepared.preparedManifestHash,
      sourceProjectionHash: prepared.sourceProjectionHash, receiptHash: prepared.receiptHash,
      executionEnvironmentHash: sha256(canonical(prepared.executionEnvironment)), databaseHash: prepared.databaseHash };
    let cleaned = false;
    return { sourceRoot: prepared.preparedRoot, environment: prepared.executionEnvironment, database: prepared.database, proof, cleanup: async () => {
      if (cleaned) return; cleaned = true;
      await executor!.dispose(prepared!);
      fs.rmSync(root, { recursive: true, force: false });
    } };
  } catch (error) {
    let cleanupError:unknown;
    if (prepared && executor) try { await executor.dispose(prepared); } catch (failed) { cleanupError=failed; }
    // A failed Docker/retained-copy cleanup deliberately hands ownership to a
    // detached watchdog. Its journals and label-sweep scratch files live below
    // this root, so only remove the tree after every watchdog acknowledged.
    let pending=true;try{pending=hasPendingWatchdogCleanup(input.runDir);}catch(failed){cleanupError??=failed;}
    if(!cleanupError&&!pending)try { fs.rmSync(root, { recursive: true, force: false }); } catch {}
    if(cleanupError)throw cleanupError;
    throw error;
  }
}

/** No arbitrary runner configuration crosses this boundary; images and paths came from the catalog. */
export async function createDockerScannerRunner(context: ScannerRunnerContext): Promise<ScannerRunner> {
  const { input, plan, profile, runtime, application, deadline } = context;
  const attempt = `scanner-${input.id}-${randomBytes(12).toString('hex')}`;
  const controlDir = secureDirectory(join(input.runDir, 'supervision', attempt));
  const policyDir = secureDirectory(join(controlDir, 'policy'));
  const files: Array<{ host: string; container: string }> = [];
  const writePolicy = (container: string, content: string): void => {
    if (redact(content) !== content) throw new CsoError('REDACTION_FAILED', 'Scanner policy contains secret-bearing material');
    const host = join(policyDir, String(files.length)); fs.writeFileSync(host, content, { mode: 0o600, flag: 'wx' });
    files.push({ host, container });
  };
  let group: DockerGroup | undefined;
  try {
    for (const file of plan.trustedFiles) writePolicy(file.path, file.content);
    if (input.request?.api) writePolicy('/policy/openapi.json', JSON.stringify(input.request.api.schema));
    const endpoint: DockerEndpoint = await dockerEndpoint(controlDir);
    group = await DockerGroup.create(endpoint, attempt, controlDir, deadline, profile.image, input.watchdogPath);
    const createScanner=()=>group!.createContainer({ role: runtime ? 'verifier' : 'app', image: profile.image, source: join(input.runDir, 'snapshot'), command: ['/bin/sleep', '2147483647'], env: plan.env, readonlyFiles: files });
    let scanner = await createScanner();
    await group.start(scanner);
    const capture = async (command: string[]): Promise<ScannerExecution> => {
      if(!scanner)throw new CsoError('ISOLATION_FAILED','Scanner container is unavailable');
      const result = await group!.execCapture(scanner, command, { workdir: '/work', env: plan.env });
      return { stdout: result.stdout, stderr: result.stderr, exitCode: result.code };
    };
    return {
      version: () => capture([profile.executable, ...plan.versionArgs]),
      scan: async () => {
        const api = input.request?.api;
        if (api && runtime) {
          if (!application) throw new CsoError('ISOLATION_FAILED', 'Schemathesis application was not materialized through offline preparation');
          const env={ ...application.environment, PORT: String(api.port), HOST: '127.0.0.1', NODE_ENV: 'test', RAILS_ENV: 'test', RACK_ENV: 'test', PYTHONUNBUFFERED: '1', CI: '1', SECRET_KEY_BASE: 'cso-synthetic-test-key' };
          const rails=runtime.stack==='rails';
          if(rails){await group!.removeContainer(scanner);scanner='';}
          if(application.database?.adapter==='postgresql'){
            const databaseFile=join(policyDir,'postgresql.databases'),names=application.database.connections.map(name=>`cso_${name}`);
            if(!names.length||names.some(name=>!/^cso_[A-Za-z_][A-Za-z0-9_]{0,47}$/.test(name)))throw new CsoError('INCOMPATIBLE_INPUT','Prepared PostgreSQL connection names are invalid');
            fs.writeFileSync(databaseFile,names.join('\n')+'\n',{mode:0o444,flag:'wx'});
            const postgres=await group!.createContainer({role:'postgres',image:application.database.sidecar.image,command:['/opt/cso/run-postgresql','/policy/postgresql.databases'],postgresDatabasePolicy:databaseFile});await group!.start(postgres);
            let ready=false;for(let attempt=0;attempt<100&&!ready;attempt++){const checked=await group!.execCapture(postgres,['/opt/cso/postgresql-ready','/policy/postgresql.databases']);ready=checked.code===0;if(!ready)await new Promise(resolveWait=>setTimeout(resolveWait,50));}
            if(!ready)throw new CsoError('TOOL_FAILED','Disposable PostgreSQL did not become ready for Rails API scanning');
          }
          const app = await group!.createContainer({ role: 'app', image: runtime.image, source: application.sourceRoot, env,
            command:rails?['/opt/cso/run-app','/bin/sleep','2147483647']:['/opt/cso/run-app', api.start.executable, ...api.start.args] });
          await group!.start(app);
          if(rails){const clean=['/usr/bin/env','-i',...Object.entries(env).sort(([a],[b])=>a.localeCompare(b)).map(([key,value])=>`${key}=${value}`),'/usr/local/bin/bundle','exec','rails','db:prepare'];const prepared=await group!.execCapture(app,clean,{workdir:'/work'});if(prepared.code!==0)throw new CsoError('TOOL_FAILED','Rails API database preparation failed');await group!.execDetached(app,[api.start.executable,...api.start.args]);}
          const security = { ...api.control, vulnerable: { status: api.control.expected.status === 599 ? 598 : 599 } };
          const controlFile = join(policyDir, 'control.json');
          fs.writeFileSync(controlFile, JSON.stringify({ phase: 'after', port: api.port, legitimate: [api.control], security }), { mode: 0o600, flag: 'wx' });
          const probe = await group!.createContainer({ role: schemathesisControlRole(), image: runtime.image, command: ['/opt/cso/verifier', '/policy/control.json'], readonlyFiles: [{ host: controlFile, container: '/policy/control.json' }] });
          const observed = await group!.startAttach(probe); await group!.removeContainer(probe);
          let valid = false;
          try { const v = validateVerificationObservation(JSON.parse(observed.output)); valid = observed.code === 0 && v.booted && v.legitimate && v.security === 'pass'; } catch {}
          if (!valid) throw new CsoError('PREREQUISITE', 'API application boot or legitimate control failed; no Schemathesis requests were sent');
          if(rails){scanner=await createScanner();await group!.start(scanner);}
        }
        const execution = await capture([profile.executable, ...plan.args]);
        if (plan.outputPath) {
          const report = await capture(['/bin/cat', plan.outputPath]);
          if (report.exitCode !== 0) throw new CsoError('PREREQUISITE', 'Scanner did not produce its required bounded report file');
          return { ...execution, stdout: report.stdout, stderr: [execution.stderr, report.stderr].filter(Boolean).join('\n') };
        }
        return execution;
      },
      cleanup: async () => { await group!.cleanup(); fs.rmSync(policyDir, { recursive: true, force: true }); },
    };
  } catch (error) {
    if (group) await group.cleanup();
    fs.rmSync(policyDir, { recursive: true, force: true });
    throw error;
  }
}