get_specific_alarm

Retrieve detailed information about a specific Firewalla alarm using its unique ID to analyze security events and network incidents.

Instructions

Get detailed information for a specific Firewalla alarm

Input Schema

TableJSON Schema

Name	Required	Description	Default
`alarm_id`	Yes	Alarm ID (required for API call)

Implementation Reference

src/tools/handlers/security.ts:486-596 (handler)

GetSpecificAlarmHandler class: core implementation executing the tool logic. Validates alarm_id, calls firewalla.getSpecificAlarm(alarmId), applies geo-enrichment, handles errors including not found, formats unified response.

export class GetSpecificAlarmHandler extends BaseToolHandler {
  name = 'get_specific_alarm';
  description =
    'Get detailed information for a specific alarm by alarm ID. Requires alarm_id parameter obtained from get_active_alarms or search_alarms (aid field is automatically normalized). Features improved ID resolution that automatically tries multiple ID formats to handle API inconsistencies.';
  category = 'security' as const;

  constructor() {
    super({
      enableGeoEnrichment: true,
      enableFieldNormalization: true,
      additionalMeta: {
        data_source: 'specific_alarm',
        entity_type: 'security_alarm_detail',
        supports_geographic_enrichment: true,
        supports_field_normalization: true,
        standardization_version: '2.0.0',
      },
    });
  }

  async execute(
    args: ToolArgs,
    firewalla: FirewallaClient
  ): Promise<ToolResponse> {
    try {
      const alarmIdValidation = ParameterValidator.validateAlarmId(
        args?.alarm_id,
        'alarm_id'
      );

      if (!alarmIdValidation.isValid) {
        return this.createErrorResponse(
          'Parameter validation failed',
          ErrorType.VALIDATION_ERROR,
          undefined,
          alarmIdValidation.errors
        );
      }

      const rawAlarmId = alarmIdValidation.sanitizedValue as string;
      const alarmId = validateAlarmId(rawAlarmId);

      const response = await withToolTimeout(
        async () => firewalla.getSpecificAlarm(alarmId),
        'get_specific_alarm'
      );

      // Check if alarm exists
      if (!response || !response.results || response.results.length === 0) {
        return this.createErrorResponse(
          `Alarm with ID '${alarmId}' not found. Please verify the alarm ID is correct and the alarm has not been deleted.`,
          ErrorType.API_ERROR,
          {
            alarm_id: alarmId,
            suggestion:
              'Use get_active_alarms to list available alarms and their IDs',
          }
        );
      }

      const startTime = Date.now();

      // Apply geographic enrichment to the alarm data
      const enrichedAlarm = await this.enrichGeoIfNeeded(response, [
        'src',
        'dst',
        'device.ip',
        'remote.ip',
      ]);

      const unifiedResponseData = {
        alarm: enrichedAlarm,
        retrieved_at: getCurrentTimestamp(),
      };

      const executionTime = Date.now() - startTime;
      return this.createUnifiedResponse(unifiedResponseData, {
        executionTimeMs: executionTime,
      });
    } catch (error: unknown) {
      if (error instanceof TimeoutError) {
        return createTimeoutErrorResponse(
          'get_specific_alarm',
          error.duration,
          10000
        );
      }

      const errorMessage =
        error instanceof Error ? error.message : 'Unknown error occurred';

      // Check for specific API error patterns
      if (errorMessage.includes('404') || errorMessage.includes('not found')) {
        return this.createErrorResponse(
          `Alarm not found: ${args?.alarm_id}. The alarm may have been deleted or the ID may be incorrect.`,
          ErrorType.API_ERROR,
          {
            alarm_id: args?.alarm_id,
            suggestion:
              'Use get_active_alarms to list available alarms and their IDs',
          }
        );
      }

      return this.createErrorResponse(
        `Failed to get specific alarm: ${errorMessage}`,
        ErrorType.API_ERROR
      );
    }
  }
}

src/tools/registry.ts:134-134 (registration)
Tool registration: GetSpecificAlarmHandler is instantiated and registered in the ToolRegistry.
```
this.register(new GetSpecificAlarmHandler());
```

src/server.ts:132-146 (schema)

MCP input schema definition for get_specific_alarm tool in ListTools response.

{
  name: 'get_specific_alarm',
  description:
    'Get detailed information for a specific Firewalla alarm',
  inputSchema: {
    type: 'object',
    properties: {
      alarm_id: {
        type: 'string',
        description: 'Alarm ID (required for API call)',
      },
    },
    required: ['alarm_id'],
  },
},

firewalla-mcp-server