palaryn 0.1.0 → 0.3.0

package/src/executor/http-executor.ts

@@ -0,0 +1,330 @@
+import * as http from 'http';
+import * as https from 'https';
+import * as dns from 'dns';
+import * as net from 'net';
+import { URL } from 'url';
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+import { ExecutorConfig } from '../types/config';
+import { ToolExecutor } from './interfaces';
+
+/** Maximum response body size in bytes (10 MB) */
+const MAX_RESPONSE_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Check whether an IP address belongs to a private/reserved range.
+ * Blocks: loopback, link-local, private (RFC 1918), metadata endpoints,
+ * broadcast, multicast, and IPv6 equivalents.
+ */
+export function isPrivateIP(ip: string): boolean {
+  // IPv4 checks
+  if (net.isIPv4(ip)) {
+    const parts = ip.split('.').map(Number);
+    const [a, b] = parts;
+    // Loopback: 127.0.0.0/8
+    if (a === 127) return true;
+    // Link-local: 169.254.0.0/16 (includes cloud metadata 169.254.169.254)
+    if (a === 169 && b === 254) return true;
+    // Private: 10.0.0.0/8
+    if (a === 10) return true;
+    // Private: 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    // Private: 192.168.0.0/16
+    if (a === 192 && b === 168) return true;
+    // Current network: 0.0.0.0/8
+    if (a === 0) return true;
+    // Broadcast
+    if (ip === '255.255.255.255') return true;
+    // Multicast: 224.0.0.0/4
+    if (a >= 224 && a <= 239) return true;
+    return false;
+  }
+
+  // IPv6 checks
+  if (net.isIPv6(ip)) {
+    const normalized = ip.toLowerCase();
+    // Loopback: ::1
+    if (normalized === '::1') return true;
+    // Unspecified: ::
+    if (normalized === '::') return true;
+    // Link-local: fe80::/10
+    if (normalized.startsWith('fe80:')) return true;
+    // Unique local: fc00::/7
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+    // IPv4-mapped IPv6: ::ffff:x.x.x.x
+    const v4Mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(normalized);
+    if (v4Mapped) return isPrivateIP(v4Mapped[1]);
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Resolve a hostname and verify the resolved IP is not private/internal.
+ * Returns the pinned IP address to prevent DNS TOCTOU rebinding attacks.
+ * Prevents SSRF attacks targeting internal services or cloud metadata.
+ */
+function validateResolvedIP(hostname: string): Promise<string> {
+  // Direct IP addresses — check immediately
+  if (net.isIP(hostname)) {
+    if (isPrivateIP(hostname)) {
+      return Promise.reject(new Error(`SSRF blocked: resolved IP ${hostname} is a private/reserved address`));
+    }
+    return Promise.resolve(hostname);
+  }
+
+  return new Promise((resolve, reject) => {
+    dns.lookup(hostname, { all: true }, (err, addresses) => {
+      if (err) return reject(err);
+      if (!addresses || addresses.length === 0) {
+        return reject(new Error(`DNS lookup failed: no addresses found for "${hostname}"`));
+      }
+      for (const addr of addresses) {
+        if (isPrivateIP(addr.address)) {
+          return reject(
+            new Error(`SSRF blocked: hostname "${hostname}" resolved to private IP ${addr.address}`)
+          );
+        }
+      }
+      // Return the first resolved IP for DNS pinning
+      resolve(addresses[0].address);
+    });
+  });
+}
+
+interface CacheEntry {
+  output: ToolOutput;
+  expiresAt: number;
+}
+
+export class HttpExecutor implements ToolExecutor {
+  private config: ExecutorConfig;
+  private cache: Map<string, CacheEntry>;
+  /** Set to false to disable SSRF protection (for testing only). */
+  public ssrfProtectionEnabled: boolean = true;
+
+  constructor(config: ExecutorConfig) {
+    this.config = config;
+    this.cache = new Map();
+  }
+
+  // Execute an HTTP request based on ToolCall args
+  async execute(toolCall: ToolCall): Promise<ToolOutput> {
+    const { method = 'GET', url, headers = {}, body } = toolCall.args;
+
+    if (!url || typeof url !== 'string') {
+      throw new Error('Missing or invalid URL in tool call args');
+    }
+
+    // SSRF protection: block requests to private/internal IPs and pin DNS
+    let pinnedIP: string | undefined;
+    if (this.ssrfProtectionEnabled) {
+      const parsedUrl = new URL(url);
+      pinnedIP = await validateResolvedIP(parsedUrl.hostname);
+    }
+
+    // Check cache for GET requests
+    if (method === 'GET' && this.config.cache.enabled) {
+      const cacheKey = this.getCacheKey(url, headers);
+      const cached = this.getFromCache(cacheKey);
+      if (cached) return cached;
+    }
+
+    // Determine timeout from constraints or config
+    const timeoutMs = toolCall.constraints?.timeout_ms || this.config.http.timeout_ms;
+
+    // Execute with retries
+    let lastError: Error | null = null;
+    const maxRetries = this.config.http.max_retries;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const output = await this.makeRequest(method, url, headers, body, timeoutMs, pinnedIP);
+
+        // Cache successful GET responses
+        if (method === 'GET' && this.config.cache.enabled && output.http_status && output.http_status < 400) {
+          const cacheKey = this.getCacheKey(url, headers);
+          this.setCache(cacheKey, output);
+        }
+
+        return output;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+
+        // Don't retry on client errors (4xx) except 429
+        if (lastError.message.includes('HTTP 4') && !lastError.message.includes('HTTP 429')) {
+          throw lastError;
+        }
+
+        // Don't retry on SSRF blocks
+        if (lastError.message.includes('SSRF blocked')) {
+          throw lastError;
+        }
+
+        // Wait before retry with exponential backoff
+        if (attempt < maxRetries) {
+          const backoffMs = this.config.http.backoff_base_ms * Math.pow(2, attempt);
+          await this.sleep(backoffMs);
+        }
+      }
+    }
+
+    throw lastError || new Error('Request failed after retries');
+  }
+
+  // Make a single HTTP request using Node.js built-in http/https
+  // When pinnedIP is provided (from SSRF DNS validation), the TCP connection
+  // goes to that IP while the Host header and TLS SNI use the original hostname,
+  // preventing DNS rebinding attacks.
+  private makeRequest(
+    method: string,
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+    timeoutMs: number,
+    pinnedIP?: string,
+  ): Promise<ToolOutput> {
+    return new Promise((resolve, reject) => {
+      const parsedUrl = new URL(url);
+      const isHttps = parsedUrl.protocol === 'https:';
+      const transport = isHttps ? https : http;
+
+      const bodyStr = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined;
+
+      const requestHeaders: Record<string, string> = { ...headers };
+      // Default User-Agent so APIs like GitHub don't reject requests
+      if (!requestHeaders['user-agent'] && !requestHeaders['User-Agent']) {
+        requestHeaders['User-Agent'] = 'Palaryn/1.0';
+      }
+      if (bodyStr && !requestHeaders['content-type'] && !requestHeaders['Content-Type']) {
+        requestHeaders['Content-Type'] = 'application/json';
+      }
+      if (bodyStr) {
+        requestHeaders['Content-Length'] = Buffer.byteLength(bodyStr).toString();
+      }
+      // Preserve original Host header when connecting to pinned IP
+      if (pinnedIP && parsedUrl.hostname !== pinnedIP) {
+        requestHeaders['Host'] = parsedUrl.host;
+      }
+
+      const options: http.RequestOptions & { servername?: string } = {
+        hostname: pinnedIP || parsedUrl.hostname,
+        port: parsedUrl.port || (isHttps ? 443 : 80),
+        path: parsedUrl.pathname + parsedUrl.search,
+        method: method.toUpperCase(),
+        headers: requestHeaders,
+        timeout: timeoutMs,
+      };
+
+      // When using pinned IP with HTTPS, set servername for correct TLS SNI
+      if (pinnedIP && isHttps) {
+        options.servername = parsedUrl.hostname;
+      }
+
+      // Pin DNS resolution to the pre-validated IP to prevent TOCTOU rebinding
+      if (pinnedIP) {
+        const family = pinnedIP.includes(':') ? 6 : 4;
+        const agent = new (isHttps ? https : http).Agent({
+          lookup: (_hostname: string, _options: any, callback: Function) => {
+            callback(null, pinnedIP, family);
+          },
+        } as any);
+        options.agent = agent;
+      }
+
+      const req = transport.request(options, (res) => {
+        let data = '';
+        let receivedBytes = 0;
+        let aborted = false;
+
+        res.on('data', (chunk) => {
+          if (aborted) return;
+          receivedBytes += Buffer.byteLength(chunk);
+          if (receivedBytes > MAX_RESPONSE_BODY_BYTES) {
+            aborted = true;
+            req.destroy();
+            reject(new Error(`Response body exceeds maximum size of ${MAX_RESPONSE_BODY_BYTES} bytes`));
+            return;
+          }
+          data += chunk;
+        });
+        res.on('end', () => {
+          if (aborted) return;
+          let parsedBody: unknown = data;
+          const contentType = res.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try { parsedBody = JSON.parse(data); } catch { parsedBody = data; }
+          }
+
+          // Convert response headers to Record<string, string>
+          const responseHeaders: Record<string, string> = {};
+          for (const [key, value] of Object.entries(res.headers)) {
+            if (value) responseHeaders[key] = Array.isArray(value) ? value.join(', ') : value;
+          }
+
+          resolve({
+            http_status: res.statusCode || 0,
+            body: parsedBody,
+            headers: responseHeaders,
+          });
+        });
+      });
+
+      req.on('error', (err) => reject(err));
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error(`Request timeout after ${timeoutMs}ms`));
+      });
+
+      if (bodyStr) {
+        req.write(bodyStr);
+      }
+      req.end();
+    });
+  }
+
+  // Cache key generation
+  private getCacheKey(url: string, headers: Record<string, string>): string {
+    // Use URL + sorted header keys that affect response (Accept, Authorization)
+    const relevantHeaders = ['accept', 'authorization'];
+    const headerStr = relevantHeaders
+      .map(h => `${h}:${headers[h] || headers[h.charAt(0).toUpperCase() + h.slice(1)] || ''}`)
+      .join('|');
+    return `${url}|${headerStr}`;
+  }
+
+  // Get from cache
+  private getFromCache(key: string): ToolOutput | null {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+    return entry.output;
+  }
+
+  // Set cache entry
+  private setCache(key: string, output: ToolOutput): void {
+    this.cache.set(key, {
+      output,
+      expiresAt: Date.now() + this.config.cache.ttl_ms,
+    });
+    // Evict old entries if cache gets too large
+    if (this.cache.size > 1000) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest) this.cache.delete(oldest);
+    }
+  }
+
+  // Clear cache
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  // Sleep utility
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/src/executor/index.ts

@@ -0,0 +1,9 @@
+export { ToolExecutor } from './interfaces';
+export { ExecutorRegistry } from './registry';
+export { HttpExecutor } from './http-executor';
+export { NoopExecutor } from './noop-executor';
+export { SlackExecutor } from './slack-executor';
+export { FilesystemExecutor } from './filesystem-executor';
+export { SQLExecutor } from './sql-executor';
+export { ShellExecutor } from './shell-executor';
+export { WebSocketExecutor } from './websocket-executor';

package/src/executor/interfaces.ts

@@ -0,0 +1,11 @@
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+
+/**
+ * Base interface for all tool executors.
+ * Implement this to add support for new tool types (Slack, Git, DB, etc.).
+ */
+export interface ToolExecutor {
+  /** Execute a tool call and return the output */
+  execute(toolCall: ToolCall): Promise<ToolOutput>;
+}

package/src/executor/noop-executor.ts

@@ -0,0 +1,23 @@
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+import { ToolExecutor } from './interfaces';
+
+/**
+ * No-op executor that returns a canned response without making any external calls.
+ * Useful for dry-run policy testing, development, and unit tests.
+ */
+export class NoopExecutor implements ToolExecutor {
+  private response: ToolOutput;
+
+  constructor(response?: Partial<ToolOutput>) {
+    this.response = {
+      http_status: response?.http_status ?? 200,
+      body: response?.body ?? { dry_run: true, tool: 'noop' },
+      headers: response?.headers ?? {},
+    };
+  }
+
+  async execute(toolCall: ToolCall): Promise<ToolOutput> {
+    return { ...this.response };
+  }
+}

package/src/executor/registry.ts

@@ -0,0 +1,64 @@
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+import { ToolExecutor } from './interfaces';
+
+/**
+ * Registry that maps tool name patterns to executor instances.
+ * Patterns are matched in registration order; first match wins.
+ *
+ * Usage:
+ *   registry.register('http.*', httpExecutor);      // glob-like
+ *   registry.register('http.request', httpExecutor); // exact match
+ *   registry.register('slack.*', slackExecutor);
+ *   registry.register('*', fallbackExecutor);        // catch-all
+ */
+export class ExecutorRegistry {
+  private entries: Array<{ pattern: string; regex: RegExp; executor: ToolExecutor }> = [];
+
+  /** Register an executor for a tool name pattern. Patterns support * as wildcard.
+   *  If prepend is true, the entry is added at the front (higher priority than existing). */
+  register(pattern: string, executor: ToolExecutor, prepend = false): void {
+    // Convert glob pattern to regex: "http.*" -> /^http\..*$/
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    const regex = new RegExp(`^${escaped}$`);
+    if (prepend) {
+      this.entries.unshift({ pattern, regex, executor });
+    } else {
+      this.entries.push({ pattern, regex, executor });
+    }
+  }
+
+  /** Find the executor for a tool name. Returns undefined if no match. */
+  resolve(toolName: string): ToolExecutor | undefined {
+    for (const entry of this.entries) {
+      if (entry.regex.test(toolName)) {
+        return entry.executor;
+      }
+    }
+    return undefined;
+  }
+
+  /** Execute a tool call by resolving the executor from the tool name. */
+  async execute(toolCall: ToolCall): Promise<ToolOutput> {
+    const executor = this.resolve(toolCall.tool.name);
+    if (!executor) {
+      throw new Error(`No executor registered for tool "${toolCall.tool.name}"`);
+    }
+    return executor.execute(toolCall);
+  }
+
+  /** List all registered patterns (for debugging/introspection) */
+  listPatterns(): string[] {
+    return this.entries.map(e => e.pattern);
+  }
+
+  /** Check if any executor is registered for a tool name */
+  has(toolName: string): boolean {
+    return this.resolve(toolName) !== undefined;
+  }
+
+  /** Remove all registered executors */
+  clear(): void {
+    this.entries = [];
+  }
+}

package/src/executor/shell-executor.ts

@@ -0,0 +1,148 @@
+import { execFile } from 'child_process';
+import { ToolCall } from '../types/tool-call';
+import { ToolOutput } from '../types/tool-result';
+import { ToolExecutor } from './interfaces';
+import { ShellExecutorConfig } from '../types/config';
+
+/**
+ * Shell executor for sandboxed command execution.
+ * Handles tool calls with tool name `shell.*` (e.g., shell.exec).
+ * Uses execFile (not exec) to prevent shell injection.
+ * Empty allowlist by default - nothing runs until configured.
+ */
+export class ShellExecutor implements ToolExecutor {
+  private config: ShellExecutorConfig;
+
+  /** Default blocklist of dangerous commands/patterns */
+  private static readonly DEFAULT_BLOCKED = [
+    'rm -rf /',
+    'rm -rf /*',
+    'dd',
+    'mkfs',
+    'fdisk',
+    'format',
+    ':(){:|:&};:',
+    'chmod -R 777 /',
+    'chown -R',
+  ];
+
+  constructor(config: ShellExecutorConfig) {
+    this.config = config;
+  }
+
+  async execute(toolCall: ToolCall): Promise<ToolOutput> {
+    const action = this.resolveAction(toolCall);
+
+    switch (action) {
+      case 'exec':
+        return this.exec(toolCall);
+      default:
+        throw new Error(`Unsupported shell action: ${action}`);
+    }
+  }
+
+  private resolveAction(toolCall: ToolCall): string {
+    if (toolCall.args.action && typeof toolCall.args.action === 'string') {
+      return toolCall.args.action;
+    }
+
+    const toolName = toolCall.tool.name;
+    const dotIndex = toolName.indexOf('.');
+    if (dotIndex !== -1) {
+      return toolName.substring(dotIndex + 1);
+    }
+
+    throw new Error(`Unsupported shell action: ${toolName}`);
+  }
+
+  private isCommandAllowed(command: string): boolean {
+    return this.config.allowed_commands.includes(command);
+  }
+
+  private isCommandBlocked(command: string, args: string[]): boolean {
+    const fullCommand = [command, ...args].join(' ');
+
+    // Check config blocked_commands
+    if (this.config.blocked_commands) {
+      for (const blocked of this.config.blocked_commands) {
+        if (command === blocked || fullCommand.includes(blocked)) {
+          return true;
+        }
+      }
+    }
+
+    // Check default blocklist
+    for (const blocked of ShellExecutor.DEFAULT_BLOCKED) {
+      if (fullCommand.includes(blocked)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private async exec(toolCall: ToolCall): Promise<ToolOutput> {
+    const { command, args: cmdArgs, cwd, env, timeout_ms } = toolCall.args;
+
+    if (!command || typeof command !== 'string') {
+      throw new Error('Missing or invalid "command" argument for shell.exec');
+    }
+
+    if (!this.isCommandAllowed(command)) {
+      throw new Error(`Command "${command}" is not in the allowed commands list`);
+    }
+
+    const argsList: string[] = Array.isArray(cmdArgs) ? cmdArgs.map(String) : [];
+
+    if (this.isCommandBlocked(command, argsList)) {
+      throw new Error(`Command "${command}" with the given arguments is blocked`);
+    }
+
+    const timeoutMs = (typeof timeout_ms === 'number' ? timeout_ms : null) || this.config.timeout_ms;
+    const workingDir = (typeof cwd === 'string' ? cwd : null) || this.config.cwd;
+
+    return new Promise<ToolOutput>((resolve, reject) => {
+      const child = execFile(
+        command,
+        argsList,
+        {
+          timeout: timeoutMs,
+          maxBuffer: this.config.max_output_bytes,
+          cwd: workingDir || undefined,
+          env: env && typeof env === 'object' ? { ...process.env, ...(env as Record<string, string>) } : undefined,
+        },
+        (error, stdout, stderr) => {
+          if (error && !('code' in error)) {
+            reject(error);
+            return;
+          }
+
+          const exitCode = error && 'code' in error ? (error as { code: number }).code : 0;
+          const stdoutStr = typeof stdout === 'string' ? stdout : '';
+          const stderrStr = typeof stderr === 'string' ? stderr : '';
+
+          // Enforce max_output_bytes on combined output
+          const totalBytes = Buffer.byteLength(stdoutStr) + Buffer.byteLength(stderrStr);
+          if (totalBytes > this.config.max_output_bytes) {
+            resolve({
+              body: stdoutStr.substring(0, this.config.max_output_bytes),
+              exit_code: exitCode,
+              stderr: stderrStr.substring(0, 1024),
+              metadata: { truncated: true, total_bytes: totalBytes },
+            });
+            return;
+          }
+
+          resolve({
+            body: stdoutStr,
+            exit_code: exitCode,
+            stderr: stderrStr || undefined,
+          });
+        },
+      );
+
+      // Safety: ensure child process is cleaned up
+      child.on('error', reject);
+    });
+  }
+}