myaidev-method 0.2.18 → 0.2.22

package/src/libs/security/authorization-checker.js

@@ -0,0 +1,606 @@
+/**
+ * MyAIDev Method - Security Authorization Checker
+ *
+ * CRITICAL: This module enforces authorization requirements for all security testing operations.
+ * No security tool should be executed without passing authorization validation.
+ *
+ * @module security/authorization-checker
+ * @version 1.0.0
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * Authorization manifest file location
+ * This file MUST exist and contain valid authorization data before any security testing
+ */
+const AUTH_MANIFEST_FILE = '.security-authorization.json';
+
+/**
+ * Authorization levels
+ */
+const AuthLevel = {
+  NONE: 'none',
+  PASSIVE: 'passive',      // OSINT only, no direct target interaction
+  ACTIVE: 'active',        // Active reconnaissance and scanning
+  EXPLOITATION: 'exploitation',  // Full penetration testing including exploitation
+  INTERNAL: 'internal'     // Internal network testing
+};
+
+/**
+ * Scope types
+ */
+const ScopeType = {
+  DOMAIN: 'domain',
+  IP_RANGE: 'ip_range',
+  URL: 'url',
+  NETWORK: 'network',
+  APPLICATION: 'application'
+};
+
+/**
+ * Authorization Checker Class
+ */
+class AuthorizationChecker {
+  constructor() {
+    this.manifest = null;
+    this.manifestPath = null;
+    this.loaded = false;
+  }
+
+  /**
+   * Load authorization manifest from file
+   * @param {string} [customPath] - Optional custom path to manifest file
+   * @returns {Promise<Object>} - Loaded manifest
+   * @throws {Error} - If manifest not found or invalid
+   */
+  async loadManifest(customPath = null) {
+    try {
+      // Determine manifest path
+      this.manifestPath = customPath || path.join(process.cwd(), AUTH_MANIFEST_FILE);
+
+      // Check if file exists
+      try {
+        await fs.access(this.manifestPath);
+      } catch (err) {
+        throw new Error(
+          `Authorization manifest not found at ${this.manifestPath}\n` +
+          `\nCRITICAL: Security testing requires explicit authorization.\n` +
+          `Create ${AUTH_MANIFEST_FILE} with proper authorization details.\n` +
+          `\nExample:\n` +
+          `{\n` +
+          `  "engagement_id": "ENG-2025-001",\n` +
+          `  "client": "Client Name",\n` +
+          `  "authorized_by": "John Smith",\n` +
+          `  "authorization_level": "exploitation",\n` +
+          `  "scope": [...],\n` +
+          `  "start_date": "2025-11-25",\n` +
+          `  "end_date": "2025-12-25"\n` +
+          `}`
+        );
+      }
+
+      // Read and parse manifest
+      const manifestData = await fs.readFile(this.manifestPath, 'utf8');
+      this.manifest = JSON.parse(manifestData);
+
+      // Validate manifest structure
+      await this.validateManifest(this.manifest);
+
+      this.loaded = true;
+      return this.manifest;
+
+    } catch (err) {
+      if (err.name === 'SyntaxError') {
+        throw new Error(`Invalid JSON in authorization manifest: ${err.message}`);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Validate authorization manifest structure and content
+   * @param {Object} manifest - Authorization manifest to validate
+   * @throws {Error} - If manifest is invalid
+   */
+  async validateManifest(manifest) {
+    const requiredFields = [
+      'engagement_id',
+      'client',
+      'authorized_by',
+      'authorization_level',
+      'scope',
+      'start_date',
+      'end_date'
+    ];
+
+    // Check required fields
+    for (const field of requiredFields) {
+      if (!manifest[field]) {
+        throw new Error(`Missing required field in authorization manifest: ${field}`);
+      }
+    }
+
+    // Validate authorization level
+    const validLevels = Object.values(AuthLevel);
+    if (!validLevels.includes(manifest.authorization_level)) {
+      throw new Error(
+        `Invalid authorization_level: ${manifest.authorization_level}\n` +
+        `Must be one of: ${validLevels.join(', ')}`
+      );
+    }
+
+    // Validate scope is an array
+    if (!Array.isArray(manifest.scope) || manifest.scope.length === 0) {
+      throw new Error('Scope must be a non-empty array of authorized targets');
+    }
+
+    // Validate each scope item
+    for (const scopeItem of manifest.scope) {
+      if (!scopeItem.type || !scopeItem.target) {
+        throw new Error('Each scope item must have "type" and "target" fields');
+      }
+
+      const validTypes = Object.values(ScopeType);
+      if (!validTypes.includes(scopeItem.type)) {
+        throw new Error(
+          `Invalid scope type: ${scopeItem.type}\n` +
+          `Must be one of: ${validTypes.join(', ')}`
+        );
+      }
+    }
+
+    // Validate dates
+    const startDate = new Date(manifest.start_date);
+    const endDate = new Date(manifest.end_date);
+    const now = new Date();
+
+    if (isNaN(startDate.getTime())) {
+      throw new Error(`Invalid start_date format: ${manifest.start_date}`);
+    }
+
+    if (isNaN(endDate.getTime())) {
+      throw new Error(`Invalid end_date format: ${manifest.end_date}`);
+    }
+
+    if (endDate <= startDate) {
+      throw new Error('end_date must be after start_date');
+    }
+
+    // Check if engagement is active
+    if (now < startDate) {
+      throw new Error(
+        `Engagement has not started yet.\n` +
+        `Start date: ${manifest.start_date}\n` +
+        `Current date: ${now.toISOString().split('T')[0]}`
+      );
+    }
+
+    if (now > endDate) {
+      throw new Error(
+        `Engagement has expired.\n` +
+        `End date: ${manifest.end_date}\n` +
+        `Current date: ${now.toISOString().split('T')[0]}`
+      );
+    }
+  }
+
+  /**
+   * Check if a target is within authorized scope
+   * @param {string} target - Target to check (domain, IP, URL, etc.)
+   * @param {string} [targetType] - Optional target type hint
+   * @returns {Promise<boolean>} - True if target is authorized
+   */
+  async isAuthorized(target, targetType = null) {
+    if (!this.loaded) {
+      await this.loadManifest();
+    }
+
+    // Check each scope item
+    for (const scopeItem of this.manifest.scope) {
+      // If type specified, must match
+      if (targetType && scopeItem.type !== targetType) {
+        continue;
+      }
+
+      // Check if target matches scope
+      if (this.matchesScope(target, scopeItem)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Check if target matches a scope item
+   * @param {string} target - Target to check
+   * @param {Object} scopeItem - Scope item with type and target
+   * @returns {boolean} - True if matches
+   */
+  matchesScope(target, scopeItem) {
+    const { type, target: scopeTarget } = scopeItem;
+
+    switch (type) {
+      case ScopeType.DOMAIN:
+        // Match exact domain or subdomain
+        return this.matchesDomain(target, scopeTarget);
+
+      case ScopeType.IP_RANGE:
+        // Match IP address in CIDR range
+        return this.matchesIPRange(target, scopeTarget);
+
+      case ScopeType.URL:
+        // Match URL or URL prefix
+        return this.matchesURL(target, scopeTarget);
+
+      case ScopeType.NETWORK:
+        // Match network range
+        return this.matchesNetwork(target, scopeTarget);
+
+      case ScopeType.APPLICATION:
+        // Match application name
+        return this.matchesApplication(target, scopeTarget);
+
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Check if target matches domain scope
+   * @param {string} target - Target domain
+   * @param {string} scopeDomain - Authorized domain
+   * @returns {boolean} - True if matches
+   */
+  matchesDomain(target, scopeDomain) {
+    // Remove protocol and path from target
+    const cleanTarget = target.replace(/^https?:\/\//, '').split('/')[0].toLowerCase();
+    const cleanScope = scopeDomain.toLowerCase();
+
+    // Exact match
+    if (cleanTarget === cleanScope) {
+      return true;
+    }
+
+    // Subdomain match (*.example.com matches sub.example.com)
+    if (cleanScope.startsWith('*.')) {
+      const baseDomain = cleanScope.substring(2);
+      return cleanTarget === baseDomain || cleanTarget.endsWith(`.${baseDomain}`);
+    }
+
+    // Check if target is subdomain of scope
+    return cleanTarget.endsWith(`.${cleanScope}`);
+  }
+
+  /**
+   * Check if target IP is in authorized range
+   * @param {string} target - Target IP address
+   * @param {string} scopeRange - CIDR range (e.g., "192.168.1.0/24")
+   * @returns {boolean} - True if in range
+   */
+  matchesIPRange(target, scopeRange) {
+    try {
+      // Parse CIDR notation
+      const [rangeIP, prefixLength] = scopeRange.split('/');
+      const prefix = parseInt(prefixLength, 10);
+
+      // Convert IPs to integers for comparison
+      const targetInt = this.ipToInt(target);
+      const rangeInt = this.ipToInt(rangeIP);
+
+      // Calculate network mask
+      const mask = -1 << (32 - prefix);
+
+      // Check if target is in range
+      return (targetInt & mask) === (rangeInt & mask);
+
+    } catch (err) {
+      return false;
+    }
+  }
+
+  /**
+   * Convert IP address string to integer
+   * @param {string} ip - IP address
+   * @returns {number} - Integer representation
+   */
+  ipToInt(ip) {
+    const parts = ip.split('.').map(Number);
+    return (parts[0] << 24) + (parts[1] << 16) + (parts[2] << 8) + parts[3];
+  }
+
+  /**
+   * Check if target URL matches authorized URL
+   * @param {string} target - Target URL
+   * @param {string} scopeURL - Authorized URL
+   * @returns {boolean} - True if matches
+   */
+  matchesURL(target, scopeURL) {
+    const cleanTarget = target.toLowerCase();
+    const cleanScope = scopeURL.toLowerCase();
+
+    // Exact match
+    if (cleanTarget === cleanScope) {
+      return true;
+    }
+
+    // Prefix match (scope URL is prefix of target)
+    return cleanTarget.startsWith(cleanScope);
+  }
+
+  /**
+   * Check if target network matches authorized network
+   * @param {string} target - Target network identifier
+   * @param {string} scopeNetwork - Authorized network
+   * @returns {boolean} - True if matches
+   */
+  matchesNetwork(target, scopeNetwork) {
+    // Try IP range matching first
+    if (scopeNetwork.includes('/')) {
+      return this.matchesIPRange(target, scopeNetwork);
+    }
+
+    // Otherwise simple string match
+    return target.toLowerCase() === scopeNetwork.toLowerCase();
+  }
+
+  /**
+   * Check if target application matches authorized application
+   * @param {string} target - Target application name
+   * @param {string} scopeApp - Authorized application
+   * @returns {boolean} - True if matches
+   */
+  matchesApplication(target, scopeApp) {
+    return target.toLowerCase() === scopeApp.toLowerCase();
+  }
+
+  /**
+   * Verify operation is allowed at current authorization level
+   * @param {string} requiredLevel - Minimum authorization level required
+   * @returns {Promise<boolean>} - True if allowed
+   * @throws {Error} - If authorization level insufficient
+   */
+  async verifyLevel(requiredLevel) {
+    if (!this.loaded) {
+      await this.loadManifest();
+    }
+
+    const levels = [
+      AuthLevel.NONE,
+      AuthLevel.PASSIVE,
+      AuthLevel.ACTIVE,
+      AuthLevel.EXPLOITATION,
+      AuthLevel.INTERNAL
+    ];
+
+    const currentIndex = levels.indexOf(this.manifest.authorization_level);
+    const requiredIndex = levels.indexOf(requiredLevel);
+
+    if (currentIndex < requiredIndex) {
+      throw new Error(
+        `Insufficient authorization level.\n` +
+        `Required: ${requiredLevel}\n` +
+        `Current: ${this.manifest.authorization_level}\n` +
+        `\nThis operation requires higher authorization level.`
+      );
+    }
+
+    return true;
+  }
+
+  /**
+   * Create authorization log entry
+   * @param {Object} operation - Operation details
+   * @returns {Promise<void>}
+   */
+  async logOperation(operation) {
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      engagement_id: this.manifest.engagement_id,
+      operation: operation.type,
+      target: operation.target,
+      result: operation.result,
+      user: operation.user || 'system'
+    };
+
+    // Append to engagement log file
+    const logFile = path.join(
+      path.dirname(this.manifestPath),
+      `.security-engagement-${this.manifest.engagement_id}.log`
+    );
+
+    const logLine = JSON.stringify(logEntry) + '\n';
+    await fs.appendFile(logFile, logLine, 'utf8');
+  }
+
+  /**
+   * Get current authorization manifest
+   * @returns {Object} - Current manifest
+   * @throws {Error} - If manifest not loaded
+   */
+  getManifest() {
+    if (!this.loaded) {
+      throw new Error('Authorization manifest not loaded. Call loadManifest() first.');
+    }
+    return this.manifest;
+  }
+
+  /**
+   * Get authorization summary
+   * @returns {Object} - Authorization summary
+   */
+  getSummary() {
+    if (!this.loaded) {
+      return { authorized: false };
+    }
+
+    return {
+      authorized: true,
+      engagement_id: this.manifest.engagement_id,
+      client: this.manifest.client,
+      level: this.manifest.authorization_level,
+      scope_count: this.manifest.scope.length,
+      start_date: this.manifest.start_date,
+      end_date: this.manifest.end_date,
+      days_remaining: this.getDaysRemaining()
+    };
+  }
+
+  /**
+   * Calculate days remaining in engagement
+   * @returns {number} - Days remaining
+   */
+  getDaysRemaining() {
+    const endDate = new Date(this.manifest.end_date);
+    const now = new Date();
+    const diffTime = endDate - now;
+    const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+    return Math.max(0, diffDays);
+  }
+
+  /**
+   * Create sample authorization manifest
+   * @param {string} outputPath - Path to write sample manifest
+   * @returns {Promise<string>} - Path to created file
+   */
+  static async createSampleManifest(outputPath = AUTH_MANIFEST_FILE) {
+    const sample = {
+      engagement_id: `ENG-${new Date().getFullYear()}-001`,
+      client: "Client Company Name",
+      authorized_by: "John Smith (CTO)",
+      authorization_document: "signed_authorization_letter.pdf",
+      authorization_level: "exploitation",
+      scope: [
+        {
+          type: "domain",
+          target: "*.example.com",
+          description: "All subdomains of example.com"
+        },
+        {
+          type: "ip_range",
+          target: "192.168.1.0/24",
+          description: "Internal network range"
+        },
+        {
+          type: "url",
+          target: "https://app.example.com",
+          description: "Web application"
+        }
+      ],
+      out_of_scope: [
+        "production-db.example.com",
+        "backup.example.com"
+      ],
+      start_date: new Date().toISOString().split('T')[0],
+      end_date: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
+      rules_of_engagement: {
+        testing_hours: "24/7",
+        exploit_depth: "full_exploitation_allowed",
+        data_exfiltration: "proof_of_concept_only",
+        service_disruption: "not_allowed",
+        social_engineering: "email_only",
+        physical_security: "not_authorized"
+      },
+      contacts: {
+        primary: "security@example.com",
+        emergency: "+1-555-0123"
+      },
+      reporting: {
+        critical_findings: "immediate_notification",
+        regular_updates: "weekly",
+        final_report: "within_5_days_of_completion"
+      },
+      notes: "Penetration test authorized per signed agreement dated 2025-11-25"
+    };
+
+    await fs.writeFile(
+      outputPath,
+      JSON.stringify(sample, null, 2),
+      'utf8'
+    );
+
+    return outputPath;
+  }
+}
+
+/**
+ * Global authorization checker instance
+ */
+let globalChecker = null;
+
+/**
+ * Get or create global authorization checker
+ * @returns {AuthorizationChecker} - Global instance
+ */
+function getChecker() {
+  if (!globalChecker) {
+    globalChecker = new AuthorizationChecker();
+  }
+  return globalChecker;
+}
+
+/**
+ * Quick authorization check function
+ * @param {string} target - Target to check
+ * @param {string} level - Required authorization level
+ * @returns {Promise<boolean>} - True if authorized
+ * @throws {Error} - If not authorized
+ */
+async function checkAuthorization(target, level = AuthLevel.PASSIVE) {
+  const checker = getChecker();
+
+  // Load manifest if not loaded
+  if (!checker.loaded) {
+    await checker.loadManifest();
+  }
+
+  // Verify authorization level
+  await checker.verifyLevel(level);
+
+  // Check if target is in scope
+  const authorized = await checker.isAuthorized(target);
+
+  if (!authorized) {
+    throw new Error(
+      `Target not in authorized scope: ${target}\n` +
+      `\nAuthorized scope:\n` +
+      checker.manifest.scope.map(s => `  - ${s.type}: ${s.target}`).join('\n') +
+      `\n\nThis target is NOT authorized for testing.`
+    );
+  }
+
+  // Log the operation
+  await checker.logOperation({
+    type: 'authorization_check',
+    target,
+    result: 'authorized'
+  });
+
+  return true;
+}
+
+/**
+ * Require authorization before proceeding
+ * @param {string} target - Target to authorize
+ * @param {string} level - Required authorization level
+ * @returns {Promise<void>}
+ * @throws {Error} - If not authorized
+ */
+async function requireAuthorization(target, level = AuthLevel.PASSIVE) {
+  await checkAuthorization(target, level);
+}
+
+export {
+  AuthorizationChecker,
+  AuthLevel,
+  ScopeType,
+  getChecker,
+  checkAuthorization,
+  requireAuthorization,
+  AuthorizationChecker as default
+};
+
+export const createSampleManifest = AuthorizationChecker.createSampleManifest;