@etcsec-com/etc-collector 1.4.0

package/src/providers/azure/graph-client.ts

@@ -0,0 +1,315 @@
+/**
+ * Microsoft Graph Client
+ *
+ * Handles authentication and API requests to Microsoft Graph using OAuth 2.0 client credentials flow.
+ * Supports automatic token refresh and retry logic with rate limit handling.
+ *
+ * Task 2: Implement Microsoft Graph Client with OAuth 2.0 (Story 1.6)
+ */
+
+import { Client } from '@microsoft/microsoft-graph-client';
+import { ClientSecretCredential } from '@azure/identity';
+import { AzureProviderConfig } from '../../types/config.types';
+import {
+  AzureAuthenticationError,
+  AzureAPIError,
+  AzureRateLimitError,
+  AzureTimeoutError,
+} from './azure-errors';
+import { retryWithBackoff, AZURE_RETRY_CONFIGS, RetryOptions } from './azure-retry';
+
+/**
+ * Graph client options
+ */
+export interface GraphClientOptions {
+  timeout?: number; // milliseconds (default: 30000)
+  maxRetries?: number; // default: 3
+  apiVersion?: string; // default: 'v1.0'
+}
+
+/**
+ * Token info
+ */
+interface TokenInfo {
+  accessToken: string;
+  expiresAt: Date;
+}
+
+/**
+ * Microsoft Graph Client
+ *
+ * Provides authenticated access to Microsoft Graph API using Azure AD service principal.
+ */
+export class GraphClient {
+  private client: Client | null = null;
+  private credential: ClientSecretCredential;
+  private tokenInfo: TokenInfo | null = null;
+  private readonly config: AzureProviderConfig;
+  private readonly options: Required<GraphClientOptions>;
+  private readonly graphScope = 'https://graph.microsoft.com/.default';
+
+  constructor(config: AzureProviderConfig, options: GraphClientOptions = {}) {
+    this.config = config;
+    this.options = {
+      timeout: options.timeout || 30000,
+      maxRetries: options.maxRetries || 3,
+      apiVersion: options.apiVersion || 'v1.0',
+    };
+
+    // Initialize Azure AD credential
+    this.credential = new ClientSecretCredential(
+      config.tenantId,
+      config.clientId,
+      config.clientSecret
+    );
+  }
+
+  /**
+   * Authenticate and initialize Graph client
+   *
+   * Obtains an access token using OAuth 2.0 client credentials flow.
+   *
+   * @throws {AzureAuthenticationError} If authentication fails
+   */
+  async authenticate(): Promise<void> {
+    try {
+      // Get access token
+      const tokenResponse = await this.credential.getToken(this.graphScope);
+
+      if (!tokenResponse) {
+        throw new AzureAuthenticationError(
+          'Failed to obtain access token',
+          this.config.tenantId,
+          this.config.clientId
+        );
+      }
+
+      // Store token info
+      this.tokenInfo = {
+        accessToken: tokenResponse.token,
+        expiresAt: tokenResponse.expiresOnTimestamp
+          ? new Date(tokenResponse.expiresOnTimestamp)
+          : new Date(Date.now() + 3600 * 1000), // 1 hour default
+      };
+
+      // Initialize Graph client with token
+      this.client = Client.init({
+        authProvider: (done) => {
+          done(null, this.tokenInfo!.accessToken);
+        },
+        defaultVersion: this.options.apiVersion,
+      });
+    } catch (error) {
+      throw new AzureAuthenticationError(
+        `Authentication failed: ${error instanceof Error ? error.message : String(error)}`,
+        this.config.tenantId,
+        this.config.clientId,
+        error instanceof Error ? error : undefined
+      );
+    }
+  }
+
+  /**
+   * Check if token is expired or about to expire
+   *
+   * @returns True if token needs refresh (expired or expires in <5 minutes)
+   */
+  private isTokenExpired(): boolean {
+    if (!this.tokenInfo) {
+      return true;
+    }
+
+    const now = Date.now();
+    const expiresAt = this.tokenInfo.expiresAt.getTime();
+    const fiveMinutes = 5 * 60 * 1000;
+
+    return expiresAt - now < fiveMinutes;
+  }
+
+  /**
+   * Ensure client is authenticated
+   *
+   * Automatically refreshes token if expired.
+   *
+   * @throws {AzureAuthenticationError} If not authenticated and authentication fails
+   */
+  private async ensureAuthenticated(): Promise<void> {
+    if (!this.client || this.isTokenExpired()) {
+      await this.authenticate();
+    }
+  }
+
+  /**
+   * Make a GET request to Graph API
+   *
+   * Handles authentication, rate limiting, and retries automatically.
+   *
+   * @param endpoint - Graph API endpoint (e.g., '/users', '/groups')
+   * @param params - Query parameters
+   * @param retryOptions - Override default retry options
+   * @returns Response data
+   * @throws {AzureAPIError} If request fails
+   */
+  async get<T = unknown>(
+    endpoint: string,
+    params?: Record<string, unknown>,
+    retryOptions?: RetryOptions
+  ): Promise<T> {
+    // Wrap the request with retry logic
+    return retryWithBackoff(async () => {
+      await this.ensureAuthenticated();
+
+      if (!this.client) {
+        throw new AzureAPIError('Graph client not initialized', endpoint);
+      }
+
+      try {
+        let request = this.client.api(endpoint);
+
+        // Add query parameters
+        if (params) {
+          const queryParams: Record<string, string> = {};
+          for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null) {
+              queryParams[key] = String(value);
+            }
+          }
+          if (Object.keys(queryParams).length > 0) {
+            request = request.query(queryParams);
+          }
+        }
+
+        // Set timeout
+        request = request.options({
+          timeout: this.options.timeout,
+        });
+
+        // Execute request
+        const response = await request.get();
+        return response as T;
+      } catch (error) {
+        // Handle rate limit (429)
+        if (error instanceof Error && 'statusCode' in error && error.statusCode === 429) {
+          const retryAfter = this.extractRetryAfter(error);
+          throw new AzureRateLimitError(
+            `Rate limit exceeded for ${endpoint}. Retry after ${retryAfter}s`,
+            endpoint,
+            retryAfter
+          );
+        }
+
+        // Handle timeout
+        if (error instanceof Error && error.message.includes('timeout')) {
+          throw new AzureTimeoutError(
+            `Request to ${endpoint} timed out after ${this.options.timeout}ms`,
+            `GET ${endpoint}`,
+            this.options.timeout
+          );
+        }
+
+        // Generic API error
+        const statusCode =
+          error instanceof Error && 'statusCode' in error
+            ? (error as { statusCode: number }).statusCode
+            : undefined;
+
+        throw new AzureAPIError(
+          `Graph API request failed: ${error instanceof Error ? error.message : String(error)}`,
+          endpoint,
+          statusCode,
+          error instanceof Error ? error : undefined
+        );
+      }
+    }, retryOptions || AZURE_RETRY_CONFIGS.default);
+  }
+
+  /**
+   * Get all results with pagination
+   *
+   * Automatically follows @odata.nextLink to retrieve all pages.
+   *
+   * @param endpoint - Graph API endpoint
+   * @param params - Query parameters
+   * @returns Array of all results
+   */
+  async getAll<T = unknown>(endpoint: string, params?: Record<string, unknown>): Promise<T[]> {
+    const results: T[] = [];
+    let nextLink: string | undefined = endpoint;
+    let currentParams: Record<string, unknown> | undefined = params;
+
+    while (nextLink) {
+      const response: { value: T[]; '@odata.nextLink'?: string } = await this.get<{
+        value: T[];
+        '@odata.nextLink'?: string;
+      }>(nextLink, currentParams);
+
+      if (response.value && Array.isArray(response.value)) {
+        results.push(...response.value);
+      }
+
+      nextLink = response['@odata.nextLink'];
+      // For subsequent pages, don't pass params (they're in the nextLink)
+      currentParams = undefined;
+    }
+
+    return results;
+  }
+
+  /**
+   * Extract retry-after value from error
+   *
+   * @param error - Error object
+   * @returns Retry after seconds (default: 60)
+   */
+  private extractRetryAfter(error: Error): number {
+    try {
+      if ('headers' in error && error.headers && typeof error.headers === 'object') {
+        const headers = error.headers as Record<string, string>;
+        const retryAfter = headers['retry-after'] || headers['Retry-After'];
+        if (retryAfter) {
+          const seconds = parseInt(retryAfter, 10);
+          if (!isNaN(seconds)) {
+            return seconds;
+          }
+        }
+      }
+    } catch {
+      // Ignore parsing errors
+    }
+    return 60; // Default to 60 seconds
+  }
+
+  /**
+   * Test connection to Microsoft Graph
+   *
+   * Verifies authentication and basic API access.
+   *
+   * @returns True if connection is successful
+   * @throws {AzureAuthenticationError | AzureAPIError} If connection fails
+   */
+  async testConnection(): Promise<boolean> {
+    await this.authenticate();
+
+    // Try a simple API call to verify access
+    await this.get('/organization');
+
+    return true;
+  }
+
+  /**
+   * Get current access token
+   *
+   * @returns Access token or null if not authenticated
+   */
+  getAccessToken(): string | null {
+    return this.tokenInfo?.accessToken || null;
+  }
+
+  /**
+   * Clear cached token and client
+   */
+  disconnect(): void {
+    this.client = null;
+    this.tokenInfo = null;
+  }
+}

package/src/providers/azure/graph.provider.ts

@@ -0,0 +1,294 @@
+/**
+ * Microsoft Graph Provider
+ *
+ * High-level provider for querying Azure AD / Microsoft Graph API.
+ * Implements the IGraphProvider interface with full support for users, groups, applications, and policies.
+ *
+ * Task 3: Create Azure Provider query methods (Story 1.6)
+ */
+
+import {
+  IGraphProvider,
+  AzureConnectionTestResult,
+  GraphQueryOptions,
+} from '../interfaces/IGraphProvider';
+import { AzureUser, AzureGroup, AzureApp, AzurePolicy } from '../../types/azure.types';
+import { AzureProviderConfig } from '../../types/config.types';
+import { GraphClient } from './graph-client';
+import {
+  AzureAPIError,
+  AzureAuthenticationError,
+  AzurePermissionError,
+} from './azure-errors';
+
+/**
+ * Microsoft Graph Provider
+ *
+ * Provides high-level methods for querying Azure AD objects via Microsoft Graph API.
+ */
+export class GraphProvider implements IGraphProvider {
+  private readonly client: GraphClient;
+  private readonly config: AzureProviderConfig;
+  private readonly graphApiUrl = 'https://graph.microsoft.com';
+
+  constructor(config: AzureProviderConfig) {
+    this.config = config;
+    this.client = new GraphClient(config, {
+      timeout: 30000, // 30 seconds
+      maxRetries: 3,
+      apiVersion: 'v1.0',
+    });
+  }
+
+  /**
+   * Authenticate with Microsoft Graph
+   *
+   * @throws {AzureAuthenticationError} If authentication fails
+   */
+  async authenticate(): Promise<void> {
+    await this.client.authenticate();
+  }
+
+  /**
+   * Test connection to Microsoft Graph API
+   *
+   * @returns Connection test result with diagnostics
+   */
+  async testConnection(): Promise<AzureConnectionTestResult> {
+    const startTime = Date.now();
+
+    try {
+      // Authenticate
+      await this.authenticate();
+
+      // Test basic API access by getting organization info
+      await this.client.get<{ value: { id: string }[] }>('/organization');
+
+      const responseTime = Date.now() - startTime;
+
+      return {
+        success: true,
+        message: 'Connection successful',
+        details: {
+          tenantId: this.config.tenantId,
+          clientId: this.config.clientId,
+          graphApiUrl: this.graphApiUrl,
+          authenticated: true,
+          permissions: ['User.Read.All', 'Group.Read.All'], // TODO: Get actual permissions
+          responseTime,
+        },
+      };
+    } catch (error) {
+      const responseTime = Date.now() - startTime;
+
+      if (error instanceof AzureAuthenticationError) {
+        return {
+          success: false,
+          message: `Authentication failed: ${error.message}`,
+          details: {
+            tenantId: this.config.tenantId,
+            clientId: this.config.clientId,
+            graphApiUrl: this.graphApiUrl,
+            authenticated: false,
+            responseTime,
+          },
+        };
+      }
+
+      return {
+        success: false,
+        message: `Connection test failed: ${error instanceof Error ? error.message : String(error)}`,
+        details: {
+          tenantId: this.config.tenantId,
+          clientId: this.config.clientId,
+          graphApiUrl: this.graphApiUrl,
+          authenticated: false,
+          responseTime,
+        },
+      };
+    }
+  }
+
+  /**
+   * Query Azure AD users
+   *
+   * @param options - Query options (filter, select, top, etc.)
+   * @returns Array of Azure AD users
+   * @throws {AzureAPIError} If the API request fails
+   */
+  async getUsers(options?: GraphQueryOptions): Promise<AzureUser[]> {
+    try {
+      const params = this.buildQueryParams(options);
+
+      // Use getAll to handle pagination
+      const users = await this.client.getAll<AzureUser>('/users', params);
+
+      return users;
+    } catch (error) {
+      if (
+        error instanceof AzureAPIError &&
+        error.statusCode === 403
+      ) {
+        throw new AzurePermissionError(
+          'Insufficient permissions to read users. Required: User.Read.All',
+          '/users',
+          ['User.Read.All']
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Query Azure AD groups
+   *
+   * @param options - Query options (filter, select, top, etc.)
+   * @returns Array of Azure AD groups
+   * @throws {AzureAPIError} If the API request fails
+   */
+  async getGroups(options?: GraphQueryOptions): Promise<AzureGroup[]> {
+    try {
+      const params = this.buildQueryParams(options);
+
+      const groups = await this.client.getAll<AzureGroup>('/groups', params);
+
+      return groups;
+    } catch (error) {
+      if (error instanceof AzureAPIError && error.statusCode === 403) {
+        throw new AzurePermissionError(
+          'Insufficient permissions to read groups. Required: Group.Read.All',
+          '/groups',
+          ['Group.Read.All']
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Query Azure AD applications
+   *
+   * @param options - Query options (filter, select, top, etc.)
+   * @returns Array of Azure AD applications
+   * @throws {AzureAPIError} If the API request fails
+   */
+  async getApplications(options?: GraphQueryOptions): Promise<AzureApp[]> {
+    try {
+      const params = this.buildQueryParams(options);
+
+      const apps = await this.client.getAll<AzureApp>('/applications', params);
+
+      return apps;
+    } catch (error) {
+      if (error instanceof AzureAPIError && error.statusCode === 403) {
+        throw new AzurePermissionError(
+          'Insufficient permissions to read applications. Required: Application.Read.All',
+          '/applications',
+          ['Application.Read.All']
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Query Conditional Access policies
+   *
+   * @param options - Query options (filter, select, top, etc.)
+   * @returns Array of Conditional Access policies
+   * @throws {AzureAPIError} If the API request fails
+   */
+  async getPolicies(options?: GraphQueryOptions): Promise<AzurePolicy[]> {
+    try {
+      const params = this.buildQueryParams(options);
+
+      const policies = await this.client.getAll<AzurePolicy>(
+        '/identity/conditionalAccess/policies',
+        params
+      );
+
+      return policies;
+    } catch (error) {
+      if (error instanceof AzureAPIError && error.statusCode === 403) {
+        throw new AzurePermissionError(
+          'Insufficient permissions to read policies. Required: Policy.Read.All',
+          '/identity/conditionalAccess/policies',
+          ['Policy.Read.All']
+        );
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get organization/tenant information
+   *
+   * @returns Organization info with display name
+   */
+  async getOrganization(): Promise<{ displayName: string; id: string; verifiedDomains: string[] }> {
+    await this.authenticate();
+    const response = await this.client.get<{
+      value: Array<{
+        id: string;
+        displayName: string;
+        verifiedDomains: Array<{ name: string; isDefault: boolean }>;
+      }>;
+    }>('/organization');
+
+    const org = response.value[0];
+    return {
+      id: org?.id || this.config.tenantId,
+      displayName: org?.displayName || 'Unknown',
+      verifiedDomains: org?.verifiedDomains?.map((d) => d.name) || [],
+    };
+  }
+
+  /**
+   * Disconnect from Microsoft Graph
+   *
+   * Clears cached tokens and connection state.
+   */
+  async disconnect(): Promise<void> {
+    this.client.disconnect();
+  }
+
+  /**
+   * Build OData query parameters from options
+   *
+   * @param options - Query options
+   * @returns Query parameters for Graph API
+   */
+  private buildQueryParams(options?: GraphQueryOptions): Record<string, string> | undefined {
+    if (!options) {
+      return undefined;
+    }
+
+    const params: Record<string, string> = {};
+
+    if (options.filter) {
+      params['$filter'] = options.filter;
+    }
+
+    if (options.select && options.select.length > 0) {
+      params['$select'] = options.select.join(',');
+    }
+
+    if (options.expand && options.expand.length > 0) {
+      params['$expand'] = options.expand.join(',');
+    }
+
+    if (options.orderBy) {
+      params['$orderby'] = options.orderBy;
+    }
+
+    if (options.top !== undefined) {
+      params['$top'] = String(options.top);
+    }
+
+    if (options.skip !== undefined) {
+      params['$skip'] = String(options.skip);
+    }
+
+    return Object.keys(params).length > 0 ? params : undefined;
+  }
+}

package/src/providers/azure/queries/app.queries.ts

@@ -0,0 +1,9 @@
+/**
+ * Microsoft Graph Application Queries
+ * TODO: Full implementation in Story 1.6
+ */
+export const GraphAppQueries = {
+  ALL_APPS: '/applications',
+  SERVICE_PRINCIPALS: '/servicePrincipals',
+  APP_REGISTRATIONS: '/applications?$filter=signInAudience eq \'AzureADMyOrg\'',
+};

package/src/providers/azure/queries/policy.queries.ts

@@ -0,0 +1,9 @@
+/**
+ * Microsoft Graph Policy Queries
+ * TODO: Full implementation in Story 1.6
+ */
+export const GraphPolicyQueries = {
+  CONDITIONAL_ACCESS: '/identity/conditionalAccess/policies',
+  AUTH_METHODS: '/policies/authenticationMethodsPolicy',
+  AUTHORIZATION: '/policies/authorizationPolicy',
+};

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

@@ -0,0 +1,10 @@
+/**
+ * Microsoft Graph User Queries
+ * TODO: Full implementation in Story 1.6
+ */
+export const GraphUserQueries = {
+  ALL_USERS: '/users',
+  ENABLED_USERS: '/users?$filter=accountEnabled eq true',
+  DISABLED_USERS: '/users?$filter=accountEnabled eq false',
+  ADMIN_USERS: '/directoryRoles/members',
+};