cipher-security 2.0.0

package/lib/autonomous/runner.js

@@ -0,0 +1,955 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * runner.js — Mode registry, FlagValidator, and RED mode agent.
+ *
+ * Ported from autonomous/runner.py (lines 1-630). Contains:
+ * - FlagValidator: RED mode output validation (FLAG{hex} pattern)
+ * - RED mode tool handlers, schemas, system prompts, factory
+ * - MODE_REGISTRY: Map of mode name → factory function
+ * - registerMode / availableModes / initModes
+ *
+ * The dispatcher (runAutonomous) is in T04.
+ *
+ * @module autonomous/runner
+ */
+
+import { ModeAgentConfig, ToolRegistry, ValidationResult } from './framework.js';
+
+const debug = process.env.CIPHER_DEBUG === '1'
+  ? (/** @type {string} */ msg) => process.stderr.write(`[bridge:node] ${msg}\n`)
+  : () => {};
+
+// ---------------------------------------------------------------------------
+// FlagValidator — RED mode output validation
+// ---------------------------------------------------------------------------
+
+/** @type {RegExp} */
+export const FLAG_PATTERN = /FLAG\{[a-fA-F0-9]+\}/;
+
+/**
+ * Validates that a FLAG{hex} pattern was captured.
+ *
+ * Checks both result.outputText and result.steps since the flag may
+ * appear in tool output (recorded in steps via [complete]) rather
+ * than in the LLM's text response.
+ */
+export class FlagValidator {
+  /**
+   * @param {import('./framework.js').ModeAgentResult} result
+   * @returns {ValidationResult}
+   */
+  validate(result) {
+    // Check outputText first
+    const textMatch = FLAG_PATTERN.exec(result.outputText);
+    if (textMatch) {
+      return new ValidationResult({
+        valid: true,
+        errors: [],
+        warnings: [],
+        score: 1.0,
+        metadata: { flag: textMatch[0] },
+      });
+    }
+
+    // Check steps (flag may have triggered completion from tool output)
+    for (const step of result.steps) {
+      const stepMatch = FLAG_PATTERN.exec(step);
+      if (stepMatch) {
+        return new ValidationResult({
+          valid: true,
+          errors: [],
+          warnings: [],
+          score: 1.0,
+          metadata: { flag: stepMatch[0] },
+        });
+      }
+    }
+
+    return new ValidationResult({
+      valid: false,
+      errors: ['No FLAG{hex} pattern found in output or steps'],
+      warnings: [],
+      score: 0.0,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// RED mode completion check
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if text contains a FLAG{hex} pattern.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function _redCompletionCheck(text) {
+  return FLAG_PATTERN.test(text);
+}
+
+// ---------------------------------------------------------------------------
+// RED mode tool handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute an arbitrary shell command in the sandbox.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _redSandboxExec(context, toolInput) {
+  const command = toolInput.command;
+  const [exitCode, stdout, stderr] = context.execTool(command);
+
+  const parts = [];
+  if (stdout.trim()) parts.push(`STDOUT:\n${stdout}`);
+  if (stderr.trim()) parts.push(`STDERR:\n${stderr}`);
+  parts.push(`EXIT CODE: ${exitCode}`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Make an HTTP request via curl inside the sandbox.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _redHttpRequest(context, toolInput) {
+  const url = toolInput.url;
+  const method = (toolInput.method || 'GET').toUpperCase();
+  const headers = toolInput.headers || {};
+  const body = toolInput.body;
+
+  const cmdParts = ['curl', '-s', '-S', '-i', '-X', method];
+
+  for (const [key, value] of Object.entries(headers)) {
+    const escapedVal = value.replace(/'/g, "'\\''");
+    cmdParts.push('-H', `'${key}: ${escapedVal}'`);
+  }
+
+  if (body) {
+    const escapedBody = body.replace(/'/g, "'\\''");
+    cmdParts.push('-d', `'${escapedBody}'`);
+  }
+
+  const escapedUrl = url.replace(/"/g, '\\"');
+  cmdParts.push(`"${escapedUrl}"`);
+  const command = cmdParts.join(' ');
+
+  const [exitCode, stdout, stderr] = context.execTool(command);
+
+  const parts = [];
+  if (stdout.trim()) parts.push(stdout);
+  if (stderr.trim()) parts.push(`CURL ERROR:\n${stderr}`);
+  parts.push(`EXIT CODE: ${exitCode}`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Read a file inside the sandbox.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _redReadFile(context, toolInput) {
+  const path = toolInput.path;
+  const [exitCode, stdout, stderr] = context.execTool(`cat '${path}'`);
+
+  if (exitCode !== 0) {
+    return `ERROR reading ${path}: ${stderr.trim()}`;
+  }
+
+  return stdout;
+}
+
+// ---------------------------------------------------------------------------
+// Network exploitation tool handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan a target for open ports using nmap in the sandbox.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _netPortScan(context, toolInput) {
+  const target = toolInput.target;
+  const ports = toolInput.ports || '1-1000';
+
+  const command = `nmap -sV -T4 -p ${ports} ${target}`;
+  debug(`port_scan: ${command}`);
+  const [exitCode, stdout, stderr] = context.execTool(command);
+
+  const parts = [];
+  if (stdout.trim()) parts.push(stdout);
+  if (stderr.trim()) parts.push(`STDERR:\n${stderr}`);
+  parts.push(`EXIT CODE: ${exitCode}`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Open a raw TCP connection and return the banner.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _netConnectTcp(context, toolInput) {
+  const host = toolInput.host;
+  const port = toolInput.port;
+  const timeout = toolInput.timeout || 5;
+
+  const command = `echo | nc -w${timeout} ${host} ${port}`;
+  debug(`connect_tcp: ${command}`);
+  const [exitCode, stdout, stderr] = context.execTool(command);
+
+  const parts = [];
+  if (stdout.trim()) parts.push(stdout);
+  if (stderr.trim()) parts.push(`STDERR:\n${stderr}`);
+  parts.push(`EXIT CODE: ${exitCode}`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Send a payload over TCP and return the response.
+ * @param {*} context
+ * @param {Object} toolInput
+ * @returns {string}
+ */
+function _netSendPayload(context, toolInput) {
+  const host = toolInput.host;
+  const port = toolInput.port;
+  const data = toolInput.data;
+  const timeout = toolInput.timeout || 5;
+
+  const escapedData = data.replace(/'/g, "'\\''");
+  const command =
+    `python3 -c "` +
+    `import socket; ` +
+    `s=socket.socket(); ` +
+    `s.settimeout(${timeout}); ` +
+    `s.connect(('${host}',${port})); ` +
+    `s.sendall(b'${escapedData}'); ` +
+    `print(s.recv(4096).decode('utf-8','replace')); ` +
+    `s.close()"`;
+  debug(`send_payload: ${command}`);
+  const [exitCode, stdout, stderr] = context.execTool(command);
+
+  const parts = [];
+  if (stdout.trim()) parts.push(stdout);
+  if (stderr.trim()) parts.push(`STDERR:\n${stderr}`);
+  parts.push(`EXIT CODE: ${exitCode}`);
+
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// RED mode tool schemas (Anthropic format)
+// ---------------------------------------------------------------------------
+
+const _RED_SANDBOX_EXEC_SCHEMA = {
+  name: 'sandbox_exec',
+  description:
+    'Execute a shell command in the security sandbox. ' +
+    'Use this to run any tool: curl, nmap, sqlmap, python3, grep, etc. ' +
+    'Returns the command\'s stdout, stderr, and exit code.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'Shell command to execute (passed to /bin/sh -c)',
+      },
+    },
+    required: ['command'],
+  },
+};
+
+const _RED_HTTP_REQUEST_SCHEMA = {
+  name: 'http_request',
+  description:
+    'Make an HTTP request to a URL. Convenience wrapper around curl. ' +
+    'Use for GET/POST/PUT requests with optional headers and body.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'Target URL (e.g., http://web:80/login)',
+      },
+      method: {
+        type: 'string',
+        description: 'HTTP method (GET, POST, PUT, DELETE)',
+        default: 'GET',
+      },
+      headers: {
+        type: 'object',
+        description: 'HTTP headers as key-value pairs',
+        additionalProperties: { type: 'string' },
+      },
+      body: {
+        type: 'string',
+        description: 'Request body (for POST/PUT)',
+      },
+    },
+    required: ['url'],
+  },
+};
+
+const _RED_READ_FILE_SCHEMA = {
+  name: 'read_file',
+  description:
+    'Read the contents of a file inside the sandbox. ' +
+    'Use to inspect downloaded files, configuration, source code, etc.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Absolute or relative file path inside the sandbox',
+      },
+    },
+    required: ['path'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Network exploitation tool schemas
+// ---------------------------------------------------------------------------
+
+const _NET_PORT_SCAN_SCHEMA = {
+  name: 'port_scan',
+  description:
+    'Scan a target for open ports using nmap. ' +
+    'Returns service version info for discovered ports.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      target: {
+        type: 'string',
+        description: 'Hostname or IP address to scan',
+      },
+      ports: {
+        type: 'string',
+        description:
+          "Port range in nmap syntax (e.g. '1-1000', '21,22,80'). Defaults to '1-1000'.",
+      },
+    },
+    required: ['target'],
+  },
+};
+
+const _NET_CONNECT_TCP_SCHEMA = {
+  name: 'connect_tcp',
+  description:
+    'Open a raw TCP connection and return the banner/greeting. ' +
+    'Useful for identifying services (FTP, SSH, SMTP, etc.).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      host: {
+        type: 'string',
+        description: 'Hostname or IP address',
+      },
+      port: {
+        type: 'integer',
+        description: 'TCP port number',
+      },
+      timeout: {
+        type: 'integer',
+        description: 'Connection timeout in seconds (default: 5)',
+      },
+    },
+    required: ['host', 'port'],
+  },
+};
+
+const _NET_SEND_PAYLOAD_SCHEMA = {
+  name: 'send_payload',
+  description:
+    'Send a payload over TCP and return the response. ' +
+    'Use for interacting with network services (FTP commands, ' +
+    'SMTP commands, custom protocols, etc.).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      host: {
+        type: 'string',
+        description: 'Hostname or IP address',
+      },
+      port: {
+        type: 'integer',
+        description: 'TCP port number',
+      },
+      data: {
+        type: 'string',
+        description: 'Payload string to send',
+      },
+      timeout: {
+        type: 'integer',
+        description: 'Socket timeout in seconds (default: 5)',
+      },
+    },
+    required: ['host', 'port', 'data'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// RED mode system prompts
+// ---------------------------------------------------------------------------
+
+const _RED_SYSTEM_PROMPT = `\
+You are an expert security researcher performing an authorized penetration test \
+against a web application. Your goal is to find and extract the flag.
+
+The flag format is FLAG{hex_string} (e.g., FLAG{a1b2c3d4e5f6...}).
+
+## Target
+URL: {target_url}
+Description: {challenge_description}
+
+## Strategy
+1. First, explore the target with HTTP requests to understand the application
+2. Read HTML source, headers, error messages for clues about the technology stack
+3. Based on clues, identify the vulnerability class (SQLi, SSTI, XSS, SSRF, etc.)
+4. Craft exploitation payloads step by step — test each one and analyze the response
+5. When exploitation succeeds, look for the flag in the response
+6. The flag is often stored in a file like /flag, /flag.txt, or an environment variable
+
+## Important Execution Notes
+- Use sandbox_exec with curl commands for full control over HTTP requests
+- Example: sandbox_exec with command: curl -s -H "Host: localhost" "http://web:8000/"
+- If you get "DisallowedHost" or 400 errors, add -H "Host: localhost" to curl
+- CRITICAL: Shell braces {{ and }} are eaten by /bin/sh. Always URL-encode template \
+injection payloads in the URL. For example, use %7B%7B7*7%7D%7D instead of {{7*7}}.
+- For SSTI: try URL-encoded payloads like %7B%7B7*7%7D%7D, %7B%7BFLAG%7D%7D, \
+%7B%7Bconfig%7D%7D, %7B%7Bsettings%7D%7D, %7B%7Brequest.META%7D%7D
+- XBOW challenges typically pass the flag as a template context variable named FLAG — \
+always try %7B%7BFLAG%7D%7D (URL-encoded {{FLAG}}) early in your SSTI attempts
+- The flag is often in a template variable like FLAG, or in /flag.txt, or an env var
+- You have curl, nmap, and python3 available in your sandbox
+- Be persistent — if a payload returns 500, try a different approach
+- NEVER give up after just a few attempts. Keep trying different payloads.
+- When you find the flag (FLAG{...}), state it clearly in your response
+`;
+
+const _RED_NETWORK_SYSTEM_PROMPT = `\
+You are an expert security researcher performing an authorized penetration test \
+against a network service. Your goal is to find and extract the flag.
+
+The flag format is FLAG{hex_string} (e.g., FLAG{a1b2c3d4e5f6...}).
+
+## Target
+Host: {target_host}
+Port: {target_port}
+Description: {challenge_description}
+
+## Available Tools
+- **port_scan**: Scan the target for open ports and service versions (nmap)
+- **connect_tcp**: Open a TCP connection to grab service banners
+- **send_payload**: Send arbitrary data over TCP and read the response
+- **sandbox_exec**: Run any shell command (python3, curl, nmap, netcat, etc.)
+- **read_file**: Read files inside the sandbox
+
+## Strategy
+1. Use port_scan to discover open ports and running services on the target
+2. Use connect_tcp to grab banners and identify service versions
+3. Identify the service type: FTP, SSH, Telnet, SMTP, custom, etc.
+4. Based on the service, try common exploitation patterns:
+   - **FTP**: anonymous login, directory traversal, SITE commands, known CVEs
+   - **SSH**: default credentials, key-based auth weaknesses
+   - **Telnet**: default credentials, command injection
+   - **SMTP**: open relay, VRFY enumeration, header injection
+   - **Custom**: protocol fuzzing, buffer overflow, format string
+5. Use send_payload for direct protocol interaction (e.g., FTP commands)
+6. Use sandbox_exec for complex exploits (python3 scripts, metasploit patterns)
+7. Look for FLAG{hex} in service responses, files (/flag, /flag.txt), or env vars
+
+## Important Execution Notes
+- Start with port_scan to understand what's running
+- Use connect_tcp to see the service banner before crafting exploits
+- For FTP: try "USER anonymous\\r\\nPASS \\r\\n" via send_payload or sandbox_exec
+- For multi-step protocols, use sandbox_exec with a python3 script
+- The flag may be in a file accessible through the service, not just in banners
+- Be persistent — try multiple approaches if the first doesn't work
+- When you find the flag (FLAG{...}), state it clearly in your response
+`;
+
+const _RED_BINARY_SYSTEM_PROMPT = `\
+You are an expert security researcher performing an authorized penetration test \
+against a binary service. Your goal is to find and extract the flag.
+
+The flag format is FLAG{hex_string} (e.g., FLAG{a1b2c3d4e5f6...}).
+
+## Target
+Host: {target_host}
+Port: {target_port}
+Description: {challenge_description}
+
+## Available Tools
+- **sandbox_exec**: Run any shell command (python3, gcc, objdump, gdb, etc.)
+- **read_file**: Read files inside the sandbox
+- **send_payload**: Send arbitrary data over TCP and read the response
+
+## Setup
+Install useful tools first:
+\`\`\`
+apt-get update && apt-get install -y binutils file netcat-openbsd
+\`\`\`
+
+## Binary Exploitation Strategy
+1. **Probe the service**: Connect to the target and observe its behavior. Note any \
+prompts or output format.
+2. **Identify the vulnerability class**: Send format string specifiers (%p, %x, %s) \
+as input. If the service reflects hex addresses or crashes differently, it is a \
+format string vulnerability.
+3. **Leak stack data**: Send a sequence of \`%p.\` markers to dump stack values. \
+Look for hex patterns that correspond to ASCII text (especially the flag).
+4. **Targeted leaks**: Use positional format specifiers like \`%7$p\`, \`%8$p\`, etc. \
+to read specific stack slots.
+5. **Decode the flag**: Stack values are typically 8 bytes in little-endian order. \
+Convert hex to ASCII and reverse the byte order within each 8-byte word.
+
+## Format String Reference
+- \`%p\` — print pointer (hex value from stack), walks the stack one argument at a time
+- \`%N$p\` — print the Nth argument from the stack (e.g., \`%7$p\` reads the 7th)
+- \`%s\` — dereference a pointer on the stack and print the string it points to
+- \`%N$s\` — dereference the Nth argument as a string pointer
+
+## Worked Example: Hex-to-ASCII Decoding
+If \`%7$p\` returns \`0x4c467b47414c46\` (8 bytes), decode it:
+\`\`\`python
+import struct
+val = 0x4c467b47414c46
+raw = struct.pack('<Q', val)  # little-endian 8-byte word
+print(raw)  # b'FLAG{L'
+\`\`\`
+Concatenate decoded words from consecutive stack slots until you have the full flag.
+
+## Important Execution Notes
+- **Always use python3 scripts** for exploit payloads — avoid shell escaping issues \
+with \`$\` and \`%\` characters in format strings.
+- Example: write a python3 script that connects via socket, sends the format string, \
+and parses the response.
+- The flag is stored somewhere accessible to the binary (a file it reads, or on \
+the stack). Leak stack contents to find it.
+- Be systematic: probe offsets %1$p through %20$p and look for hex values that \
+decode to printable ASCII in the FLAG{...} pattern.
+- When you find the flag (FLAG{...}), state it clearly in your response.
+`;
+
+// ---------------------------------------------------------------------------
+// RED mode factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a RED-mode ModeAgentConfig, selecting tools by challenge category.
+ *
+ * @param {string} [category='web'] - 'web', 'network', or 'binary'
+ * @returns {ModeAgentConfig}
+ */
+function _makeRedConfig(category = 'web') {
+  const reg = new ToolRegistry();
+
+  let systemPrompt;
+
+  if (category === 'network') {
+    reg.register('port_scan', _NET_PORT_SCAN_SCHEMA, _netPortScan);
+    reg.register('connect_tcp', _NET_CONNECT_TCP_SCHEMA, _netConnectTcp);
+    reg.register('send_payload', _NET_SEND_PAYLOAD_SCHEMA, _netSendPayload);
+    reg.register('sandbox_exec', _RED_SANDBOX_EXEC_SCHEMA, _redSandboxExec);
+    reg.register('read_file', _RED_READ_FILE_SCHEMA, _redReadFile);
+    systemPrompt = _RED_NETWORK_SYSTEM_PROMPT;
+    debug('_makeRedConfig: category=network, 5 tools registered');
+  } else if (category === 'binary') {
+    reg.register('sandbox_exec', _RED_SANDBOX_EXEC_SCHEMA, _redSandboxExec);
+    reg.register('read_file', _RED_READ_FILE_SCHEMA, _redReadFile);
+    reg.register('send_payload', _NET_SEND_PAYLOAD_SCHEMA, _netSendPayload);
+    systemPrompt = _RED_BINARY_SYSTEM_PROMPT;
+    debug('_makeRedConfig: category=binary, 3 tools registered');
+  } else {
+    reg.register('sandbox_exec', _RED_SANDBOX_EXEC_SCHEMA, _redSandboxExec);
+    reg.register('http_request', _RED_HTTP_REQUEST_SCHEMA, _redHttpRequest);
+    reg.register('read_file', _RED_READ_FILE_SCHEMA, _redReadFile);
+    systemPrompt = _RED_SYSTEM_PROMPT;
+    debug('_makeRedConfig: category=web, 3 tools registered');
+  }
+
+  return new ModeAgentConfig({
+    mode: 'RED',
+    toolRegistry: reg,
+    systemPromptTemplate: systemPrompt,
+    validator: new FlagValidator(),
+    maxTurns: 30,
+    requiresSandbox: true,
+    completionCheck: _redCompletionCheck,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Mode registry
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, Function>} */
+const MODE_REGISTRY = new Map();
+
+// Register RED mode immediately
+MODE_REGISTRY.set('RED', _makeRedConfig);
+
+/**
+ * Register a mode config factory for use with runAutonomous().
+ *
+ * @param {string} mode - Mode name (will be uppercased)
+ * @param {Function} factory - Callable that returns a fresh ModeAgentConfig
+ * @throws {Error} If the mode is already registered
+ */
+export function registerMode(mode, factory) {
+  const key = mode.toUpperCase();
+  if (MODE_REGISTRY.has(key)) {
+    throw new Error(
+      `Mode already registered: '${key}'. ` +
+      `Registered modes: ${[...MODE_REGISTRY.keys()].sort().join(', ')}`
+    );
+  }
+  MODE_REGISTRY.set(key, factory);
+  debug(`Registered mode: ${key}`);
+}
+
+/**
+ * Return sorted array of registered mode names.
+ * @returns {string[]}
+ */
+export function availableModes() {
+  return [...MODE_REGISTRY.keys()].sort();
+}
+
+/**
+ * Get the MODE_REGISTRY map (for runAutonomous and testing).
+ * @returns {Map<string, Function>}
+ */
+export function getModeRegistry() {
+  return MODE_REGISTRY;
+}
+
+// ---------------------------------------------------------------------------
+// Lazy mode initialization
+// ---------------------------------------------------------------------------
+
+let _modesInitialized = false;
+
+/**
+ * Lazily import all mode files and call their register() functions.
+ * Runs only once — subsequent calls are no-ops.
+ *
+ * @returns {Promise<void>}
+ */
+export async function initModes() {
+  if (_modesInitialized) return;
+  _modesInitialized = true;
+
+  debug('Initializing mode agents');
+
+  const modeModules = await Promise.all([
+    import('./modes/blue.js'),
+    import('./modes/incident.js'),
+    import('./modes/purple.js'),
+    import('./modes/recon.js'),
+    import('./modes/privacy.js'),
+    import('./modes/architect.js'),
+  ]);
+
+  for (const mod of modeModules) {
+    mod.register(registerMode);
+  }
+
+  debug(`Mode initialization complete: ${availableModes().join(', ')}`);
+}
+
+/**
+ * Reset mode initialization state (for testing only).
+ * Clears all modes except RED, resets the initialized flag.
+ */
+export function _resetModes() {
+  _modesInitialized = false;
+  // Keep only RED
+  for (const key of [...MODE_REGISTRY.keys()]) {
+    if (key !== 'RED') {
+      MODE_REGISTRY.delete(key);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// makeAgentClient — auto-detect LLM backend
+// ---------------------------------------------------------------------------
+
+/** Default Claude model when using env var directly */
+const DEFAULT_CLAUDE_MODEL = 'claude-sonnet-4-20250514';
+
+/** Default Ollama model */
+const DEFAULT_OLLAMA_MODEL = 'qwen2.5:32b';
+
+/** Preferred Ollama models in priority order */
+const PREFERRED_OLLAMA_MODELS = [
+  'qwen2.5:32b',
+  'qwen2.5:14b',
+  'llama3.1:70b',
+  'llama3.1:8b',
+  'mistral:7b',
+];
+
+/**
+ * Try loading CIPHER gateway config and building a client.
+ *
+ * @param {string|null} backendOverride
+ * @returns {Promise<{client: Object, model: string}|null>}
+ */
+async function _tryGatewayConfig(backendOverride) {
+  try {
+    const { loadConfig, configExists } = await import('../config.js');
+    if (!configExists()) return null;
+
+    const raw = loadConfig();
+    if (backendOverride) {
+      raw.llm_backend = backendOverride;
+    }
+
+    const { validateConfig } = await import('../gateway/config-validate.js');
+    const config = validateConfig(raw);
+    const { makeClient } = await import('../gateway/client.js');
+    return await makeClient(config);
+  } catch (e) {
+    debug(`_tryGatewayConfig: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Try creating a Claude client from ANTHROPIC_API_KEY env var.
+ *
+ * @returns {Promise<{client: Object, model: string}|null>}
+ */
+async function _tryAnthropicEnv() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return null;
+
+  try {
+    const { makeClient } = await import('../gateway/client.js');
+    const config = {
+      backend: 'claude',
+      claude_api_key: apiKey,
+      claude_model: DEFAULT_CLAUDE_MODEL,
+      claude_timeout: 60,
+    };
+    const result = await makeClient(config);
+    debug(`makeAgentClient: using ANTHROPIC_API_KEY env, model=${DEFAULT_CLAUDE_MODEL}`);
+    return result;
+  } catch (e) {
+    debug(`_tryAnthropicEnv: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Try connecting to local Ollama and picking the best model.
+ *
+ * @returns {Promise<{client: Object, model: string}|null>}
+ */
+async function _tryOllama() {
+  const baseUrl = process.env.OLLAMA_BASE_URL || 'http://localhost:11434';
+  try {
+    // Probe Ollama with a short timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 2000);
+
+    const resp = await fetch(`${baseUrl}/api/tags`, { signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    if (!resp.ok) return null;
+
+    const data = await resp.json();
+    const models = data.models || [];
+    if (models.length === 0) return null;
+
+    // Pick the best available model
+    const availableNames = new Set(models.map(m => m.name || ''));
+    let selected = '';
+    for (const preferred of PREFERRED_OLLAMA_MODELS) {
+      if (availableNames.has(preferred)) {
+        selected = preferred;
+        break;
+      }
+    }
+    if (!selected) {
+      selected = models[0].name || '';
+    }
+    if (!selected) return null;
+
+    const { makeClient } = await import('../gateway/client.js');
+    const config = {
+      backend: 'ollama',
+      ollama_base_url: baseUrl,
+      ollama_model: selected,
+      ollama_timeout: 120,
+    };
+    const result = await makeClient(config);
+    debug(`makeAgentClient: using Ollama at ${baseUrl}, model=${selected}`);
+    return result;
+  } catch (e) {
+    debug(`_tryOllama: ${e.message}`);
+    return null;
+  }
+}
+
+/**
+ * Create an LLM client for autonomous mode.
+ *
+ * Auto-detects the best available backend matching Python's
+ * benchmark.llm.make_agent_client() precedence:
+ *   1. Explicit override → validate and build
+ *   2. CIPHER config file
+ *   3. ANTHROPIC_API_KEY env var
+ *   4. Local Ollama probe
+ *
+ * @param {string|null} [backendOverride=null]
+ * @returns {Promise<{client: Object, model: string}>}
+ * @throws {Error} If no backend is available
+ */
+export async function makeAgentClient(backendOverride = null) {
+  debug(`makeAgentClient: override=${backendOverride || 'none'}`);
+
+  // 1. Explicit override
+  if (backendOverride) {
+    if (backendOverride === 'ollama') {
+      const result = await _tryOllama();
+      if (result) return result;
+      throw new Error(
+        `Ollama not available at ${process.env.OLLAMA_BASE_URL || 'http://localhost:11434'}. ` +
+        'Start Ollama with: ollama serve'
+      );
+    }
+    if (backendOverride === 'claude') {
+      const envResult = await _tryAnthropicEnv();
+      if (envResult) return envResult;
+      const gwResult = await _tryGatewayConfig('claude');
+      if (gwResult) return gwResult;
+      throw new Error(
+        'Claude API key not found. Set ANTHROPIC_API_KEY or run: cipher setup'
+      );
+    }
+    // For other overrides (litellm, etc.), try gateway config
+    const gwResult = await _tryGatewayConfig(backendOverride);
+    if (gwResult) return gwResult;
+    throw new Error(
+      `Backend '${backendOverride}' not configured. Run: cipher setup`
+    );
+  }
+
+  // 2. Try existing CIPHER config
+  const gwResult = await _tryGatewayConfig(null);
+  if (gwResult) return gwResult;
+
+  // 3. Try ANTHROPIC_API_KEY env var
+  const envResult = await _tryAnthropicEnv();
+  if (envResult) return envResult;
+
+  // 4. Try local Ollama
+  const ollamaResult = await _tryOllama();
+  if (ollamaResult) return ollamaResult;
+
+  // 5. Nothing available
+  throw new Error(
+    'No LLM backend available for autonomous mode.\n' +
+    'Options:\n' +
+    '  1. Start Ollama locally: ollama serve && ollama pull qwen2.5:32b\n' +
+    '  2. Set ANTHROPIC_API_KEY environment variable\n' +
+    '  3. Run cipher setup to configure a backend'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// runAutonomous — main dispatch entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an autonomous agent for the given mode.
+ *
+ * Looks up the mode config from MODE_REGISTRY, creates an LLM client,
+ * and runs a BaseAgent loop.
+ *
+ * @param {string} mode - Mode name (case-insensitive)
+ * @param {Object} taskInput - Dict of task parameters passed to BaseAgent.run()
+ * @param {string|null} [backend=null] - LLM backend override
+ * @param {*} [context=null] - Pre-created context (e.g. SandboxContainer)
+ * @returns {Promise<import('./framework.js').ModeAgentResult>}
+ * @throws {Error} If mode is unknown or required context is missing
+ */
+export async function runAutonomous(mode, taskInput, backend = null, context = null) {
+  const modeKey = mode.toUpperCase();
+  debug(`runAutonomous: mode=${modeKey}, backend=${backend || 'auto-detect'}`);
+
+  // Ensure all modes are registered
+  await initModes();
+
+  // Look up mode factory
+  const factory = MODE_REGISTRY.get(modeKey);
+  if (!factory) {
+    throw new Error(
+      `Unknown mode: '${modeKey}'. ` +
+      `Available: ${availableModes().join(', ')}`
+    );
+  }
+
+  // Create fresh config
+  const config = factory();
+
+  // Validate context requirement
+  if (config.requiresSandbox && !context) {
+    throw new Error(
+      `Mode '${modeKey}' requires a sandbox context. ` +
+      `Pass a pre-created context via the 'context' parameter.`
+    );
+  }
+
+  // Create LLM client
+  const { client, model } = await makeAgentClient(backend);
+  debug(`runAutonomous: client ready, model=${model}`);
+
+  // Run the agent
+  const { BaseAgent } = await import('./framework.js');
+  const agent = new BaseAgent({ client, model, config, context });
+  const result = await agent.run(taskInput);
+
+  debug(
+    `runAutonomous: mode=${modeKey} completed — ` +
+    `turns=${result.turnsUsed}, tools=${result.toolCalls}, ` +
+    `tokens_in=${result.tokensIn}, tokens_out=${result.tokensOut}, ` +
+    `valid=${result.validation ? result.validation.valid : 'N/A'}`
+  );
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Exports for testing
+// ---------------------------------------------------------------------------
+
+export {
+  _makeRedConfig,
+  _redCompletionCheck,
+  _redSandboxExec,
+  _redHttpRequest,
+  _redReadFile,
+  _netPortScan,
+  _netConnectTcp,
+  _netSendPayload,
+  _tryGatewayConfig,
+  _tryAnthropicEnv,
+  _tryOllama,
+};