@sentriflow/core 0.1.0

package/src/engine/Runner.ts

@@ -0,0 +1,312 @@
+// packages/core/src/engine/Runner.ts
+
+import type { ConfigNode } from '../types/ConfigNode';
+import type { IRule, RuleResult, Context } from '../types/IRule';
+import { RuleExecutor } from './RuleExecutor';
+import type { ExecutionOptions } from './RuleExecutor';
+
+/**
+ * Index structure for fast rule lookup.
+ * Reduces selector matching from O(N×R) to O(N×k) where k << R.
+ */
+interface RuleIndex {
+  /** Rules indexed by first keyword of selector (lowercase) */
+  byPrefix: Map<string, IRule[]>;
+  /** Rules with no selector (global rules that run on all nodes) */
+  global: IRule[];
+  /** Rules indexed by exact selector match (lowercase) */
+  exact: Map<string, IRule[]>;
+}
+
+/**
+ * Options for RuleEngine.
+ */
+export interface EngineOptions {
+  /** Enable timeout protection for rule execution */
+  enableTimeoutProtection?: boolean;
+  /** Options for the rule executor (timeout settings) */
+  executionOptions?: ExecutionOptions;
+}
+
+/**
+ * Rule Engine with selector indexing for high-performance rule evaluation.
+ *
+ * Performance characteristics:
+ * - Index build: O(R) where R = number of rules
+ * - Per-node lookup: O(1) average case (hash map lookup)
+ * - Total scan: O(N×k) where N = nodes, k = average matching rules per node
+ *
+ * For 500 rules with good selector distribution, k is typically 5-20,
+ * giving ~25-100× improvement over naive O(N×R) scanning.
+ */
+export class RuleEngine {
+  private index: RuleIndex | null = null;
+  private indexedRules: IRule[] = [];
+  private indexVersion = 0;
+  private executor: RuleExecutor | null = null;
+  private options: EngineOptions;
+
+  constructor(options: EngineOptions = {}) {
+    this.options = {
+      enableTimeoutProtection: options.enableTimeoutProtection ?? false,
+      executionOptions: options.executionOptions,
+    };
+
+    if (this.options.enableTimeoutProtection) {
+      this.executor = new RuleExecutor(this.options.executionOptions);
+    }
+  }
+
+  /**
+   * Build an index for fast rule lookup.
+   * Call this once when rules change, not on every scan.
+   *
+   * @param rules The rules to index
+   */
+  public buildIndex(rules: IRule[]): void {
+    this.index = {
+      byPrefix: new Map(),
+      global: [],
+      exact: new Map(),
+    };
+    this.indexedRules = rules;
+    this.indexVersion++;
+
+    for (const rule of rules) {
+      if (!rule.selector) {
+        // No selector = global rule, runs on everything
+        this.index.global.push(rule);
+        continue;
+      }
+
+      const selector = rule.selector.toLowerCase();
+
+      // Index by exact selector
+      const exactBucket = this.index.exact.get(selector);
+      if (exactBucket) {
+        exactBucket.push(rule);
+      } else {
+        this.index.exact.set(selector, [rule]);
+      }
+
+      // Index by first word (prefix) for partial matches
+      const prefix = selector.split(/\s+/)[0] ?? selector;
+      const prefixBucket = this.index.byPrefix.get(prefix);
+      if (prefixBucket) {
+        prefixBucket.push(rule);
+      } else {
+        this.index.byPrefix.set(prefix, [rule]);
+      }
+    }
+  }
+
+  /**
+   * Get rules that might match a node.
+   * Returns a small subset of total rules based on prefix matching.
+   *
+   * @param node The configuration node to find candidate rules for
+   * @returns Array of rules that may match the node
+   */
+  private getCandidateRules(node: ConfigNode): IRule[] {
+    if (!this.index) {
+      return this.indexedRules; // Fallback to all rules if no index
+    }
+
+    const nodeId = node.id.toLowerCase();
+    const nodePrefix = nodeId.split(/\s+/)[0] ?? nodeId;
+
+    // Start with global rules (always run)
+    const candidates: IRule[] = [...this.index.global];
+
+    // Add rules matching the node's prefix
+    const prefixRules = this.index.byPrefix.get(nodePrefix);
+    if (prefixRules) {
+      candidates.push(...prefixRules);
+    }
+
+    return candidates;
+  }
+
+  /**
+   * Run rules against nodes using the index for fast lookup.
+   *
+   * @param nodes The root nodes of the configuration AST
+   * @param rules Optional rules array - if provided and different from indexed rules, rebuilds index
+   * @param context Optional global context to pass to rules
+   * @returns Array of RuleResult objects
+   */
+  public run(
+    nodes: ConfigNode[],
+    rules?: IRule[],
+    context: Partial<Context> = {}
+  ): RuleResult[] {
+    // Rebuild index if rules provided and different
+    if (rules && rules !== this.indexedRules) {
+      this.buildIndex(rules);
+    }
+
+    // If no rules indexed, return empty results
+    if (this.indexedRules.length === 0) {
+      return [];
+    }
+
+    const results: RuleResult[] = [];
+
+    // Create context once with lazy AST getter
+    const ruleContext: Context = {
+      ...context,
+      getAst: () => nodes,
+    };
+
+    const visit = (node: ConfigNode): void => {
+      // Only check candidate rules, not all rules
+      const candidates = this.getCandidateRules(node);
+
+      for (const rule of candidates) {
+        if (this.matchesSelector(node, rule.selector)) {
+          // Use executor if timeout protection is enabled
+          if (this.executor) {
+            const result = this.executor.execute(rule, node, ruleContext);
+            if (result) {
+              results.push(result);
+            }
+          } else {
+            // Direct execution without timeout protection
+            try {
+              const result = rule.check(node, ruleContext);
+              if (result) {
+                results.push(result);
+              }
+            } catch (error) {
+              results.push({
+                passed: false,
+                message: `Rule execution error: ${
+                  error instanceof Error ? error.message : String(error)
+                }`,
+                ruleId: rule.id,
+                nodeId: node.id,
+                level: 'error',
+                loc: node.loc,
+              });
+            }
+          }
+        }
+      }
+
+      // Recurse into children
+      for (const child of node.children) {
+        visit(child);
+      }
+    };
+
+    for (const node of nodes) {
+      visit(node);
+    }
+
+    return results;
+  }
+
+  /**
+   * Checks if a node matches a rule's selector.
+   * Uses case-insensitive prefix matching.
+   *
+   * @param node The configuration node
+   * @param selector The selector string (e.g., "interface", "router bgp")
+   * @returns True if the node matches the selector
+   */
+  private matchesSelector(node: ConfigNode, selector?: string): boolean {
+    if (!selector) return true;
+    return node.id.toLowerCase().startsWith(selector.toLowerCase());
+  }
+
+  /**
+   * Check if the index needs rebuilding.
+   * Useful for determining when to call buildIndex().
+   *
+   * @param rules The rules to check against
+   * @returns True if the rules differ from the indexed rules
+   */
+  public needsReindex(rules: IRule[]): boolean {
+    return rules !== this.indexedRules;
+  }
+
+  /**
+   * Get the current index version.
+   * Increments each time buildIndex() is called.
+   */
+  public getIndexVersion(): number {
+    return this.indexVersion;
+  }
+
+  /**
+   * Get statistics about the current index.
+   * Useful for debugging and performance monitoring.
+   */
+  public getIndexStats(): {
+    totalRules: number;
+    globalRules: number;
+    prefixBuckets: number;
+    exactBuckets: number;
+    avgRulesPerPrefix: number;
+  } {
+    if (!this.index) {
+      return {
+        totalRules: 0,
+        globalRules: 0,
+        prefixBuckets: 0,
+        exactBuckets: 0,
+        avgRulesPerPrefix: 0,
+      };
+    }
+
+    const prefixBuckets = this.index.byPrefix.size;
+    let totalPrefixRules = 0;
+    for (const bucket of this.index.byPrefix.values()) {
+      totalPrefixRules += bucket.length;
+    }
+
+    return {
+      totalRules: this.indexedRules.length,
+      globalRules: this.index.global.length,
+      prefixBuckets,
+      exactBuckets: this.index.exact.size,
+      avgRulesPerPrefix: prefixBuckets > 0 ? totalPrefixRules / prefixBuckets : 0,
+    };
+  }
+
+  /**
+   * Clear the index and release memory.
+   */
+  public clearIndex(): void {
+    this.index = null;
+    this.indexedRules = [];
+  }
+
+  /**
+   * Get the rule executor (if timeout protection is enabled).
+   */
+  public getExecutor(): RuleExecutor | null {
+    return this.executor;
+  }
+
+  /**
+   * Get list of auto-disabled rules (if timeout protection is enabled).
+   */
+  public getDisabledRules(): string[] {
+    return this.executor?.getDisabledRules() ?? [];
+  }
+
+  /**
+   * Re-enable a previously disabled rule.
+   */
+  public enableRule(ruleId: string): void {
+    this.executor?.enableRule(ruleId);
+  }
+
+  /**
+   * Reset executor state (timeout counts, disabled rules).
+   */
+  public resetExecutor(): void {
+    this.executor?.resetAll();
+  }
+}

package/src/engine/SandboxedExecutor.ts

@@ -0,0 +1,208 @@
+// packages/core/src/engine/SandboxedExecutor.ts
+
+/**
+ * SEC-001: Sandboxed Executor for Declarative Rules
+ *
+ * Provides safe evaluation of declarative rules without executing
+ * arbitrary JavaScript. Custom code blocks run in a VM sandbox
+ * with strict timeouts and limited API access.
+ */
+
+import { createContext, Script, type Context as VMContext } from 'vm';
+import type { ConfigNode } from '../types/ConfigNode';
+import type { Context } from '../types/IRule';
+import type { IRule, RuleResult, RuleVendor } from '../types/IRule';
+import type { DeclarativeRule, DeclarativeCheck } from '../types/DeclarativeRule';
+
+/** Timeout for custom code execution in milliseconds */
+const CUSTOM_CODE_TIMEOUT_MS = 100;
+
+/**
+ * Compiles a DeclarativeRule into an IRule with a safe check function.
+ *
+ * For most declarative checks, this produces a native function that
+ * executes without any sandboxing overhead. Only 'custom' type checks
+ * require VM sandboxing.
+ */
+export class SandboxedExecutor {
+    private readonly sandbox: Record<string, unknown>;
+    private readonly vmContext: VMContext;
+
+    constructor() {
+        this.sandbox = this.createSandbox();
+        this.vmContext = createContext(this.sandbox);
+    }
+
+    /**
+     * Compiles a declarative rule into an executable IRule.
+     */
+    compileRule(decl: DeclarativeRule): IRule {
+        return {
+            id: decl.id,
+            selector: decl.selector,
+            vendor: decl.vendor as RuleVendor | RuleVendor[] | undefined,
+            metadata: decl.metadata,
+            check: (node: ConfigNode, ctx: Context): RuleResult => {
+                return this.evaluate(decl.check, node, ctx, decl);
+            },
+        };
+    }
+
+    /**
+     * Evaluates a declarative check condition against a node.
+     */
+    private evaluate(
+        check: DeclarativeCheck,
+        node: ConfigNode,
+        ctx: Context,
+        rule: DeclarativeRule
+    ): RuleResult {
+        const passed = this.evaluateCondition(check, node);
+        return {
+            passed,
+            message: passed
+                ? `${rule.id}: Check passed`
+                : `${rule.id}: Check failed - ${rule.metadata.remediation ?? 'See rule documentation'}`,
+            ruleId: rule.id,
+            nodeId: node.id,
+            level: rule.metadata.level,
+            loc: node.loc,
+        };
+    }
+
+    /**
+     * Recursively evaluates a declarative check condition.
+     * Returns true if the condition is satisfied.
+     */
+    private evaluateCondition(check: DeclarativeCheck, node: ConfigNode): boolean {
+        switch (check.type) {
+            case 'match':
+                return new RegExp(check.pattern, check.flags).test(node.id);
+
+            case 'not_match':
+                return !new RegExp(check.pattern, check.flags).test(node.id);
+
+            case 'contains':
+                return node.id.includes(check.text);
+
+            case 'not_contains':
+                return !node.id.includes(check.text);
+
+            case 'child_exists':
+                return node.children.some(c =>
+                    c.id.toLowerCase().startsWith(check.selector.toLowerCase())
+                );
+
+            case 'child_not_exists':
+                return !node.children.some(c =>
+                    c.id.toLowerCase().startsWith(check.selector.toLowerCase())
+                );
+
+            case 'child_matches': {
+                const matchingChildren = node.children.filter(c =>
+                    c.id.toLowerCase().startsWith(check.selector.toLowerCase())
+                );
+                const regex = new RegExp(check.pattern, check.flags);
+                return matchingChildren.some(c => regex.test(c.id));
+            }
+
+            case 'child_contains': {
+                const containsChildren = node.children.filter(c =>
+                    c.id.toLowerCase().startsWith(check.selector.toLowerCase())
+                );
+                return containsChildren.some(c => c.id.includes(check.text));
+            }
+
+            case 'and':
+                return check.conditions.every(c => this.evaluateCondition(c, node));
+
+            case 'or':
+                return check.conditions.some(c => this.evaluateCondition(c, node));
+
+            case 'not':
+                return !this.evaluateCondition(check.condition, node);
+
+            case 'custom':
+                return this.executeCustomCode(check.code, node);
+
+            default:
+                // Unknown check type - fail closed for safety
+                return false;
+        }
+    }
+
+    /**
+     * Executes custom code in a VM sandbox.
+     * Returns the boolean result of the code execution.
+     */
+    private executeCustomCode(code: string, node: ConfigNode): boolean {
+        // Prepare a frozen copy of the node for the sandbox
+        this.sandbox.node = Object.freeze({
+            id: node.id,
+            type: node.type,
+            children: node.children.map(c => Object.freeze({
+                id: c.id,
+                type: c.type,
+            })),
+        });
+
+        try {
+            const wrappedCode = `(function() { ${code} })()`;
+            const script = new Script(wrappedCode, {
+                filename: 'custom-check.js',
+                timeout: CUSTOM_CODE_TIMEOUT_MS,
+            } as { filename: string; timeout: number });
+            const result = script.runInContext(this.vmContext);
+            return Boolean(result);
+        } catch {
+            // Any error (timeout, syntax, runtime) = fail closed
+            return false;
+        }
+    }
+
+    /**
+     * Creates a minimal sandbox for custom code execution.
+     * Only provides safe, read-only access to basic JavaScript features.
+     */
+    private createSandbox(): Record<string, unknown> {
+        return Object.freeze({
+            // The node being checked (set dynamically)
+            node: null,
+
+            // Safe built-ins (frozen)
+            Boolean,
+            Number,
+            String,
+            Array,
+            Object,
+            RegExp,
+
+            // Safe JSON access
+            JSON: Object.freeze({
+                parse: JSON.parse,
+                stringify: JSON.stringify,
+            }),
+
+            // Safe Math access
+            Math: Object.freeze(Math),
+
+            // Primitives
+            true: true,
+            false: false,
+            undefined,
+            null: null,
+            NaN,
+            Infinity,
+
+            // No console, no require, no import, no process, no global
+        });
+    }
+}
+
+/**
+ * Creates a SandboxedExecutor instance.
+ * Use this for compiling declarative rules.
+ */
+export function createSandboxedExecutor(): SandboxedExecutor {
+    return new SandboxedExecutor();
+}

package/src/errors.ts

@@ -0,0 +1,88 @@
+// packages/core/src/errors.ts
+
+/**
+ * Base error class for all SentriFlow errors.
+ * Provides structured error handling with error codes.
+ */
+export class SentriflowError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'SentriflowError';
+    // Maintains proper stack trace for where error was thrown (V8 only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Returns a user-friendly error message without internal details.
+   */
+  toUserMessage(): string {
+    return `[${this.code}] ${this.message}`;
+  }
+
+  /**
+   * Returns a JSON representation for logging.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+/**
+ * Error thrown when configuration loading fails.
+ */
+export class SentriflowConfigError extends SentriflowError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('CONFIG_ERROR', message, details);
+    this.name = 'SentriflowConfigError';
+  }
+}
+
+/**
+ * Error thrown when path validation fails.
+ */
+export class SentriflowPathError extends SentriflowError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('PATH_ERROR', message, details);
+    this.name = 'SentriflowPathError';
+  }
+}
+
+/**
+ * Error thrown when parsing fails.
+ */
+export class SentriflowParseError extends SentriflowError {
+  constructor(message: string, line?: number) {
+    super('PARSE_ERROR', message, line !== undefined ? { line } : undefined);
+    this.name = 'SentriflowParseError';
+  }
+}
+
+/**
+ * Error thrown when rule validation or execution fails.
+ */
+export class SentriflowRuleError extends SentriflowError {
+  constructor(message: string, ruleId?: string) {
+    super('RULE_ERROR', message, ruleId ? { ruleId } : undefined);
+    this.name = 'SentriflowRuleError';
+  }
+}
+
+/**
+ * Error thrown when input size exceeds limits.
+ */
+export class SentriflowSizeLimitError extends SentriflowError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('SIZE_LIMIT_ERROR', message, details);
+    this.name = 'SentriflowSizeLimitError';
+  }
+}