firewalla-mcp-server

Instructions

Implementation Reference

• src/tools/handlers/search.ts:941-1107 (handler)

  The SearchRulesHandler class that implements the core logic for the 'search_rules' tool. Handles input validation using validateCommonSearchParameters, calls the Firewalla search_rules API via searchTools, processes NetworkRule results into standardized format, creates search metadata, and returns a unified ToolResponse.

  export class SearchRulesHandler extends BaseToolHandler {
    name = 'search_rules';
    description = `Firewall rule searching with comprehensive filtering for actions, targets, and status.
  
  Search through firewall rules to manage policies, troubleshoot blocking issues, and analyze rule effectiveness.
  
  QUERY EXAMPLES:
  - Action filtering: "action:block", "action:allow", "action:timelimit"
  - Target searches: "target_value:*.facebook.com", "target_type:domain", "target_value:192.168.*"
  - Status queries: "enabled:true", "paused:false", "active:true"
  - Direction: "direction:inbound", "direction:outbound", "direction:bidirection"
  - Combined filters: "action:block AND target_value:*.social.* AND enabled:true"
  
  RULE MANAGEMENT EXAMPLES:
  - Social media blocks: "action:block AND (target_value:*.facebook.com OR target_value:*.twitter.com)"
  - Gaming restrictions: "action:timelimit AND target_category:gaming"
  - Security rules: "action:block AND target_type:malware_domain"
  - Active blocking rules: "action:block AND enabled:true AND paused:false"
  
  TROUBLESHOOTING:
  - Find conflicting rules: "target_value:example.com" (then check different actions)
  - Identify inactive rules: "enabled:false OR paused:true"
  - Review recent changes: "modified:>=yesterday"
  
  PERFORMANCE NOTES:
  - Rules are cached for 10 minutes for optimal performance
  - Use specific target_value searches for fastest results
  - Group by action or target_type for rule analysis
  
  For rule management operations, see pause_rule and resume_rule tools.`;
    category = 'search' as const;
  
    constructor() {
      // Enable field normalization for firewall rules (no geographic enrichment needed)
      super({
        enableGeoEnrichment: false, // Firewall rules don't typically contain IP addresses
        enableFieldNormalization: true, // Ensure consistent snake_case field naming across all responses
        additionalMeta: {
          data_source: 'rules',
          entity_type: 'firewall_rules',
          supports_geographic_enrichment: false,
          supports_field_normalization: true,
          standardization_version: '2.0.0',
        },
      });
    }
  
    async execute(
      args: ToolArgs,
      firewalla: FirewallaClient
    ): Promise<ToolResponse> {
      const searchArgs = args as SearchRulesArgs;
      const startTime = Date.now();
  
      try {
        // Validate common search parameters
        const validation = validateCommonSearchParameters(
          searchArgs,
          this.name,
          'rules'
        );
  
        if (!validation.isValid) {
          return validation.response;
        }
  
        const searchTools = createSearchTools(firewalla);
        const searchParams: SearchParams = {
          query: searchArgs.query,
          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,
        };
  
        const result = await withToolTimeout(
          async () => searchTools.search_rules(searchParams),
          this.name
        );
        const executionTime = Date.now() - startTime;
  
        // Process rule data
        const processedRules = SafeAccess.safeArrayMap(
          (result as any).results,
          (rule: NetworkRule) => ({
            id: SafeAccess.getNestedValue(rule as any, 'id', 'unknown'),
            action: SafeAccess.getNestedValue(rule as any, 'action', 'unknown'),
            target_type: SafeAccess.getNestedValue(
              rule as any,
              'target.type',
              'unknown'
            ),
            target_value: SafeAccess.getNestedValue(
              rule as any,
              'target.value',
              'unknown'
            ),
            direction: SafeAccess.getNestedValue(
              rule as any,
              'direction',
              'unknown'
            ),
            status: SafeAccess.getNestedValue(rule as any, 'status', 'unknown'),
            hit_count: SafeAccess.getNestedValue(rule as any, 'hit.count', 0),
          })
        );
  
        // Create metadata for standardized response
        const metadata: SearchMetadata = {
          query: SafeAccess.getNestedValue(
            result as any,
            'query',
            searchArgs.query || ''
          ) as string,
          entityType: 'rules',
          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 = {
          rules: processedRules,
          metadata,
          query_info: {
            original_query: searchArgs.query,
            applied_filters: {
              grouping: !!searchArgs.group_by,
              sorting: !!searchArgs.sort_by,
              aggregation: !!searchArgs.aggregate,
            },
          },
        };
  
        // Return unified response
        return this.createUnifiedResponse(unifiedResponseData, {
          executionTimeMs: executionTime,
        });
      } catch (error: unknown) {
        if (error instanceof TimeoutError) {
          return createTimeoutErrorResponse(this.name, error.duration, 10000);
        }
  
        const errorMessage =
          error instanceof Error ? error.message : 'Unknown error occurred';
        return createErrorResponse(
          this.name,
          `Failed to search rules: ${errorMessage}`,
          ErrorType.SEARCH_ERROR
        );
      }
    }
  }

• src/server.ts:509-522 (schema)

  MCP tool schema definition for 'search_rules' including inputSchema with query parameter description and validation rules, registered in the server tools list.

  name: 'search_rules',
  description:
    'Search firewall rules by target, action or status. Supports all rule fields.',
  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description:
          'Search query using Firewalla syntax. Supported fields: action:allow/block/timelimit, target.type:domain/ip/device, target.value:*.facebook.com, status:active/paused, direction:bidirection/inbound/outbound, protocol:tcp/udp, gid:box_id, scope.type:device/network, notes:"description text". Examples: "action:block AND target.value:*.social.com", "status:paused", "target.type:domain AND action:block"',
      },
    },
    required: [],
  },

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

  Registration of the SearchRulesHandler instance in the central ToolRegistry during automatic handler registration in the constructor.

  this.register(new SearchRulesHandler());

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

  TypeScript interface defining the input arguments for SearchRulesHandler, extending BaseSearchArgs which includes query, limit, offset, cursor, sort_by, etc.

  export interface SearchRulesArgs extends BaseSearchArgs {}

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

  Shared validation helper function used by all search handlers including search_rules for parameter validation, query syntax checking, field validation, and limit enforcement.

  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,
    };
  }