@sentriflow/core 0.2.0 → 0.3.0

package/README.md

@@ -20,6 +20,7 @@ bun add @sentriflow/core
 - **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
+- **GRX2 Loader**: Load and decrypt extended encrypted rule packs for offline usage
 - **TypeScript native**: Full type safety with comprehensive type definitions
 
 ## Supported Vendors
@@ -104,6 +105,71 @@ const summary = extractIPSummary(config);
 - `includeSubnetNetworks`: Include subnet network addresses in address lists
 - `skipIPv4`, `skipIPv6`, `skipSubnets`: Skip specific extraction types
 
+## GRX2 Loader Module
+
+The `grx2-loader` module provides functionality for loading extended encrypted rule packs (.grx2). These packs embed wrapped encryption keys, enabling offline scanning without network access.
+
+### Exported Functions
+
+```typescript
+import {
+  loadExtendedPack,
+  loadAllPacks,
+  getPackInfo,
+  getMachineId,
+  getMachineIdSync,
+  isExtendedGRX2,
+} from '@sentriflow/core/grx2-loader';
+```
+
+| Function | Description |
+|----------|-------------|
+| `loadExtendedPack(filePath, licenseKey, machineId?)` | Load and decrypt a single GRX2 pack |
+| `loadAllPacks(directory, licenseKey, machineId?)` | Load all GRX2 packs from a directory |
+| `getPackInfo(filePath)` | Get metadata from a pack without decrypting |
+| `getMachineId()` | Get the current machine identifier (async) |
+| `getMachineIdSync()` | Get the current machine identifier (sync) |
+| `isExtendedGRX2(buffer)` | Check if a buffer contains an extended GRX2 pack |
+
+### Types
+
+```typescript
+import type {
+  GRX2ExtendedHeader,
+  GRX2PackLoadResult,
+  EncryptedPackInfo,
+  EncryptedPackErrorCode,
+  LicensePayload,
+} from '@sentriflow/core/grx2-loader';
+
+import { EncryptedPackError } from '@sentriflow/core/grx2-loader';
+```
+
+### Example Usage
+
+```typescript
+import { loadExtendedPack, getMachineId } from '@sentriflow/core/grx2-loader';
+
+const licenseKey = process.env.SENTRIFLOW_LICENSE_KEY;
+const machineId = await getMachineId();
+
+try {
+  const result = await loadExtendedPack('./rules.grx2', licenseKey, machineId);
+  if (result.success) {
+    console.log(`Loaded ${result.totalRules} rules`);
+  }
+} catch (error) {
+  if (error instanceof EncryptedPackError) {
+    console.error(`Pack error: ${error.code} - ${error.message}`);
+  }
+}
+```
+
+### Machine-Bound vs Portable Packs
+
+- **Portable packs**: Pass empty string for `machineId` parameter
+- **Machine-bound packs**: Pass the result of `getMachineId()` for device-specific binding
+
 ## Related Packages
 
 - [`@sentriflow/cli`](https://github.com/sentriflow/sentriflow/tree/main/packages/cli) - Command-line interface

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@sentriflow/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SentriFlow core engine for network configuration validation",
   "license": "Apache-2.0",
   "module": "src/index.ts",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./grx2-loader": "./src/grx2-loader/index.ts",
     "./helpers": "./src/helpers/index.ts",
     "./helpers/common": "./src/helpers/common/index.ts",
     "./helpers/arista": "./src/helpers/arista/index.ts",
@@ -51,8 +52,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "node-machine-id": "^1.1.12"
+  },
   "devDependencies": {
-    "bun-types": "latest"
+    "bun-types": "latest",
+    "@types/node": "^20.0.0"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/constants.ts

@@ -23,9 +23,12 @@ export const MAX_TRAVERSAL_DEPTH = 20;
 /** Allowed extensions for config/rules files */
 export const ALLOWED_CONFIG_EXTENSIONS = ['.js', '.ts', '.mjs', '.cjs'];
 
-/** SEC-012: Allowed extensions for encrypted rule packs */
+/** SEC-012: Allowed extensions for encrypted rule packs (.grpx legacy format) */
 export const ALLOWED_ENCRYPTED_PACK_EXTENSIONS = ['.grpx'];
 
+/** Allowed extensions for GRX2 extended encrypted rule packs */
+export const ALLOWED_GRX2_PACK_EXTENSIONS = ['.grx2'];
+
 /** Allowed extensions for JSON rule files */
 export const ALLOWED_JSON_RULES_EXTENSIONS = ['.json'];
 

package/src/engine/RuleExecutor.ts

@@ -16,6 +16,8 @@ export interface ExecutionOptions {
   onTimeout?: (ruleId: string, nodeId: string, elapsedMs: number) => void;
   /** Callback when a rule is auto-disabled */
   onRuleDisabled?: (ruleId: string, reason: string) => void;
+  /** Callback when a rule throws an error during execution */
+  onError?: (ruleId: string, nodeId: string, error: unknown) => void;
 }
 
 /**
@@ -55,7 +57,7 @@ export class RuleExecutor {
   private timeoutCounts = new Map<string, number>();
   private executionTimes = new Map<string, { count: number; totalMs: number }>();
   private disabledRules = new Set<string>();
-  private options: Required<ExecutionOptions>;
+  private options: Required<Omit<ExecutionOptions, 'onError'>> & Pick<ExecutionOptions, 'onError'>;
 
   constructor(options: ExecutionOptions = {}) {
     this.options = {
@@ -63,6 +65,7 @@ export class RuleExecutor {
       maxTimeouts: options.maxTimeouts ?? 3,
       onTimeout: options.onTimeout ?? (() => {}),
       onRuleDisabled: options.onRuleDisabled ?? (() => {}),
+      onError: options.onError,
     };
   }
 
@@ -103,6 +106,9 @@ export class RuleExecutor {
       const elapsed = performance.now() - startTime;
       this.trackExecutionTime(rule.id, elapsed);
 
+      // Call error callback if provided (for debugging)
+      this.options.onError?.(rule.id, node.id, error);
+
       // SEC-005: Sanitize error message to prevent information disclosure
       // Don't expose internal error details which could reveal file paths or sensitive data
       return {