cipher-security 2.0.8 → 2.2.0

package/lib/autonomous/modes/red.js

@@ -0,0 +1,585 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * RED mode agent — Offensive Security / Penetration Testing.
+ *
+ * Extracted from runner.js. Provides sandbox execution, HTTP requests,
+ * file reading, and network exploitation tools for CTF-style challenges.
+ * Supports web, network, and binary challenge categories.
+ *
+ * @module autonomous/modes/red
+ */
+
+import { ModeAgentConfig, ToolRegistry } from '../framework.js';
+import { FlagValidator, FLAG_PATTERN } from '../runner.js';
+
+const debug = process.env.CIPHER_DEBUG === '1'
+  ? (/** @type {string} */ msg) => process.stderr.write(`[red-mode] ${msg}\n`)
+  : () => {};
+
+// ---------------------------------------------------------------------------
+// Completion check
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if text contains a FLAG{hex} pattern.
+ * @param {string} text
+ * @returns {boolean}
+ */
+function _redCompletionCheck(text) {
+  return FLAG_PATTERN.test(text);
+}
+
+// ---------------------------------------------------------------------------
+// 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');
+}
+
+// ---------------------------------------------------------------------------
+// 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'],
+  },
+};
+
+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'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// 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.
+`;
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a RED-mode ModeAgentConfig, selecting tools by challenge category.
+ *
+ * @param {string} [category='web'] - 'web', 'network', or 'binary'
+ * @returns {ModeAgentConfig}
+ */
+export 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,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Handoff filter — strips raw exploit payloads, keeps finding summaries
+// ---------------------------------------------------------------------------
+
+/** @type {import('../handoff.js').HandoffFilter} */
+export const RED_HANDOFF_FILTER = {
+  transform: (context) => {
+    const filtered = {};
+    // Keep structured summaries
+    if (context.reason) filtered.reason = context.reason;
+    if (context.priorOutput) {
+      // Strip raw payloads: long hex strings (0x + 8+ hex chars) and \x escape sequences
+      filtered.priorOutput = context.priorOutput
+        .replace(/0x[0-9a-f]{8,}/gi, '[REDACTED:payload]')
+        .replace(/(\\x[0-9a-f]{2}){3,}/gi, '[REDACTED:payload]')
+        .replace(/[\x00-\x08\x0e-\x1f]/g, '');
+    }
+    if (context.priorFindings) {
+      // Keep finding metadata, strip exploit details
+      const { exploit, payload, shellcode, ...safe } = context.priorFindings;
+      filtered.priorFindings = safe;
+    }
+    return filtered;
+  },
+  acceptsFrom: [], // RED accepts handoffs from any mode
+};
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register RED mode with the given registerMode function.
+ * @param {Function} registerMode
+ */
+export function register(registerMode) {
+  registerMode('RED', _makeRedConfig);
+}
+
+// ---------------------------------------------------------------------------
+// Exports for testing
+// ---------------------------------------------------------------------------
+
+export {
+  _redCompletionCheck,
+  _redSandboxExec,
+  _redHttpRequest,
+  _redReadFile,
+  _netPortScan,
+  _netConnectTcp,
+  _netSendPayload,
+  RED_HANDOFF_FILTER,
+};