firewalla-mcp-server/dist/validation/field-mapper.d.ts

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

/**
 * Field Mapping Utilities for Cross-Reference Searches
 * Handles field compatibility between different Firewalla data types
 */
/**
 * Interface for entities that can be used in field mapping and correlation
 */
export type MappableEntity = Record<string, unknown>;
/**
 * Type for field values that can be used in correlations
 */
export type FieldValue = string | number | boolean | null | undefined;
import { type ScoredCorrelationResult, type EnhancedCorrelationStats, type CorrelationWeights, type FuzzyMatchConfig } from './enhanced-correlation.js';
export type EntityType = 'flows' | 'alarms' | 'rules' | 'devices' | 'target_lists';
/**
 * Valid correlation field names for type safety
 */
export type CorrelationFieldName = 'source_ip' | 'destination_ip' | 'device_ip' | 'device_id' | 'protocol' | 'bytes' | 'timestamp' | 'direction' | 'blocked' | 'gid' | 'subnet' | 'network_segment' | 'port' | 'port_range' | 'device_type' | 'device_vendor' | 'device_group' | 'mac_vendor' | 'device_category' | 'time_window' | 'hour_of_day' | 'day_of_week' | 'time_pattern' | 'country' | 'continent' | 'city' | 'region' | 'asn' | 'organization' | 'hosting_provider' | 'is_cloud_provider' | 'is_proxy' | 'is_vpn' | 'geographic_risk_score' | 'timezone' | 'isp' | 'user_agent' | 'application' | 'application_category' | 'domain_category' | 'ssl_subject' | 'ssl_issuer' | 'session_duration' | 'frequency_score' | 'bytes_per_session' | 'connection_pattern' | 'activity_level' | 'mac' | 'name' | 'vendor' | 'online' | 'last_seen' | 'network_id' | 'group_id' | 'severity' | 'alarm_type' | 'type' | 'resolution_status' | 'aid' | 'message_type' | 'category' | 'rule_category' | 'target_domain' | 'target_category' | 'action' | 'target_value' | 'creation_time' | 'last_hit' | 'hit_count' | 'rule_status' | 'direction' | 'policy_group' | 'owner' | 'target_count' | 'last_updated';
/**
 * Valid correlation operation types
 */
export type CorrelationType = 'AND' | 'OR';
/**
 * Valid time window units for temporal correlation
 */
export type TimeWindowUnit = 'seconds' | 'minutes' | 'hours' | 'days';
/**
 * Field mapping configuration for each entity type
 */
export declare const FIELD_MAPPINGS: Record<EntityType, Record<string, string[]>>;
/**
 * Common correlation fields that can be used across different entity types
 */
export declare const CORRELATION_FIELDS: Record<string, EntityType[]>;
/**
 * Returns the list of correlation fields that are supported by both specified entity types.
 *
 * @param primaryType - The first entity type to compare
 * @param secondaryType - The second entity type to compare
 * @returns An array of correlation field names compatible with both entity types
 */
/**
 * Gets the list of fields that are compatible between two entity types for correlation
 *
 * @param primaryType - The primary entity type to match against
 * @param secondaryType - The secondary entity type to match against
 * @returns Array of field names that can be used for correlation between the two types
 */
export declare function getCompatibleFields(primaryType: EntityType, secondaryType: EntityType): string[];
/**
 * Determines whether a correlation field is supported by all specified entity types.
 *
 * @param field - The correlation field to check
 * @param entityTypes - The list of entity types to validate against
 * @returns True if the field is supported by every entity type in the list; otherwise, false
 */
export declare function isFieldCompatible(field: string, entityTypes: EntityType[]): boolean;
/**
 * Determines whether a correlation field is suitable for cross-reference searches.
 * For cross-reference searches, the field needs to be supported by at least 2 entity types
 * (at least the primary and one secondary), not necessarily all entity types.
 *
 * @param field - The correlation field to check
 * @param entityTypes - The list of entity types to validate against
 * @returns True if the field is supported by at least 2 entity types; otherwise, false
 */
export declare function isFieldCompatibleForCrossReference(field: string, entityTypes: EntityType[]): boolean;
/**
 * Retrieves the value of a specified field from an entity object of a given type, using mapped field paths when available.
 *
 * If the field has mapped paths for the entity type, attempts each path in order and returns the first non-null, non-undefined value found. Falls back to direct field access if no mapping exists.
 *
 * @param entity - The entity object to extract the field value from
 * @param field - The standardized field name to retrieve
 * @param entityType - The type of the entity, used to determine field mappings
 * @returns The value of the field if found, otherwise `undefined`
 */
/**
 * Extracts the value of a field from an entity using entity-specific field mappings
 *
 * @param entity - The entity object to extract the field value from
 * @param field - The logical field name to extract
 * @param entityType - The type of entity to determine the correct field mapping
 * @returns The extracted field value, or undefined if not found
 */
export declare function getFieldValue(entity: MappableEntity, field: string, entityType: EntityType): FieldValue;
/**
 * Extracts unique correlation values from a collection of entities for a specific field
 *
 * Normalization ensures consistent comparison of values such as IP addresses, MAC addresses, and protocol names.
 *
 * @param results - Array of entities to extract values from
 * @param field - The field name to extract values for
 * @param entityType - The type of entities in the results array
 * @returns Set of unique field values found in the entities
 */
export declare function extractCorrelationValues(results: MappableEntity[], field: string, entityType: EntityType): Set<FieldValue>;
/**
 * Normalizes a field value for consistent comparison across different entities
 *
 * Trims and lowercases IP addresses, removes separators and lowercases MAC addresses,
 * lowercases protocol names, and returns other values unchanged.
 *
 * @param value - The field value to normalize
 * @param field - The field name (used to determine normalization strategy)
 * @returns The normalized field value suitable for comparison
 */
export declare function normalizeFieldValue(value: FieldValue, field: string): FieldValue;
/**
 * Returns entities whose normalized value for a specified correlation field matches any value in the provided set.
 *
 * Filters the input array to include only those entities where the normalized value of the given field is present in `correlationValues`.
 *
 * @param results - The array of entities to filter
 * @param field - The correlation field to evaluate
 * @param entityType - The type of entity being filtered
 * @param correlationValues - Set of normalized values to match against
 * @returns An array of entities matching the correlation criteria
 */
/**
 * Filters entities based on correlation values for a specific field
 *
 * @param results - Array of entities to filter
 * @param field - The field name to use for correlation
 * @param entityType - The type of entities in the results array
 * @param correlationValues - Set of values to match against
 * @returns Filtered array of entities that match the correlation values
 */
export declare function filterByCorrelation(results: MappableEntity[], field: string, entityType: EntityType, correlationValues: Set<FieldValue>): MappableEntity[];
/**
 * Suggests the most likely entity type for a query string based on the presence of keywords or field patterns.
 *
 * Returns the matching entity type if recognized, or defaults to 'flows' if no specific pattern is found.
 *
 * @param query - The input query string to analyze
 * @returns The suggested entity type, or null if no match is found
 */
export declare function suggestEntityType(query: string): EntityType | null;
/**
 * Validates parameters for a cross-reference search, ensuring queries and correlation field are present and compatible.
 *
 * Checks that the primary query, secondary queries, and correlation field are non-empty, suggests entity types for each query, and verifies that the correlation field is supported by all detected entity types.
 *
 * @param primaryQuery - The main search query string
 * @param secondaryQueries - An array of secondary search query strings
 * @param correlationField - The field name used for correlating entities
 * @returns An object indicating whether the parameters are valid, any error messages, and the detected entity types
 */
export declare function validateCrossReference(primaryQuery: string, secondaryQueries: string[], correlationField: string): {
    isValid: boolean;
    errors: string[];
    entityTypes?: EntityType[];
};
/**
 * Enhanced correlation parameters for multi-field correlation
 */
/**
 * Enhanced correlation parameters with strict type checking
 */
export interface EnhancedCorrelationParams {
    /** Array of correlation field names (must be valid CorrelationFieldName values) */
    correlationFields: CorrelationFieldName[];
    /** Type of correlation logic to apply */
    correlationType: CorrelationType;
    /** Optional temporal window for time-based correlation */
    temporalWindow?: {
        /** Size of the time window (must be positive) */
        windowSize: number;
        /** Unit of time for the window */
        windowUnit: TimeWindowUnit;
    };
    /** Optional network scope configuration */
    networkScope?: {
        /** Whether to include subnet-level matching */
        includeSubnets: boolean;
        /** Whether to include port-level matching */
        includePorts: boolean;
    };
    /** Optional device scope configuration */
    deviceScope?: {
        /** Whether to include vendor-level matching */
        includeVendor: boolean;
        /** Whether to include group-level matching */
        includeGroup: boolean;
    };
}
/**
 * Validates parameters for enhanced multi-field cross-reference search
 */
export declare function validateEnhancedCrossReference(primaryQuery: string, secondaryQueries: string[], correlationParams: EnhancedCorrelationParams): {
    isValid: boolean;
    errors: string[];
    entityTypes?: EntityType[];
};
/**
 * Perform multi-field correlation between entity results
 */
export declare function performMultiFieldCorrelation(primaryResults: MappableEntity[], secondaryResults: MappableEntity[], primaryType: EntityType, secondaryType: EntityType, correlationParams: EnhancedCorrelationParams): {
    correlatedResults: MappableEntity[];
    correlationStats: Record<string, unknown>;
    warnings?: string[];
};
/**
 * Get all supported correlation field combinations for a set of entity types
 */
export declare function getSupportedCorrelationCombinations(entityTypes: EntityType[]): string[][];
/**
 * Enhanced correlation parameters with scoring and fuzzy matching options
 */
export interface ScoringCorrelationParams extends EnhancedCorrelationParams {
    enableScoring?: boolean;
    enableFuzzyMatching?: boolean;
    minimumScore?: number;
    customWeights?: CorrelationWeights;
    fuzzyConfig?: FuzzyMatchConfig;
}
/**
 * Enhanced correlation result with scoring information
 */
export interface EnhancedCorrelationResult {
    correlatedResults: MappableEntity[];
    scoredResults?: ScoredCorrelationResult[];
    correlationStats: Record<string, unknown>;
    enhancedStats?: EnhancedCorrelationStats;
}
/**
 * Perform enhanced multi-field correlation with optional scoring and fuzzy matching
 * This extends the existing performMultiFieldCorrelation with advanced capabilities
 */
export declare function performEnhancedMultiFieldCorrelation(primaryResults: MappableEntity[], secondaryResults: MappableEntity[], primaryType: EntityType, secondaryType: EntityType, correlationParams: ScoringCorrelationParams): EnhancedCorrelationResult;
//# sourceMappingURL=field-mapper.d.ts.map