@sentriflow/core 0.1.0

package/src/helpers/common/helpers.ts

@@ -0,0 +1,265 @@
+// packages/rule-helpers/src/common/helpers.ts
+// Common helper functions used across vendor-specific rules
+
+import type { ConfigNode } from '../../types/ConfigNode';
+
+// Re-export validation helpers for convenience
+export {
+  equalsIgnoreCase,
+  includesIgnoreCase,
+  startsWithIgnoreCase,
+  parseInteger,
+  isInRange,
+  parsePort,
+  isValidPort,
+  parsePortRange,
+  parseVlanId,
+  isValidVlanId,
+  isDefaultVlan,
+  isReservedVlan,
+  isFeatureEnabled,
+  isFeatureDisabled,
+  isValidMacAddress,
+  normalizeMacAddress,
+  parseCidr,
+  isIpInNetwork,
+  isIpInCidr,
+  type CidrInfo,
+} from './validation';
+
+/**
+ * Parse an IP address string to a 32-bit unsigned integer.
+ * @param addr The IP address string (e.g., "10.0.0.1")
+ * @returns The IP as a 32-bit unsigned number, or null if invalid
+ */
+export const parseIp = (addr: string): number | null => {
+  const parts = addr.split('.').map(Number);
+  if (parts.length !== 4 || parts.some((p) => isNaN(p) || p < 0 || p > 255)) {
+    return null;
+  }
+  // Safe: we verified parts.length === 4 above
+  const [p0, p1, p2, p3] = parts as [number, number, number, number];
+  return ((p0 << 24) | (p1 << 16) | (p2 << 8) | p3) >>> 0;
+};
+
+/**
+ * Convert a 32-bit unsigned integer to an IP address string.
+ * @param num The IP as a 32-bit unsigned number
+ * @returns The IP address string
+ */
+export const numToIp = (num: number): string => {
+  return [
+    (num >>> 24) & 255,
+    (num >>> 16) & 255,
+    (num >>> 8) & 255,
+    num & 255,
+  ].join('.');
+};
+
+/**
+ * Parse a CIDR prefix length to a subnet mask number.
+ * @param prefix The prefix length (e.g., 24)
+ * @returns The subnet mask as a 32-bit unsigned number
+ */
+export const prefixToMask = (prefix: number): number => {
+  if (prefix < 0 || prefix > 32) return 0;
+  return prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+};
+
+/**
+ * Convert a subnet mask to CIDR prefix length.
+ * @param mask The subnet mask as a 32-bit unsigned number
+ * @returns The prefix length
+ */
+export const maskToPrefix = (mask: number): number => {
+  let count = 0;
+  let m = mask;
+  while (m & 0x80000000) {
+    count++;
+    m <<= 1;
+  }
+  return count;
+};
+
+/**
+ * Check if a node has a specific child command (case-insensitive prefix match).
+ * @param node The parent ConfigNode
+ * @param prefix The command prefix to search for
+ * @returns true if a matching child exists
+ */
+export const hasChildCommand = (node: ConfigNode, prefix: string): boolean => {
+  return node.children.some((child) =>
+    child.id.toLowerCase().startsWith(prefix.toLowerCase())
+  );
+};
+
+/**
+ * Get a child command's node if it exists.
+ * @param node The parent ConfigNode
+ * @param prefix The command prefix to search for
+ * @returns The matching child node, or undefined
+ */
+export const getChildCommand = (
+  node: ConfigNode,
+  prefix: string
+): ConfigNode | undefined => {
+  return node.children.find((child) =>
+    child.id.toLowerCase().startsWith(prefix.toLowerCase())
+  );
+};
+
+/**
+ * Get all child commands matching a prefix.
+ * @param node The parent ConfigNode
+ * @param prefix The command prefix to search for
+ * @returns Array of matching child nodes
+ */
+export const getChildCommands = (
+  node: ConfigNode,
+  prefix: string
+): ConfigNode[] => {
+  return node.children.filter((child) =>
+    child.id.toLowerCase().startsWith(prefix.toLowerCase())
+  );
+};
+
+/**
+ * Check if a value is a valid IP address string.
+ * @param value The string to check
+ * @returns true if it's a valid IP address
+ */
+export const isValidIpAddress = (value: string): boolean => {
+  return parseIp(value) !== null;
+};
+
+/**
+ * Check if an IP is in the multicast range (224.0.0.0 - 239.255.255.255).
+ * @param ipNum The IP as a 32-bit unsigned number
+ * @returns true if it's a multicast address
+ */
+export const isMulticastAddress = (ipNum: number): boolean => {
+  const firstOctet = ipNum >>> 24;
+  return firstOctet >= 224 && firstOctet <= 239;
+};
+
+/**
+ * Check if an IP is the global broadcast address (255.255.255.255).
+ * @param ipNum The IP as a 32-bit unsigned number
+ * @returns true if it's the broadcast address
+ */
+export const isBroadcastAddress = (ipNum: number): boolean => {
+  return ipNum === 0xffffffff;
+};
+
+/**
+ * Check if an IP is a private address (RFC 1918).
+ * @param ipNum The IP as a 32-bit unsigned number
+ * @returns true if it's a private address
+ */
+export const isPrivateAddress = (ipNum: number): boolean => {
+  // 10.0.0.0/8
+  if ((ipNum & 0xff000000) >>> 0 === 0x0a000000) return true;
+  // 172.16.0.0/12
+  if ((ipNum & 0xfff00000) >>> 0 === 0xac100000) return true;
+  // 192.168.0.0/16
+  if ((ipNum & 0xffff0000) >>> 0 === 0xc0a80000) return true;
+  return false;
+};
+
+/**
+ * Extract a parameter value from a node's params array.
+ * @param node The ConfigNode
+ * @param keyword The keyword to find
+ * @returns The value after the keyword, or undefined
+ */
+export const getParamValue = (
+  node: ConfigNode,
+  keyword: string
+): string | undefined => {
+  const idx = node.params.findIndex(
+    (p) => p.toLowerCase() === keyword.toLowerCase()
+  );
+  if (idx >= 0 && idx < node.params.length - 1) {
+    return node.params[idx + 1];
+  }
+  return undefined;
+};
+
+/**
+ * Check if an interface is administratively shutdown.
+ * Works for both Cisco ("shutdown") and Juniper ("disable") syntax.
+ * @param node The interface ConfigNode
+ * @returns true if the interface is shutdown/disabled
+ */
+export const isShutdown = (node: ConfigNode): boolean => {
+  return node.children.some((child) => {
+    const id = child.id.toLowerCase().trim();
+    return id === 'shutdown' || id === 'disable';
+  });
+};
+
+/**
+ * Check if a node is an actual interface definition (not a reference or sub-command).
+ * Interface definitions are top-level sections that define physical/logical interfaces.
+ *
+ * This helper distinguishes real interface definitions from:
+ * - Interface references inside protocol blocks (OSPF, LLDP, etc.)
+ * - Sub-commands like "interface-type", "interface-mode"
+ * - Generic references like "interface all"
+ *
+ * @param node The ConfigNode to check
+ * @returns true if this is an actual interface definition
+ */
+export const isInterfaceDefinition = (node: ConfigNode): boolean => {
+  const id = node.id.toLowerCase();
+
+  // Must be a section type (has children or is a block)
+  if (node.type !== 'section') {
+    return false;
+  }
+
+  // Must start with exactly "interface " followed by interface name
+  if (!id.startsWith('interface ')) {
+    return false;
+  }
+
+  // Skip "interface-type", "interface-mode", etc. (compound words)
+  if (id.startsWith('interface-')) {
+    return false;
+  }
+
+  // Get the interface name part
+  const ifName = id.slice('interface '.length).trim();
+
+  // Skip generic references like "interface all" (LLDP/CDP config)
+  if (ifName === 'all' || ifName === 'default') {
+    return false;
+  }
+
+  // For Juniper: interface references inside protocols/routing don't have meaningful children
+  // Real interface definitions in "interfaces { }" block have unit, family, etc.
+  // References inside ospf/lldp/etc. typically have no children or just simple options
+  // Check if this looks like a Juniper interface reference (inside protocols block)
+  // These typically have 0-1 children with simple options like "passive" or "interface-type"
+  if (node.children.length <= 1) {
+    const hasOnlySimpleChild = node.children.every((child) => {
+      const childId = child.id.toLowerCase();
+      return (
+        childId === 'passive' ||
+        childId.startsWith('interface-type') ||
+        childId.startsWith('metric') ||
+        childId.startsWith('hello-interval') ||
+        childId.startsWith('dead-interval') ||
+        childId.startsWith('priority') ||
+        childId.startsWith('authentication') ||
+        childId.startsWith('bfd-liveness')
+      );
+    });
+    // If only simple OSPF/routing options, this is likely a reference, not a definition
+    if (hasOnlySimpleChild && node.children.length > 0) {
+      return false;
+    }
+  }
+
+  return true;
+};

package/src/helpers/common/index.ts

@@ -0,0 +1,5 @@
+// packages/rule-helpers/src/common/index.ts
+// Re-export all common helpers
+
+export * from './helpers';
+export * from './validation';

package/src/helpers/common/validation.ts

@@ -0,0 +1,280 @@
+// packages/rule-helpers/src/common/validation.ts
+// Centralized validation helpers for network configuration rules
+
+import { parseIp, prefixToMask } from './helpers';
+
+// ============================================================================
+// String Comparison Helpers
+// ============================================================================
+
+/**
+ * Case-insensitive string equality check.
+ * @param a First string
+ * @param b Second string
+ * @returns true if strings are equal (case-insensitive)
+ */
+export const equalsIgnoreCase = (a: string, b: string): boolean =>
+  a.toLowerCase() === b.toLowerCase();
+
+/**
+ * Case-insensitive substring check.
+ * @param haystack String to search in
+ * @param needle String to search for
+ * @returns true if needle is found (case-insensitive)
+ */
+export const includesIgnoreCase = (haystack: string, needle: string): boolean =>
+  haystack.toLowerCase().includes(needle.toLowerCase());
+
+/**
+ * Case-insensitive prefix check.
+ * @param str String to check
+ * @param prefix Prefix to match
+ * @returns true if str starts with prefix (case-insensitive)
+ */
+export const startsWithIgnoreCase = (str: string, prefix: string): boolean =>
+  str.toLowerCase().startsWith(prefix.toLowerCase());
+
+// ============================================================================
+// Numeric Validation Helpers
+// ============================================================================
+
+/**
+ * Parse a string to integer, returning null if invalid.
+ * @param value String to parse
+ * @returns Parsed integer or null if invalid
+ */
+export const parseInteger = (value: string): number | null => {
+  const num = parseInt(value, 10);
+  return isNaN(num) ? null : num;
+};
+
+/**
+ * Check if a number is within a range (inclusive).
+ * @param value Number to check
+ * @param min Minimum value (inclusive)
+ * @param max Maximum value (inclusive)
+ * @returns true if value is in range
+ */
+export const isInRange = (value: number, min: number, max: number): boolean =>
+  value >= min && value <= max;
+
+/**
+ * Parse and validate a port number (1-65535).
+ * @param value Port string to parse
+ * @returns Port number or null if invalid
+ */
+export const parsePort = (value: string): number | null => {
+  const port = parseInteger(value);
+  if (port === null || port < 1 || port > 65535) return null;
+  return port;
+};
+
+/**
+ * Check if a port number is valid (1-65535).
+ * @param port Port number to validate
+ * @returns true if valid port
+ */
+export const isValidPort = (port: number): boolean =>
+  Number.isInteger(port) && port >= 1 && port <= 65535;
+
+/**
+ * Parse a port range string (e.g., "1-24", "80,443", "1-10,20,30-32").
+ * @param portStr Port range string
+ * @returns Array of individual port numbers (empty array if no valid ports found)
+ */
+export const parsePortRange = (portStr: string): number[] => {
+  const ports: number[] = [];
+  const parts = portStr.split(',');
+
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed.includes('-')) {
+      const rangeParts = trimmed.split('-').map((p) => parseInt(p.trim(), 10));
+      const start = rangeParts[0];
+      const end = rangeParts[1];
+      if (start !== undefined && end !== undefined && !isNaN(start) && !isNaN(end)) {
+        for (let i = start; i <= end; i++) {
+          ports.push(i);
+        }
+      }
+    } else {
+      const num = parseInt(trimmed, 10);
+      if (!isNaN(num)) {
+        ports.push(num);
+      }
+    }
+  }
+
+  return ports;
+};
+
+// ============================================================================
+// VLAN Validation Helpers
+// ============================================================================
+
+/**
+ * Parse a VLAN ID string to number.
+ * @param vlanStr VLAN ID string
+ * @returns VLAN number or null if invalid
+ */
+export const parseVlanId = (vlanStr: string): number | null => {
+  const vlan = parseInteger(vlanStr);
+  if (vlan === null || vlan < 1 || vlan > 4094) return null;
+  return vlan;
+};
+
+/**
+ * Check if a VLAN ID is valid (1-4094).
+ * @param vlanId VLAN ID to validate
+ * @returns true if valid VLAN ID
+ */
+export const isValidVlanId = (vlanId: number): boolean =>
+  Number.isInteger(vlanId) && vlanId >= 1 && vlanId <= 4094;
+
+/**
+ * Check if VLAN is the default VLAN (VLAN 1).
+ * @param vlanId VLAN ID string or number
+ * @returns true if VLAN 1
+ */
+export const isDefaultVlan = (vlanId: string | number): boolean => {
+  const id = typeof vlanId === 'string' ? parseInteger(vlanId) : vlanId;
+  return id === 1;
+};
+
+/**
+ * Check if VLAN is in the reserved range (1002-1005 for Cisco).
+ * @param vlanId VLAN ID
+ * @returns true if in reserved range
+ */
+export const isReservedVlan = (vlanId: number): boolean =>
+  vlanId >= 1002 && vlanId <= 1005;
+
+// ============================================================================
+// Feature State Helpers
+// ============================================================================
+
+/**
+ * Check if a feature value represents "enabled" state.
+ * Handles common variations: "enable", "enabled", "yes", "true", "on", "1"
+ * @param value Feature state string
+ * @returns true if enabled
+ */
+export const isFeatureEnabled = (value: string | undefined): boolean => {
+  if (!value) return false;
+  const normalized = value.toLowerCase().trim();
+  return ['enable', 'enabled', 'yes', 'true', 'on', '1'].includes(normalized);
+};
+
+/**
+ * Check if a feature value represents "disabled" state.
+ * Handles common variations: "disable", "disabled", "no", "false", "off", "0"
+ * @param value Feature state string
+ * @returns true if disabled
+ */
+export const isFeatureDisabled = (value: string | undefined): boolean => {
+  if (!value) return false;
+  const normalized = value.toLowerCase().trim();
+  return ['disable', 'disabled', 'no', 'false', 'off', '0'].includes(normalized);
+};
+
+// ============================================================================
+// MAC Address Validation Helpers
+// ============================================================================
+
+/**
+ * Validate MAC address format.
+ * Supports: XX:XX:XX:XX:XX:XX, XX-XX-XX-XX-XX-XX, XXXX.XXXX.XXXX
+ * @param mac MAC address string
+ * @returns true if valid MAC format
+ */
+export const isValidMacAddress = (mac: string): boolean => {
+  // Colon-separated (Linux/Unix style)
+  if (/^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/.test(mac)) return true;
+  // Hyphen-separated (Windows style)
+  if (/^([0-9A-Fa-f]{2}-){5}[0-9A-Fa-f]{2}$/.test(mac)) return true;
+  // Dot-separated (Cisco style)
+  if (/^([0-9A-Fa-f]{4}\.){2}[0-9A-Fa-f]{4}$/.test(mac)) return true;
+  return false;
+};
+
+/**
+ * Normalize MAC address to lowercase colon-separated format.
+ * @param mac MAC address in any supported format
+ * @returns Normalized MAC or null if invalid
+ */
+export const normalizeMacAddress = (mac: string): string | null => {
+  if (!isValidMacAddress(mac)) return null;
+
+  // Remove all separators and convert to lowercase
+  const hex = mac.replace(/[:\-.]/g, '').toLowerCase();
+
+  // Insert colons every 2 characters
+  const matched = hex.match(/.{2}/g);
+  return matched ? matched.join(':') : null;
+};
+
+// ============================================================================
+// CIDR/Subnet Validation Helpers
+// ============================================================================
+
+/**
+ * Result of parsing CIDR notation.
+ */
+export interface CidrInfo {
+  /** Network address as 32-bit unsigned number */
+  network: number;
+  /** CIDR prefix length (0-32) */
+  prefix: number;
+  /** Subnet mask as 32-bit unsigned number */
+  mask: number;
+}
+
+/**
+ * Parse CIDR notation (e.g., "10.0.0.0/24").
+ * @param cidr CIDR string
+ * @returns Object with network, prefix, mask or null if invalid
+ */
+export const parseCidr = (cidr: string): CidrInfo | null => {
+  const parts = cidr.split('/');
+  if (parts.length !== 2) return null;
+
+  const ipPart = parts[0];
+  const prefixPart = parts[1];
+
+  if (!ipPart || !prefixPart) return null;
+
+  const network = parseIp(ipPart);
+  const prefix = parseInteger(prefixPart);
+
+  if (network === null || prefix === null) return null;
+  if (prefix < 0 || prefix > 32) return null;
+
+  const mask = prefixToMask(prefix);
+
+  return { network, prefix, mask };
+};
+
+/**
+ * Check if an IP is within a CIDR block.
+ * @param ip IP address (as 32-bit number)
+ * @param network Network address (as 32-bit number)
+ * @param mask Subnet mask (as 32-bit number)
+ * @returns true if IP is in the network
+ */
+export const isIpInNetwork = (ip: number, network: number, mask: number): boolean =>
+  (ip & mask) === (network & mask);
+
+/**
+ * Check if an IP string is within a CIDR block string.
+ * @param ipStr IP address string
+ * @param cidrStr CIDR notation string
+ * @returns true if IP is in the CIDR block, false if invalid or not in range
+ */
+export const isIpInCidr = (ipStr: string, cidrStr: string): boolean => {
+  const ip = parseIp(ipStr);
+  const cidr = parseCidr(cidrStr);
+
+  if (ip === null || cidr === null) return false;
+
+  return isIpInNetwork(ip, cidr.network, cidr.mask);
+};