@unrdf/knowledge-engine 5.0.1

package/src/security/sandbox-restrictions.mjs

@@ -0,0 +1,331 @@
+/**
+ * @file Sandbox Restrictions for Hook Execution
+ * @module sandbox-restrictions
+ *
+ * @description
+ * Defines and enforces security restrictions for sandboxed hook execution.
+ * Prevents privilege escalation and unauthorized system access.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for sandbox configuration
+ */
+const SandboxConfigSchema = z
+  .object({
+    allowFileSystem: z.boolean().default(false),
+    allowNetwork: z.boolean().default(false),
+    allowProcessAccess: z.boolean().default(false),
+    allowEval: z.boolean().default(false),
+    timeoutMs: z.number().default(5000),
+    memoryLimitMB: z.number().default(50),
+    maxIterations: z.number().default(100000),
+  })
+  .strict();
+
+/**
+ * Dangerous Node.js modules that should be blocked
+ */
+const BLOCKED_MODULES = new Set([
+  'fs',
+  'fs/promises',
+  'child_process',
+  'cluster',
+  'crypto',
+  'dgram',
+  'dns',
+  'http',
+  'https',
+  'http2',
+  'inspector',
+  'net',
+  'os',
+  'perf_hooks',
+  'process',
+  'repl',
+  'tls',
+  'tty',
+  'v8',
+  'vm',
+  'worker_threads',
+  'zlib',
+]);
+
+/**
+ * Dangerous global objects/functions
+ */
+const BLOCKED_GLOBALS = new Set([
+  'eval',
+  'Function',
+  'require',
+  'import',
+  'process',
+  'global',
+  '__dirname',
+  '__filename',
+  'Buffer',
+  'clearImmediate',
+  'setImmediate',
+  'clearInterval',
+  'clearTimeout',
+  'setInterval',
+  'setTimeout',
+]);
+
+/**
+ * Sandbox Restrictions Manager
+ */
+export class SandboxRestrictions {
+  /**
+   * @param {Object} [config] - Sandbox configuration
+   */
+  constructor(config = {}) {
+    this.config = SandboxConfigSchema.parse(config);
+    this.iterationCount = 0;
+    this.startTime = null;
+  }
+
+  /**
+   * Create a restricted context for hook execution
+   * @returns {Object} Restricted context object
+   */
+  createRestrictedContext() {
+    const context = {
+      // Allow safe Math operations
+      Math: Math,
+
+      // Allow safe JSON operations
+      JSON: JSON,
+
+      // Allow safe Date operations (read-only)
+      Date: Date,
+
+      // Allow safe String/Number/Boolean/Array operations
+      String: String,
+      Number: Number,
+      Boolean: Boolean,
+      Array: Array,
+      Object: Object,
+
+      // Logging (safe, write-only)
+      console: {
+        log: (...args) => console.log('[Sandboxed]', ...args),
+        error: (...args) => console.error('[Sandboxed]', ...args),
+        warn: (...args) => console.warn('[Sandboxed]', ...args),
+      },
+
+      // Block dangerous functions
+      eval: undefined,
+      Function: undefined,
+      require: undefined,
+      import: undefined,
+      process: undefined,
+      global: undefined,
+      __dirname: undefined,
+      __filename: undefined,
+      Buffer: undefined,
+
+      // Block timers (DoS prevention)
+      setTimeout: undefined,
+      setInterval: undefined,
+      setImmediate: undefined,
+      clearTimeout: undefined,
+      clearInterval: undefined,
+      clearImmediate: undefined,
+    };
+
+    // Freeze context to prevent modification
+    return Object.freeze(context);
+  }
+
+  /**
+   * Validate hook function code for dangerous patterns
+   * @param {Function} hookFn - Hook function to validate
+   * @returns {Object} Validation result { valid, violations }
+   */
+  validateHookCode(hookFn) {
+    if (typeof hookFn !== 'function') {
+      return {
+        valid: false,
+        violations: ['Hook must be a function'],
+      };
+    }
+
+    const codeString = hookFn.toString();
+    const violations = [];
+
+    // Check for blocked module requires
+    for (const moduleName of BLOCKED_MODULES) {
+      if (codeString.includes(`require('${moduleName}')`)) {
+        violations.push(`Blocked module access: ${moduleName}`);
+      }
+      if (codeString.includes(`require("${moduleName}")`)) {
+        violations.push(`Blocked module access: ${moduleName}`);
+      }
+      if (codeString.includes(`from '${moduleName}'`)) {
+        violations.push(`Blocked module import: ${moduleName}`);
+      }
+    }
+
+    // Check for blocked globals
+    for (const globalName of BLOCKED_GLOBALS) {
+      // Use word boundaries to avoid false positives
+      const pattern = new RegExp(`\\b${globalName}\\b`, 'g');
+      if (pattern.test(codeString)) {
+        violations.push(`Blocked global access: ${globalName}`);
+      }
+    }
+
+    // Check for file system access patterns
+    if (!this.config.allowFileSystem) {
+      if (/\bfs\./g.test(codeString) || /readFileSync|writeFileSync/g.test(codeString)) {
+        violations.push('File system access not allowed');
+      }
+    }
+
+    // Check for network access patterns
+    if (!this.config.allowNetwork) {
+      if (/\bfetch\(|XMLHttpRequest|WebSocket/g.test(codeString)) {
+        violations.push('Network access not allowed');
+      }
+    }
+
+    // Check for process access
+    if (!this.config.allowProcessAccess) {
+      if (/\bprocess\./g.test(codeString)) {
+        violations.push('Process access not allowed');
+      }
+    }
+
+    // Check for eval usage
+    if (!this.config.allowEval) {
+      if (/\beval\(|new Function\(/g.test(codeString)) {
+        violations.push('Dynamic code evaluation not allowed');
+      }
+    }
+
+    return {
+      valid: violations.length === 0,
+      violations,
+    };
+  }
+
+  /**
+   * Execute a hook function with restrictions
+   * @param {Function} hookFn - Hook function to execute
+   * @param {Object} event - Event object
+   * @returns {Promise<Object>} Execution result
+   */
+  async executeRestricted(hookFn, event) {
+    // Validate code before execution
+    const validation = this.validateHookCode(hookFn);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: `Security validation failed: ${validation.violations.join(', ')}`,
+      };
+    }
+
+    this.startTime = Date.now();
+    this.iterationCount = 0;
+
+    try {
+      // Create restricted context
+      const restrictedContext = this.createRestrictedContext();
+
+      // Execute with timeout
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Execution timeout after ${this.config.timeoutMs}ms`));
+        }, this.config.timeoutMs);
+      });
+
+      // Wrap hook function to prevent context mutation
+      const wrappedFn = async () => {
+        try {
+          // Prevent event mutation by freezing
+          const frozenEvent = this._deepFreeze({ ...event });
+
+          // Execute in restricted context
+          const result = await hookFn.call(restrictedContext, frozenEvent);
+
+          // Check iteration limit
+          if (this.iterationCount > this.config.maxIterations) {
+            throw new Error('Maximum iteration count exceeded');
+          }
+
+          return result;
+        } catch (error) {
+          // Block system access errors
+          if (error.code === 'EACCES' || error.code === 'EPERM') {
+            return {
+              success: false,
+              error: 'System access denied',
+            };
+          }
+          throw error;
+        }
+      };
+
+      const result = await Promise.race([wrappedFn(), timeoutPromise]);
+
+      return result || { success: true };
+    } catch (error) {
+      if (error.message.includes('timeout')) {
+        return {
+          success: false,
+          error: 'Execution timeout exceeded',
+        };
+      }
+
+      if (error.message.includes('iteration')) {
+        return {
+          success: false,
+          error: 'Maximum iteration count exceeded',
+        };
+      }
+
+      return {
+        success: false,
+        error: error.message || 'Hook execution failed',
+      };
+    }
+  }
+
+  /**
+   * Deep freeze an object to prevent mutation
+   * @param {Object} obj - Object to freeze
+   * @returns {Object} Frozen object
+   * @private
+   */
+  _deepFreeze(obj) {
+    if (obj === null || typeof obj !== 'object') {
+      return obj;
+    }
+
+    Object.freeze(obj);
+
+    Object.getOwnPropertyNames(obj).forEach(prop => {
+      if (obj[prop] !== null && typeof obj[prop] === 'object') {
+        this._deepFreeze(obj[prop]);
+      }
+    });
+
+    return obj;
+  }
+}
+
+/**
+ * Create sandbox restrictions instance
+ * @param {Object} [config] - Sandbox configuration
+ * @returns {SandboxRestrictions} Restrictions instance
+ */
+export function createSandboxRestrictions(config = {}) {
+  return new SandboxRestrictions(config);
+}
+
+/**
+ * Default sandbox restrictions (strict mode)
+ */
+export const defaultSandboxRestrictions = new SandboxRestrictions();

package/src/security-validator.mjs

@@ -0,0 +1,389 @@
+/**
+ * @file Security Validator for Knowledge Hooks
+ * @module security-validator
+ *
+ * @description
+ * Security validation functions for preventing malicious patterns,
+ * injection attacks, and unauthorized access in knowledge hooks.
+ */
+
+import { z } from 'zod';
+
+/**
+ * Schema for security validation result
+ */
+const SecurityValidationResultSchema = z.object({
+  valid: z.boolean(),
+  violations: z.array(z.string()).default([]),
+  blocked: z.boolean().default(false),
+  blockReason: z.string().optional(),
+  securityViolation: z.string().optional(),
+});
+
+/**
+ * Security Validator for Knowledge Hooks
+ */
+export class SecurityValidator {
+  /**
+   *
+   */
+  constructor(options = {}) {
+    this.strictMode = options.strictMode ?? true;
+    this.enablePathTraversalCheck = options.enablePathTraversalCheck ?? true;
+    this.enableInjectionCheck = options.enableInjectionCheck ?? true;
+    this.enableResourceLimitCheck = options.enableResourceLimitCheck ?? true;
+  }
+
+  /**
+   * Validate a file URI for malicious patterns
+   * @param {string} uri - The file URI to validate
+   * @returns {Object} Validation result
+   */
+  validateFileUri(uri) {
+    const violations = [];
+
+    if (!uri || typeof uri !== 'string') {
+      return {
+        valid: false,
+        violations: ['Invalid URI: must be a non-empty string'],
+        blocked: true,
+        blockReason: 'Invalid URI format',
+      };
+    }
+
+    // Skip validation in non-strict mode (for tests)
+    if (!this.strictMode) {
+      return {
+        valid: true,
+        violations: [],
+        blocked: false,
+      };
+    }
+
+    // Check for path traversal patterns
+    if (this.enablePathTraversalCheck) {
+      const pathTraversalPatterns = [
+        /\.\.\//g, // ../
+        /\.\.\\/g, // ..\
+        /\.\.%2f/gi, // ..%2f (URL encoded)
+        /\.\.%5c/gi, // ..%5c (URL encoded)
+        /\.\.%252f/gi, // Double URL encoded
+        /\.\.%255c/gi, // Double URL encoded
+        /\.\.%c0%af/gi, // Unicode bypass
+        /\.\.%c1%9c/gi, // Unicode bypass
+      ];
+
+      for (const pattern of pathTraversalPatterns) {
+        if (pattern.test(uri)) {
+          violations.push('Path traversal detected');
+          break;
+        }
+      }
+
+      // Check for absolute paths
+      if (uri.includes('://') && !uri.startsWith('file://')) {
+        violations.push('Absolute path detected');
+      }
+
+      // Check for system paths
+      const systemPaths = ['/etc/', '/usr/', '/bin/', '/sbin/', '/var/', 'C:\\', 'D:\\'];
+      for (const sysPath of systemPaths) {
+        if (uri.includes(sysPath)) {
+          violations.push('System path access detected');
+          break;
+        }
+      }
+    }
+
+    // Check for injection patterns
+    if (this.enableInjectionCheck) {
+      const injectionPatterns = [
+        /<script[^>]*>/gi, // Script tags
+        /javascript:/gi, // JavaScript protocol
+        /data:text\/html/gi, // Data URLs
+        /vbscript:/gi, // VBScript protocol
+        /on\w+\s*=/gi, // Event handlers
+        /eval\s*\(/gi, // Eval function
+        /Function\s*\(/gi, // Function constructor
+        /setTimeout\s*\(/gi, // setTimeout
+        /setInterval\s*\(/gi, // setInterval
+      ];
+
+      for (const pattern of injectionPatterns) {
+        if (pattern.test(uri)) {
+          violations.push('Code injection pattern detected');
+          break;
+        }
+      }
+    }
+
+    const blocked = violations.length > 0;
+    const result = {
+      valid: !blocked,
+      violations,
+      blocked,
+      blockReason: blocked ? violations.join(', ') : undefined,
+      securityViolation: blocked ? violations[0] : undefined,
+    };
+
+    return SecurityValidationResultSchema.parse(result);
+  }
+
+  /**
+   * Validate a SPARQL query for dangerous operations
+   * @param {string} sparql - The SPARQL query to validate
+   * @returns {Object} Validation result
+   */
+  validateSparqlQuery(sparql) {
+    const violations = [];
+
+    if (!sparql || typeof sparql !== 'string') {
+      return {
+        valid: false,
+        violations: ['Invalid SPARQL: must be a non-empty string'],
+        blocked: true,
+        blockReason: 'Invalid SPARQL format',
+      };
+    }
+
+    // Skip validation in non-strict mode (for tests)
+    if (!this.strictMode) {
+      return {
+        valid: true,
+        violations: [],
+        blocked: false,
+      };
+    }
+
+    const upperSparql = sparql.toUpperCase();
+
+    // Check for dangerous SPARQL operations
+    const dangerousOperations = [
+      'INSERT',
+      'DELETE',
+      'DROP',
+      'CREATE',
+      'LOAD',
+      'CLEAR',
+      'COPY',
+      'MOVE',
+      'ADD',
+      'MODIFY',
+      'ALTER',
+    ];
+
+    for (const operation of dangerousOperations) {
+      if (upperSparql.includes(operation)) {
+        violations.push(`Dangerous SPARQL operation: ${operation}`);
+      }
+    }
+
+    // Check for injection patterns
+    if (this.enableInjectionCheck) {
+      const injectionPatterns = [
+        /UNION\s+SELECT/gi, // UNION injection
+        /';.*--/gi, // SQL comment injection
+        /\/\*.*\*\//gi, // Block comment injection
+        /0x[0-9a-f]+/gi, // Hex encoding
+        /CHAR\s*\(/gi, // CHAR function
+        /ASCII\s*\(/gi, // ASCII function
+        /SUBSTRING\s*\(/gi, // SUBSTRING function
+        /CONCAT\s*\(/gi, // CONCAT function
+      ];
+
+      for (const pattern of injectionPatterns) {
+        if (pattern.test(sparql)) {
+          violations.push('SPARQL injection pattern detected');
+          break;
+        }
+      }
+    }
+
+    // Check for resource exhaustion patterns
+    if (this.enableResourceLimitCheck) {
+      const resourcePatterns = [
+        /SELECT\s+\*\s+WHERE\s*\{[^}]*\?[a-zA-Z_][a-zA-Z0-9_]*\s+\?[a-zA-Z_][a-zA-Z0-9_]*\s+\?[a-zA-Z_][a-zA-Z0-9_]*[^}]*\}/gi, // Cartesian product
+        /OPTIONAL\s*\{[^}]*OPTIONAL\s*\{[^}]*OPTIONAL\s*\{/gi, // Deep optional nesting
+      ];
+
+      for (const pattern of resourcePatterns) {
+        if (pattern.test(sparql)) {
+          violations.push('Resource exhaustion pattern detected');
+          break;
+        }
+      }
+    }
+
+    const blocked = violations.length > 0;
+    const result = {
+      valid: !blocked,
+      violations,
+      blocked,
+      blockReason: blocked ? violations.join(', ') : undefined,
+      securityViolation: blocked ? violations[0] : undefined,
+    };
+
+    return SecurityValidationResultSchema.parse(result);
+  }
+
+  /**
+   * Validate a hook effect for security violations
+   * @param {string} effectCode - The effect code to validate
+   * @returns {Object} Validation result
+   */
+  validateEffectCode(effectCode) {
+    const violations = [];
+
+    if (!effectCode || typeof effectCode !== 'string') {
+      return {
+        valid: false,
+        violations: ['Invalid effect code: must be a non-empty string'],
+        blocked: true,
+        blockReason: 'Invalid effect code format',
+      };
+    }
+
+    // Skip validation in non-strict mode (for tests)
+    if (!this.strictMode) {
+      return {
+        valid: true,
+        violations: [],
+        blocked: false,
+      };
+    }
+
+    // Check for dangerous JavaScript patterns
+    const dangerousPatterns = [
+      /require\s*\(/gi, // require() calls
+      /import\s+.*\s+from/gi, // ES6 imports
+      /process\./gi, // process object access
+      /global\./gi, // global object access
+      /window\./gi, // window object access
+      /document\./gi, // document object access
+      /eval\s*\(/gi, // eval function
+      /new\s+Function\s*\(/gi, // Function constructor
+      /setTimeout\s*\(/gi, // setTimeout
+      /setInterval\s*\(/gi, // setInterval
+      /setImmediate\s*\(/gi, // setImmediate
+      /fs\./gi, // filesystem access
+      /child_process/gi, // child process
+      /os\./gi, // OS access
+      /crypto\./gi, // crypto access
+      /http\./gi, // HTTP access
+      /https\./gi, // HTTPS access
+      /net\./gi, // network access
+      /dns\./gi, // DNS access
+      /tls\./gi, // TLS access
+      /cluster\./gi, // cluster access
+      /worker_threads/gi, // worker threads
+    ];
+
+    for (const pattern of dangerousPatterns) {
+      if (pattern.test(effectCode)) {
+        violations.push(`Dangerous JavaScript pattern: ${pattern.source}`);
+      }
+    }
+
+    // Check for infinite loops
+    const loopPatterns = [
+      /while\s*\(\s*true\s*\)/gi, // while(true)
+      /for\s*\(\s*;\s*;\s*\)/gi, // for(;;)
+      /for\s*\(\s*.*\s*;\s*.*\s*;\s*\)/gi, // for loops without increment
+    ];
+
+    for (const pattern of loopPatterns) {
+      if (pattern.test(effectCode)) {
+        violations.push('Potential infinite loop detected');
+      }
+    }
+
+    const blocked = violations.length > 0;
+    const result = {
+      valid: !blocked,
+      violations,
+      blocked,
+      blockReason: blocked ? violations.join(', ') : undefined,
+      securityViolation: blocked ? violations[0] : undefined,
+    };
+
+    return SecurityValidationResultSchema.parse(result);
+  }
+
+  /**
+   * Validate a knowledge hook for security violations
+   * @param {Object} hook - The knowledge hook to validate
+   * @returns {Object} Validation result
+   */
+  validateKnowledgeHook(hook) {
+    const violations = [];
+
+    if (!hook || typeof hook !== 'object') {
+      return {
+        valid: false,
+        violations: ['Invalid hook: must be an object'],
+        blocked: true,
+        blockReason: 'Invalid hook format',
+      };
+    }
+
+    // Skip validation in non-strict mode (for tests)
+    if (!this.strictMode) {
+      return {
+        valid: true,
+        violations: [],
+        blocked: false,
+      };
+    }
+
+    // Validate hook metadata
+    if (!hook.meta || !hook.meta.name) {
+      violations.push('Hook missing required metadata');
+    }
+
+    // Validate condition
+    if (hook.when) {
+      if (hook.when.kind === 'sparql-ask' || hook.when.kind === 'sparql-select') {
+        if (hook.when.ref && hook.when.ref.uri) {
+          const uriValidation = this.validateFileUri(hook.when.ref.uri);
+          if (!uriValidation.valid) {
+            violations.push(...uriValidation.violations);
+          }
+        }
+      }
+    }
+
+    // Validate effect code
+    if (hook.run && typeof hook.run === 'function') {
+      const effectCode = hook.run.toString();
+      const effectValidation = this.validateEffectCode(effectCode);
+      if (!effectValidation.valid) {
+        violations.push(...effectValidation.violations);
+      }
+    }
+
+    const blocked = violations.length > 0;
+    const result = {
+      valid: !blocked,
+      violations,
+      blocked,
+      blockReason: blocked ? violations.join(', ') : undefined,
+      securityViolation: blocked ? violations[0] : undefined,
+    };
+
+    return SecurityValidationResultSchema.parse(result);
+  }
+}
+
+/**
+ * Create a security validator instance
+ * @param {Object} [options] - Validator options
+ * @returns {SecurityValidator} Validator instance
+ */
+export function createSecurityValidator(options = {}) {
+  return new SecurityValidator(options);
+}
+
+/**
+ * Default security validator instance
+ */
+export const defaultSecurityValidator = new SecurityValidator();