@opena2a/oasb 0.1.0

package/src/e2e/E2E-003.live-network-detection.test.ts

@@ -0,0 +1,114 @@
+// E2E-003: Live Network Detection
+// Proves ARP's NetworkMonitor detects real TCP connections via lsof/ss polling.
+// No event injection — the monitor polls the OS network state directly.
+//
+// NOTE: Requires lsof (macOS) or ss (Linux) to be available.
+// Test skips gracefully if neither tool is present.
+//
+// ATLAS: AML.T0024
+// OWASP: A04
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { execSync } from 'child_process';
+import * as net from 'net';
+import * as os from 'os';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+function hasNetworkTool(): boolean {
+  try {
+    if (os.platform() === 'darwin') {
+      execSync('which lsof', { encoding: 'utf-8', timeout: 2000 });
+    } else {
+      execSync('which ss', { encoding: 'utf-8', timeout: 2000 });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+describe('E2E-003: Live Network Detection', () => {
+  let networkAvailable: boolean;
+
+  beforeAll(() => {
+    networkAvailable = hasNetworkTool();
+  });
+
+  let arp: ArpWrapper;
+  let server: net.Server;
+  let serverPort: number;
+  let clientSocket: net.Socket | null = null;
+
+  beforeEach(async () => {
+    if (!networkAvailable) return;
+
+    // Start a local TCP server on a random port
+    server = net.createServer((socket) => {
+      socket.on('data', (data) => socket.write(data));
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        if (addr && typeof addr === 'object') {
+          serverPort = addr.port;
+        }
+        resolve();
+      });
+    });
+
+    arp = new ArpWrapper({
+      monitors: {
+        process: false,
+        network: true,
+        filesystem: false,
+      },
+      networkIntervalMs: 1000,
+    });
+    await arp.start();
+
+    // Let the initial snapshot complete
+    await new Promise((r) => setTimeout(r, 1100));
+  });
+
+  afterEach(async () => {
+    if (!networkAvailable) return;
+
+    if (clientSocket) {
+      clientSocket.destroy();
+      clientSocket = null;
+    }
+    await arp.stop();
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  });
+
+  it('should detect a new outbound TCP connection', async () => {
+    if (!networkAvailable) {
+      console.log('SKIP: lsof/ss not available — network E2E test requires system tools');
+      return;
+    }
+
+    clientSocket = net.connect({ host: '127.0.0.1', port: serverPort });
+
+    await new Promise<void>((resolve, reject) => {
+      clientSocket!.on('connect', resolve);
+      clientSocket!.on('error', reject);
+    });
+
+    // Send data to ensure connection is fully active
+    clientSocket.write('test-payload');
+
+    const event = await arp.waitForEvent(
+      (e) =>
+        e.source === 'network' &&
+        e.data.remotePort === serverPort,
+      15000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.source).toBe('network');
+    expect(event.data.remotePort).toBe(serverPort);
+  });
+});

package/src/e2e/E2E-004.interceptor-process.test.ts

@@ -0,0 +1,125 @@
+// E2E-004: Process Interceptor — Zero-Latency Detection
+// Proves ARP's ProcessInterceptor catches child_process.spawn/exec BEFORE execution.
+// Unlike the polling ProcessMonitor, this has zero detection latency and 100% accuracy.
+//
+// ATLAS: AML.T0046
+// OWASP: A04
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import type { ChildProcess } from 'child_process';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+// Use require() to get the same CJS module the interceptor patches
+// (ESM imports are snapshots and won't reflect interceptor patches)
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cp = require('child_process');
+
+describe('E2E-004: Process Interceptor', () => {
+  let arp: ArpWrapper;
+  const children: ChildProcess[] = [];
+
+  beforeEach(async () => {
+    arp = new ArpWrapper({
+      monitors: {
+        process: false,
+        network: false,
+        filesystem: false,
+      },
+      interceptors: {
+        process: true,
+      },
+    });
+    await arp.start();
+  });
+
+  afterEach(async () => {
+    for (const child of children) {
+      try { child.kill('SIGKILL'); } catch { /* already dead */ }
+    }
+    children.length = 0;
+    await arp.stop();
+  });
+
+  it('should intercept spawn() with zero latency', async () => {
+    const child = cp.spawn('echo', ['hello'], { stdio: 'ignore' });
+    children.push(child);
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const echoEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'process' && e.data.binary === 'echo',
+    );
+
+    expect(echoEvent).toBeDefined();
+    expect(echoEvent!.data.intercepted).toBe(true);
+    expect(echoEvent!.data.command).toContain('echo');
+  });
+
+  it('should detect suspicious binary via interceptor', async () => {
+    const child = cp.spawn('curl', ['--version'], { stdio: 'ignore' });
+    children.push(child);
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const curlEvent = events.find(
+      (e: { source: string; category: string; data: Record<string, unknown> }) =>
+        e.source === 'process' && e.data.binary === 'curl',
+    );
+
+    expect(curlEvent).toBeDefined();
+    expect(curlEvent!.category).toBe('violation');
+    expect(curlEvent!.severity).toBe('high');
+    expect(curlEvent!.data.suspicious).toBe(true);
+    expect(curlEvent!.data.intercepted).toBe(true);
+  });
+
+  it('should intercept exec() shell commands', async () => {
+    const child = cp.exec('echo test-exec', () => {});
+    children.push(child);
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const execEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'process' &&
+        typeof e.data.command === 'string' &&
+        e.data.command.includes('echo test-exec'),
+    );
+
+    expect(execEvent).toBeDefined();
+    expect(execEvent!.data.intercepted).toBe(true);
+  });
+
+  it('should detect suspicious binary in exec() command', async () => {
+    const child = cp.exec('curl --version', () => {});
+    children.push(child);
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const curlEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'process' && e.data.binary === 'curl',
+    );
+
+    expect(curlEvent).toBeDefined();
+    expect(curlEvent!.category).toBe('violation');
+    expect(curlEvent!.severity).toBe('high');
+  });
+
+  it('should restore original functions after stop', async () => {
+    await arp.stop();
+
+    const child = cp.spawn('echo', ['after-stop'], { stdio: 'ignore' });
+    children.push(child);
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    expect(events.length).toBe(0);
+  });
+});

package/src/e2e/E2E-005.interceptor-network.test.ts

@@ -0,0 +1,134 @@
+// E2E-005: Network Interceptor — Zero-Latency Connection Detection
+// Proves ARP's NetworkInterceptor catches net.Socket.connect BEFORE connection.
+// Unlike lsof/ss polling, this works everywhere and has zero detection latency.
+//
+// ATLAS: AML.T0024, AML.T0057
+// OWASP: A04
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as net from 'net';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+describe('E2E-005: Network Interceptor', () => {
+  let arp: ArpWrapper;
+  let server: net.Server;
+  let serverPort: number;
+  let clientSocket: net.Socket | null = null;
+
+  beforeEach(async () => {
+    // Start a local TCP server
+    server = net.createServer((socket) => {
+      socket.on('data', (data) => socket.write(data));
+    });
+
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => {
+        const addr = server.address();
+        if (addr && typeof addr === 'object') {
+          serverPort = addr.port;
+        }
+        resolve();
+      });
+    });
+
+    arp = new ArpWrapper({
+      monitors: {
+        process: false,
+        network: false, // Disable polling monitor
+        filesystem: false,
+      },
+      interceptors: {
+        network: true, // Enable interceptor
+      },
+    });
+    await arp.start();
+  });
+
+  afterEach(async () => {
+    if (clientSocket) {
+      clientSocket.destroy();
+      clientSocket = null;
+    }
+    await arp.stop();
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+  });
+
+  it('should intercept outbound TCP connection with zero latency', async () => {
+    clientSocket = net.connect({ host: '127.0.0.1', port: serverPort });
+
+    // Wait for connection event (should be nearly instant)
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const connEvent = events.find(
+      (e) =>
+        e.source === 'network' &&
+        e.data.remotePort === serverPort,
+    );
+
+    expect(connEvent).toBeDefined();
+    expect(connEvent!.data.intercepted).toBe(true);
+    expect(connEvent!.data.remoteAddr).toBe('127.0.0.1');
+    expect(connEvent!.data.remotePort).toBe(serverPort);
+  });
+
+  it('should classify connections to allowed hosts as normal', async () => {
+    // Restart with allowed hosts
+    await arp.stop();
+    arp = new ArpWrapper({
+      monitors: { process: false, network: false, filesystem: false },
+      interceptors: { network: true },
+      interceptorNetworkAllowedHosts: ['127.0.0.1'],
+    });
+    await arp.start();
+
+    clientSocket = net.connect({ host: '127.0.0.1', port: serverPort });
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const connEvent = events.find(
+      (e) => e.source === 'network' && e.data.remotePort === serverPort,
+    );
+
+    expect(connEvent).toBeDefined();
+    expect(connEvent!.category).toBe('normal');
+    expect(connEvent!.data.allowed).toBe(true);
+  });
+
+  it('should classify connections to non-allowed hosts as anomaly', async () => {
+    // Restart with restricted allowed hosts (not including 127.0.0.1)
+    await arp.stop();
+    arp = new ArpWrapper({
+      monitors: { process: false, network: false, filesystem: false },
+      interceptors: { network: true },
+      interceptorNetworkAllowedHosts: ['api.example.com'],
+    });
+    await arp.start();
+
+    clientSocket = net.connect({ host: '127.0.0.1', port: serverPort });
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const connEvent = events.find(
+      (e) => e.source === 'network' && e.data.remotePort === serverPort,
+    );
+
+    expect(connEvent).toBeDefined();
+    expect(connEvent!.category).toBe('anomaly');
+    expect(connEvent!.severity).toBe('medium');
+    expect(connEvent!.data.allowed).toBe(false);
+  });
+
+  it('should restore net.Socket after stop', async () => {
+    await arp.stop();
+
+    // After stop, connections should not generate events
+    clientSocket = net.connect({ host: '127.0.0.1', port: serverPort });
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    expect(events.length).toBe(0);
+  });
+});

package/src/e2e/E2E-006.interceptor-filesystem.test.ts

@@ -0,0 +1,140 @@
+// E2E-006: Filesystem Interceptor — Zero-Latency File Operation Detection
+// Proves ARP's FilesystemInterceptor catches fs.readFile/writeFile BEFORE I/O.
+// Unlike fs.watch, this catches reads, works on ALL paths, and has zero latency.
+//
+// ATLAS: AML.T0057, AML.T0018
+// OWASP: A07
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as path from 'path';
+import * as os from 'os';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+// Use require() to get the same CJS module the interceptor patches
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require('fs');
+
+describe('E2E-006: Filesystem Interceptor', () => {
+  let arp: ArpWrapper;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arp-e2e-fsi-'));
+
+    arp = new ArpWrapper({
+      monitors: {
+        process: false,
+        network: false,
+        filesystem: false,
+      },
+      interceptors: {
+        filesystem: true,
+      },
+    });
+    await arp.start();
+  });
+
+  afterEach(async () => {
+    await arp.stop();
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // best effort
+    }
+  });
+
+  it('should intercept writeFileSync to sensitive .env path', async () => {
+    const envPath = path.join(tmpDir, '.env');
+    fs.writeFileSync(envPath, 'SECRET=intercepted\n');
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const writeEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'filesystem' &&
+        e.data.intercepted === true &&
+        String(e.data.path).includes('.env'),
+    );
+
+    expect(writeEvent).toBeDefined();
+    expect(writeEvent!.category).toBe('violation');
+    expect(writeEvent!.severity).toBe('high');
+    expect(writeEvent!.data.sensitive).toBe(true);
+    expect(writeEvent!.data.operation).toBe('writeFileSync');
+  });
+
+  it('should intercept readFileSync on sensitive .ssh path', async () => {
+    const sshPath = path.join(tmpDir, '.ssh');
+    fs.mkdirSync(sshPath, { recursive: true });
+    const keyPath = path.join(sshPath, 'id_rsa');
+    fs.writeFileSync(keyPath, 'fake-key\n');
+
+    // Now read it
+    fs.readFileSync(keyPath, 'utf-8');
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const readEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'filesystem' &&
+        e.data.operation === 'read' &&
+        String(e.data.path).includes('.ssh'),
+    );
+
+    expect(readEvent).toBeDefined();
+    expect(readEvent!.category).toBe('violation');
+    expect(readEvent!.severity).toBe('high');
+    expect(readEvent!.data.sensitive).toBe(true);
+  });
+
+  it('should intercept normal file writes without marking as violation', async () => {
+    const normalPath = path.join(tmpDir, 'output.json');
+    fs.writeFileSync(normalPath, '{"ok": true}\n');
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const writeEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'filesystem' &&
+        e.data.intercepted === true &&
+        String(e.data.path).includes('output.json'),
+    );
+
+    expect(writeEvent).toBeDefined();
+    expect(writeEvent!.category).toBe('normal');
+    expect(writeEvent!.severity).toBe('info');
+  });
+
+  it('should intercept .bashrc write as persistence attempt', async () => {
+    const bashrcPath = path.join(tmpDir, '.bashrc');
+    fs.writeFileSync(bashrcPath, 'alias x="malicious"\n');
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    const bashrcEvent = events.find(
+      (e: { source: string; data: Record<string, unknown> }) =>
+        e.source === 'filesystem' &&
+        String(e.data.path).includes('.bashrc'),
+    );
+
+    expect(bashrcEvent).toBeDefined();
+    expect(bashrcEvent!.category).toBe('violation');
+    expect(bashrcEvent!.severity).toBe('high');
+  });
+
+  it('should restore fs module after stop', async () => {
+    await arp.stop();
+
+    const normalPath = path.join(tmpDir, 'after-stop.txt');
+    fs.writeFileSync(normalPath, 'no events\n');
+
+    await new Promise((r) => setTimeout(r, 50));
+
+    const events = arp.collector.getEvents();
+    expect(events.length).toBe(0);
+  });
+});

package/src/harness/arp-wrapper.ts

@@ -0,0 +1,121 @@
+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';
+
+/**
+ * Wraps AgentRuntimeProtection for controlled testing.
+ * Creates temp dataDir per test, registers EventCollector,
+ * and provides injection + assertion helpers.
+ */
+export class ArpWrapper {
+  private arp: AgentRuntimeProtection;
+  private _dataDir: string;
+  readonly collector: EventCollector;
+
+  constructor(labConfig?: LabConfig) {
+    this._dataDir = labConfig?.dataDir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'arp-lab-'));
+
+    const config: ARPConfig = {
+      agentName: 'arp-lab-target',
+      agentDescription: 'Test target for ARP security lab',
+      declaredCapabilities: ['file read/write', 'HTTP requests'],
+      dataDir: this._dataDir,
+      monitors: {
+        process: {
+          enabled: labConfig?.monitors?.process ?? false,
+          intervalMs: labConfig?.processIntervalMs,
+        },
+        network: {
+          enabled: labConfig?.monitors?.network ?? false,
+          intervalMs: labConfig?.networkIntervalMs,
+          allowedHosts: labConfig?.networkAllowedHosts,
+        },
+        filesystem: {
+          enabled: labConfig?.monitors?.filesystem ?? false,
+          watchPaths: labConfig?.filesystemWatchPaths,
+          allowedPaths: labConfig?.filesystemAllowedPaths,
+        },
+      },
+      rules: labConfig?.rules,
+      intelligence: {
+        enabled: labConfig?.intelligence?.enabled ?? false,
+        budgetUsd: 0,
+      },
+      interceptors: {
+        process: { enabled: labConfig?.interceptors?.process ?? false },
+        network: {
+          enabled: labConfig?.interceptors?.network ?? false,
+          allowedHosts: labConfig?.interceptorNetworkAllowedHosts,
+        },
+        filesystem: {
+          enabled: labConfig?.interceptors?.filesystem ?? false,
+          allowedPaths: labConfig?.interceptorFilesystemAllowedPaths,
+        },
+      },
+    };
+
+    this.arp = new AgentRuntimeProtection(config);
+    this.collector = new EventCollector();
+
+    // Register event and enforcement collectors
+    this.arp.onEvent(this.collector.eventHandler);
+    this.arp.onEnforcement(this.collector.enforcementHandler);
+  }
+
+  async start(): Promise<void> {
+    await this.arp.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.arp.stop();
+    this.collector.reset();
+    // Clean up temp dir
+    try {
+      fs.rmSync(this._dataDir, { recursive: true, force: true });
+    } catch {
+      // Best effort cleanup
+    }
+  }
+
+  /** Get the underlying ARP instance */
+  getInstance(): AgentRuntimeProtection {
+    return this.arp;
+  }
+
+  /** Get the event engine for direct event injection */
+  getEngine(): EventEngine {
+    return this.arp.getEngine();
+  }
+
+  /** Get the enforcement engine */
+  getEnforcement(): EnforcementEngine {
+    return this.arp.getEnforcement();
+  }
+
+  /** 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);
+  }
+
+  /** Wait for an event matching a predicate */
+  waitForEvent(
+    predicate: (event: ARPEvent) => boolean,
+    timeoutMs: number = 10000,
+  ): Promise<ARPEvent> {
+    return this.collector.waitForEvent(predicate, timeoutMs);
+  }
+
+  /** Get the data directory */
+  get dataDir(): string {
+    return this._dataDir;
+  }
+}