firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/search.ts:306-652 (handler)

  Core handler class for 'search_flows' tool. Implements execute() method with full logic: input validation, Firewalla search API integration, flow data processing/normalization, geographic enrichment, caching control, retry/timeout handling, and standardized ToolResponse output.

  export class SearchFlowsHandler extends BaseToolHandler {
    name = 'search_flows';
    description = `Advanced network flow searching with powerful query syntax and enhanced reliability. Data cached for 15 seconds, use force_refresh=true for real-time network analysis.
    
  Search through network traffic flows using complex queries with logical operators, wildcards, and field-specific filters. Features automatic boolean query translation for improved compatibility.
  
  REQUIRED PARAMETERS:
  - query: Search query string using flow field syntax
  
  OPTIONAL PARAMETERS:
  - limit: Maximum number of results to return (default: 200, max: 500)
  - force_refresh: Bypass cache for real-time data (default: false)
  - cursor: Pagination cursor from previous response
  - time_range: Time window for search (start/end timestamps)
  - sort_by: Field to sort results by
  - group_by: Field to group results by for aggregation
  - aggregate: Enable aggregation statistics
  
  QUERY EXAMPLES (with automatic boolean translation):
  - Boolean fields (both syntaxes supported): "blocked:true" OR "blocked=true", "allowed:false" OR "allowed=false" (automatically converted to backend format)
  - Basic field queries: "protocol:tcp", "source_ip:192.168.1.100", "destination_port:443"
  - Logical operators: "protocol:tcp AND blocked:false", "blocked=true OR allowed=false"
  - Wildcards: "source_ip:192.168.*", "destination_domain:*.facebook.com"
  - Ranges: "bytes:[1000 TO 50000]", "timestamp:>=2024-01-01"
  - Complex queries: "(protocol:tcp OR protocol:udp) AND source_ip:192.168.* NOT blocked=true"
  
  CACHE CONTROL:
  - Default: 15-second cache for optimal performance
  - Real-time: Use force_refresh=true for live network monitoring
  - Cache info included in responses for timing awareness
  
  PERFORMANCE TIPS:
  - Use specific time ranges for better performance: {"time_range": {"start": "2024-01-01T00:00:00Z", "end": "2024-01-02T00:00:00Z"}}
  - Limit results with reasonable values (100-1000) for faster responses
  - Use cursor for pagination with large datasets
  - Group by fields like "source_ip" or "protocol" for aggregated insights
  
  See the Query Syntax Guide for complete documentation: /docs/query-syntax-guide.md`;
    category = 'search' as const;
  
    constructor() {
      // Enable full standardization: geographic enrichment and field normalization for network flows
      super({
        enableGeoEnrichment: true, // Network flows have IP addresses that require geographic enrichment
        enableFieldNormalization: true, // Ensure consistent snake_case field naming across all responses
        additionalMeta: {
          data_source: 'flows',
          entity_type: 'network_flows',
          supports_geographic_enrichment: true,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      const searchArgs = args as SearchFlowsArgs;
      const startTime = Date.now();
  
      try {
        // Validate common search parameters
        const validation = validateCommonSearchParameters(
          searchArgs,
          this.name,
          'flows'
        );
  
        if (!validation.isValid) {
          return validation.response;
        }
  
        // Validate force_refresh parameter if provided
        const forceRefreshValidation = ParameterValidator.validateBoolean(
          searchArgs.force_refresh,
          'force_refresh',
          false
        );
  
        if (!forceRefreshValidation.isValid) {
          return createErrorResponse(
            this.name,
            'Force refresh parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            forceRefreshValidation.errors
          );
        }
  
        const finalQuery = searchArgs.query;
  
        // ------------------------------------------------------------
        // Validate geographic_filters if provided
        // ------------------------------------------------------------
        if (searchArgs.geographic_filters !== undefined) {
          // Validate it's an object
          if (
            typeof searchArgs.geographic_filters !== 'object' ||
            searchArgs.geographic_filters === null
          ) {
            return createErrorResponse(
              this.name,
              'Invalid geographic_filters parameter',
              ErrorType.VALIDATION_ERROR,
              {
                provided_value: searchArgs.geographic_filters,
                expected:
                  'object with optional fields: countries, continents, regions, cities, etc.',
              }
            );
          }
  
          // Validate country codes if provided
          if (
            searchArgs.geographic_filters.countries &&
            searchArgs.geographic_filters.countries.length > 0
          ) {
            const countryValidation = validateCountryCodes(
              searchArgs.geographic_filters.countries
            );
            if (!countryValidation.valid) {
              return createErrorResponse(
                this.name,
                `Country code validation failed: Invalid country codes: ${countryValidation.invalid.join(', ')}`,
                ErrorType.VALIDATION_ERROR,
                {
                  invalid_codes: countryValidation.invalid,
                  valid_codes: countryValidation.valid,
                  documentation:
                    'Country codes must be ISO 3166-1 alpha-2 format (e.g., US, CN, GB)',
                }
              );
            }
          }
        }
  
        // ------------------------------------------------------------
        // Validate include_analytics parameter if provided
        // ------------------------------------------------------------
        const includeAnalyticsValidation = ParameterValidator.validateBoolean(
          searchArgs.include_analytics,
          'include_analytics',
          false
        );
  
        if (!includeAnalyticsValidation.isValid) {
          return createErrorResponse(
            this.name,
            'Include analytics parameter validation failed',
            ErrorType.VALIDATION_ERROR,
            undefined,
            includeAnalyticsValidation.errors
          );
        }
  
        const searchTools = createSearchTools(firewalla);
        const searchParams: SearchParams = {
          query: finalQuery,
          limit: searchArgs.limit,
          offset: searchArgs.offset,
          cursor: searchArgs.cursor,
          sort_by: searchArgs.sort_by,
          sort_order: searchArgs.sort_order,
          group_by: searchArgs.group_by,
          aggregate: searchArgs.aggregate,
          time_range: searchArgs.time_range,
          force_refresh: forceRefreshValidation.sanitizedValue as boolean,
          geographic_filters: searchArgs.geographic_filters,
          include_analytics: includeAnalyticsValidation.sanitizedValue as boolean,
        };
  
        // Use retry logic for search operations as they can be prone to timeouts
        const result = await withRetryAndTimeout(
          async () => searchTools.search_flows(searchParams),
          this.name,
          {
            maxAttempts: 2, // Conservative retry for search operations
            initialDelayMs: 2000, // Wait 2 seconds before retry
            shouldRetry: (error, attempt) => {
              // Retry on timeouts and network errors, but not on validation errors
              if (error instanceof TimeoutError) {
                return true;
              }
              return isRetryableError(error) && attempt === 1; // Only retry once for search
            },
          }
        );
        const executionTime = Date.now() - startTime;
  
        // Process flow data with enhanced standardization
        let processedFlows = SafeAccess.safeArrayMap(
          (result as any).results,
          (flow: Flow) => ({
            timestamp: unixToISOStringOrNow(flow.ts),
            source_ip: SafeAccess.getNestedValue(
              flow as any,
              'source.ip',
              'unknown'
            ),
            source_country: SafeAccess.getNestedValue(
              flow as any,
              'source.geo.country',
              'unknown'
            ),
            source_city: SafeAccess.getNestedValue(
              flow as any,
              'source.geo.city',
              'unknown'
            ),
            source_continent: SafeAccess.getNestedValue(
              flow as any,
              'source.geo.continent',
              'unknown'
            ),
            destination_ip: SafeAccess.getNestedValue(
              flow as any,
              'destination.ip',
              'unknown'
            ),
            destination_country: SafeAccess.getNestedValue(
              flow as any,
              'destination.geo.country',
              'unknown'
            ),
            destination_city: SafeAccess.getNestedValue(
              flow as any,
              'destination.geo.city',
              'unknown'
            ),
            destination_continent: SafeAccess.getNestedValue(
              flow as any,
              'destination.geo.continent',
              'unknown'
            ),
            protocol: SafeAccess.getNestedValue(
              flow as any,
              'protocol',
              'unknown'
            ),
            // bytes field is calculated as total traffic: download + upload
            bytes:
              (SafeAccess.getNestedValue(flow as any, 'download', 0) as number) +
              (SafeAccess.getNestedValue(flow as any, 'upload', 0) as number),
            blocked: SafeAccess.getNestedValue(flow as any, 'block', false),
            direction: SafeAccess.getNestedValue(
              flow as any,
              'direction',
              'unknown'
            ),
            device: SafeAccess.getNestedValue(flow as any, 'device', {}),
          })
        );
  
        // Apply geographic enrichment pipeline for IP addresses
        processedFlows = await this.enrichGeoIfNeeded(processedFlows, [
          'source_ip',
          'destination_ip',
        ]);
  
        // Create metadata for standardized response
        const metadata: SearchMetadata = {
          query: SafeAccess.getNestedValue(
            result as any,
            'query',
            searchArgs.query || ''
          ) as string,
          entityType: 'flows',
          executionTime: SafeAccess.getNestedValue(
            result as any,
            'execution_time_ms',
            executionTime
          ) as number,
          cached: false,
          cursor: (result as any).next_cursor,
          hasMore: !!(result as any).next_cursor,
          limit: searchArgs.limit,
          aggregations: SafeAccess.getNestedValue(
            result as any,
            'aggregations',
            null
          ) as Record<string, any> | undefined,
        };
  
        // Create unified response with standardized metadata
        const unifiedResponseData = {
          flows: processedFlows,
          metadata,
          query_info: {
            original_query: searchArgs.query,
            final_query: finalQuery,
            applied_filters: {
              geographic: !!searchArgs.geographic_filters,
              time_range: !!searchArgs.time_range,
              analytics: !!searchArgs.include_analytics,
            },
          },
        };
  
        // Return unified response
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        if (error instanceof TimeoutError) {
          return createTimeoutErrorResponse(
            this.name,
            error.duration,
            10000 // Default timeout from timeout-manager
          );
        }
  
        // Handle retry failure errors with enhanced context
        if (error instanceof Error && error.name === 'RetryFailureError') {
          const { retryContext } = error as any;
          const { userGuidance } = error as any;
  
          return createErrorResponse(
            this.name,
            `Search flows operation failed after ${retryContext?.attempts || 'multiple'} attempts: ${error.message}`,
            ErrorType.SEARCH_ERROR,
            {
              retry_attempts: retryContext?.attempts,
              total_duration_ms: retryContext?.totalDurationMs,
              final_error:
                retryContext?.originalError instanceof Error
                  ? retryContext.originalError.message
                  : 'Unknown error',
            },
            userGuidance || [
              'Multiple retry attempts failed',
              'Try reducing the scope of your search query',
              'Check network connectivity and try again later',
            ]
          );
        }
  
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        return createErrorResponse(
          this.name,
          `Failed to search flows: ${errorMessage}`,
          ErrorType.SEARCH_ERROR
        );
      }
    }

• src/tools/registry.ts:156-156 (registration)

  Tool registration in ToolRegistry constructor's registerHandlers() method.

  this.register(new SearchFlowsHandler());

• src/tools/registry.ts:67-73 (registration)

  Import statement for SearchFlowsHandler from handlers/search.ts

  import {
    SearchFlowsHandler,
    SearchAlarmsHandler,
    SearchRulesHandler,
    SearchDevicesHandler,
    SearchTargetListsHandler,
  } from './handlers/search.js';

• src/tools/handlers/search.ts:44-74 (schema)

  TypeScript interfaces defining input schema (SearchFlowsArgs extending BaseSearchArgs) for tool parameters including query, pagination, sorting, time/geographic filters.

  export interface BaseSearchArgs extends ToolArgs {
    query: string;
    limit: number;
    offset?: number;
    cursor?: string;
    sort_by?: string;
    sort_order?: 'asc' | 'desc';
    group_by?: string;
    aggregate?: boolean;
    force_refresh?: boolean;
  }
  
  // Search argument interfaces for type safety
  export interface SearchFlowsArgs extends BaseSearchArgs {
    time_range?: {
      start?: string;
      end?: string;
    };
    geographic_filters?: {
      countries?: string[];
      continents?: string[];
      regions?: string[];
      cities?: string[];
      asns?: string[];
      hosting_providers?: string[];
      exclude_vpn?: boolean;
      exclude_cloud?: boolean;
      min_risk_score?: number;
    };
    include_analytics?: boolean;
  }

• src/tools/handlers/search.ts:155-304 (helper)

  Shared validation helper function used by search_flows handler for common parameter validation (limit, query syntax/fields, cursor, group_by). Called at line 370 in execute().

  function validateCommonSearchParameters(
    args: BaseSearchArgs,
    toolName: string,
    entityType: 'flows' | 'alarms' | 'rules' | 'devices' | 'target_lists'
  ): CommonSearchValidationResult {
    // Validate optional limit parameter with default
    const limitValidation = ParameterValidator.validateNumber(
      args.limit,
      'limit',
      {
        required: false,
        defaultValue: 200,
        ...getLimitValidationConfig(toolName),
      }
    );
  
    if (!limitValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          limitValidation.errors
        ),
      };
    }
  
    // Validate required query parameter
    const queryValidation = ParameterValidator.validateRequiredString(
      args.query,
      'query'
    );
  
    if (!queryValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Query parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          queryValidation.errors
        ),
      };
    }
  
    // Validate query syntax
    const querySyntaxValidation = validateFirewallaQuerySyntax(args.query);
  
    if (!querySyntaxValidation.isValid) {
      const examples = getExampleQueries(entityType);
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Invalid query syntax',
          ErrorType.VALIDATION_ERROR,
          {
            query: args.query,
            syntax_errors: querySyntaxValidation.errors,
            examples: examples.slice(0, 3),
            hint: 'Use field:value syntax with logical operators (AND, OR, NOT)',
          },
          querySyntaxValidation.errors
        ),
      };
    }
  
    // Validate field names in the query
    const fieldValidation = QuerySanitizer.validateQueryFields(
      args.query,
      entityType
    );
  
    if (!fieldValidation.isValid) {
      return {
        isValid: false,
        response: createErrorResponse(
          toolName,
          'Query contains invalid field names',
          ErrorType.VALIDATION_ERROR,
          {
            query: args.query,
            documentation:
              entityType === 'alarms'
                ? 'See /docs/error-handling-guide.md for troubleshooting'
                : 'See /docs/query-syntax-guide.md for valid field names',
          },
          fieldValidation.errors
        ),
      };
    }
  
    // Validate cursor format if provided
    if (args.cursor !== undefined) {
      const cursorValidation = ParameterValidator.validateCursor(
        args.cursor,
        'cursor'
      );
      if (!cursorValidation.isValid) {
        return {
          isValid: false,
          response: createErrorResponse(
            toolName,
            'Invalid cursor format',
            ErrorType.VALIDATION_ERROR,
            undefined,
            cursorValidation.errors
          ),
        };
      }
    }
  
    // Validate group_by parameter if provided
    if (args.group_by !== undefined) {
      const groupByValidation = ParameterValidator.validateEnum(
        args.group_by,
        'group_by',
        SEARCH_FIELDS[entityType],
        false
      );
  
      if (!groupByValidation.isValid) {
        return {
          isValid: false,
          response: createErrorResponse(
            toolName,
            'Invalid group_by field',
            ErrorType.VALIDATION_ERROR,
            {
              group_by: args.group_by,
              valid_fields: SEARCH_FIELDS[entityType],
              documentation: 'See /docs/query-syntax-guide.md for valid fields',
            },
            groupByValidation.errors
          ),
        };
      }
    }
  
    return {
      isValid: true,
      limit: args.limit,
      query: args.query,
      cursor: args.cursor,
      groupBy: args.group_by,
    };
  }