aiox-core 5.0.0

package/docs/guides/security-hardening.md

@@ -0,0 +1,1359 @@
+# AIOX Security Hardening Guide
+
+> **EN** | [PT](../pt/guides/security-hardening.md) | [ES](../es/guides/security-hardening.md)
+
+---
+
+> Complete guide to hardening security for Synkra AIOX deployments - from development to production.
+
+**Version:** 2.1.0
+**Last Updated:** 2026-01-29
+
+---
+
+## Table of Contents
+
+1. [Security Overview](#security-overview)
+2. [API Key Management](#api-key-management)
+3. [Environment Variables and Secrets](#environment-variables-and-secrets)
+4. [File and Directory Permissions](#file-and-directory-permissions)
+5. [Sandboxing and Isolation](#sandboxing-and-isolation)
+6. [Input Validation](#input-validation)
+7. [Injection Protection](#injection-protection)
+8. [Logging and Auditing](#logging-and-auditing)
+9. [Production vs Development Configuration](#production-vs-development-configuration)
+10. [Security Checklist](#security-checklist)
+11. [Vulnerability Reporting](#vulnerability-reporting)
+
+---
+
+## Security Overview
+
+Synkra AIOX operates at a privileged layer between AI models and your system. This guide covers hardening strategies specific to AI-orchestrated development environments.
+
+### Security Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        EXTERNAL LAYER                            │
+│    Network Firewall | WAF | TLS Termination | Rate Limiting     │
+├─────────────────────────────────────────────────────────────────┤
+│                      APPLICATION LAYER                           │
+│   Permission Modes | Input Validation | Command Sanitization    │
+├─────────────────────────────────────────────────────────────────┤
+│                       EXECUTION LAYER                            │
+│    Sandboxing | Process Isolation | Resource Limits | Hooks     │
+├─────────────────────────────────────────────────────────────────┤
+│                         DATA LAYER                               │
+│   Encryption at Rest | Secure Storage | Audit Logging           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### AIOX-Specific Security Concerns
+
+| Concern                  | Risk Level | Mitigation                        |
+| ------------------------ | ---------- | --------------------------------- |
+| Agent code execution     | CRITICAL   | Permission Modes, Sandboxing      |
+| API key exposure         | CRITICAL   | Environment isolation, encryption |
+| Command injection via AI | HIGH       | Input sanitization, hooks         |
+| Unauthorized file access | HIGH       | Directory restrictions            |
+| Session hijacking        | MEDIUM     | Token rotation, secure storage    |
+| Information disclosure   | MEDIUM     | Audit logging, access controls    |
+
+### Defense in Depth
+
+AIOX implements multiple layers of protection:
+
+1. **Permission Modes** - Control agent autonomy (Explore/Ask/Auto)
+2. **Claude Hooks** - Pre-execution validation (read-protection, sql-governance)
+3. **Input Sanitization** - All user/AI input is validated
+4. **Process Isolation** - MCP servers run in containers
+5. **Audit Logging** - All operations are recorded
+
+---
+
+## API Key Management
+
+API keys are the most critical secrets in AIOX. Compromised keys can lead to unauthorized usage, data breaches, and significant financial impact.
+
+### Storage Hierarchy
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│  NEVER                                                          │
+│  ❌ Source code                                                 │
+│  ❌ Git repositories                                            │
+│  ❌ Configuration files (committed)                             │
+│  ❌ Log files                                                   │
+│  ❌ Error messages                                              │
+├────────────────────────────────────────────────────────────────┤
+│  ACCEPTABLE (Development)                                       │
+│  ⚠️  .env files (gitignored)                                    │
+│  ⚠️  Local environment variables                                │
+├────────────────────────────────────────────────────────────────┤
+│  RECOMMENDED (Production)                                       │
+│  ✅ Secret managers (Vault, AWS Secrets, etc.)                  │
+│  ✅ CI/CD secret injection                                      │
+│  ✅ Kubernetes secrets                                          │
+│  ✅ Encrypted credential stores                                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### Secure API Key Configuration
+
+**Development (.env file - never commit)**
+
+```bash
+# .env - Add to .gitignore IMMEDIATELY
+# API Provider Keys
+ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# MCP Server Keys
+EXA_API_KEY=exa-xxxxxxxxxxxxxxxxxxxxxxxx
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+APIFY_TOKEN=apify_api_xxxxxxxxxxxxxxxxxxxxx
+
+# Never use default or weak values
+JWT_SECRET=your-256-bit-cryptographically-secure-random-key
+```
+
+**Production (using secret manager)**
+
+```javascript
+// Load secrets from secure vault
+const secrets = await SecretManager.loadSecrets({
+  provider: 'aws-secrets-manager', // or 'hashicorp-vault', 'gcp-secrets'
+  secretName: 'aiox/production/api-keys',
+  region: process.env.AWS_REGION,
+});
+
+process.env.ANTHROPIC_API_KEY = secrets.ANTHROPIC_API_KEY;
+process.env.OPENAI_API_KEY = secrets.OPENAI_API_KEY;
+```
+
+### Key Rotation Policy
+
+| Key Type         | Rotation Frequency | On Compromise      |
+| ---------------- | ------------------ | ------------------ |
+| AI Provider Keys | 90 days            | Immediate          |
+| JWT Secrets      | 30 days            | Immediate          |
+| MCP Server Keys  | 90 days            | Immediate          |
+| Service Tokens   | 7 days             | Immediate          |
+| Development Keys | Never reuse        | Revoke immediately |
+
+### Key Validation on Startup
+
+```javascript
+// .aiox-core/core/security/key-validator.js
+const requiredKeys = [
+  { name: 'ANTHROPIC_API_KEY', pattern: /^sk-ant-[a-zA-Z0-9_-]+$/ },
+  { name: 'JWT_SECRET', minLength: 32 },
+];
+
+function validateApiKeys() {
+  const errors = [];
+
+  for (const key of requiredKeys) {
+    const value = process.env[key.name];
+
+    if (!value) {
+      errors.push(`Missing required key: ${key.name}`);
+      continue;
+    }
+
+    if (key.pattern && !key.pattern.test(value)) {
+      errors.push(`Invalid format for ${key.name}`);
+    }
+
+    if (key.minLength && value.length < key.minLength) {
+      errors.push(`${key.name} must be at least ${key.minLength} characters`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`API Key Validation Failed:\n${errors.join('\n')}`);
+  }
+}
+```
+
+---
+
+## Environment Variables and Secrets
+
+### Secure .env File Template
+
+```bash
+# ============================================================
+# AIOX ENVIRONMENT CONFIGURATION
+# ============================================================
+# SECURITY: This file must NEVER be committed to version control
+# Add to .gitignore: .env, .env.local, .env.*.local
+# ============================================================
+
+# ------------------------------------------------------------
+# ENVIRONMENT
+# ------------------------------------------------------------
+NODE_ENV=development
+AIOX_DEBUG=false
+LOG_LEVEL=info
+
+# ------------------------------------------------------------
+# AI PROVIDER CONFIGURATION
+# ------------------------------------------------------------
+# Primary provider
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=
+
+# Fallback provider (optional)
+OPENAI_API_KEY=
+
+# ------------------------------------------------------------
+# AUTHENTICATION & SESSION
+# ------------------------------------------------------------
+# Generate with: openssl rand -hex 32
+JWT_SECRET=
+JWT_EXPIRY=1h
+REFRESH_TOKEN_EXPIRY=7d
+
+# Session configuration
+SESSION_SECRET=
+SESSION_TIMEOUT=3600000
+
+# ------------------------------------------------------------
+# ENCRYPTION
+# ------------------------------------------------------------
+# Generate with: openssl rand -hex 32
+DATABASE_ENCRYPTION_KEY=
+FILE_ENCRYPTION_KEY=
+
+# ------------------------------------------------------------
+# MCP SERVERS
+# ------------------------------------------------------------
+# EXA Web Search
+EXA_API_KEY=
+
+# GitHub Integration
+GITHUB_TOKEN=
+
+# Apify Web Scraping
+APIFY_TOKEN=
+
+# ------------------------------------------------------------
+# SECURITY SETTINGS
+# ------------------------------------------------------------
+# Rate limiting
+RATE_LIMIT_WINDOW=900000
+RATE_LIMIT_MAX_REQUESTS=1000
+
+# CORS (production only)
+CORS_ORIGIN=https://your-domain.com
+
+# Content Security Policy
+CSP_ENABLED=true
+
+# ------------------------------------------------------------
+# AUDIT & LOGGING
+# ------------------------------------------------------------
+AUDIT_LOG_ENABLED=true
+AUDIT_LOG_PATH=/var/log/aiox/audit.log
+AUDIT_LOG_RETENTION_DAYS=90
+```
+
+### Secret File Protection
+
+```bash
+# Create secure directory for secrets
+mkdir -p ~/.aiox/secrets
+chmod 700 ~/.aiox/secrets
+
+# Create encrypted secrets file
+# Never store plaintext secrets
+openssl enc -aes-256-cbc -salt -pbkdf2 \
+  -in secrets.txt \
+  -out ~/.aiox/secrets/encrypted.dat
+
+# Set proper permissions
+chmod 600 ~/.aiox/secrets/*
+
+# Verify no secrets in git history
+git log -p --all -S "API_KEY" -- .
+```
+
+### Environment Isolation
+
+```javascript
+// Validate environment isolation
+function validateEnvironment() {
+  // Ensure production secrets aren't used in development
+  if (process.env.NODE_ENV === 'development') {
+    if (process.env.ANTHROPIC_API_KEY?.includes('prod')) {
+      throw new Error('Production API key detected in development environment');
+    }
+  }
+
+  // Ensure debug mode is off in production
+  if (process.env.NODE_ENV === 'production') {
+    if (process.env.AIOX_DEBUG === 'true') {
+      console.warn('WARNING: Debug mode enabled in production');
+    }
+  }
+}
+```
+
+---
+
+## File and Directory Permissions
+
+### AIOX Directory Structure Permissions
+
+```bash
+# ============================================================
+# RECOMMENDED PERMISSIONS
+# ============================================================
+
+# Project root (standard)
+chmod 755 /path/to/project
+
+# AIOX configuration directories
+chmod 700 .aiox/              # Only owner can access
+chmod 700 .aiox-core/         # Framework source
+chmod 700 .claude/            # Claude configuration
+
+# Sensitive configuration files
+chmod 600 .env                # Environment variables
+chmod 600 .aiox/config.yaml   # Main config
+chmod 600 .aiox/users.json    # User database
+chmod 600 .aiox/sessions.json # Active sessions
+
+# Secrets directory
+chmod 700 ~/.aiox/secrets/
+chmod 600 ~/.aiox/secrets/*
+
+# Log files
+chmod 640 logs/*.log          # Owner read/write, group read
+chmod 750 logs/               # Owner full, group read/execute
+
+# Temporary files
+chmod 700 .aiox/temp/
+chmod 600 .aiox/temp/*
+```
+
+### Directory Access Control
+
+```yaml
+# .aiox/config.yaml - Allowed directories configuration
+security:
+  allowedDirectories:
+    read:
+      - '${PROJECT_ROOT}'
+      - '${HOME}/.aiox'
+    write:
+      - '${PROJECT_ROOT}/src'
+      - '${PROJECT_ROOT}/docs'
+      - '${PROJECT_ROOT}/tests'
+    execute:
+      - '${PROJECT_ROOT}/scripts'
+      - '${PROJECT_ROOT}/node_modules/.bin'
+
+  blockedPaths:
+    - '/etc'
+    - '/var'
+    - '/usr'
+    - '${HOME}/.ssh'
+    - '${HOME}/.gnupg'
+    - '${HOME}/.aws'
+```
+
+### Permission Validation Script
+
+```bash
+#!/bin/bash
+# scripts/check-permissions.sh
+
+echo "AIOX Security Permission Check"
+echo "=============================="
+
+# Check critical files
+check_permission() {
+  local file=$1
+  local expected=$2
+  local actual=$(stat -f "%Lp" "$file" 2>/dev/null || stat -c "%a" "$file" 2>/dev/null)
+
+  if [ "$actual" != "$expected" ]; then
+    echo "WARNING: $file has permissions $actual, expected $expected"
+    return 1
+  else
+    echo "OK: $file ($actual)"
+    return 0
+  fi
+}
+
+# Check critical files
+check_permission ".env" "600"
+check_permission ".aiox" "700"
+check_permission ".aiox/config.yaml" "600"
+
+# Check for world-readable sensitive files
+find . -name "*.key" -o -name "*.pem" -o -name "*.env*" | while read f; do
+  perms=$(stat -f "%Lp" "$f" 2>/dev/null || stat -c "%a" "$f" 2>/dev/null)
+  if [ "${perms: -1}" != "0" ]; then
+    echo "CRITICAL: $f is world-readable!"
+  fi
+done
+
+echo ""
+echo "Permission check complete."
+```
+
+---
+
+## Sandboxing and Isolation
+
+### Docker MCP Isolation
+
+AIOX uses Docker containers to isolate MCP servers from the host system:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      HOST SYSTEM                             │
+│                                                              │
+│  ┌────────────────┐    ┌────────────────────────────────┐  │
+│  │  Claude Code   │    │      Docker Container          │  │
+│  │                │    │  ┌──────────────────────────┐  │  │
+│  │  ┌──────────┐  │    │  │  docker-gateway          │  │  │
+│  │  │ Native   │  │◄──►│  │  ┌─────┐ ┌─────────┐    │  │  │
+│  │  │ Tools    │  │    │  │  │ EXA │ │Context7 │    │  │  │
+│  │  └──────────┘  │    │  │  └─────┘ └─────────┘    │  │  │
+│  │                │    │  │  ┌─────────┐            │  │  │
+│  │  ┌──────────┐  │    │  │  │  Apify  │            │  │  │
+│  │  │Playwright│  │    │  │  └─────────┘            │  │  │
+│  │  └──────────┘  │    │  └──────────────────────────┘  │  │
+│  └────────────────┘    └────────────────────────────────┘  │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Container Security Configuration
+
+```yaml
+# docker-compose.security.yml
+version: '3.8'
+
+services:
+  mcp-gateway:
+    image: docker-mcp-gateway:latest
+    security_opt:
+      - no-new-privileges:true
+      - seccomp:./seccomp-profile.json
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    read_only: true
+    tmpfs:
+      - /tmp:noexec,nosuid,nodev
+    networks:
+      - mcp-isolated
+    deploy:
+      resources:
+        limits:
+          cpus: '1.0'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 128M
+
+networks:
+  mcp-isolated:
+    driver: bridge
+    internal: true # No external access
+```
+
+### Process Isolation with Permission Modes
+
+```javascript
+// Permission mode enforcement
+const { OperationGuard } = require('./.aiox-core/core/permissions');
+
+async function executeWithIsolation(operation, context) {
+  const guard = new OperationGuard();
+
+  // Check if operation is allowed in current mode
+  const permission = await guard.guard(operation.tool, {
+    command: operation.command,
+    args: operation.args,
+  });
+
+  if (!permission.proceed) {
+    if (permission.needsConfirmation) {
+      // Request user confirmation
+      const confirmed = await requestUserConfirmation(operation);
+      if (!confirmed) {
+        throw new Error('Operation denied by user');
+      }
+    } else {
+      throw new Error(`Operation blocked: ${permission.reason}`);
+    }
+  }
+
+  // Execute in isolated context
+  return await isolatedExecutor.run(operation, {
+    timeout: 30000,
+    maxMemory: '256M',
+    networkAccess: false,
+  });
+}
+```
+
+### Resource Limits
+
+```javascript
+// Resource limit configuration
+const resourceLimits = {
+  cpu: {
+    maxPercent: 50,
+    throttleAt: 80,
+  },
+  memory: {
+    maxMB: 512,
+    warnAt: 400,
+  },
+  disk: {
+    maxWriteMB: 100,
+    tempDirMaxMB: 50,
+  },
+  network: {
+    maxRequestsPerMinute: 100,
+    maxBandwidthMBps: 10,
+  },
+  process: {
+    maxConcurrent: 5,
+    maxRuntime: 300000, // 5 minutes
+  },
+};
+```
+
+---
+
+## Input Validation
+
+### Validation Rules by Input Type
+
+| Input Type        | Validation Rules                        | Example                   |
+| ----------------- | --------------------------------------- | ------------------------- |
+| **File paths**    | No traversal, whitelist dirs, normalize | `/project/src/file.ts`    |
+| **Commands**      | Whitelist commands, sanitize args       | `npm run build`           |
+| **Project names** | Alphanumeric, dashes, underscores       | `my-project-01`           |
+| **URLs**          | Protocol whitelist, domain validation   | `https://api.example.com` |
+| **User input**    | Length limits, character filtering      | `User comment here`       |
+| **Configuration** | Type checking, enum validation          | `{ mode: "ask" }`         |
+
+### Input Sanitizer Implementation
+
+```javascript
+// .aiox-core/core/security/input-sanitizer.js
+
+class InputSanitizer {
+  /**
+   * Sanitize file path to prevent directory traversal
+   */
+  static sanitizePath(inputPath, basePath) {
+    // Remove null bytes
+    let sanitized = inputPath.replace(/\0/g, '');
+
+    // Normalize path separators
+    sanitized = sanitized.replace(/\\/g, '/');
+
+    // Remove directory traversal attempts
+    sanitized = sanitized.replace(/\.\.+\//g, '');
+    sanitized = sanitized.replace(/\/\.\.+/g, '');
+
+    // Resolve to absolute path
+    const resolved = path.resolve(basePath, sanitized);
+
+    // Verify path is within allowed directory
+    if (!resolved.startsWith(path.resolve(basePath))) {
+      throw new SecurityError('Path traversal attempt detected');
+    }
+
+    return resolved;
+  }
+
+  /**
+   * Sanitize command for safe execution
+   */
+  static sanitizeCommand(command) {
+    // Block dangerous patterns
+    const dangerousPatterns = [
+      /;/g, // Command chaining
+      /\|/g, // Pipes
+      /&/g, // Background/AND
+      /`/g, // Command substitution
+      /\$\(/g, // Command substitution
+      />/g, // Redirect
+      /</g, // Redirect
+      /\n/g, // Newlines
+      /\r/g, // Carriage returns
+    ];
+
+    let sanitized = command;
+    for (const pattern of dangerousPatterns) {
+      sanitized = sanitized.replace(pattern, '');
+    }
+
+    // Limit length
+    if (sanitized.length > 1000) {
+      throw new SecurityError('Command too long');
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Validate and sanitize project name
+   */
+  static sanitizeProjectName(name) {
+    // Only allow alphanumeric, dashes, and underscores
+    const sanitized = name.replace(/[^a-zA-Z0-9-_]/g, '');
+
+    if (sanitized.length === 0) {
+      throw new SecurityError('Invalid project name');
+    }
+
+    if (sanitized.length > 64) {
+      throw new SecurityError('Project name too long');
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Validate URL
+   */
+  static validateUrl(url) {
+    const allowedProtocols = ['https:', 'http:'];
+
+    try {
+      const parsed = new URL(url);
+
+      if (!allowedProtocols.includes(parsed.protocol)) {
+        throw new SecurityError('Invalid URL protocol');
+      }
+
+      // Block localhost in production
+      if (process.env.NODE_ENV === 'production') {
+        if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+          throw new SecurityError('Localhost URLs not allowed in production');
+        }
+      }
+
+      return parsed.toString();
+    } catch (error) {
+      throw new SecurityError(`Invalid URL: ${error.message}`);
+    }
+  }
+}
+```
+
+### Schema Validation
+
+```javascript
+// Use JSON Schema for configuration validation
+const Ajv = require('ajv');
+const ajv = new Ajv({ allErrors: true });
+
+const configSchema = {
+  type: 'object',
+  required: ['version', 'permissions'],
+  properties: {
+    version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
+    permissions: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['explore', 'ask', 'auto'] },
+      },
+      required: ['mode'],
+    },
+    security: {
+      type: 'object',
+      properties: {
+        allowedDirectories: {
+          type: 'array',
+          items: { type: 'string' },
+        },
+      },
+    },
+  },
+  additionalProperties: false,
+};
+
+function validateConfig(config) {
+  const validate = ajv.compile(configSchema);
+  const valid = validate(config);
+
+  if (!valid) {
+    throw new SecurityError(`Config validation failed: ${JSON.stringify(validate.errors)}`);
+  }
+
+  return config;
+}
+```
+
+---
+
+## Injection Protection
+
+### Command Injection Prevention
+
+```javascript
+// DANGEROUS - Never do this
+const userInput = req.query.file;
+exec(`cat ${userInput}`); // Command injection vulnerability!
+
+// SAFE - Use parameterized execution
+const { execFile } = require('child_process');
+const userInput = sanitizePath(req.query.file, PROJECT_ROOT);
+execFile('cat', [userInput], (error, stdout) => {
+  // Safe execution
+});
+
+// SAFEST - Use built-in file operations
+const fs = require('fs').promises;
+const safePath = sanitizePath(req.query.file, PROJECT_ROOT);
+const content = await fs.readFile(safePath, 'utf8');
+```
+
+### SQL Injection Prevention (SQL Governance Hook)
+
+```python
+# .claude/hooks/sql-governance.py
+# This hook is automatically enforced
+
+BLOCKED_PATTERNS = [
+    r'CREATE\s+TABLE',
+    r'DROP\s+TABLE',
+    r'ALTER\s+TABLE',
+    r'TRUNCATE',
+    r'DELETE\s+FROM',
+    r'UPDATE\s+.*\s+SET',
+    r'INSERT\s+INTO',
+]
+
+def validate_sql(query: str) -> bool:
+    """Block dangerous SQL operations without explicit approval"""
+    for pattern in BLOCKED_PATTERNS:
+        if re.search(pattern, query, re.IGNORECASE):
+            raise SecurityError(f"Blocked SQL pattern detected: {pattern}")
+    return True
+```
+
+### Template Injection Prevention
+
+```javascript
+// DANGEROUS - Direct template interpolation
+const template = `Hello ${userInput}!`; // XSS vulnerability!
+
+// SAFE - HTML encoding
+const { escape } = require('html-escaper');
+const template = `Hello ${escape(userInput)}!`;
+
+// For Markdown templates
+function safeMarkdownInterpolation(template, data) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    const value = data[key];
+    if (value === undefined) return match;
+
+    // Escape special Markdown characters
+    return String(value).replace(/[\\`*_{}[\]()#+\-.!]/g, '\\$&');
+  });
+}
+```
+
+### Path Traversal Prevention
+
+```javascript
+// Hook enforcement for protected files
+// .claude/hooks/read-protection.py
+
+PROTECTED_FILES = [
+    '.claude/CLAUDE.md',
+    '.claude/rules/*.md',
+    '.aiox-core/development/agents/*.md',
+    'package.json',
+    'tsconfig.json'
+]
+
+def validate_read(file_path: str, params: dict) -> bool:
+    """Block partial reads on protected files"""
+    for pattern in PROTECTED_FILES:
+        if fnmatch.fnmatch(file_path, pattern):
+            if params.get('limit') or params.get('offset'):
+                raise SecurityError(
+                    f"Partial read blocked on protected file: {file_path}\n"
+                    "Must read complete file."
+                )
+    return True
+```
+
+### Prototype Pollution Prevention
+
+```javascript
+// Prevent prototype pollution attacks
+function safeObjectMerge(target, source) {
+  const blockedKeys = ['__proto__', 'constructor', 'prototype'];
+
+  function merge(t, s, depth = 0) {
+    if (depth > 10) {
+      throw new SecurityError('Object merge depth exceeded');
+    }
+
+    for (const key of Object.keys(s)) {
+      if (blockedKeys.includes(key)) {
+        throw new SecurityError(`Blocked property: ${key}`);
+      }
+
+      if (typeof s[key] === 'object' && s[key] !== null) {
+        t[key] = t[key] || {};
+        merge(t[key], s[key], depth + 1);
+      } else {
+        t[key] = s[key];
+      }
+    }
+
+    return t;
+  }
+
+  return merge(target, source);
+}
+```
+
+---
+
+## Logging and Auditing
+
+### Audit Log Configuration
+
+```yaml
+# .aiox/config.yaml - Audit configuration
+audit:
+  enabled: true
+  level: info # debug, info, warn, error
+
+  # What to log
+  events:
+    - authentication
+    - authorization
+    - fileAccess
+    - commandExecution
+    - configChange
+    - agentActivation
+    - modeChange
+    - error
+
+  # Output configuration
+  output:
+    file:
+      enabled: true
+      path: .aiox/logs/audit.log
+      maxSize: 10M
+      maxFiles: 10
+      compress: true
+    console:
+      enabled: false
+    remote:
+      enabled: false
+      endpoint: https://logs.example.com/audit
+
+  # Retention
+  retention:
+    days: 90
+    archivePath: .aiox/logs/archive
+```
+
+### Audit Log Format
+
+```json
+{
+  "timestamp": "2026-01-29T14:30:00.000Z",
+  "level": "info",
+  "event": "commandExecution",
+  "actor": {
+    "type": "agent",
+    "id": "dev",
+    "name": "Dex"
+  },
+  "action": {
+    "type": "execute",
+    "tool": "Bash",
+    "command": "npm run build"
+  },
+  "context": {
+    "mode": "ask",
+    "project": "my-project",
+    "story": "1.1"
+  },
+  "result": {
+    "status": "success",
+    "duration": 12500
+  },
+  "security": {
+    "approved": true,
+    "approvedBy": "user",
+    "riskLevel": "low"
+  }
+}
+```
+
+### Audit Logger Implementation
+
+```javascript
+// .aiox-core/core/security/audit-logger.js
+
+const winston = require('winston');
+const { format } = winston;
+
+class AuditLogger {
+  constructor(config) {
+    this.config = config;
+    this.logger = this.createLogger();
+  }
+
+  createLogger() {
+    const transports = [];
+
+    if (this.config.output.file.enabled) {
+      transports.push(
+        new winston.transports.File({
+          filename: this.config.output.file.path,
+          maxsize: this.parseSize(this.config.output.file.maxSize),
+          maxFiles: this.config.output.file.maxFiles,
+          tailable: true,
+        })
+      );
+    }
+
+    return winston.createLogger({
+      level: this.config.level,
+      format: format.combine(format.timestamp(), format.json()),
+      transports,
+    });
+  }
+
+  log(event, data) {
+    if (!this.config.events.includes(event)) {
+      return;
+    }
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      event,
+      ...this.sanitizeData(data),
+    };
+
+    this.logger.info(entry);
+  }
+
+  sanitizeData(data) {
+    // Remove sensitive information before logging
+    const sensitivePatterns = [/api[_-]?key/i, /password/i, /secret/i, /token/i, /auth/i];
+
+    const sanitized = JSON.parse(JSON.stringify(data));
+
+    function redact(obj) {
+      for (const key of Object.keys(obj)) {
+        if (sensitivePatterns.some((p) => p.test(key))) {
+          obj[key] = '[REDACTED]';
+        } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+          redact(obj[key]);
+        }
+      }
+    }
+
+    redact(sanitized);
+    return sanitized;
+  }
+
+  // Specific logging methods
+  logAuthentication(result, context) {
+    this.log('authentication', {
+      action: { type: 'authenticate', result: result.success ? 'success' : 'failure' },
+      context,
+      security: { failureReason: result.reason },
+    });
+  }
+
+  logCommandExecution(command, result, context) {
+    this.log('commandExecution', {
+      action: { type: 'execute', command },
+      result: { status: result.success ? 'success' : 'failure', duration: result.duration },
+      context,
+    });
+  }
+
+  logFileAccess(path, operation, context) {
+    this.log('fileAccess', {
+      action: { type: operation, path },
+      context,
+    });
+  }
+
+  logSecurityEvent(event, severity, details) {
+    this.log('security', {
+      action: { type: event },
+      security: { severity, ...details },
+    });
+  }
+}
+
+module.exports = AuditLogger;
+```
+
+### Log Analysis Queries
+
+```bash
+# Find all failed authentications
+jq 'select(.event == "authentication" and .result.status == "failure")' audit.log
+
+# Find all command executions by agent
+jq 'select(.event == "commandExecution" and .actor.type == "agent")' audit.log
+
+# Find all security events in last 24 hours
+jq 'select(.event == "security" and (.timestamp | fromdateiso8601) > (now - 86400))' audit.log
+
+# Count events by type
+jq -s 'group_by(.event) | map({event: .[0].event, count: length})' audit.log
+```
+
+---
+
+## Production vs Development Configuration
+
+### Environment Detection
+
+```javascript
+// Environment-aware configuration loading
+function loadSecurityConfig() {
+  const env = process.env.NODE_ENV || 'development';
+
+  const baseConfig = require('./security-config.base.json');
+  const envConfig = require(`./security-config.${env}.json`);
+
+  return deepMerge(baseConfig, envConfig);
+}
+```
+
+### Configuration Comparison
+
+| Setting                | Development       | Production       |
+| ---------------------- | ----------------- | ---------------- |
+| **AIOX_DEBUG**         | `true`            | `false`          |
+| **LOG_LEVEL**          | `debug`           | `info`           |
+| **Permission Mode**    | `auto`            | `ask`            |
+| **Rate Limiting**      | Relaxed           | Strict           |
+| **CORS**               | `*`               | Specific origins |
+| **Error Details**      | Full stack traces | Generic messages |
+| **API Key Validation** | Warn only         | Block on invalid |
+| **SSL/TLS**            | Optional          | Required         |
+| **Audit Logging**      | Optional          | Required         |
+| **Session Timeout**    | 24 hours          | 1 hour           |
+
+### Development Configuration
+
+```yaml
+# .aiox/config.development.yaml
+security:
+  debug: true
+
+  validation:
+    strict: false
+    warnOnly: true
+
+  rateLimiting:
+    enabled: false
+
+  cors:
+    origin: '*'
+    credentials: true
+
+  session:
+    timeout: 86400000 # 24 hours
+    secure: false
+
+  audit:
+    enabled: true
+    level: debug
+    console: true
+
+  permissions:
+    mode: auto
+```
+
+### Production Configuration
+
+```yaml
+# .aiox/config.production.yaml
+security:
+  debug: false
+
+  validation:
+    strict: true
+    warnOnly: false
+
+  rateLimiting:
+    enabled: true
+    windowMs: 900000 # 15 minutes
+    maxRequests: 1000
+
+  cors:
+    origin:
+      - https://app.example.com
+      - https://admin.example.com
+    credentials: true
+
+  session:
+    timeout: 3600000 # 1 hour
+    secure: true
+    sameSite: strict
+
+  tls:
+    enabled: true
+    minVersion: TLSv1.2
+    ciphers: ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384
+
+  headers:
+    hsts: true
+    hstsMaxAge: 31536000
+    xssProtection: true
+    noSniff: true
+    frameOptions: DENY
+
+  audit:
+    enabled: true
+    level: info
+    console: false
+    remote:
+      enabled: true
+      endpoint: https://logs.example.com/audit
+
+  permissions:
+    mode: ask
+    requireApprovalFor:
+      - delete
+      - execute
+```
+
+### Environment Validation Script
+
+```javascript
+// Validate production security requirements
+function validateProductionSecurity() {
+  const errors = [];
+
+  // Required environment variables
+  const required = ['JWT_SECRET', 'DATABASE_ENCRYPTION_KEY', 'SESSION_SECRET'];
+  for (const key of required) {
+    if (!process.env[key]) {
+      errors.push(`Missing required env var: ${key}`);
+    }
+  }
+
+  // Debug must be off
+  if (process.env.AIOX_DEBUG === 'true') {
+    errors.push('AIOX_DEBUG must be false in production');
+  }
+
+  // TLS must be enabled (check for cert files)
+  if (!fs.existsSync(process.env.TLS_CERT_PATH)) {
+    errors.push('TLS certificate not found');
+  }
+
+  // Secret strength
+  if (process.env.JWT_SECRET?.length < 32) {
+    errors.push('JWT_SECRET must be at least 32 characters');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Production security validation failed:\n${errors.join('\n')}`);
+  }
+
+  console.log('Production security validation passed');
+}
+```
+
+---
+
+## Security Checklist
+
+### Pre-Deployment Checklist
+
+```markdown
+## Pre-Deployment Security Checklist
+
+### Secrets Management
+
+- [ ] All API keys stored in environment variables or secret manager
+- [ ] No secrets in source code or git history
+- [ ] .env file added to .gitignore
+- [ ] Production secrets use separate keys from development
+- [ ] Secret rotation schedule established
+
+### Configuration
+
+- [ ] NODE_ENV set to 'production'
+- [ ] Debug mode disabled
+- [ ] Error messages don't expose internal details
+- [ ] Rate limiting configured and tested
+- [ ] CORS properly configured for production domains
+
+### Authentication & Authorization
+
+- [ ] Strong password policy enforced
+- [ ] JWT secrets are cryptographically strong (32+ chars)
+- [ ] Token expiration set appropriately
+- [ ] Session management implemented
+- [ ] Permission modes configured (default: ask)
+
+### Input Validation
+
+- [ ] All user input sanitized
+- [ ] File path validation enabled
+- [ ] Command injection protection active
+- [ ] SQL governance hooks installed
+- [ ] Schema validation for configuration
+
+### Network Security
+
+- [ ] TLS 1.2+ required
+- [ ] Security headers configured (HSTS, CSP, etc.)
+- [ ] Unnecessary ports closed
+- [ ] Firewall rules in place
+
+### Logging & Monitoring
+
+- [ ] Audit logging enabled
+- [ ] Log files secured (permissions 640)
+- [ ] Sensitive data redacted from logs
+- [ ] Alerting configured for security events
+- [ ] Log retention policy established
+
+### Dependency Security
+
+- [ ] npm audit shows no critical vulnerabilities
+- [ ] Dependabot or similar enabled
+- [ ] Lockfile committed and verified
+```
+
+### Ongoing Security Checklist
+
+```markdown
+## Ongoing Security Maintenance
+
+### Weekly
+
+- [ ] Review security alerts from monitoring
+- [ ] Check for new dependency vulnerabilities
+- [ ] Review access logs for anomalies
+
+### Monthly
+
+- [ ] Run full security scan (npm audit, snyk)
+- [ ] Update dependencies with security patches
+- [ ] Review and rotate service tokens
+- [ ] Audit user access and permissions
+
+### Quarterly
+
+- [ ] Full penetration testing
+- [ ] Review and update security policies
+- [ ] Rotate long-lived secrets (API keys, JWT secrets)
+- [ ] Security training refresher
+
+### Annually
+
+- [ ] Third-party security audit
+- [ ] Disaster recovery testing
+- [ ] Complete secrets rotation
+- [ ] Security architecture review
+```
+
+---
+
+## Vulnerability Reporting
+
+### Responsible Disclosure Policy
+
+If you discover a security vulnerability in Synkra AIOX, please follow responsible disclosure practices:
+
+### Reporting Process
+
+1. **DO NOT** create a public GitHub issue for security vulnerabilities
+2. Report security concerns via [GitHub Security Advisories](https://github.com/SynkraAI/aiox-core/security/advisories)
+3. Include the following in your report:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact assessment
+   - Any suggested fixes (optional)
+
+### What to Include
+
+```markdown
+## Vulnerability Report Template
+
+**Vulnerability Type:** [e.g., Command Injection, XSS, Auth Bypass]
+
+**Severity:** [Critical / High / Medium / Low]
+
+**Affected Component:** [e.g., InputSanitizer, AuthSystem, MCP Gateway]
+
+**AIOX Version:** [e.g., 2.1.0]
+
+**Description:**
+[Detailed description of the vulnerability]
+
+**Steps to Reproduce:**
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+**Proof of Concept:**
+[Code or commands to demonstrate the vulnerability]
+
+**Impact:**
+[What an attacker could accomplish with this vulnerability]
+
+**Suggested Fix:**
+[Optional: Your recommendation for fixing the issue]
+```
+
+### Response Timeline
+
+| Stage                  | Timeframe              |
+| ---------------------- | ---------------------- |
+| Initial acknowledgment | 24 hours               |
+| Preliminary assessment | 72 hours               |
+| Fix development        | 7-14 days              |
+| Patch release          | 14-30 days             |
+| Public disclosure      | 90 days (or after fix) |
+
+### Security Hall of Fame
+
+Contributors who responsibly disclose vulnerabilities are recognized in our Security Hall of Fame (with permission).
+
+### Bug Bounty Program
+
+Currently, Synkra AIOX does not have a formal bug bounty program. However, significant security contributions are recognized and may receive AIOX Pro licenses or other recognition.
+
+---
+
+## Related Documentation
+
+- [Security Best Practices](../security-best-practices.md) - General security guidelines
+- [Permission Modes Guide](./permission-modes.md) - Agent autonomy control
+- [MCP Global Setup](./mcp-global-setup.md) - Secure MCP configuration
+- [Quality Gates](./quality-gates.md) - Security checks in CI/CD
+
+---
+
+_Synkra AIOX Security Hardening Guide v4.0.4_