@etcsec-com/etc-collector 1.4.0

package/src/providers/ldap/ldap-sanitizer.ts

@@ -0,0 +1,273 @@
+/**
+ * LDAP Injection Prevention
+ *
+ * Sanitizes LDAP filters and Distinguished Names to prevent injection attacks.
+ * Follows OWASP guidelines and RFC 4515 (LDAP filters) / RFC 4514 (DNs).
+ *
+ * Task 2: Implement LDAP Sanitizer for Injection Prevention (Story 1.5)
+ */
+
+/**
+ * LDAP Sanitizer
+ *
+ * Provides methods to sanitize and validate LDAP inputs.
+ */
+export class LDAPSanitizer {
+  /**
+   * LDAP filter special characters that require escaping (RFC 4515)
+   */
+  private static readonly FILTER_ESCAPE_MAP: Record<string, string> = {
+    '\\': '\\5c', // Backslash (must be first)
+    '*': '\\2a', // Asterisk
+    '(': '\\28', // Left parenthesis
+    ')': '\\29', // Right parenthesis
+    '\0': '\\00', // NUL character
+  };
+
+  /**
+   * DN special characters that require escaping (RFC 4514)
+   */
+  private static readonly DN_SPECIAL_CHARS = [',', '=', '+', '<', '>', '#', ';', '\\', '"'];
+
+  /**
+   * Sanitize LDAP filter string to prevent injection attacks
+   *
+   * Escapes special characters in LDAP filter values according to RFC 4515.
+   * This prevents attackers from injecting malicious filter logic.
+   *
+   * @param filter - The filter string to sanitize
+   * @returns Sanitized filter string with escaped special characters
+   *
+   * @example
+   * ```typescript
+   * // Prevents injection: (uid=*)(objectClass=*)
+   * LDAPSanitizer.sanitizeFilter("*)(objectClass=*")
+   * // Returns: "\2a\29\28objectClass=\2a"
+   * ```
+   */
+  static sanitizeFilter(filter: string): string {
+    if (!filter) {
+      return filter;
+    }
+
+    let sanitized = filter;
+
+    // Process in specific order: backslash first to avoid double-escaping
+    for (const [char, escape] of Object.entries(this.FILTER_ESCAPE_MAP)) {
+      sanitized = sanitized.split(char).join(escape);
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Sanitize Distinguished Name (DN) to prevent injection
+   *
+   * Escapes special characters in DN components according to RFC 4514.
+   * Handles leading/trailing spaces and special character positions.
+   *
+   * @param dn - The DN string to sanitize
+   * @returns Sanitized DN string with properly escaped characters
+   *
+   * @example
+   * ```typescript
+   * LDAPSanitizer.sanitizeDN('cn=John, Doe')
+   * // Returns: "cn=John\\, Doe"
+   * ```
+   */
+  static sanitizeDN(dn: string): string {
+    if (!dn) {
+      return dn;
+    }
+
+    let sanitized = dn;
+
+    // Escape backslash first to prevent double-escaping
+    sanitized = sanitized.replace(/\\/g, '\\\\');
+
+    // Escape other special characters
+    for (const char of this.DN_SPECIAL_CHARS) {
+      if (char === '\\') continue; // Already handled
+      const regex = new RegExp(`\\${char}`, 'g');
+      sanitized = sanitized.replace(regex, `\\${char}`);
+    }
+
+    // Escape leading space
+    if (sanitized.startsWith(' ')) {
+      sanitized = '\\' + sanitized;
+    }
+
+    // Escape trailing space
+    if (sanitized.endsWith(' ') && !sanitized.endsWith('\\ ')) {
+      sanitized = sanitized.slice(0, -1) + '\\ ';
+    }
+
+    // Escape leading # (hash)
+    if (sanitized.startsWith('#')) {
+      sanitized = '\\' + sanitized;
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Validate LDAP filter syntax
+   *
+   * Checks if an LDAP filter has valid syntax:
+   * - Balanced parentheses
+   * - Valid operators (&, |, !)
+   * - Proper filter structure
+   *
+   * @param filter - The filter to validate
+   * @returns true if filter syntax is valid, false otherwise
+   *
+   * @example
+   * ```typescript
+   * LDAPSanitizer.isValidFilter('(uid=john)')  // true
+   * LDAPSanitizer.isValidFilter('(uid=john')   // false - unbalanced
+   * LDAPSanitizer.isValidFilter('uid=john')    // false - missing parens
+   * ```
+   */
+  static isValidFilter(filter: string): boolean {
+    if (!filter || typeof filter !== 'string') {
+      return false;
+    }
+
+    // Filter must start and end with parentheses
+    if (!filter.startsWith('(') || !filter.endsWith(')')) {
+      return false;
+    }
+
+    // Check balanced parentheses
+    let depth = 0;
+    for (const char of filter) {
+      if (char === '(') {
+        depth++;
+      } else if (char === ')') {
+        depth--;
+      }
+      // Depth should never go negative
+      if (depth < 0) {
+        return false;
+      }
+    }
+
+    // Must end with depth 0 (balanced)
+    if (depth !== 0) {
+      return false;
+    }
+
+    // Basic structure validation: must contain at least one operator or attribute
+    // Valid filters: (&(...)), (|(...)), (!(...)), or (attribute=value)
+    const hasLogicalOp = /^(\(&|\(\||\(!)/.test(filter);
+    const hasAttribute = /\w+=/.test(filter);
+
+    if (!hasLogicalOp && !hasAttribute) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Validate Distinguished Name (DN) format
+   *
+   * Checks if a DN has valid structure:
+   * - Contains attribute=value pairs
+   * - Properly formatted with commas
+   *
+   * @param dn - The DN to validate
+   * @returns true if DN format is valid, false otherwise
+   *
+   * @example
+   * ```typescript
+   * LDAPSanitizer.isValidDN('cn=John Doe,ou=Users,dc=example,dc=com')  // true
+   * LDAPSanitizer.isValidDN('invalid-dn')  // false
+   * ```
+   */
+  static isValidDN(dn: string): boolean {
+    if (!dn || typeof dn !== 'string') {
+      return false;
+    }
+
+    // DN must contain at least one attribute=value pair
+    const dnPattern = /^([a-zA-Z][a-zA-Z0-9-]*=[^,]+)(,\s*[a-zA-Z][a-zA-Z0-9-]*=[^,]+)*$/;
+    return dnPattern.test(dn.trim());
+  }
+
+  /**
+   * Sanitize LDAP attribute name
+   *
+   * Ensures attribute name only contains valid characters.
+   * Attribute names should only contain alphanumeric characters, hyphens, and dots.
+   *
+   * @param attribute - The attribute name to sanitize
+   * @returns Sanitized attribute name or empty string if invalid
+   */
+  static sanitizeAttribute(attribute: string): string {
+    if (!attribute || typeof attribute !== 'string') {
+      return '';
+    }
+
+    // Remove any characters that aren't alphanumeric, hyphen, or dot
+    return attribute.replace(/[^a-zA-Z0-9.-]/g, '');
+  }
+
+  /**
+   * Build safe LDAP filter from components
+   *
+   * Constructs an LDAP filter with properly sanitized values.
+   * Use this instead of string concatenation to build filters.
+   *
+   * @param attribute - Attribute name
+   * @param operator - Comparison operator (=, >=, <=, ~=)
+   * @param value - Value to filter by (will be sanitized)
+   * @returns Safe LDAP filter string
+   *
+   * @example
+   * ```typescript
+   * LDAPSanitizer.buildFilter('uid', '=', 'john*')
+   * // Returns: "(uid=john\\2a)"
+   * ```
+   */
+  static buildFilter(
+    attribute: string,
+    operator: '=' | '>=' | '<=' | '~=' | '=*',
+    value: string
+  ): string {
+    const safeAttribute = this.sanitizeAttribute(attribute);
+    const safeValue = operator === '=*' ? value : this.sanitizeFilter(value);
+
+    return `(${safeAttribute}${operator}${safeValue})`;
+  }
+
+  /**
+   * Build safe logical filter (AND/OR/NOT)
+   *
+   * Combines multiple filters with logical operators.
+   *
+   * @param operator - Logical operator (&, |, !)
+   * @param filters - Array of filter strings to combine
+   * @returns Combined filter string
+   *
+   * @example
+   * ```typescript
+   * LDAPSanitizer.buildLogicalFilter('&', [
+   *   '(objectClass=user)',
+   *   '(uid=john)',
+   * ])
+   * // Returns: "(&(objectClass=user)(uid=john))"
+   * ```
+   */
+  static buildLogicalFilter(operator: '&' | '|' | '!', filters: string[]): string {
+    if (!filters || filters.length === 0) {
+      return '';
+    }
+
+    if (operator === '!' && filters.length !== 1) {
+      throw new Error('NOT operator requires exactly one filter');
+    }
+
+    return `(${operator}${filters.join('')})`;
+  }
+}

package/src/providers/ldap/ldap.provider.ts

@@ -0,0 +1,293 @@
+import { ILDAPProvider, SearchOptions, ConnectionTestResult } from '../interfaces/ILDAPProvider';
+import { ADUser, ADGroup, ADComputer, ADOU } from '../../types/ad.types';
+import { LDAPConfig } from '../../types/config.types';
+import { LDAPClient, LDAPConnectionOptions } from './ldap-client';
+import { LDAPSanitizer } from './ldap-sanitizer';
+import { mapToADUser, mapToADGroup, mapToADComputer, mapToADOU, mapToGeneric } from './ad-mappers';
+import { logger } from '../../utils/logger';
+
+/**
+ * LDAP Provider Implementation
+ *
+ * Provides Active Directory connectivity via LDAP/LDAPS.
+ * Implements all LDAP operations with sanitization and type mapping.
+ *
+ * Task 3: Implement LDAP Provider (Story 1.5)
+ */
+export class LDAPProvider implements ILDAPProvider {
+  private client: LDAPClient;
+  private config: LDAPConfig;
+
+  /**
+   * Get base DN for searches
+   */
+  getBaseDN(): string {
+    return this.config.baseDN;
+  }
+
+  /**
+   * Get LDAP URL (for debugging)
+   */
+  getUrl(): string {
+    return this.config.url;
+  }
+
+  constructor(config: LDAPConfig) {
+    this.config = config;
+
+    // Create client with connection options
+    const connectionOptions: LDAPConnectionOptions = {
+      url: config.url,
+      bindDN: config.bindDN,
+      bindPassword: config.bindPassword,
+      timeout: config.timeout,
+      caCertPath: config.caCertPath,
+      tlsOptions: {
+        rejectUnauthorized: config.tlsVerify,
+      },
+      skipHostnameVerification: config.skipHostnameVerification,
+      tlsServername: config.tlsServername,
+    };
+
+    this.client = new LDAPClient(connectionOptions);
+  }
+
+  /**
+   * Connect and bind to LDAP server
+   */
+  async connect(): Promise<void> {
+    logger.info('Connecting to LDAP server...');
+    await this.client.connect();
+  }
+
+  /**
+   * Disconnect from LDAP server
+   */
+  async disconnect(): Promise<void> {
+    logger.info('Disconnecting from LDAP server...');
+    await this.client.disconnect();
+  }
+
+  /**
+   * Test LDAP connection
+   */
+  async testConnection(): Promise<ConnectionTestResult> {
+    logger.info('Testing LDAP connection...');
+
+    const result = await this.client.testConnection();
+
+    if (result.success) {
+      // Determine protocol from URL
+      const protocol = this.config.url.startsWith('ldaps://') ? 'ldaps' : 'ldap';
+
+      return {
+        success: true,
+        message: 'Connection successful',
+        details: {
+          url: this.config.url,
+          baseDN: this.config.baseDN,
+          protocol,
+          bindDN: this.config.bindDN,
+          responseTime: result.responseTime,
+        },
+      };
+    } else {
+      return {
+        success: false,
+        message: 'Connection failed',
+      };
+    }
+  }
+
+  /**
+   * Search for users in Active Directory
+   *
+   * Default filter: (&(objectClass=user)(objectCategory=person))
+   */
+  async searchUsers(filter?: string, attributes?: string[]): Promise<ADUser[]> {
+    // Build filter with sanitization
+    const userFilter = filter
+      ? `(&(objectClass=user)(objectCategory=person)${filter})`
+      : '(&(objectClass=user)(objectCategory=person))';
+
+    logger.debug(`Searching for users with filter: ${userFilter}`);
+
+    // Default attributes for users
+    const defaultAttributes = [
+      'dn',
+      'sAMAccountName',
+      'userPrincipalName',
+      'displayName',
+      'userAccountControl',
+      'pwdLastSet',
+      'lastLogon',
+      'adminCount',
+      'memberOf',
+    ];
+
+    const searchOptions: SearchOptions = {
+      filter: userFilter,
+      scope: 'sub',
+      attributes: attributes || defaultAttributes,
+      paged: true,
+    };
+
+    const entries = await this.client.search(this.config.baseDN, searchOptions);
+
+    // Map entries to ADUser objects
+    return entries.map(mapToADUser);
+  }
+
+  /**
+   * Search for groups in Active Directory
+   *
+   * Default filter: (objectClass=group)
+   */
+  async searchGroups(filter?: string, attributes?: string[]): Promise<ADGroup[]> {
+    // Build filter
+    const groupFilter = filter ? `(&(objectClass=group)${filter})` : '(objectClass=group)';
+
+    logger.debug(`Searching for groups with filter: ${groupFilter}`);
+
+    // Default attributes for groups
+    const defaultAttributes = [
+      'dn',
+      'sAMAccountName',
+      'displayName',
+      'groupType',
+      'memberOf',
+      'member',
+    ];
+
+    const searchOptions: SearchOptions = {
+      filter: groupFilter,
+      scope: 'sub',
+      attributes: attributes || defaultAttributes,
+      paged: true,
+    };
+
+    const entries = await this.client.search(this.config.baseDN, searchOptions);
+
+    // Map entries to ADGroup objects
+    return entries.map(mapToADGroup);
+  }
+
+  /**
+   * Search for computers in Active Directory
+   *
+   * Default filter: (objectClass=computer)
+   */
+  async searchComputers(filter?: string, attributes?: string[]): Promise<ADComputer[]> {
+    // Build filter
+    const computerFilter = filter ? `(&(objectClass=computer)${filter})` : '(objectClass=computer)';
+
+    logger.debug(`Searching for computers with filter: ${computerFilter}`);
+
+    // Default attributes for computers
+    const defaultAttributes = [
+      'dn',
+      'sAMAccountName',
+      'dNSHostName',
+      'operatingSystem',
+      'operatingSystemVersion',
+      'lastLogon',
+      'userAccountControl',
+    ];
+
+    const searchOptions: SearchOptions = {
+      filter: computerFilter,
+      scope: 'sub',
+      attributes: attributes || defaultAttributes,
+      paged: true,
+    };
+
+    const entries = await this.client.search(this.config.baseDN, searchOptions);
+
+    // Map entries to ADComputer objects
+    return entries.map(mapToADComputer);
+  }
+
+  /**
+   * Search for organizational units in Active Directory
+   *
+   * Default filter: (objectClass=organizationalUnit)
+   */
+  async searchOUs(filter?: string, attributes?: string[]): Promise<ADOU[]> {
+    // Build filter
+    const ouFilter = filter
+      ? `(&(objectClass=organizationalUnit)${filter})`
+      : '(objectClass=organizationalUnit)';
+
+    logger.debug(`Searching for OUs with filter: ${ouFilter}`);
+
+    // Default attributes for OUs
+    const defaultAttributes = ['dn', 'name', 'ou', 'description'];
+
+    const searchOptions: SearchOptions = {
+      filter: ouFilter,
+      scope: 'sub',
+      attributes: attributes || defaultAttributes,
+      paged: true,
+    };
+
+    const entries = await this.client.search(this.config.baseDN, searchOptions);
+
+    // Map entries to ADOU objects
+    return entries.map(mapToADOU);
+  }
+
+  /**
+   * Generic LDAP search
+   *
+   * Performs a low-level LDAP search with custom base DN and options.
+   */
+  async search<T>(baseDN: string, options: SearchOptions): Promise<T[]> {
+    logger.debug(`Generic LDAP search: baseDN=${baseDN}, filter=${options.filter}`);
+
+    // Validate filter syntax
+    if (!LDAPSanitizer.isValidFilter(options.filter)) {
+      throw new Error(`Invalid LDAP filter syntax: ${options.filter}`);
+    }
+
+    // Validate base DN
+    if (!LDAPSanitizer.isValidDN(baseDN)) {
+      throw new Error(`Invalid LDAP DN: ${baseDN}`);
+    }
+
+    const entries = await this.client.search(baseDN, options);
+
+    // Map to generic objects
+    return entries.map((entry) => mapToGeneric(entry) as T);
+  }
+
+  /**
+   * Build a safe LDAP filter
+   *
+   * Utility method to build filters with sanitization.
+   *
+   * @param attribute - Attribute name
+   * @param operator - Comparison operator
+   * @param value - Value to filter by (will be sanitized)
+   * @returns Safe LDAP filter
+   */
+  buildSafeFilter(
+    attribute: string,
+    operator: '=' | '>=' | '<=' | '~=' | '=*',
+    value: string
+  ): string {
+    return LDAPSanitizer.buildFilter(attribute, operator, value);
+  }
+
+  /**
+   * Build a logical filter (AND/OR/NOT)
+   *
+   * Utility method to combine multiple filters.
+   *
+   * @param operator - Logical operator
+   * @param filters - Array of filter strings
+   * @returns Combined filter
+   */
+  buildLogicalFilter(operator: '&' | '|' | '!', filters: string[]): string {
+    return LDAPSanitizer.buildLogicalFilter(operator, filters);
+  }
+}

package/src/providers/ldap/queries/computer.queries.ts

@@ -0,0 +1,9 @@
+/**
+ * Predefined LDAP Computer Queries
+ * TODO: Full implementation in Story 1.5
+ */
+export const ComputerQueries = {
+  ALL_COMPUTERS: '(objectClass=computer)',
+  SERVERS: '(&(objectClass=computer)(operatingSystem=*Server*))',
+  WORKSTATIONS: '(&(objectClass=computer)(!(operatingSystem=*Server*)))',
+};

package/src/providers/ldap/queries/group.queries.ts

@@ -0,0 +1,9 @@
+/**
+ * Predefined LDAP Group Queries
+ * TODO: Full implementation in Story 1.5
+ */
+export const GroupQueries = {
+  ALL_GROUPS: '(objectClass=group)',
+  SECURITY_GROUPS: '(&(objectClass=group)(groupType:1.2.840.113556.1.4.803:=2147483648))',
+  DISTRIBUTION_GROUPS: '(&(objectClass=group)(!(groupType:1.2.840.113556.1.4.803:=2147483648)))',
+};

package/src/providers/ldap/queries/user.queries.ts

@@ -0,0 +1,10 @@
+/**
+ * Predefined LDAP User Queries
+ * TODO: Full implementation in Story 1.5
+ */
+export const UserQueries = {
+  ALL_USERS: '(objectClass=user)',
+  ENABLED_USERS: '(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))',
+  DISABLED_USERS: '(&(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))',
+  ADMIN_USERS: '(&(objectClass=user)(adminCount=1))',
+};