get_boxes
Retrieve a list of Firewalla boxes to monitor network security devices, manage firewall configurations, and analyze network infrastructure.
Instructions
Retrieve list of Firewalla boxes
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | Get boxes within a specific group (requires group ID) |
Implementation Reference
- src/tools/handlers/analytics.ts:26-141 (handler)The GetBoxesHandler class implements the core logic for the 'get_boxes' tool. It validates optional group_id parameter, calls firewalla.getBoxes(), normalizes and enriches the box data (including geo-enrichment for public IPs), and returns a unified response with total_boxes and detailed box information.export class GetBoxesHandler extends BaseToolHandler { name = 'get_boxes'; description = 'List all managed Firewalla boxes with status and configuration details.'; category = 'analytics' as const; constructor() { super({ enableGeoEnrichment: false, enableFieldNormalization: false, additionalMeta: { data_source: 'flow_trends', entity_type: 'historical_flow_data', supports_geographic_enrichment: false, supports_field_normalization: false, standardization_version: '2.0.0', }, }); } async execute( _args: ToolArgs, firewalla: FirewallaClient ): Promise<ToolResponse> { try { const groupIdValidation = ParameterValidator.validateOptionalString( _args?.group_id, 'group_id' ); if (!groupIdValidation.isValid) { return this.createErrorResponse( 'Parameter validation failed', ErrorType.VALIDATION_ERROR, undefined, groupIdValidation.errors ); } const groupId = groupIdValidation.sanitizedValue; const boxesResponse = await withToolTimeout( async () => firewalla.getBoxes(groupId as string), this.name ); const boxResults = SafeAccess.safeArrayAccess( boxesResponse.results, (arr: any[]) => arr, [] ) as any[]; const normalizedBoxes = batchNormalize(boxResults, { name: (v: any) => sanitizeFieldValue(v, 'Unknown Box').value, model: (v: any) => sanitizeFieldValue(v, 'unknown').value, mode: (v: any) => sanitizeFieldValue(v, 'unknown').value, version: (v: any) => sanitizeFieldValue(v, 'unknown').value, group: (v: any) => (v ? normalizeUnknownFields(v) : null), location: (v: any) => sanitizeFieldValue(v, 'unknown').value, online: (v: any) => Boolean(v), gid: (v: any) => sanitizeFieldValue(v, 'unknown').value, license: (v: any) => sanitizeFieldValue(v, 'unknown').value, publicIP: (v: any) => sanitizeFieldValue(v, 'unknown').value, deviceCount: (v: any) => Number(v) || 0, ruleCount: (v: any) => Number(v) || 0, alarmCount: (v: any) => Number(v) || 0, }); const startTime = Date.now(); const boxData = normalizedBoxes.map((box: any) => { const timestampNormalized = normalizeTimestamps(box); const finalBox = timestampNormalized.data; return { gid: SafeAccess.getNestedValue(finalBox, 'gid', 'unknown'), name: finalBox.name, model: finalBox.model, mode: finalBox.mode, version: finalBox.version, online: SafeAccess.getNestedValue(finalBox, 'online', false), last_seen: SafeAccess.getNestedValue(finalBox, 'lastSeen', 0), license: SafeAccess.getNestedValue(finalBox, 'license', null), public_ip: finalBox.publicIP || finalBox.public_ip || 'unknown', group: finalBox.group, location: finalBox.location, device_count: SafeAccess.getNestedValue(finalBox, 'deviceCount', 0), rule_count: SafeAccess.getNestedValue(finalBox, 'ruleCount', 0), alarm_count: SafeAccess.getNestedValue(finalBox, 'alarmCount', 0), }; }); // Apply geographic enrichment for public IP addresses const enrichedBoxData = await this.enrichGeoIfNeeded(boxData, [ 'public_ip', ]); const unifiedResponseData = { total_boxes: normalizedBoxes.length, boxes: enrichedBoxData, }; 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 boxes: ${errorMessage}`, ErrorType.API_ERROR ); } } }
- src/server.ts:525-537 (schema)Defines the input schema for the get_boxes tool in the MCP server's tools configuration, specifying an optional 'group' parameter.name: 'get_boxes', description: 'Retrieve list of Firewalla boxes', inputSchema: { type: 'object', properties: { group: { type: 'string', description: 'Get boxes within a specific group (requires group ID)', }, }, required: [], },
- src/tools/registry.ts:161-161 (registration)Registers the GetBoxesHandler instance in the central ToolRegistry during initialization.this.register(new GetBoxesHandler());
- src/tools/registry.ts:58-59 (registration)Imports the GetBoxesHandler from the analytics handlers module for use in the registry.GetBoxesHandler, GetSimpleStatisticsHandler,