@sentriflow/core 0.1.0

package/src/json-rules/JsonRuleCompiler.ts

@@ -0,0 +1,339 @@
+// packages/core/src/json-rules/JsonRuleCompiler.ts
+
+/**
+ * JSON Rule Compiler
+ *
+ * Compiles JSON rule definitions into executable IRule objects.
+ * Supports all check types including helper invocation and expression evaluation.
+ */
+
+import type { ConfigNode } from '../types/ConfigNode';
+import type { IRule, Context, RuleResult } from '../types/IRule';
+import type { JsonRule, JsonCheck, JsonArgValue } from './types';
+import {
+    type HelperRegistry,
+    type HelperFunction,
+    getHelperRegistry,
+    resolveHelper,
+} from './HelperRegistry';
+import { ExpressionEvaluator, createExpressionEvaluator } from './ExpressionEvaluator';
+
+/**
+ * Options for the JSON rule compiler.
+ */
+export interface JsonRuleCompilerOptions {
+    /** Custom helper registry (uses default if not provided) */
+    registry?: HelperRegistry;
+    /** Pre-compile expressions at rule load time (default: true) */
+    precompileExpressions?: boolean;
+}
+
+/**
+ * Compiles JSON rules into executable IRule objects.
+ */
+export class JsonRuleCompiler {
+    private readonly registry: HelperRegistry;
+    private readonly evaluator: ExpressionEvaluator;
+    private readonly precompileExpressions: boolean;
+    private readonly regexCache: Map<string, RegExp> = new Map();
+
+    constructor(options: JsonRuleCompilerOptions = {}) {
+        this.registry = options.registry ?? getHelperRegistry();
+        this.evaluator = createExpressionEvaluator(this.registry);
+        this.precompileExpressions = options.precompileExpressions ?? true;
+    }
+
+    /**
+     * Get a cached regex or create and cache a new one.
+     */
+    private getRegex(pattern: string, flags?: string): RegExp {
+        const key = `${pattern}::${flags ?? ''}`;
+        let regex = this.regexCache.get(key);
+        if (!regex) {
+            regex = new RegExp(pattern, flags);
+            this.regexCache.set(key, regex);
+        }
+        return regex;
+    }
+
+    /**
+     * Format a message template by replacing placeholders.
+     */
+    private formatMessage(template: string, nodeId: string, ruleId: string): string {
+        return template.replaceAll('{nodeId}', nodeId).replaceAll('{ruleId}', ruleId);
+    }
+
+    /**
+     * Get children matching a selector (case-insensitive prefix match).
+     */
+    private getMatchingChildren(node: ConfigNode, selector: string): ConfigNode[] {
+        const selectorLower = selector.toLowerCase();
+        return node.children.filter((child) =>
+            child.id.toLowerCase().startsWith(selectorLower)
+        );
+    }
+
+    /**
+     * Compile a JSON rule into an executable IRule.
+     *
+     * @param jsonRule The JSON rule definition
+     * @returns An executable IRule object
+     */
+    compile(jsonRule: JsonRule): IRule {
+        // Pre-compile expressions if enabled
+        if (this.precompileExpressions) {
+            this.precompileCheckExpressions(jsonRule.check);
+        }
+
+        return {
+            id: jsonRule.id,
+            selector: jsonRule.selector,
+            vendor: jsonRule.vendor,
+            metadata: jsonRule.metadata,
+            check: (node: ConfigNode, _ctx: Context): RuleResult => {
+                // Check defines failure conditions - invert to get pass status
+                const passed = !this.evaluateCheck(jsonRule.check, node);
+
+                // Format message with placeholders
+                const template = passed
+                    ? (jsonRule.successMessage ?? `${jsonRule.id}: Check passed`)
+                    : (jsonRule.failureMessage ?? jsonRule.metadata.description ?? `${jsonRule.id}: Check failed`);
+                const message = this.formatMessage(template, node.id, jsonRule.id);
+
+                return {
+                    passed,
+                    message,
+                    ruleId: jsonRule.id,
+                    nodeId: node.id,
+                    level: passed ? 'info' : jsonRule.metadata.level,
+                    loc: node.loc,
+                    remediation: passed ? undefined : jsonRule.metadata.remediation,
+                };
+            },
+        };
+    }
+
+    /**
+     * Compile multiple JSON rules.
+     *
+     * @param jsonRules Array of JSON rule definitions
+     * @returns Array of executable IRule objects
+     */
+    compileAll(jsonRules: JsonRule[]): IRule[] {
+        return jsonRules.map((rule) => this.compile(rule));
+    }
+
+    /**
+     * Pre-compile all expressions in a check tree.
+     */
+    private precompileCheckExpressions(check: JsonCheck): void {
+        switch (check.type) {
+            case 'expr':
+                this.evaluator.precompile(check.expr);
+                break;
+            case 'and':
+            case 'or':
+                for (const condition of check.conditions) {
+                    this.precompileCheckExpressions(condition);
+                }
+                break;
+            case 'not':
+                this.precompileCheckExpressions(check.condition);
+                break;
+            // Other types don't have expressions to pre-compile
+        }
+    }
+
+    /**
+     * Evaluate a check condition against a node.
+     */
+    private evaluateCheck(check: JsonCheck, node: ConfigNode): boolean {
+        switch (check.type) {
+            case 'match':
+                return this.evaluateMatch(check.pattern, check.flags, node);
+
+            case 'not_match':
+                return !this.evaluateMatch(check.pattern, check.flags, node);
+
+            case 'contains':
+                return node.id.toLowerCase().includes(check.text.toLowerCase());
+
+            case 'not_contains':
+                return !node.id.toLowerCase().includes(check.text.toLowerCase());
+
+            case 'child_exists':
+                return this.hasMatchingChild(node, check.selector);
+
+            case 'child_not_exists':
+                return !this.hasMatchingChild(node, check.selector);
+
+            case 'child_matches':
+                return this.childMatches(node, check.selector, check.pattern, check.flags);
+
+            case 'child_contains':
+                return this.childContains(node, check.selector, check.text);
+
+            case 'helper':
+                return this.evaluateHelper(check, node);
+
+            case 'expr':
+                return this.evaluator.evaluate(check.expr, node);
+
+            case 'and':
+                return check.conditions.every((c) => this.evaluateCheck(c, node));
+
+            case 'or':
+                return check.conditions.some((c) => this.evaluateCheck(c, node));
+
+            case 'not':
+                return !this.evaluateCheck(check.condition, node);
+
+            default:
+                // Unknown check type - fail closed
+                return false;
+        }
+    }
+
+    /**
+     * Evaluate a regex match on node.id.
+     */
+    private evaluateMatch(pattern: string, flags: string | undefined, node: ConfigNode): boolean {
+        try {
+            const regex = this.getRegex(pattern, flags);
+            return regex.test(node.id);
+        } catch {
+            return false; // Invalid regex
+        }
+    }
+
+    /**
+     * Check if node has a child matching the selector (case-insensitive prefix).
+     */
+    private hasMatchingChild(node: ConfigNode, selector: string): boolean {
+        return this.getMatchingChildren(node, selector).length > 0;
+    }
+
+    /**
+     * Check if any matching child's id matches the pattern.
+     */
+    private childMatches(
+        node: ConfigNode,
+        selector: string,
+        pattern: string,
+        flags?: string
+    ): boolean {
+        const matchingChildren = this.getMatchingChildren(node, selector);
+        try {
+            const regex = this.getRegex(pattern, flags);
+            return matchingChildren.some((child) => regex.test(child.id));
+        } catch {
+            return false; // Invalid regex
+        }
+    }
+
+    /**
+     * Check if any matching child's id contains the text.
+     */
+    private childContains(node: ConfigNode, selector: string, text: string): boolean {
+        const textLower = text.toLowerCase();
+        const matchingChildren = this.getMatchingChildren(node, selector);
+        return matchingChildren.some((child) =>
+            child.id.toLowerCase().includes(textLower)
+        );
+    }
+
+    /**
+     * Evaluate a helper function check.
+     */
+    private evaluateHelper(
+        check: { type: 'helper'; helper: string; args?: JsonArgValue[]; negate?: boolean },
+        node: ConfigNode
+    ): boolean {
+        const helperFn = resolveHelper(this.registry, check.helper);
+        if (!helperFn) {
+            // Unknown helper - fail closed
+            return false;
+        }
+
+        // Resolve arguments
+        const args = (check.args ?? []).map((arg) => this.resolveArg(arg, node));
+
+        try {
+            const result = (helperFn as HelperFunction)(...args);
+            const boolResult = Boolean(result);
+            return check.negate ? !boolResult : boolResult;
+        } catch {
+            return false; // Helper execution error
+        }
+    }
+
+    /**
+     * Resolve an argument value, handling $ref references.
+     */
+    private resolveArg(arg: JsonArgValue, node: ConfigNode): unknown {
+        if (arg === null) return null;
+        if (typeof arg !== 'object') return arg;
+
+        if ('$ref' in arg) {
+            switch (arg.$ref) {
+                case 'node':
+                    return node;
+                case 'node.id':
+                    return node.id;
+                case 'node.type':
+                    return node.type;
+                case 'node.children':
+                    return node.children;
+                case 'node.params':
+                    return node.params;
+                case 'node.rawText':
+                    return node.rawText;
+                default:
+                    return undefined;
+            }
+        }
+
+        return arg;
+    }
+}
+
+/**
+ * Create a new JSON rule compiler.
+ */
+export function createJsonRuleCompiler(options?: JsonRuleCompilerOptions): JsonRuleCompiler {
+    return new JsonRuleCompiler(options);
+}
+
+// Default singleton compiler for convenience
+let defaultCompiler: JsonRuleCompiler | null = null;
+
+/**
+ * Get the default JSON rule compiler (singleton).
+ */
+export function getJsonRuleCompiler(): JsonRuleCompiler {
+    if (!defaultCompiler) {
+        defaultCompiler = new JsonRuleCompiler();
+    }
+    return defaultCompiler;
+}
+
+/**
+ * Compile a JSON rule to IRule using the default compiler.
+ */
+export function compileJsonRule(jsonRule: JsonRule): IRule {
+    return getJsonRuleCompiler().compile(jsonRule);
+}
+
+/**
+ * Compile multiple JSON rules to IRule array using the default compiler.
+ */
+export function compileJsonRules(jsonRules: JsonRule[]): IRule[] {
+    return getJsonRuleCompiler().compileAll(jsonRules);
+}
+
+/**
+ * Clear the default compiler (useful for testing).
+ */
+export function clearJsonRuleCompiler(): void {
+    defaultCompiler = null;
+}

package/src/json-rules/JsonRuleValidator.ts

@@ -0,0 +1,371 @@
+// packages/core/src/json-rules/JsonRuleValidator.ts
+
+/**
+ * JSON Rule Validator
+ *
+ * Validates JSON rule files for both structural correctness and semantic validity.
+ * Provides detailed error messages for debugging rule authoring issues.
+ */
+
+import { isValidVendorId, VALID_VENDOR_IDS, type RuleVendor } from '../types/IRule';
+import { RULE_ID_PATTERN, MAX_PATTERN_LENGTH, REDOS_PATTERN } from '../constants';
+import { isJsonRule, isJsonRuleFile, isJsonCheck, type JsonRule, type JsonRuleFile, type JsonCheck } from './types';
+import { getHelperRegistry, hasHelper, type HelperRegistry } from './HelperRegistry';
+import { isValidExpression } from './ExpressionEvaluator';
+
+/**
+ * A validation error with path and message.
+ */
+export interface ValidationError {
+    /** JSON path to the error location (e.g., "/rules/0/check/helper") */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error severity */
+    severity: 'error' | 'warning';
+}
+
+/**
+ * Result of validation.
+ */
+export interface ValidationResult {
+    /** Whether the validation passed (no errors) */
+    valid: boolean;
+    /** Array of validation errors */
+    errors: ValidationError[];
+    /** Array of validation warnings */
+    warnings: ValidationError[];
+}
+
+/**
+ * Options for validation.
+ */
+export interface ValidationOptions {
+    /** Custom helper registry for validating helper names */
+    registry?: HelperRegistry;
+    /** Whether to validate helper names exist (default: true) */
+    validateHelpers?: boolean;
+    /** Whether to validate expressions are safe (default: true) */
+    validateExpressions?: boolean;
+    /** Whether to allow unknown vendors (default: false) */
+    allowUnknownVendors?: boolean;
+}
+
+/**
+ * Validate a JSON rule file.
+ *
+ * @param data The data to validate
+ * @param options Validation options
+ * @returns Validation result with errors and warnings
+ */
+export function validateJsonRuleFile(
+    data: unknown,
+    options: ValidationOptions = {}
+): ValidationResult {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationError[] = [];
+    const registry = options.registry ?? getHelperRegistry();
+    const validateHelpers = options.validateHelpers ?? true;
+    const validateExpressions = options.validateExpressions ?? true;
+    const allowUnknownVendors = options.allowUnknownVendors ?? false;
+
+    // Phase 1: Structural validation using type guards
+    if (!isJsonRuleFile(data)) {
+        errors.push({
+            path: '',
+            message: 'Invalid JSON rule file structure',
+            severity: 'error',
+        });
+
+        // Try to provide more specific errors
+        if (typeof data !== 'object' || data === null) {
+            errors.push({
+                path: '',
+                message: 'Expected an object',
+                severity: 'error',
+            });
+        } else {
+            const obj = data as Record<string, unknown>;
+
+            if (obj.version !== '1.0') {
+                errors.push({
+                    path: '/version',
+                    message: `Invalid version: expected "1.0", got "${String(obj.version)}"`,
+                    severity: 'error',
+                });
+            }
+
+            if (!Array.isArray(obj.rules)) {
+                errors.push({
+                    path: '/rules',
+                    message: 'Expected "rules" to be an array',
+                    severity: 'error',
+                });
+            }
+        }
+
+        return { valid: false, errors, warnings };
+    }
+
+    const file = data as JsonRuleFile;
+
+    // Phase 2: Validate each rule
+    for (let i = 0; i < file.rules.length; i++) {
+        const rule = file.rules[i];
+        if (!rule) continue;
+        const rulePath = `/rules/${i}`;
+
+        validateRule(rule, rulePath, {
+            errors,
+            warnings,
+            registry,
+            validateHelpers,
+            validateExpressions,
+            allowUnknownVendors,
+        });
+    }
+
+    // Phase 3: Check for duplicate rule IDs
+    const ruleIds = new Set<string>();
+    for (let i = 0; i < file.rules.length; i++) {
+        const rule = file.rules[i];
+        if (!rule) continue;
+
+        if (ruleIds.has(rule.id)) {
+            errors.push({
+                path: `/rules/${i}/id`,
+                message: `Duplicate rule ID: "${rule.id}"`,
+                severity: 'error',
+            });
+        }
+        ruleIds.add(rule.id);
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+
+/**
+ * Validate a single JSON rule.
+ */
+export function validateJsonRule(
+    data: unknown,
+    options: ValidationOptions = {}
+): ValidationResult {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationError[] = [];
+    const registry = options.registry ?? getHelperRegistry();
+    const validateHelpers = options.validateHelpers ?? true;
+    const validateExpressions = options.validateExpressions ?? true;
+    const allowUnknownVendors = options.allowUnknownVendors ?? false;
+
+    if (!isJsonRule(data)) {
+        errors.push({
+            path: '',
+            message: 'Invalid JSON rule structure',
+            severity: 'error',
+        });
+        return { valid: false, errors, warnings };
+    }
+
+    validateRule(data as JsonRule, '', {
+        errors,
+        warnings,
+        registry,
+        validateHelpers,
+        validateExpressions,
+        allowUnknownVendors,
+    });
+
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+
+interface ValidationContext {
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    registry: HelperRegistry;
+    validateHelpers: boolean;
+    validateExpressions: boolean;
+    allowUnknownVendors: boolean;
+}
+
+/**
+ * Validate a rule and add errors/warnings to context.
+ */
+function validateRule(rule: JsonRule, path: string, ctx: ValidationContext): void {
+    // Validate rule ID format
+    if (!RULE_ID_PATTERN.test(rule.id)) {
+        ctx.errors.push({
+            path: `${path}/id`,
+            message: `Invalid rule ID format: "${rule.id}". Must match pattern: ^[A-Z][A-Z0-9_-]{2,49}$`,
+            severity: 'error',
+        });
+    }
+
+    // Validate vendor(s)
+    if (rule.vendor !== undefined) {
+        const vendors = Array.isArray(rule.vendor) ? rule.vendor : [rule.vendor];
+        for (const vendor of vendors) {
+            if (!ctx.allowUnknownVendors && !isValidVendorId(vendor)) {
+                ctx.errors.push({
+                    path: `${path}/vendor`,
+                    message: `Unknown vendor: "${vendor}". Valid vendors: ${VALID_VENDOR_IDS.join(', ')}`,
+                    severity: 'error',
+                });
+            }
+        }
+    }
+
+    // Validate metadata
+    if (!rule.metadata.description) {
+        ctx.warnings.push({
+            path: `${path}/metadata/description`,
+            message: 'Rule should have a description',
+            severity: 'warning',
+        });
+    }
+
+    if (!rule.metadata.remediation) {
+        ctx.warnings.push({
+            path: `${path}/metadata/remediation`,
+            message: 'Rule should have remediation guidance',
+            severity: 'warning',
+        });
+    }
+
+    // Validate check
+    validateCheck(rule.check, `${path}/check`, ctx);
+}
+
+/**
+ * Validate a check condition recursively.
+ */
+function validateCheck(check: JsonCheck, path: string, ctx: ValidationContext): void {
+    switch (check.type) {
+        case 'match':
+        case 'not_match':
+            validateRegex(check.pattern, check.flags, `${path}/pattern`, ctx);
+            break;
+
+        case 'child_matches':
+            validateRegex(check.pattern, check.flags, `${path}/pattern`, ctx);
+            break;
+
+        case 'helper':
+            if (ctx.validateHelpers && !hasHelper(ctx.registry, check.helper)) {
+                ctx.errors.push({
+                    path: `${path}/helper`,
+                    message: `Unknown helper: "${check.helper}"`,
+                    severity: 'error',
+                });
+            }
+            break;
+
+        case 'expr':
+            if (ctx.validateExpressions && !isValidExpression(check.expr)) {
+                ctx.errors.push({
+                    path: `${path}/expr`,
+                    message: `Invalid or unsafe expression: "${check.expr}"`,
+                    severity: 'error',
+                });
+            }
+            break;
+
+        case 'and':
+        case 'or':
+            if (check.conditions.length === 0) {
+                ctx.errors.push({
+                    path: `${path}/conditions`,
+                    message: `Empty conditions array in "${check.type}" check - this will always ${check.type === 'and' ? 'pass' : 'fail'}`,
+                    severity: 'error',
+                });
+            }
+            for (let i = 0; i < check.conditions.length; i++) {
+                const cond = check.conditions[i];
+                if (cond) {
+                    validateCheck(cond, `${path}/conditions/${i}`, ctx);
+                }
+            }
+            break;
+
+        case 'not':
+            validateCheck(check.condition, `${path}/condition`, ctx);
+            break;
+    }
+}
+
+/**
+ * Validate a regex pattern.
+ */
+function validateRegex(
+    pattern: string,
+    flags: string | undefined,
+    path: string,
+    ctx: ValidationContext
+): void {
+    // Check pattern length (ReDoS protection)
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        ctx.errors.push({
+            path,
+            message: `Regex pattern too long: ${pattern.length} chars exceeds limit of ${MAX_PATTERN_LENGTH}`,
+            severity: 'error',
+        });
+        return;
+    }
+
+    // Check for ReDoS patterns (nested quantifiers)
+    if (REDOS_PATTERN.test(pattern)) {
+        ctx.errors.push({
+            path,
+            message: `Regex pattern contains nested quantifiers which may cause ReDoS: "${pattern.slice(0, 50)}${pattern.length > 50 ? '...' : ''}"`,
+            severity: 'error',
+        });
+        return;
+    }
+
+    try {
+        new RegExp(pattern, flags);
+    } catch (e) {
+        ctx.errors.push({
+            path,
+            message: `Invalid regex: ${e instanceof Error ? e.message : 'unknown error'}`,
+            severity: 'error',
+        });
+    }
+}
+
+/**
+ * Format validation result as a human-readable string.
+ */
+export function formatValidationResult(result: ValidationResult): string {
+    const lines: string[] = [];
+
+    if (result.valid) {
+        lines.push('✓ Validation passed');
+    } else {
+        lines.push('✗ Validation failed');
+    }
+
+    if (result.errors.length > 0) {
+        lines.push(`\nErrors (${result.errors.length}):`);
+        for (const error of result.errors) {
+            lines.push(`  ${error.path || '/'}: ${error.message}`);
+        }
+    }
+
+    if (result.warnings.length > 0) {
+        lines.push(`\nWarnings (${result.warnings.length}):`);
+        for (const warning of result.warnings) {
+            lines.push(`  ${warning.path || '/'}: ${warning.message}`);
+        }
+    }
+
+    return lines.join('\n');
+}