firewalla-mcp-server
Version:
Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client
243 lines • 8.39 kB
TypeScript
/**
* Search Tools Implementation for Firewalla MCP Server
* Provides advanced search capabilities across all entity types
*/
import type { SearchParams, SearchResult } from '../search/types.js';
import type { FirewallaClient } from '../firewalla/client.js';
import { type EnhancedCorrelationParams } from '../validation/field-mapper.js';
/**
* Configuration interface for risk thresholds and performance settings
*/
export interface SearchConfig {
riskThresholds: {
lowMax: number;
mediumMax: number;
highMax: number;
highRiskCountryMin: number;
highRiskFlowMin: number;
suspiciousAsnMin: number;
};
performance: {
correlationTimeoutMs: number;
maxCorrelationResults: number;
cacheExpirationMs: number;
};
}
/**
* Update search configuration at runtime
*/
export declare function updateSearchConfig(newConfig: Partial<SearchConfig>): void;
/**
* Get current search configuration
*/
export declare function getSearchConfig(): SearchConfig;
/**
* Search Engine for executing complex queries
*/
export declare class SearchEngine {
private firewalla;
private strategies;
constructor(firewalla: FirewallaClient);
/**
* Validate basic search parameters
*/
private validateBasicSearchParams;
/**
* Validate correlation field count
*/
private validateCorrelationFieldCount;
/**
* Validate geographic filters and return a sanitized (cloned) version.
* This avoids mutating the caller-supplied object which could lead to
* subtle side-effects elsewhere in the codebase.
*/
private validateGeographicFilters;
/**
* Helper function to extract and apply query filters from a query string
* Extracts common patterns like field:value and applies them to filter results
*/
private applyQueryFilters;
/**
* Initialize search strategies for different entity types
*/
private initializeStrategies;
/**
* Shared helper for validating limit parameter across all search methods
* @param limit - The limit value to validate
* @param entityType - The entity type for context-specific limits
* @param options - Additional validation options
*/
private validateLimitParameter;
/**
* Standardized parameter validation for all search operations
*/
private validateSearchParams;
/**
* Generic search execution method that handles common patterns
*/
private executeSearch;
/**
* Execute a search query for flows using simplified implementation with direct API calls.
* Performs basic validation and uses getFlowData API directly for improved reliability.
* Supports time range filtering and proper limit enforcement.
*/
searchFlows(params: SearchParams): Promise<SearchResult>;
/**
* Execute a search query for alarms using simplified implementation with direct API calls.
* Performs basic validation and uses getActiveAlarms API directly for improved reliability.
* Supports query filtering and proper limit enforcement.
*/
searchAlarms(params: SearchParams): Promise<SearchResult>;
/**
* Execute a search query for rules
*/
searchRules(params: SearchParams): Promise<SearchResult>;
/**
* Execute a search query for devices using cursor-based pagination
*/
searchDevices(params: SearchParams): Promise<SearchResult>;
/**
* Execute a search query for target lists
*/
searchTargetLists(params: SearchParams): Promise<SearchResult>;
/**
* Execute search for a specific entity type and query
*/
private executeSearchByType;
/**
* Enhanced cross-reference search with multi-field correlation capabilities
*/
enhancedCrossReferenceSearch(params: {
primary_query: string;
secondary_queries: string[];
correlation_params: EnhancedCorrelationParams;
limit?: number;
entity_types?: {
primary?: 'flows' | 'alarms' | 'rules' | 'devices';
secondary?: Array<'flows' | 'alarms' | 'rules' | 'devices'>;
};
}): Promise<any>;
/**
* Cross-reference search across multiple entity types with improved field mapping
*/
crossReferenceSearch(params: {
primary_query: string;
secondary_queries: string[];
correlation_field: string;
limit?: number;
primary_entity_type?: 'flows' | 'alarms' | 'rules' | 'devices';
}): Promise<any>;
/**
* Extract field value from item for correlation
*/
private extractFieldValue;
/**
* Recursively apply filters to a query AST
*/
private applyFiltersRecursively;
/**
* Sort results by a field
*/
private sortResults;
/**
* Generate aggregations for results
*/
private generateAggregations;
/**
* Get nested value from object using dot notation (enhanced with field mapping)
*/
private getNestedValue;
/**
* Get suggested correlation field combinations for given queries with enhanced validation
*/
getCorrelationSuggestions(params: {
primary_query: string;
secondary_queries: string[];
}): Promise<any>;
/**
* Determine entity type from query content with improved heuristics
*/
private determineEntityTypeFromQuery;
/**
* Generate contextual recommendations based on entity type combinations
*/
private generateContextualRecommendations;
/**
* Generate field usage statistics for entity types
*/
private generateFieldUsageStats;
/**
* Build geographic query string from filters using FirewallaClient
*/
private buildGeographicQuery;
/**
* Advanced geographic search for alarms with location-based threat analysis.
* Builds proper query strings for the Firewalla API.
*/
searchAlarmsByGeography(params: {
query?: string;
geographic_filters?: {
countries?: string[];
continents?: string[];
regions?: string[];
high_risk_countries?: boolean;
exclude_known_providers?: boolean;
threat_analysis?: boolean;
};
limit: number;
sort_by?: string;
group_by?: string;
}): Promise<any>;
/**
* Comprehensive geographic statistics and analytics
*/
getGeographicStatistics(params: {
entity_type: 'flows' | 'alarms';
time_range?: {
start: string;
end: string;
};
analysis_type?: 'summary' | 'detailed' | 'threat_intelligence';
group_by?: 'country' | 'continent' | 'region' | 'asn' | 'provider';
limit?: number;
}): Promise<any>;
/**
* Analyze geographic data for patterns and insights
*/
private analyzeGeographicData;
/**
* Analyze geographic threats for security insights
*/
private analyzeGeographicThreats;
/**
* Group results by geographic field for client-side processing
*/
private groupResultsByGeographicField;
/**
* Generate detailed geographic statistics
*/
private generateGeographicStatistics;
}
/**
* Search tools interface for type safety
*/
interface SearchTools {
search_flows: SearchEngine['searchFlows'];
search_alarms: SearchEngine['searchAlarms'];
search_rules: SearchEngine['searchRules'];
search_devices: SearchEngine['searchDevices'];
search_target_lists: SearchEngine['searchTargetLists'];
search_cross_reference: SearchEngine['crossReferenceSearch'];
search_enhanced_cross_reference: SearchEngine['enhancedCrossReferenceSearch'];
get_correlation_suggestions: SearchEngine['getCorrelationSuggestions'];
search_alarms_by_geography: SearchEngine['searchAlarmsByGeography'];
get_geographic_statistics: SearchEngine['getGeographicStatistics'];
}
/**
* Creates and returns a set of advanced search functions for querying Firewalla MCP server entities.
*
* The returned object provides methods for searching flows, alarms, rules, devices, target lists, and performing cross-reference searches, all using the provided Firewalla client instance.
*/
export declare function createSearchTools(firewalla: FirewallaClient): SearchTools;
export {};
//# sourceMappingURL=search.d.ts.map