get_statistics_by_region
Retrieve blocked flow statistics by region to identify top security threats and monitor network activity. Customize results by group and limit for targeted insights.
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)Core handler implementation: GetStatisticsByRegionHandler class that executes firewalla.getStatisticsByRegion(), processes regional flow statistics, calculates percentages, sorts top regions, and returns unified response with geographic analysis.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/server.ts:553-574 (schema)MCP protocol input schema definition for the tool, specifying optional parameters: group (string) and limit (number, min 1, default 5).{ 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:163-163 (registration)Tool registration in ToolRegistry: instantiates and registers GetStatisticsByRegionHandler during registry initialization.this.register(new GetStatisticsByRegionHandler());
- src/tools/registry.ts:60-60 (registration)Import of GetStatisticsByRegionHandler from './handlers/analytics.js' in registry.GetStatisticsByRegionHandler,