@etcsec-com/etc-collector 1.4.0

package/src/providers/ldap/ad-mappers.ts

@@ -0,0 +1,280 @@
+import { Entry } from 'ldapts';
+import { ADUser, ADGroup, ADComputer, ADOU } from '../../types/ad.types';
+import { logger } from '../../utils/logger';
+
+/**
+ * Active Directory Type Mappers
+ *
+ * Maps raw LDAP entries to typed AD objects.
+ * Handles AD-specific attributes and data type conversions.
+ *
+ * Task 4: Create AD Type Mappers (Story 1.5)
+ */
+
+/**
+ * Convert Windows FILETIME to JavaScript Date
+ *
+ * Windows FILETIME is 100-nanosecond intervals since Jan 1, 1601 UTC.
+ * JavaScript Date uses milliseconds since Jan 1, 1970 UTC.
+ *
+ * @param filetime - FILETIME value as string
+ * @returns Date object or undefined if invalid
+ */
+function fileTimeToDate(filetime: string | undefined): Date | undefined {
+  if (!filetime) {
+    return undefined;
+  }
+
+  try {
+    const value = BigInt(filetime);
+
+    // Special values in AD
+    if (value === BigInt(0) || value === BigInt('9223372036854775807')) {
+      // 0 or max value means "never" or "not set"
+      return undefined;
+    }
+
+    // Convert Windows FILETIME to Unix timestamp
+    // 116444736000000000 = 100-ns intervals between 1601 and 1970
+    const unixTimestamp = Number((value - BigInt('116444736000000000')) / BigInt(10000));
+
+    return new Date(unixTimestamp);
+  } catch (error) {
+    logger.warn(`Failed to convert FILETIME: ${filetime}`, error);
+    return undefined;
+  }
+}
+
+/**
+ * Get string value from LDAP attribute
+ *
+ * LDAP attributes can be strings, arrays, or Buffer objects.
+ *
+ * @param value - LDAP attribute value
+ * @returns String value or undefined
+ */
+function getString(value: unknown): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value[0]?.toString();
+  }
+
+  if (Buffer.isBuffer(value)) {
+    return value.toString('utf-8');
+  }
+
+  return String(value);
+}
+
+/**
+ * Get string array from LDAP attribute
+ *
+ * @param value - LDAP attribute value
+ * @returns Array of strings or undefined
+ */
+function getStringArray(value: unknown): string[] | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((v) => (Buffer.isBuffer(v) ? v.toString('utf-8') : String(v)));
+  }
+
+  // Single value
+  return [getString(value)!].filter(Boolean);
+}
+
+/**
+ * Get number from LDAP attribute
+ *
+ * @param value - LDAP attribute value
+ * @returns Number or undefined
+ */
+function getNumber(value: unknown): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const str = getString(value);
+  if (!str) {
+    return undefined;
+  }
+
+  const num = parseInt(str, 10);
+  return isNaN(num) ? undefined : num;
+}
+
+/**
+ * Check if AD account is enabled
+ *
+ * Uses userAccountControl attribute bit flags.
+ * Bit 1 (0x0002) = ACCOUNTDISABLE
+ *
+ * @param userAccountControl - userAccountControl value
+ * @returns true if enabled, false if disabled
+ */
+function isAccountEnabled(userAccountControl: number | undefined): boolean {
+  if (userAccountControl === undefined) {
+    return true; // Default to enabled if not specified
+  }
+
+  const ACCOUNTDISABLE = 0x0002;
+  return (userAccountControl & ACCOUNTDISABLE) === 0;
+}
+
+/**
+ * Map LDAP entry to ADUser
+ *
+ * @param entry - LDAP search entry
+ * @returns ADUser object
+ */
+export function mapToADUser(entry: Entry): ADUser {
+  const userAccountControl = getNumber(entry['userAccountControl']);
+
+  const user: ADUser = {
+    dn: entry.dn,
+    sAMAccountName: getString(entry['sAMAccountName']) || '',
+    userPrincipalName: getString(entry['userPrincipalName']),
+    displayName: getString(entry['displayName']),
+    enabled: isAccountEnabled(userAccountControl),
+    passwordLastSet: fileTimeToDate(getString(entry['pwdLastSet'])),
+    lastLogon: fileTimeToDate(getString(entry['lastLogon'])),
+    adminCount: getNumber(entry['adminCount']),
+    memberOf: getStringArray(entry['memberOf']),
+    userAccountControl,
+  };
+
+  // Include all other attributes
+  for (const [key, value] of Object.entries(entry)) {
+    if (!(key in user)) {
+      user[key] = value;
+    }
+  }
+
+  return user;
+}
+
+/**
+ * Map LDAP entry to ADGroup
+ *
+ * @param entry - LDAP search entry
+ * @returns ADGroup object
+ */
+export function mapToADGroup(entry: Entry): ADGroup {
+  const group: ADGroup = {
+    dn: entry.dn,
+    sAMAccountName: getString(entry['sAMAccountName']) || '',
+    displayName: getString(entry['displayName']),
+    groupType: getNumber(entry['groupType']),
+    memberOf: getStringArray(entry['memberOf']),
+    member: getStringArray(entry['member']),
+  };
+
+  // Include all other attributes
+  for (const [key, value] of Object.entries(entry)) {
+    if (!(key in group)) {
+      group[key] = value;
+    }
+  }
+
+  return group;
+}
+
+/**
+ * Map LDAP entry to ADComputer
+ *
+ * @param entry - LDAP search entry
+ * @returns ADComputer object
+ */
+export function mapToADComputer(entry: Entry): ADComputer {
+  const userAccountControl = getNumber(entry['userAccountControl']);
+
+  const computer: ADComputer = {
+    dn: entry.dn,
+    sAMAccountName: getString(entry['sAMAccountName']) || '',
+    dNSHostName: getString(entry['dNSHostName']),
+    operatingSystem: getString(entry['operatingSystem']),
+    operatingSystemVersion: getString(entry['operatingSystemVersion']),
+    lastLogon: fileTimeToDate(getString(entry['lastLogon'])),
+    enabled: isAccountEnabled(userAccountControl),
+  };
+
+  // Include all other attributes
+  for (const [key, value] of Object.entries(entry)) {
+    if (!(key in computer)) {
+      computer[key] = value;
+    }
+  }
+
+  return computer;
+}
+
+/**
+ * Map LDAP entry to ADOU
+ *
+ * @param entry - LDAP search entry
+ * @returns ADOU object
+ */
+export function mapToADOU(entry: Entry): ADOU {
+  const ou: ADOU = {
+    dn: entry.dn,
+    name: getString(entry['name']) || getString(entry['ou']) || '',
+    description: getString(entry['description']),
+  };
+
+  // Include all other attributes
+  for (const [key, value] of Object.entries(entry)) {
+    if (!(key in ou)) {
+      ou[key] = value;
+    }
+  }
+
+  return ou;
+}
+
+/**
+ * Generic mapper for custom types
+ *
+ * Maps LDAP entry to a plain object with all attributes.
+ *
+ * @param entry - LDAP search entry
+ * @returns Plain object with all entry attributes
+ */
+export function mapToGeneric(entry: Entry): Record<string, unknown> {
+  const result: Record<string, unknown> = {
+    dn: entry.dn,
+  };
+
+  // Binary attributes that should NOT be converted to strings
+  const binaryAttributes = new Set(['nTSecurityDescriptor', 'objectGUID', 'objectSid']);
+
+  // Include all attributes
+  for (const [key, value] of Object.entries(entry)) {
+    if (key === 'dn') continue; // Already added
+
+    // Preserve binary attributes as Buffers
+    if (binaryAttributes.has(key) && Buffer.isBuffer(value)) {
+      result[key] = value;
+    }
+    // Try to convert to proper types
+    else if (typeof value === 'string' && /^\d+$/.test(value)) {
+      result[key] = parseInt(value, 10);
+    } else if (Array.isArray(value)) {
+      result[key] = value.map((v) => (Buffer.isBuffer(v) ? v.toString('utf-8') : v));
+    } else if (Buffer.isBuffer(value)) {
+      result[key] = value.toString('utf-8');
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

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

@@ -0,0 +1,259 @@
+import { Client, SearchResult, Entry } from 'ldapts';
+import { logger } from '../../utils/logger';
+import { SearchOptions, LDAPControl } from '../interfaces/ILDAPProvider';
+import { retryWithBackoff, LDAP_RETRY_OPTIONS } from './ldap-retry';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * LDAP Client Wrapper
+ *
+ * Wraps ldapts library to provide LDAP connectivity.
+ * Handles connection lifecycle, search operations, and error handling.
+ *
+ * Task 3: Implement LDAP Provider (Story 1.5)
+ */
+
+/**
+ * LDAP connection options
+ */
+export interface LDAPConnectionOptions {
+  url: string;
+  bindDN: string;
+  bindPassword: string;
+  timeout?: number;
+  tlsOptions?: {
+    rejectUnauthorized?: boolean;
+    ca?: Buffer | Buffer[];
+    checkServerIdentity?: (hostname: string, cert: unknown) => Error | undefined;
+    servername?: string;
+  };
+  caCertPath?: string;
+  skipHostnameVerification?: boolean;
+  tlsServername?: string;
+}
+
+/**
+ * LDAP Client
+ *
+ * Low-level wrapper around ldapts client.
+ */
+export class LDAPClient {
+  private client: Client | null = null;
+  private options: LDAPConnectionOptions;
+  private isConnected = false;
+
+  constructor(options: LDAPConnectionOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Connect and bind to LDAP server
+   *
+   * Uses retry logic with exponential backoff for transient failures.
+   *
+   * @throws Error if connection or bind fails after retries
+   */
+  async connect(): Promise<void> {
+    if (this.isConnected) {
+      logger.debug('LDAP client already connected');
+      return;
+    }
+
+    await retryWithBackoff(async () => {
+      try {
+        logger.debug(`Connecting to LDAP server: ${this.options.url}`);
+
+        // Build TLS options
+        let tlsOptions = this.options.tlsOptions || {};
+
+        // Load CA certificate if path provided and TLS verification is enabled
+        // Skip CA cert loading if rejectUnauthorized is explicitly false
+        const shouldLoadCaCert =
+          this.options.caCertPath && tlsOptions.rejectUnauthorized !== false;
+
+        if (shouldLoadCaCert) {
+          try {
+            const certPath = path.resolve(this.options.caCertPath!);
+            if (fs.existsSync(certPath)) {
+              const caCert = fs.readFileSync(certPath);
+              tlsOptions = {
+                ...tlsOptions,
+                ca: caCert,
+              };
+              logger.debug(`Loaded CA certificate from: ${certPath}`);
+            } else {
+              logger.warn(`CA certificate not found at ${certPath}, using system CA store`);
+            }
+          } catch (error) {
+            logger.warn(`Failed to load CA certificate from ${this.options.caCertPath}:`, error);
+            // Don't throw - fall back to system CA store
+          }
+        } else if (tlsOptions.rejectUnauthorized === false) {
+          logger.debug('TLS verification disabled (rejectUnauthorized=false)');
+        }
+
+        // Use servername for TLS validation when connecting via IP but cert has hostname
+        if (this.options.tlsServername) {
+          tlsOptions = {
+            ...tlsOptions,
+            servername: this.options.tlsServername,
+          };
+          logger.debug(`Using TLS servername for certificate validation: ${this.options.tlsServername}`);
+        }
+
+        // Skip hostname verification if configured (for IP-based connections)
+        if (this.options.skipHostnameVerification) {
+          tlsOptions = {
+            ...tlsOptions,
+            checkServerIdentity: (hostname: string, _cert: unknown): undefined => {
+              logger.debug(`Skipping hostname verification for: ${hostname}`);
+              return undefined;
+            },
+          };
+          logger.debug('Hostname verification disabled (skipHostnameVerification=true)');
+        }
+
+        // Create client
+        this.client = new Client({
+          url: this.options.url,
+          timeout: this.options.timeout || 5000,
+          connectTimeout: this.options.timeout || 5000,
+          tlsOptions,
+        });
+
+        // Bind to server
+        await this.client.bind(this.options.bindDN, this.options.bindPassword);
+
+        this.isConnected = true;
+        logger.info(`Connected to LDAP server: ${this.options.url}`);
+      } catch (error) {
+        this.isConnected = false;
+        this.client = null;
+        logger.error('Failed to connect to LDAP server:', error);
+        throw new Error(
+          `LDAP connection failed: ${error instanceof Error ? error.message : 'Unknown error'}`
+        );
+      }
+    }, LDAP_RETRY_OPTIONS);
+  }
+
+  /**
+   * Disconnect from LDAP server
+   */
+  async disconnect(): Promise<void> {
+    if (!this.client) {
+      return;
+    }
+
+    try {
+      await this.client.unbind();
+      logger.debug('Disconnected from LDAP server');
+    } catch (error) {
+      logger.warn('Error during LDAP disconnect:', error);
+    } finally {
+      this.client = null;
+      this.isConnected = false;
+    }
+  }
+
+  /**
+   * Test connection to LDAP server
+   *
+   * @returns Connection test with response time
+   */
+  async testConnection(): Promise<{ success: boolean; responseTime: number }> {
+    const startTime = Date.now();
+
+    try {
+      // Attempt to connect and bind
+      await this.connect();
+
+      const responseTime = Date.now() - startTime;
+
+      return {
+        success: true,
+        responseTime,
+      };
+    } catch (error) {
+      logger.error('LDAP connection test failed:', error);
+      return {
+        success: false,
+        responseTime: Date.now() - startTime,
+      };
+    }
+  }
+
+  /**
+   * Search LDAP directory
+   *
+   * Uses retry logic with exponential backoff for transient failures.
+   *
+   * @param baseDN - Base distinguished name for search
+   * @param options - Search options (filter, scope, attributes, etc.)
+   * @returns Array of search entry results
+   *
+   * @throws Error if not connected or search fails after retries
+   */
+  async search(baseDN: string, options: SearchOptions): Promise<Entry[]> {
+    if (!this.client || !this.isConnected) {
+      throw new Error('LDAP client not connected. Call connect() first.');
+    }
+
+    return retryWithBackoff(async () => {
+      try {
+        logger.debug(`LDAP search: baseDN=${baseDN}, filter=${options.filter}`);
+
+        // Map our SearchOptions to ldapts SearchOptions
+        const searchOptions: any = {
+          filter: options.filter,
+          scope: options.scope,
+          attributes: options.attributes,
+          sizeLimit: options.sizeLimit,
+          timeLimit: options.timeLimit,
+          paged: options.paged ? { pageSize: 1000 } : undefined,
+        };
+
+        // Map controls if provided
+        if (options.controls && options.controls.length > 0) {
+          searchOptions.controls = options.controls.map((ctrl: LDAPControl) => {
+            const control: any = {
+              type: ctrl.oid,
+              critical: ctrl.critical || false,
+            };
+            if (ctrl.value) {
+              control.value = Buffer.isBuffer(ctrl.value) ? ctrl.value : Buffer.from(ctrl.value);
+            }
+            return control;
+          });
+        }
+
+        // Perform search
+        const searchResult: SearchResult = await this.client!.search(baseDN, searchOptions);
+
+        logger.debug(`LDAP search returned ${searchResult.searchEntries.length} entries`);
+
+        return searchResult.searchEntries;
+      } catch (error) {
+        logger.error(`LDAP search failed: baseDN=${baseDN}`, error);
+        throw new Error(
+          `LDAP search failed: ${error instanceof Error ? error.message : 'Unknown error'}`
+        );
+      }
+    }, LDAP_RETRY_OPTIONS);
+  }
+
+  /**
+   * Check if client is currently connected
+   */
+  isClientConnected(): boolean {
+    return this.isConnected;
+  }
+
+  /**
+   * Get connection URL (for debugging)
+   */
+  getConnectionUrl(): string {
+    return this.options.url;
+  }
+}