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
147 lines • 5.66 kB
TypeScript
/**
* Enhanced Correlation Algorithms with Scoring and Fuzzy Matching
* Provides intelligent correlation scoring and flexible matching strategies
*
* Weight Handling Logic:
* =====================
*
* Field weights control the importance of each field in correlation scoring.
* The weight fallback hierarchy is:
*
* 1. Explicit field weight: weights[field] - Used if it's a valid number (including 0)
* 2. Default weight: weights.default - Used if field weight is invalid
* 3. Hardcoded fallback: 0.5 - Used as last resort
*
* Special Weight Values:
* - 0: Field is completely ignored (not included in weighted average calculation)
* - 0.1 to 1.0: Field contributes to scoring with given weight
* - null/undefined/false/string: Invalid, falls back to default or 0.5
*
* Examples:
* - weights = { source_ip: 0 } → source_ip ignored completely
* - weights = { source_ip: undefined } → uses default weight
* - weights = { source_ip: 0.8 } → source_ip weighted at 80% importance
*
* Backward Compatibility:
* - Existing code using nullish coalescing (??) continues to work
* - Zero weights now properly excluded from calculations
* - Invalid weights (non-numbers) properly fall back to defaults
*/
import { type EntityType, type MappableEntity } from './field-mapper.js';
/**
* Configuration for correlation scoring weights
*/
export type CorrelationWeights = Record<string, number>;
/**
* Validates and resolves field weight with proper fallback handling
*
* @param field - The field name to get weight for
* @param weights - The weights configuration object
* @returns Validated weight value between 0 and 1
*/
export declare function resolveFieldWeight(field: string, weights: CorrelationWeights): number;
/**
* Default field weights for correlation scoring
*/
export declare const DEFAULT_CORRELATION_WEIGHTS: CorrelationWeights;
/**
* Fuzzy matching configuration
*/
export interface FuzzyMatchConfig {
enabled: boolean;
stringThreshold: number;
ipSubnetMatching: boolean;
numericTolerance: number;
geographicRadius: number;
}
/**
* Default fuzzy matching configuration
*/
export declare const DEFAULT_FUZZY_CONFIG: FuzzyMatchConfig;
/**
* Enhanced correlation result with scoring
*/
export interface ScoredCorrelationResult {
entity: MappableEntity;
correlationScore: number;
fieldScores: Record<string, number>;
fieldMatchTypes: Record<string, 'exact' | 'fuzzy' | 'partial'>;
matchType: 'exact' | 'fuzzy' | 'partial';
confidence: 'high' | 'medium' | 'low';
}
/**
* Enhanced correlation statistics with scoring details
*/
export interface EnhancedCorrelationStats {
totalSecondaryResults: number;
correlatedResults: number;
averageScore: number;
scoreDistribution: {
high: number;
medium: number;
low: number;
};
fieldStatistics: Record<string, {
exactMatches: number;
fuzzyMatches: number;
partialMatches: number;
averageScore: number;
}>;
fuzzyMatchingEnabled: boolean;
totalProcessingTime: number;
}
/**
* Perform enhanced multi-field correlation with scoring and fuzzy matching
*/
export declare function performEnhancedCorrelation(primaryResults: MappableEntity[], secondaryResults: MappableEntity[], primaryType: EntityType, secondaryType: EntityType, correlationFields: string[], correlationType: 'AND' | 'OR', weights?: CorrelationWeights, fuzzyConfig?: FuzzyMatchConfig, minimumScore?: number): {
correlatedResults: ScoredCorrelationResult[];
stats: EnhancedCorrelationStats;
};
/**
* Calculate IP address similarity (subnet matching)
*/
/**
* Calculates similarity between two IP addresses using subnet matching
*
* @param ip1 - First IP address to compare
* @param ip2 - Second IP address to compare
* @returns Similarity score between 0.0 and 1.0, where 1.0 is exact match
*/
export declare function calculateIPSimilarity(ip1: string, ip2: string): number;
/**
* Calculate string similarity using Levenshtein distance
*/
/**
* Calculates string similarity using Levenshtein distance algorithm
*
* @param str1 - First string to compare
* @param str2 - Second string to compare
* @param threshold - Minimum similarity threshold (0.0 to 1.0)
* @returns Similarity score between 0.0 and 1.0, where 1.0 is exact match
*/
export declare function calculateStringSimilarity(str1: string, str2: string, threshold: number): number;
/**
* Calculates similarity between two numeric values with tolerance
*
* @param num1 - First number to compare
* @param num2 - Second number to compare
* @param tolerance - Acceptable tolerance for considering values similar (0.0 to 1.0)
* @returns Similarity score between 0.0 and 1.0, where 1.0 is exact match
*/
export declare function calculateNumericSimilarity(num1: number, num2: number, tolerance: number): number;
/**
* Simple client-side correlation function that matches entities based on a single field
* This function provides basic correlation without API calls
*
* @param primaryResults - Array of primary results (e.g., flows)
* @param secondaryResults - Array of secondary results (e.g., alarms)
* @param correlationField - Field name to correlate on (e.g., 'source_ip')
* @returns Array of correlated results with both primary and secondary data
*/
export declare function correlateResults(primaryResults: MappableEntity[], secondaryResults: MappableEntity[], correlationField: string): Array<{
primary: MappableEntity;
secondary: MappableEntity;
correlationType: 'exact' | 'fuzzy';
correlationScore: number;
}>;
//# sourceMappingURL=enhanced-correlation.d.ts.map