/** * Sandbox Executor - command filtering before running a command on the host. * * Every mode checks the command text against allow/deny lists and then runs it * on the host as the current user. It is not isolation and not a security * boundary (see SECURITY.md, "Not a security boundary"): a filter over a * command string cannot be complete. For untrusted commands use an isolating * backend from praisonai-sandbox (Docker, Sandlock, E2B, ...). * * Mode names are kept for compatibility and describe what is filtered: * - `basic`: deny-listed commands, paths and shell patterns. * - `strict`: as basic, no shell, and a minimal environment. * - `network-isolated`: as basic, plus network-tool names refused and proxy * variables pointed at a dead port. The process still has network access. * - `disabled`: nothing runs. */ export type SandboxMode = 'disabled' | 'basic' | 'strict' | 'network-isolated'; export interface SandboxConfig { mode: SandboxMode; allowedCommands?: string[]; blockedCommands?: string[]; blockedPaths?: string[]; timeout?: number; maxOutputSize?: number; cwd?: string; env?: Record; } export interface ExecutionResult { success: boolean; stdout: string; stderr: string; exitCode: number; duration: number; truncated?: boolean; } /** * Default blocked commands (dangerous operations) */ export declare const DEFAULT_BLOCKED_COMMANDS: string[]; /** * Default blocked paths */ export declare const DEFAULT_BLOCKED_PATHS: string[]; /** Shell metacharacters that enable command chaining or substitution */ export declare const SHELL_METACHAR_PATTERN: RegExp; /** Commands that typically require network access */ export declare const NETWORK_COMMANDS: string[]; export declare function containsShellMetacharacters(command: string): boolean; /** * Command validator: string checks on the command text. A guard rail against * mistakes, not a boundary. */ export declare class CommandValidator { private blockedCommands; private blockedPaths; private allowedCommands?; private networkIsolated; constructor(config?: Partial); /** * Validate a command */ validate(command: string): { valid: boolean; reason?: string; }; } /** * Sandbox Executor: filters a command, then runs it on the host (not isolated). */ export declare class SandboxExecutor { private config; private validator; constructor(config?: Partial); /** * Filter the command, then run it on the host as the current user */ execute(command: string): Promise; /** * Spawn the command without shell when allowlisted or in strict mode */ private spawn; /** * Build environment variables based on the filter mode */ private buildEnv; /** * Check if a command would be allowed */ wouldAllow(command: string): { allowed: boolean; reason?: string; }; /** * Get current filter mode */ getMode(): SandboxMode; /** * Update filter mode */ setMode(mode: SandboxMode): void; } /** * Create a command executor that filters, then runs on the host */ export declare function createSandboxExecutor(config?: Partial): SandboxExecutor; /** * Quick execute with the default (`basic`) filter, on the host */ export declare function sandboxExec(command: string, config?: Partial): Promise;