@opena2a/oasb 0.2.0 → 0.3.1

package/src/atomic/intelligence/AT-INT-005.baseline-learning.test.ts

@@ -8,11 +8,11 @@
 // so the detector returns to its initial state.
 
 import { describe, it, expect } from 'vitest';
-import { AnomalyDetector } from '@opena2a/arp';
-import type { ARPEvent } from '@opena2a/arp';
+import { createAdapter } from '../../harness/create-adapter';
+import type { SecurityEvent, AnomalyScorer } from '../../harness/adapter';
 
-/** Create a minimal ARPEvent for the given source. */
-function makeEvent(source: ARPEvent['source']): ARPEvent {
+/** Create a minimal SecurityEvent for the given source. */
+function makeEvent(source: SecurityEvent['source']): SecurityEvent {
   return {
     id: crypto.randomUUID(),
     timestamp: new Date().toISOString(),
@@ -27,7 +27,7 @@ function makeEvent(source: ARPEvent['source']): ARPEvent {
 
 describe('AT-INT-005: Baseline Learning', () => {
   it('should establish a baseline after recording many events', () => {
-    const detector = new AnomalyDetector();
+    const detector = createAdapter().createAnomalyScorer();
 
     // Feed 50 observations to build a solid baseline for the 'network' source
     for (let i = 0; i < 50; i++) {
@@ -41,7 +41,7 @@ describe('AT-INT-005: Baseline Learning', () => {
   });
 
   it('should return low anomaly score for events matching the baseline', () => {
-    const detector = new AnomalyDetector();
+    const detector = createAdapter().createAnomalyScorer();
 
     // Build baseline with consistent frequency
     for (let i = 0; i < 50; i++) {
@@ -54,7 +54,7 @@ describe('AT-INT-005: Baseline Learning', () => {
   });
 
   it('should track baselines independently per source', () => {
-    const detector = new AnomalyDetector();
+    const detector = createAdapter().createAnomalyScorer();
 
     // Build baseline for 'network' only
     for (let i = 0; i < 50; i++) {
@@ -71,7 +71,7 @@ describe('AT-INT-005: Baseline Learning', () => {
   });
 
   it('should clear all baselines on reset and return score 0', () => {
-    const detector = new AnomalyDetector();
+    const detector = createAdapter().createAnomalyScorer();
 
     // Build baselines for two sources
     for (let i = 0; i < 50; i++) {
@@ -94,7 +94,7 @@ describe('AT-INT-005: Baseline Learning', () => {
   });
 
   it('should differentiate between sources with different baselines', () => {
-    const detector = new AnomalyDetector();
+    const detector = createAdapter().createAnomalyScorer();
 
     // Build baseline for 'network' with many events
     for (let i = 0; i < 50; i++) {

package/src/baseline/BL-002.anomaly-injection.test.ts

@@ -7,11 +7,11 @@
 // the detection threshold.
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { AnomalyDetector } from '@opena2a/arp';
-import type { ARPEvent } from '@opena2a/arp';
+import { createAdapter } from '../harness/create-adapter';
+import type { SecurityEvent, AnomalyScorer } from '../harness/adapter';
 
-/** Helper: create a minimal ARPEvent for a given source */
-function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): ARPEvent {
+/** Helper: create a minimal SecurityEvent for a given source */
+function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): SecurityEvent {
   return {
     id: `bl002-${source}-${index}`,
     timestamp: new Date().toISOString(),
@@ -25,10 +25,10 @@ function makeEvent(source: 'process' | 'network' | 'filesystem', index: number):
 }
 
 describe('BL-002: Controlled Anomaly Injection', () => {
-  let detector: AnomalyDetector;
+  let detector: AnomalyScorer;
 
   beforeEach(() => {
-    detector = new AnomalyDetector();
+    detector = createAdapter().createAnomalyScorer();
   });
 
   it('should return z-score 0 before baseline is established', () => {

package/src/baseline/BL-003.baseline-persistence.test.ts

@@ -7,11 +7,11 @@
 // would need to serialize baselines to disk or a database to survive restarts.
 
 import { describe, it, expect, beforeEach } from 'vitest';
-import { AnomalyDetector } from '@opena2a/arp';
-import type { ARPEvent } from '@opena2a/arp';
+import { createAdapter } from '../harness/create-adapter';
+import type { SecurityEvent, AnomalyScorer } from '../harness/adapter';
 
-/** Helper: create a minimal ARPEvent for a given source */
-function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): ARPEvent {
+/** Helper: create a minimal SecurityEvent for a given source */
+function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): SecurityEvent {
   return {
     id: `bl003-${source}-${index}`,
     timestamp: new Date().toISOString(),
@@ -25,10 +25,10 @@ function makeEvent(source: 'process' | 'network' | 'filesystem', index: number):
 }
 
 describe('BL-003: Baseline Persistence Across Restarts', () => {
-  let detector: AnomalyDetector;
+  let detector: AnomalyScorer;
 
   beforeEach(() => {
-    detector = new AnomalyDetector();
+    detector = createAdapter().createAnomalyScorer();
   });
 
   it('should accumulate baseline data during a session', () => {
@@ -53,7 +53,7 @@ describe('BL-003: Baseline Persistence Across Restarts', () => {
     expect(baselineBefore).not.toBeNull();
 
     // Simulate restart: create a new AnomalyDetector instance
-    const restartedDetector = new AnomalyDetector();
+    const restartedDetector = createAdapter().createAnomalyScorer();
 
     // KNOWN GAP: baseline is lost after restart
     const baselineAfter = restartedDetector.getBaseline('process');
@@ -88,7 +88,7 @@ describe('BL-003: Baseline Persistence Across Restarts', () => {
     }
 
     // Simulate restart
-    const restartedDetector = new AnomalyDetector();
+    const restartedDetector = createAdapter().createAnomalyScorer();
 
     // KNOWN GAP: all baselines lost
     for (const source of sources) {
@@ -107,7 +107,7 @@ describe('BL-003: Baseline Persistence Across Restarts', () => {
     const originalMean = originalBaseline!.mean;
 
     // Simulate restart
-    const restartedDetector = new AnomalyDetector();
+    const restartedDetector = createAdapter().createAnomalyScorer();
 
     // Feed the same number of events to the restarted detector
     for (let i = 0; i < 50; i++) {

package/src/harness/adapter.ts

@@ -0,0 +1,261 @@
+/**
+ * OASB Security Product Adapter Interface
+ *
+ * Implement this interface to evaluate your security product against OASB.
+ * The reference implementation (ARP adapter) is in arp-wrapper.ts.
+ *
+ * @example
+ *   // Vendor implements the adapter for their product:
+ *   class MyProductAdapter implements SecurityProductAdapter { ... }
+ *
+ *   // OASB tests use the adapter, not your product directly:
+ *   const adapter = createAdapter(); // returns configured adapter
+ *   await adapter.start();
+ *   await adapter.injectEvent({ ... });
+ *   const threats = adapter.getEventsByCategory('threat');
+ */
+
+// ─── Core Event Types ───────────────────────────────────────────────
+
+export type EventCategory = 'normal' | 'activity' | 'threat' | 'violation';
+export type EventSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical';
+export type MonitorSource = 'process' | 'network' | 'filesystem' | 'prompt' | 'mcp-protocol' | 'a2a-protocol' | string;
+export type EnforcementAction = 'log' | 'alert' | 'pause' | 'kill' | 'resume';
+
+export interface SecurityEvent {
+  id?: string;
+  timestamp?: string;
+  source: MonitorSource;
+  category: EventCategory;
+  severity: EventSeverity;
+  description: string;
+  data?: Record<string, unknown>;
+  classifiedBy?: string;
+}
+
+export interface EnforcementResult {
+  action: EnforcementAction;
+  success: boolean;
+  reason: string;
+  event: SecurityEvent;
+  pid?: number;
+}
+
+export interface AlertRule {
+  name: string;
+  condition: AlertCondition;
+  action: EnforcementAction;
+}
+
+export interface AlertCondition {
+  source?: MonitorSource;
+  category?: EventCategory;
+  minSeverity?: EventSeverity;
+  descriptionContains?: string;
+}
+
+// ─── Scanner Types ──────────────────────────────────────────────────
+
+export interface ScanResult {
+  detected: boolean;
+  matches: ScanMatch[];
+  truncated?: boolean;
+}
+
+export interface ScanMatch {
+  pattern: ThreatPattern;
+  matchedText: string;
+}
+
+export interface ThreatPattern {
+  id: string;
+  category: string;
+  description: string;
+  pattern: RegExp;
+  severity: 'medium' | 'high' | 'critical';
+}
+
+// ─── Scanner Interfaces ─────────────────────────────────────────────
+
+export interface PromptScanner {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  scanInput(text: string): ScanResult;
+  scanOutput(text: string): ScanResult;
+}
+
+export interface MCPScanner {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  scanToolCall(toolName: string, params: Record<string, unknown>): ScanResult;
+}
+
+export interface A2AScanner {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  scanMessage(from: string, to: string, content: string): ScanResult;
+}
+
+export interface PatternScanner {
+  scanText(text: string, patterns: readonly ThreatPattern[]): ScanResult;
+  getAllPatterns(): readonly ThreatPattern[];
+  getPatternSets(): Record<string, readonly ThreatPattern[]>;
+}
+
+// ─── Intelligence Interfaces ────────────────────────────────────────
+
+export interface BudgetStatus {
+  spent: number;
+  budget: number;
+  remaining: number;
+  percentUsed: number;
+  callsThisHour: number;
+  maxCallsPerHour: number;
+  totalCalls: number;
+}
+
+export interface BudgetManager {
+  canAfford(estimatedCostUsd: number): boolean;
+  record(costUsd: number, tokens: number): void;
+  getStatus(): BudgetStatus;
+  reset(): void;
+}
+
+export interface AnomalyScorer {
+  score(event: SecurityEvent): number;
+  record(event: SecurityEvent): void;
+  getBaseline(source: string): { mean: number; stddev: number; count: number } | null;
+  reset(): void;
+}
+
+// ─── LLM Adapter (for mock testing) ────────────────────────────────
+
+export interface LLMAdapter {
+  name: string;
+  assess(prompt: string): Promise<LLMResponse>;
+}
+
+export interface LLMResponse {
+  content: string;
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+// ─── Event Engine Interface ─────────────────────────────────────────
+
+export interface EventEngine {
+  emit(event: Omit<SecurityEvent, 'id' | 'timestamp' | 'classifiedBy'>): SecurityEvent;
+  onEvent(handler: (event: SecurityEvent) => void | Promise<void>): void;
+}
+
+// ─── Enforcement Interface ──────────────────────────────────────────
+
+export interface EnforcementEngine {
+  execute(action: EnforcementAction, event: SecurityEvent): Promise<EnforcementResult>;
+  pause(pid: number): boolean;
+  resume(pid: number): boolean;
+  kill(pid: number, signal?: string): boolean;
+  getPausedPids(): number[];
+  setAlertCallback(callback: (event: SecurityEvent, rule: AlertRule) => void): void;
+}
+
+// ─── Capability Declaration ─────────────────────────────────────────
+
+/**
+ * Capabilities that a security product may or may not support.
+ * Adapters declare their capabilities via getCapabilities().
+ * Tests check capabilities before running — unsupported tests are
+ * marked N/A instead of FAIL, producing an honest scorecard.
+ */
+export type Capability =
+  | 'process-monitoring'
+  | 'network-monitoring'
+  | 'filesystem-monitoring'
+  | 'prompt-input-scanning'
+  | 'prompt-output-scanning'
+  | 'mcp-scanning'
+  | 'a2a-scanning'
+  | 'anomaly-detection'
+  | 'budget-management'
+  | 'enforcement-log'
+  | 'enforcement-alert'
+  | 'enforcement-pause'
+  | 'enforcement-kill'
+  | 'enforcement-resume'
+  | 'pattern-scanning'
+  | 'event-correlation';
+
+/** Full capability declaration for a product */
+export interface CapabilityMatrix {
+  /** Product name */
+  product: string;
+  /** Product version */
+  version: string;
+  /** Set of supported capabilities */
+  capabilities: Set<Capability>;
+}
+
+// ─── Main Adapter Interface ─────────────────────────────────────────
+
+export interface SecurityProductAdapter {
+  /** Declare which capabilities this product supports */
+  getCapabilities(): CapabilityMatrix;
+
+  /** Start the security product */
+  start(): Promise<void>;
+  /** Stop the security product */
+  stop(): Promise<void>;
+
+  /** Inject a synthetic event for testing */
+  injectEvent(event: Omit<SecurityEvent, 'id' | 'timestamp' | 'classifiedBy'>): Promise<SecurityEvent>;
+
+  /** Wait for an event matching a predicate */
+  waitForEvent(predicate: (event: SecurityEvent) => boolean, timeoutMs?: number): Promise<SecurityEvent>;
+
+  /** Get collected events */
+  getEvents(): SecurityEvent[];
+  getEventsByCategory(category: EventCategory): SecurityEvent[];
+  getEnforcements(): EnforcementResult[];
+  getEnforcementsByAction(action: EnforcementAction): EnforcementResult[];
+
+  /** Reset collected events */
+  resetCollector(): void;
+
+  /** Access sub-components (for tests that need direct access) */
+  getEventEngine(): EventEngine;
+  getEnforcementEngine(): EnforcementEngine;
+
+  /** Factory methods for component-level testing */
+  createPromptScanner(): PromptScanner;
+  createMCPScanner(allowedTools?: string[]): MCPScanner;
+  createA2AScanner(trustedAgents?: string[]): A2AScanner;
+  createPatternScanner(): PatternScanner;
+  createBudgetManager(dataDir: string, config?: { budgetUsd?: number; maxCallsPerHour?: number }): BudgetManager;
+  createAnomalyScorer(): AnomalyScorer;
+}
+
+// ─── Lab Config ─────────────────────────────────────────────────────
+
+export interface LabConfig {
+  monitors?: {
+    process?: boolean;
+    network?: boolean;
+    filesystem?: boolean;
+  };
+  rules?: AlertRule[];
+  intelligence?: {
+    enabled?: boolean;
+  };
+  dataDir?: string;
+  filesystemWatchPaths?: string[];
+  filesystemAllowedPaths?: string[];
+  networkAllowedHosts?: string[];
+  processIntervalMs?: number;
+  networkIntervalMs?: number;
+  interceptors?: {
+    process?: boolean;
+    network?: boolean;
+    filesystem?: boolean;
+  };
+  interceptorNetworkAllowedHosts?: string[];
+  interceptorFilesystemAllowedPaths?: string[];
+}

package/src/harness/arp-wrapper.ts

@@ -1,30 +1,55 @@
+/**
+ * ARP Adapter — Reference implementation of SecurityProductAdapter
+ *
+ * Wraps HackMyAgent's ARP (Agent Runtime Protection) for OASB evaluation.
+ * Other vendors implement their own adapter against the same interface.
+ *
+ * Uses lazy require() for arp-guard so the module is only loaded when
+ * this adapter is actually selected. Tests that use a different adapter
+ * never trigger the arp-guard import.
+ */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import {
-  AgentRuntimeProtection,
-  EventEngine,
-  EnforcementEngine,
-  type ARPConfig,
-  type ARPEvent,
-} from '@opena2a/arp';
 import { EventCollector } from './event-collector';
-import type { LabConfig } from './types';
+import type {
+  SecurityProductAdapter,
+  SecurityEvent,
+  EnforcementResult,
+  LabConfig,
+  PromptScanner,
+  MCPScanner,
+  A2AScanner,
+  PatternScanner,
+  BudgetManager,
+  AnomalyScorer,
+  EventEngine,
+  EnforcementEngine as EnforcementEngineInterface,
+  ScanResult,
+  ThreatPattern,
+  CapabilityMatrix,
+} from './adapter';
 
-/**
- * Wraps AgentRuntimeProtection for controlled testing.
- * Creates temp dataDir per test, registers EventCollector,
- * and provides injection + assertion helpers.
- */
-export class ArpWrapper {
-  private arp: AgentRuntimeProtection;
+// Lazy-loaded arp-guard module
+let _arp: any;
+function arp(): any {
+  if (!_arp) {
+    _arp = require('arp-guard');
+  }
+  return _arp;
+}
+
+export class ArpWrapper implements SecurityProductAdapter {
+  private _arpInstance: any;
   private _dataDir: string;
   readonly collector: EventCollector;
 
   constructor(labConfig?: LabConfig) {
     this._dataDir = labConfig?.dataDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'arp-lab-'));
 
-    const config: ARPConfig = {
+    const { AgentRuntimeProtection } = arp();
+
+    const config = {
       agentName: 'arp-lab-target',
       agentDescription: 'Test target for ARP security lab',
       declaredCapabilities: ['file read/write', 'HTTP requests'],
@@ -63,22 +88,44 @@ export class ArpWrapper {
       },
     };
 
-    this.arp = new AgentRuntimeProtection(config);
+    this._arpInstance = new AgentRuntimeProtection(config);
     this.collector = new EventCollector();
 
-    // Register event and enforcement collectors
-    this.arp.onEvent(this.collector.eventHandler);
-    this.arp.onEnforcement(this.collector.enforcementHandler);
+    this._arpInstance.onEvent(this.collector.eventHandler);
+    this._arpInstance.onEnforcement(this.collector.enforcementHandler);
+  }
+
+  getCapabilities(): CapabilityMatrix {
+    return {
+      product: 'arp-guard',
+      version: arp().VERSION || '0.3.0',
+      capabilities: new Set([
+        'process-monitoring',
+        'network-monitoring',
+        'filesystem-monitoring',
+        'prompt-input-scanning',
+        'prompt-output-scanning',
+        'mcp-scanning',
+        'a2a-scanning',
+        'anomaly-detection',
+        'budget-management',
+        'enforcement-log',
+        'enforcement-alert',
+        'enforcement-pause',
+        'enforcement-kill',
+        'enforcement-resume',
+        'pattern-scanning',
+      ]),
+    };
   }
 
   async start(): Promise<void> {
-    await this.arp.start();
+    await this._arpInstance.start();
   }
 
   async stop(): Promise<void> {
-    await this.arp.stop();
+    await this._arpInstance.stop();
     this.collector.reset();
-    // Clean up temp dir
     try {
       fs.rmSync(this._dataDir, { recursive: true, force: true });
     } catch {
@@ -86,36 +133,122 @@ export class ArpWrapper {
     }
   }
 
-  /** Get the underlying ARP instance */
-  getInstance(): AgentRuntimeProtection {
-    return this.arp;
+  async injectEvent(event: Omit<SecurityEvent, 'id' | 'timestamp' | 'classifiedBy'>): Promise<SecurityEvent> {
+    return this.getEngine().emit(event);
   }
 
-  /** Get the event engine for direct event injection */
-  getEngine(): EventEngine {
-    return this.arp.getEngine();
+  waitForEvent(predicate: (event: SecurityEvent) => boolean, timeoutMs: number = 10000): Promise<SecurityEvent> {
+    return this.collector.waitForEvent(predicate, timeoutMs);
   }
 
-  /** Get the enforcement engine */
-  getEnforcement(): EnforcementEngine {
-    return this.arp.getEnforcement();
+  getEvents(): SecurityEvent[] {
+    return this.collector.getEvents();
   }
 
-  /** Inject a synthetic event into the ARP engine (for testing without real OS activity) */
-  async injectEvent(event: Omit<ARPEvent, 'id' | 'timestamp' | 'classifiedBy'>): Promise<ARPEvent> {
-    return this.getEngine().emit(event);
+  getEventsByCategory(category: string): SecurityEvent[] {
+    return this.collector.eventsByCategory(category);
   }
 
-  /** Wait for an event matching a predicate */
-  waitForEvent(
-    predicate: (event: ARPEvent) => boolean,
-    timeoutMs: number = 10000,
-  ): Promise<ARPEvent> {
-    return this.collector.waitForEvent(predicate, timeoutMs);
+  getEnforcements(): EnforcementResult[] {
+    return this.collector.getEnforcements() as EnforcementResult[];
+  }
+
+  getEnforcementsByAction(action: string): EnforcementResult[] {
+    return this.collector.enforcementsByAction(action) as EnforcementResult[];
+  }
+
+  resetCollector(): void {
+    this.collector.reset();
+  }
+
+  getInstance(): any {
+    return this._arpInstance;
+  }
+
+  getEventEngine(): EventEngine {
+    return this._arpInstance.getEngine() as unknown as EventEngine;
+  }
+
+  getEnforcementEngine(): EnforcementEngineInterface {
+    return this._arpInstance.getEnforcement() as unknown as EnforcementEngineInterface;
+  }
+
+  getEngine(): any {
+    return this._arpInstance.getEngine();
+  }
+
+  getEnforcement(): any {
+    return this._arpInstance.getEnforcement();
   }
 
-  /** Get the data directory */
   get dataDir(): string {
     return this._dataDir;
   }
+
+  // ─── Factory Methods ────────────────────────────────────────────
+
+  createPromptScanner(): PromptScanner {
+    const { EventEngine, PromptInterceptor } = arp();
+    const engine = new EventEngine({ agentName: 'oasb-prompt-test' });
+    const interceptor = new PromptInterceptor(engine);
+    return {
+      start: () => interceptor.start(),
+      stop: () => interceptor.stop(),
+      scanInput: (text: string) => interceptor.scanInput(text),
+      scanOutput: (text: string) => interceptor.scanOutput(text),
+    };
+  }
+
+  createMCPScanner(allowedTools?: string[]): MCPScanner {
+    const { EventEngine, MCPProtocolInterceptor } = arp();
+    const engine = new EventEngine({ agentName: 'oasb-mcp-test' });
+    const interceptor = new MCPProtocolInterceptor(engine, allowedTools);
+    return {
+      start: () => interceptor.start(),
+      stop: () => interceptor.stop(),
+      scanToolCall: (toolName: string, params: Record<string, unknown>) => interceptor.scanToolCall(toolName, params),
+    };
+  }
+
+  createA2AScanner(trustedAgents?: string[]): A2AScanner {
+    const { EventEngine, A2AProtocolInterceptor } = arp();
+    const engine = new EventEngine({ agentName: 'oasb-a2a-test' });
+    const interceptor = new A2AProtocolInterceptor(engine, trustedAgents);
+    return {
+      start: () => interceptor.start(),
+      stop: () => interceptor.stop(),
+      scanMessage: (from: string, to: string, content: string) => interceptor.scanMessage(from, to, content),
+    };
+  }
+
+  createPatternScanner(): PatternScanner {
+    const { scanText: _scanText, ALL_PATTERNS: _allPatterns, PATTERN_SETS: _patternSets } = arp();
+    return {
+      scanText: (text: string, patterns: readonly ThreatPattern[]) => _scanText(text, patterns) as ScanResult,
+      getAllPatterns: () => _allPatterns as unknown as readonly ThreatPattern[],
+      getPatternSets: () => _patternSets as unknown as Record<string, readonly ThreatPattern[]>,
+    };
+  }
+
+  createBudgetManager(dataDir: string, config?: { budgetUsd?: number; maxCallsPerHour?: number }): BudgetManager {
+    const { BudgetController } = arp();
+    const controller = new BudgetController(dataDir, config);
+    return {
+      canAfford: (cost: number) => controller.canAfford(cost),
+      record: (cost: number, tokens: number) => controller.record(cost, tokens),
+      getStatus: () => controller.getStatus(),
+      reset: () => controller.reset(),
+    };
+  }
+
+  createAnomalyScorer(): AnomalyScorer {
+    const { AnomalyDetector } = arp();
+    const detector = new AnomalyDetector();
+    return {
+      score: (event: SecurityEvent) => detector.score(event),
+      record: (event: SecurityEvent) => detector.record(event),
+      getBaseline: (source: string) => detector.getBaseline(source),
+      reset: () => detector.reset(),
+    };
+  }
 }