@sentriflow/core 0.1.8 → 0.2.0

package/README.md

@@ -19,6 +19,7 @@ bun add @sentriflow/core
 - **Multi-vendor support**: Cisco IOS/NX-OS, Juniper JunOS, Arista EOS, Fortinet FortiGate, Palo Alto PAN-OS, and more
 - **AST-based parsing**: Converts configurations into a vendor-agnostic Abstract Syntax Tree
 - **Extensible rule engine**: Define compliance rules for best practices or organization-specific policies
+- **IP/Subnet Extraction**: Extract and deduplicate IP addresses and CIDR subnets from configurations
 - **TypeScript native**: Full type safety with comprehensive type definitions
 
 ## Supported Vendors
@@ -75,6 +76,34 @@ Checks an AST for compliance against a set of rules.
 
 Auto-detects the vendor/platform from configuration content.
 
+### `extractIPSummary(content: string, options?: ExtractOptions): IPSummary`
+
+Extracts all IP addresses and subnets from configuration text.
+
+```typescript
+import { extractIPSummary } from '@sentriflow/core';
+
+const config = `
+interface GigabitEthernet0/1
+  ip address 192.168.1.1 255.255.255.0
+  ip route 10.0.0.0/24 via 192.168.1.254
+`;
+
+const summary = extractIPSummary(config);
+// {
+//   ipv4Addresses: ['192.168.1.1', '192.168.1.254'],
+//   ipv6Addresses: [],
+//   ipv4Subnets: ['10.0.0.0/24'],
+//   ipv6Subnets: [],
+//   counts: { total: 3, ipv4: 2, ipv6: 0, ipv4Subnets: 1, ipv6Subnets: 0 }
+// }
+```
+
+**Options:**
+- `maxContentSize`: Maximum input size in bytes (default: 50MB) - prevents DoS
+- `includeSubnetNetworks`: Include subnet network addresses in address lists
+- `skipIPv4`, `skipIPv6`, `skipSubnets`: Skip specific extraction types
+
 ## Related Packages
 
 - [`@sentriflow/cli`](https://github.com/sentriflow/sentriflow/tree/main/packages/cli) - Command-line interface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentriflow/core",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "SentriFlow core engine for network configuration validation",
   "license": "Apache-2.0",
   "module": "src/index.ts",

package/src/ip/extractor.ts

@@ -1,6 +1,78 @@
 // packages/core/src/ip/extractor.ts
 
 import type { IPAddressType, IPSummary, IPCounts, ExtractOptions } from './types';
+import { InputValidationError, DEFAULT_MAX_CONTENT_SIZE } from './types';
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Strip zone ID from IPv6 address.
+ * e.g., "fe80::1%eth0" -> "fe80::1"
+ *
+ * @param ip - IPv6 address string (with or without zone ID)
+ * @returns IPv6 address without zone ID
+ */
+function stripZoneId(ip: string): string {
+  const zoneIndex = ip.indexOf('%');
+  return zoneIndex !== -1 ? ip.substring(0, zoneIndex) : ip;
+}
+
+// ============================================================================
+// Regex Factory Functions
+// ============================================================================
+
+/**
+ * Create IPv4 pattern regex.
+ * Using factory function prevents lastIndex state issues with global flag.
+ */
+function createIPv4Pattern(): RegExp {
+  return /\b(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\b/g;
+}
+
+/**
+ * Create IPv4 CIDR pattern regex.
+ */
+function createIPv4CidrPattern(): RegExp {
+  return /\b(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\/(?:3[0-2]|[12]?[0-9])\b/g;
+}
+
+/**
+ * Create IPv4 + subnet mask pattern regex.
+ */
+function createIPv4WithMaskPattern(): RegExp {
+  return /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+(255\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/g;
+}
+
+/**
+ * Create IPv4 + "mask" keyword + subnet mask pattern regex.
+ */
+function createIPv4WithMaskKeywordPattern(): RegExp {
+  return /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+mask\s+(255\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/gi;
+}
+
+/**
+ * Create IPv4 + wildcard mask pattern regex.
+ */
+function createIPv4WithWildcardPattern(): RegExp {
+  return /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+(0\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/g;
+}
+
+/**
+ * Create IPv6 pattern regex.
+ */
+function createIPv6Pattern(): RegExp {
+  return /(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|:(?::[0-9a-fA-F]{1,4}){1,7}|(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|(?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|(?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:(?::[0-9a-fA-F]{1,4}){1,6}|(?:[0-9a-fA-F]{1,4}:){1,7}:|::/g;
+}
+
+/**
+ * Create IPv6 CIDR pattern regex.
+ * Uses negative lookahead (?!\d) to prevent matching partial prefixes like /12 from /129
+ */
+function createIPv6CidrPattern(): RegExp {
+  return /(?:(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|:(?::[0-9a-fA-F]{1,4}){1,7}|(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|(?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|(?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:(?::[0-9a-fA-F]{1,4}){1,6}|(?:[0-9a-fA-F]{1,4}:){1,7}:|::)\/(?:12[0-8]|1[01][0-9]|[1-9]?[0-9])(?!\d)/g;
+}
 
 // ============================================================================
 // Validation Functions
@@ -42,11 +114,7 @@ export function isValidIPv6(ip: string): boolean {
   if (!ip || typeof ip !== 'string') return false;
 
   // Strip zone ID if present (e.g., fe80::1%eth0)
-  let addr = ip;
-  const zoneIndex = ip.indexOf('%');
-  if (zoneIndex !== -1) {
-    addr = ip.substring(0, zoneIndex);
-  }
+  const addr = stripZoneId(ip);
 
   // Must have at least one colon
   if (!addr.includes(':')) return false;
@@ -144,14 +212,8 @@ export function normalizeIPv4(ip: string): string {
  * @returns Normalized IPv6 string (lowercase, no zone ID, fully expanded)
  */
 export function normalizeIPv6(ip: string): string {
-  // Strip zone ID
-  let addr = ip;
-  const zoneIndex = ip.indexOf('%');
-  if (zoneIndex !== -1) {
-    addr = ip.substring(0, zoneIndex);
-  }
-
-  addr = addr.toLowerCase();
+  // Strip zone ID and convert to lowercase
+  const addr = stripZoneId(ip).toLowerCase();
 
   // Handle :: expansion
   if (addr.includes('::')) {
@@ -199,11 +261,31 @@ export function normalizeIPv6(ip: string): string {
 // Comparison Functions
 // ============================================================================
 
+/**
+ * Validate and clamp octet value to valid range.
+ * T019/T020/T021: Defensive bounds checking for IPv4 octets.
+ *
+ * @param n - Raw number value
+ * @returns Valid octet value (0-255), clamped if out of range
+ */
+function clampOctet(n: number): number {
+  // T021: Check if value is an integer
+  if (!Number.isInteger(n)) {
+    return 0;
+  }
+  // T019/T020: Clamp to valid octet range
+  if (n < 0 || n > 255) {
+    return 0;
+  }
+  return n;
+}
+
 /**
  * Convert IPv4 to 32-bit number for comparison.
+ * Uses defensive octet validation to handle malformed input.
  */
 function ipv4ToNumber(ip: string): number {
-  const octets = ip.split('.').map(Number);
+  const octets = ip.split('.').map((n) => clampOctet(Number(n)));
   const o0 = octets[0] ?? 0;
   const o1 = octets[1] ?? 0;
   const o2 = octets[2] ?? 0;
@@ -227,12 +309,7 @@ export function compareIPv4(a: string, b: string): number {
  */
 function expandIPv6(ip: string): string[] {
   // Strip zone ID
-  let addr = ip;
-  const zoneIndex = ip.indexOf('%');
-  if (zoneIndex !== -1) {
-    addr = ip.substring(0, zoneIndex);
-  }
-
+  const addr = stripZoneId(ip);
   const parts = addr.split(':');
   const result: string[] = [];
 
@@ -315,12 +392,37 @@ export function sortIPv6Addresses(ips: string[]): string[] {
 
 /**
  * Parse subnet into network and prefix.
+ * T016/T017/T018: Validates format before parsing.
+ *
+ * @param subnet - CIDR notation string (e.g., "10.0.0.0/24")
+ * @returns Parsed network address and prefix length
+ * @throws InputValidationError if format is invalid
  */
 function parseSubnet(subnet: string): { network: string; prefix: number } {
   const slashIndex = subnet.lastIndexOf('/');
+
+  // T016: Validate slash presence
+  if (slashIndex === -1) {
+    throw new InputValidationError(
+      `Invalid subnet format (missing /): ${subnet}`,
+      'INVALID_FORMAT'
+    );
+  }
+
+  const prefixStr = subnet.substring(slashIndex + 1);
+  const prefix = parseInt(prefixStr, 10);
+
+  // T017: Validate prefix is a valid number
+  if (isNaN(prefix)) {
+    throw new InputValidationError(
+      `Invalid subnet prefix: ${prefixStr}`,
+      'INVALID_FORMAT'
+    );
+  }
+
   return {
     network: subnet.substring(0, slashIndex),
-    prefix: parseInt(subnet.substring(slashIndex + 1), 10),
+    prefix,
   };
 }
 
@@ -449,39 +551,6 @@ function wildcardToCidr(wildcard: string): number {
   return prefix;
 }
 
-// IPv4 pattern: 4 octets, each 0-255, no leading zeros
-const IPV4_PATTERN =
-  /\b(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\b/g;
-
-// IPv4 CIDR pattern
-const IPV4_CIDR_PATTERN =
-  /\b(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\/(?:3[0-2]|[12]?[0-9])\b/g;
-
-// IPv4 + subnet mask pattern (e.g., "ip address 192.168.1.1 255.255.255.0")
-// Captures IP address followed by space and subnet mask
-const IPV4_WITH_MASK_PATTERN =
-  /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+(255\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/g;
-
-// IPv4 + "mask" keyword + subnet mask pattern (e.g., "network 192.168.1.0 mask 255.255.255.0" in BGP)
-// Captures IP address followed by "mask" keyword and subnet mask
-const IPV4_WITH_MASK_KEYWORD_PATTERN =
-  /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+mask\s+(255\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/gi;
-
-// IPv4 + wildcard mask pattern (e.g., "access-list 10 permit 192.168.1.0 0.0.0.255")
-// Captures network address followed by space and wildcard mask
-const IPV4_WITH_WILDCARD_PATTERN =
-  /\b((?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\s+(0\.(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){2}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))\b/g;
-
-// IPv6 pattern - matches most common formats
-// Order matters: longer patterns first to prevent partial matching
-const IPV6_PATTERN =
-  /(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|:(?::[0-9a-fA-F]{1,4}){1,7}|(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|(?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|(?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:(?::[0-9a-fA-F]{1,4}){1,6}|(?:[0-9a-fA-F]{1,4}:){1,7}:|::/g;
-
-// IPv6 CIDR pattern - matches IPv6/prefix notation
-// Order matters: longer patterns first
-const IPV6_CIDR_PATTERN =
-  /(?:(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|:(?::[0-9a-fA-F]{1,4}){1,7}|(?:[0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|(?:[0-9a-fA-F]{1,4}:){1,5}(?::[0-9a-fA-F]{1,4}){1,2}|(?:[0-9a-fA-F]{1,4}:){1,4}(?::[0-9a-fA-F]{1,4}){1,3}|(?:[0-9a-fA-F]{1,4}:){1,3}(?::[0-9a-fA-F]{1,4}){1,4}|(?:[0-9a-fA-F]{1,4}:){1,2}(?::[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:(?::[0-9a-fA-F]{1,4}){1,6}|(?:[0-9a-fA-F]{1,4}:){1,7}:|::)\/(?:12[0-8]|1[01][0-9]|[1-9]?[0-9])/g;
-
 /**
  * Create an empty IP summary.
  */
@@ -513,6 +582,15 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
     return createEmptyIPSummary();
   }
 
+  // T011/T012: Validate content size to prevent DoS via memory exhaustion
+  const maxSize = options.maxContentSize ?? DEFAULT_MAX_CONTENT_SIZE;
+  if (content.length > maxSize) {
+    throw new InputValidationError(
+      `Content exceeds maximum size of ${maxSize} bytes`,
+      'SIZE_LIMIT_EXCEEDED'
+    );
+  }
+
   const ipv4Set = new Set<string>();
   const ipv6Set = new Set<string>();
   const ipv4SubnetSet = new Set<string>();
@@ -527,7 +605,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
   // Extract IPv4 subnets first (so we can exclude their network addresses from standalone IPs)
   if (!options.skipSubnets) {
     // Extract CIDR notation subnets (e.g., 10.0.0.0/24)
-    const ipv4CidrMatches = content.matchAll(IPV4_CIDR_PATTERN);
+    const ipv4CidrMatches = content.matchAll(createIPv4CidrPattern());
     for (const match of ipv4CidrMatches) {
       const subnet = match[0];
       if (isValidSubnet(subnet)) {
@@ -540,7 +618,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
 
     // Extract IP + mask pairs (e.g., "192.168.1.1 255.255.255.0")
     // These are interface addresses with their subnet info
-    const ipMaskMatches = content.matchAll(IPV4_WITH_MASK_PATTERN);
+    const ipMaskMatches = content.matchAll(createIPv4WithMaskPattern());
     for (const match of ipMaskMatches) {
       const ip = match[1];
       const mask = match[2];
@@ -556,7 +634,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
     }
 
     // Extract IP + "mask" + mask pairs (e.g., "network 10.0.0.0 mask 255.0.0.0" in BGP)
-    const ipMaskKeywordMatches = content.matchAll(IPV4_WITH_MASK_KEYWORD_PATTERN);
+    const ipMaskKeywordMatches = content.matchAll(createIPv4WithMaskKeywordPattern());
     for (const match of ipMaskKeywordMatches) {
       const ip = match[1];
       const mask = match[2];
@@ -573,7 +651,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
 
     // Extract IP + wildcard pairs (e.g., "192.168.1.0 0.0.0.255" in ACLs)
     // These define network ranges in access lists
-    const ipWildcardMatches = content.matchAll(IPV4_WITH_WILDCARD_PATTERN);
+    const ipWildcardMatches = content.matchAll(createIPv4WithWildcardPattern());
     for (const match of ipWildcardMatches) {
       const ip = match[1];
       const wildcard = match[2];
@@ -590,7 +668,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
   }
 
   // Extract IPv4 addresses (excluding those that are subnet network addresses)
-  const ipv4Matches = content.matchAll(IPV4_PATTERN);
+  const ipv4Matches = content.matchAll(createIPv4Pattern());
   for (const match of ipv4Matches) {
     const ip = match[0];
     if (isValidIPv4(ip)) {
@@ -615,7 +693,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
   if (!options.skipIPv6) {
     // Extract IPv6 subnets first
     if (!options.skipSubnets) {
-      const ipv6CidrMatches = content.matchAll(IPV6_CIDR_PATTERN);
+      const ipv6CidrMatches = content.matchAll(createIPv6CidrPattern());
       for (const match of ipv6CidrMatches) {
         const subnet = match[0];
         if (isValidSubnet(subnet)) {
@@ -628,7 +706,7 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
     }
 
     // Extract IPv6 addresses
-    const ipv6Matches = content.matchAll(IPV6_PATTERN);
+    const ipv6Matches = content.matchAll(createIPv6Pattern());
     for (const match of ipv6Matches) {
       const ip = match[0];
       if (isValidIPv6(ip)) {
@@ -640,6 +718,18 @@ export function extractIPSummary(content: string, options: ExtractOptions = {}):
     }
   }
 
+  // If includeSubnetNetworks is true, add subnet network addresses to the address sets
+  if (options.includeSubnetNetworks) {
+    for (const subnet of ipv4SubnetSet) {
+      const { network } = parseSubnet(subnet);
+      ipv4Set.add(network);
+    }
+    for (const subnet of ipv6SubnetSet) {
+      const { network } = parseSubnet(subnet);
+      ipv6Set.add(network);
+    }
+  }
+
   // Convert sets to sorted arrays
   const ipv4Addresses = sortIPv4Addresses([...ipv4Set]);
   const ipv6Addresses = sortIPv6Addresses([...ipv6Set]);

package/src/ip/index.ts

@@ -21,4 +21,7 @@ export type {
   IPSummary,
   IPCounts,
   ExtractOptions,
+  InputValidationErrorCode,
 } from './types';
+
+export { InputValidationError, DEFAULT_MAX_CONTENT_SIZE } from './types';

package/src/ip/types.ts

@@ -1,5 +1,42 @@
 // packages/core/src/ip/types.ts
 
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Default maximum content size for IP extraction (50MB).
+ * Prevents DoS attacks via memory exhaustion from processing very large files.
+ */
+export const DEFAULT_MAX_CONTENT_SIZE = 50 * 1024 * 1024; // 50MB
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error codes for input validation failures.
+ */
+export type InputValidationErrorCode = 'SIZE_LIMIT_EXCEEDED' | 'INVALID_FORMAT';
+
+/**
+ * Error thrown when input validation fails.
+ * Used for size limits and malformed input detection.
+ */
+export class InputValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly code: InputValidationErrorCode
+  ) {
+    super(message);
+    this.name = 'InputValidationError';
+  }
+}
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
 /**
  * Discriminator for IPv4 vs IPv6 addresses.
  */
@@ -97,4 +134,18 @@ export interface ExtractOptions {
    * @default false
    */
   skipSubnets?: boolean;
+
+  /**
+   * Include subnet network addresses in the addresses lists.
+   * When true, a subnet like 10.0.0.0/24 will add 10.0.0.0 to ipv4Addresses.
+   * @default false
+   */
+  includeSubnetNetworks?: boolean;
+
+  /**
+   * Maximum content size in bytes.
+   * Content exceeding this limit will throw InputValidationError.
+   * @default DEFAULT_MAX_CONTENT_SIZE (50MB)
+   */
+  maxContentSize?: number;
 }

package/src/json-rules/schema.json

@@ -135,6 +135,41 @@
         },
         "security": {
           "$ref": "#/definitions/SecurityMetadata"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/Tag" },
+          "description": "Typed tags for multi-dimensional rule categorization"
+        }
+      }
+    },
+    "TagType": {
+      "type": "string",
+      "enum": ["security", "operational", "compliance", "general"],
+      "description": "Tag classification type"
+    },
+    "Tag": {
+      "type": "object",
+      "required": ["type", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/TagType"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short identifier/label for the tag"
+        },
+        "text": {
+          "type": "string",
+          "description": "Optional extended description"
+        },
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10,
+          "description": "Optional severity/priority score (0-10 range)"
         }
       }
     },
@@ -156,11 +191,6 @@
         "cvssVector": {
           "type": "string",
           "description": "CVSS v3.1 vector string"
-        },
-        "tags": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Security-related tags"
         }
       }
     },

package/src/types/IRule.ts

@@ -179,9 +179,34 @@ export interface RulePack extends RulePackMetadata {
     disables?: PackDisableConfig;
 }
 
+/**
+ * Tag type classification for rule categorization.
+ * Allows multi-dimensional tagging beyond security-only metadata.
+ */
+export type TagType = 'security' | 'operational' | 'compliance' | 'general';
+
+/**
+ * A typed classification object for categorizing rules.
+ * Replaces the simpler string-based security tags with structured metadata.
+ */
+export interface Tag {
+    /** Tag classification type */
+    type: TagType;
+
+    /** Short identifier/label for the tag (e.g., "vlan-hopping", "access-control") */
+    label: string;
+
+    /** Optional extended description */
+    text?: string;
+
+    /** Optional severity/priority score (0-10 range) */
+    score?: number;
+}
+
 /**
  * SEC-007: Security metadata for SARIF integration.
  * Provides CWE mappings and CVSS scores for security-related rules.
+ * Note: tags field has been moved to RuleMetadata.tags for generalization.
  */
 export interface SecurityMetadata {
     /**
@@ -201,12 +226,6 @@ export interface SecurityMetadata {
      * Example: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H'
      */
     cvssVector?: string;
-
-    /**
-     * Security-related tags for categorization.
-     * Example: ['authentication', 'hardcoded-credentials', 'encryption']
-     */
-    tags?: string[];
 }
 
 /**
@@ -226,6 +245,8 @@ export interface RuleMetadata {
     remediation?: string;
     /** SEC-007: Optional security metadata for SARIF integration */
     security?: SecurityMetadata;
+    /** Typed tags for multi-dimensional rule categorization */
+    tags?: Tag[];
 }
 
 /**