get_statistics_by_region
Retrieve top regions by blocked flows to analyze network security threats and identify geographical attack patterns for Firewalla firewall monitoring.
Instructions
Retrieve statistics by region (top regions by blocked flows)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | Get statistics for specific box group | |
| limit | No | Maximum number of results (optional, default: 5) |
Implementation Reference
- src/tools/handlers/analytics.ts:277-401 (handler)The GetStatisticsByRegionHandler class implements the core logic for the 'get_statistics_by_region' tool. It extends BaseToolHandler, calls firewalla.getStatisticsByRegion(), processes regional flow statistics, calculates percentages and top regions, and returns a standardized response.export class GetStatisticsByRegionHandler extends BaseToolHandler { name = 'get_statistics_by_region'; description = 'Get flow statistics grouped by country/region for geographic analysis. No required parameters. Data cached for 1 hour for performance.'; category = 'analytics' as const; constructor() { super({ enableGeoEnrichment: false, // Already contains geographic data enableFieldNormalization: true, additionalMeta: { data_source: 'regional_statistics', entity_type: 'geographic_flow_statistics', supports_geographic_enrichment: false, supports_field_normalization: true, standardization_version: '2.0.0', }, }); } async execute( _args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { const stats = await withToolTimeout( async () => firewalla.getStatisticsByRegion(), this.name ); // Validate response structure with comprehensive null/undefined guards if ( !stats || !SafeAccess.getNestedValue(stats, 'results') || !Array.isArray(stats.results) ) { return this.createSuccessResponse({ total_regions: 0, regional_statistics: [], top_regions: [], error: 'No regional statistics available - API response missing results array', debug_info: { stats_exists: !!stats, results_exists: !!stats?.results, results_is_array: !!stats?.results && Array.isArray(stats.results), actual_structure: stats ? Object.keys(stats) : 'null', }, }); } // Calculate total flow count for percentage calculations const totalFlowCount = stats.results.reduce((sum: number, stat: any) => { return ( sum + (typeof SafeAccess.getNestedValue(stat, 'value') === 'number' ? stat.value : 0) ); }, 0); // Process regional statistics with defensive programming const regionalStatistics = SafeAccess.safeArrayFilter( stats.results, (stat: any): stat is any => stat && typeof SafeAccess.getNestedValue(stat, 'value') === 'number' && !!SafeAccess.getNestedValue(stat, 'meta') ) .map((stat: any) => ({ country_code: SafeAccess.getNestedValue(stat, 'meta.code', 'unknown'), flow_count: SafeAccess.getNestedValue(stat, 'value', 0), percentage: totalFlowCount > 0 ? Math.round( ((SafeAccess.getNestedValue(stat, 'value', 0) as number) / totalFlowCount) * 100 ) : 0, })) .sort((a: any, b: any) => b.flow_count - a.flow_count); // Get top 5 regions with defensive programming const topRegions = SafeAccess.safeArrayFilter( stats.results, (stat: any): stat is any => stat && typeof SafeAccess.getNestedValue(stat, 'value') === 'number' && SafeAccess.getNestedValue(stat, 'meta') ) .sort( (a: any, b: any) => (SafeAccess.getNestedValue(b, 'value', 0) as number) - (SafeAccess.getNestedValue(a, 'value', 0) as number) ) .slice(0, 5) .map((stat: any) => ({ country_code: SafeAccess.getNestedValue(stat, 'meta.code', 'unknown'), flow_count: SafeAccess.getNestedValue(stat, 'value', 0), })); const startTime = Date.now(); const unifiedResponseData = { total_regions: stats.results.length, regional_statistics: regionalStatistics, top_regions: topRegions, total_flow_count: totalFlowCount, }; const executionTime = Date.now() - startTime; return this.createUnifiedResponse(unifiedResponseData, { executionTimeMs: executionTime, }); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred'; return this.createErrorResponse( `Failed to get statistics by region: ${errorMessage}`, ErrorType.API_ERROR ); } } }
- src/tools/registry.ts:163-163 (registration)The tool handler is registered in the ToolRegistry by instantiating GetStatisticsByRegionHandler and calling register() during registry construction.this.register(new GetStatisticsByRegionHandler());
- src/server.ts:554-573 (schema)The MCP tool schema definition including inputSchema with optional 'group' and 'limit' parameters is hardcoded in the ListToolsRequestHandler response.name: 'get_statistics_by_region', description: 'Retrieve statistics by region (top regions by blocked flows)', inputSchema: { type: 'object', properties: { group: { type: 'string', description: 'Get statistics for specific box group', }, limit: { type: 'number', description: 'Maximum number of results (optional, default: 5)', minimum: 1, default: 5, }, }, required: [], },
- src/tools/registry.ts:60-60 (registration)Import of GetStatisticsByRegionHandler from './handlers/analytics.js' in the ToolRegistry module.GetStatisticsByRegionHandler,