agent-recon 1.0.1

package/server/fixtures/allowlist-profiles.json

@@ -0,0 +1,185 @@
+{
+  "standard-dev": {
+    "label": "Standard Development",
+    "description": "Suppresses common dev workflow false positives: package managers, build subshells, commit heredocs, credential manager patterns",
+    "rules": [
+      {
+        "scope_cat": "exec",
+        "scope_subcat": "priv-escalation",
+        "pattern": "sudo (apt|apt-get|brew|dnf|yum|pacman|apk|snap|port) ",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Package manager installs are routine system administration"
+      },
+      {
+        "scope_cat": "inject",
+        "scope_subcat": "pipe-injection",
+        "pattern": "git commit.*\\$(cat",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Claude Code standard commit pattern using heredoc"
+      },
+      {
+        "scope_cat": "inject",
+        "scope_subcat": "pipe-injection",
+        "pattern": "GH_TOKEN=\\$(pass ",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Standard credential manager retrieval via pass"
+      },
+      {
+        "scope_cat": "inject",
+        "pattern": "\\$(az (keyvault|account|functionapp|monitor|webapp|storage)",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Azure CLI subshell patterns are standard DevOps workflow"
+      },
+      {
+        "scope_cat": "inject",
+        "scope_subcat": "pipe-injection",
+        "pattern": "\\$((npm bin|which|command -v|nvm |rbenv |pyenv )",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 20,
+        "reason": "Standard tool path resolution subshells"
+      },
+      {
+        "scope_cat": "inject",
+        "scope_subcat": "pipe-injection",
+        "pattern": "\\$((cat |echo |printf |date|basename|dirname|pwd|hostname)",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 20,
+        "reason": "Benign utility command substitutions"
+      },
+      {
+        "scope_cat": "data",
+        "scope_subcat": "exfiltration",
+        "pattern": "curl.*-[dX].*POST.*(localhost|127\\.0\\.0\\.1|agent-recon)",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 15,
+        "reason": "Testing own API endpoints is not exfiltration"
+      },
+      {
+        "scope_cat": "exec",
+        "scope_subcat": "priv-escalation",
+        "pattern": "chmod (644|755|700|600|400)\\b",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Standard file permissions are not privilege escalation"
+      },
+      {
+        "scope_cat": "inject",
+        "scope_subcat": "code-injection",
+        "pattern": "node -e.*(console\\.|require\\(|JSON\\.|process\\.)",
+        "pattern_mode": "regex",
+        "action": "downgrade",
+        "target_risk": "medium",
+        "priority": 30,
+        "reason": "Simple Node.js one-liners for testing module imports and logging"
+      },
+      {
+        "scope_cat": "file",
+        "pattern": "\\.env\\.(example|test|sample|template|development|local)",
+        "pattern_mode": "regex",
+        "action": "suppress",
+        "priority": 15,
+        "reason": "Template and example environment files are not sensitive"
+      },
+      {
+        "scope_cat": "net",
+        "scope_subcat": "network-call",
+        "pattern": "curl",
+        "pattern_mode": "contains",
+        "action": "downgrade",
+        "target_risk": "low",
+        "priority": 50,
+        "reason": "Curl for dev API testing; exfiltration patterns caught by higher-priority rules"
+      },
+      {
+        "scope_cat": "data",
+        "scope_subcat": "exfiltration",
+        "pattern": "base64 -d",
+        "pattern_mode": "contains",
+        "action": "downgrade",
+        "target_risk": "low",
+        "priority": 40,
+        "reason": "Base64 decode for debugging (no pipe to shell)"
+      },
+      {
+        "scope_cat": "pii",
+        "pattern": "\\.(test|spec|mock)\\.|__tests__|__mocks__|fixtures|testdata",
+        "pattern_mode": "regex",
+        "action": "downgrade",
+        "target_risk": "medium",
+        "priority": 15,
+        "reason": "PII in test/fixture files is typically synthetic test data"
+      },
+      {
+        "scope_cat": "pii",
+        "pattern": "\\.env\\.(example|test|sample|template)",
+        "pattern_mode": "regex",
+        "action": "downgrade",
+        "target_risk": "medium",
+        "priority": 15,
+        "reason": "PII in environment template files is placeholder data"
+      }
+    ]
+  },
+  "devops": {
+    "label": "DevOps / Infrastructure",
+    "description": "Extends Standard Development with additional suppressions for SSH, chmod, and infrastructure tooling",
+    "rules": [
+      {
+        "scope_cat": "net",
+        "scope_subcat": "ssh-connection",
+        "pattern": "ssh",
+        "pattern_mode": "contains",
+        "action": "downgrade",
+        "target_risk": "low",
+        "priority": 15,
+        "reason": "SSH connections expected in infrastructure work"
+      },
+      {
+        "scope_cat": "exec",
+        "scope_subcat": "priv-escalation",
+        "pattern": "chmod ",
+        "pattern_mode": "contains",
+        "action": "suppress",
+        "priority": 10,
+        "reason": "Standard infrastructure permissions management"
+      },
+      {
+        "scope_cat": "net",
+        "scope_subcat": "network-call",
+        "pattern": "rsync|scp",
+        "pattern_mode": "regex",
+        "action": "downgrade",
+        "target_risk": "low",
+        "priority": 15,
+        "reason": "Standard infrastructure file transfer tools"
+      },
+      {
+        "scope_cat": "exec",
+        "scope_subcat": "priv-escalation",
+        "pattern": "sudo ",
+        "pattern_mode": "contains",
+        "action": "downgrade",
+        "target_risk": "medium",
+        "priority": 50,
+        "reason": "Sudo expected in infrastructure contexts"
+      }
+    ]
+  },
+  "strict": {
+    "label": "Strict (No Suppressions)",
+    "description": "All events shown at original classification - no suppressions applied",
+    "rules": []
+  }
+}

package/server/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "agent-recon-server",
+  "version": "1.0.1",
+  "description": "Real-time agent observability dashboard",
+  "main": "server.js",
+  "scripts": {
+    "start": "node start.js",
+    "test": "node --test tests/unit/*.test.js tests/frontend/*.test.js tests/integration/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:fe": "node --test tests/frontend/*.test.js",
+    "test:int": "node --test tests/integration/*.test.js",
+    "test:coverage": "c8 node --test tests/unit/*.test.js tests/frontend/*.test.js",
+    "setup:hooks": "node -e \"const fs=require('fs'),p=require('path'),s=p.join(__dirname,'pre-commit-hook.sh'),d=p.join(__dirname,'../.git/hooks/pre-commit');fs.copyFileSync(s,d);fs.chmodSync(d,0o755);console.log('Pre-commit hook installed.');\""
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@litko/yara-x": "^0.5.0",
+    "better-sqlite3": "^12.8.0",
+    "express": "^5.2.1",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "terser": "^5.46.1"
+  },
+  "optionalDependencies": {
+    "@litko/yara-x-darwin-arm64": "0.5.0",
+    "@litko/yara-x-darwin-x64": "0.5.0",
+    "@litko/yara-x-linux-x64-gnu": "0.5.0",
+    "@litko/yara-x-win32-x64-msvc": "^0.5.0"
+  }
+}

package/server/platform.js

@@ -0,0 +1,270 @@
+// Copyright 2026 PNW Great Loop LLC. All rights reserved.
+// Licensed under the Apache License, Version 2.0 — see LICENSE for terms.
+
+'use strict';
+
+/**
+ * Agent Recon — Cross-platform utility module
+ *
+ * Centralises all platform detection, binary identification, and
+ * OS-specific path logic so that other modules (start.js, credential-store.js,
+ * process-monitor.js, server.js) can import a single source of truth.
+ *
+ * Exported:
+ *   detectOS, homedir, isNtfs, credentialBackend,
+ *   detectBinaryType, needsRebuild, backupSuffix
+ */
+
+const fs   = require('fs');
+const os   = require('os');
+
+// ── OS detection ────────────────────────────────────────────────────────────
+
+/** Cached result — OS does not change at runtime. */
+let _cachedOS;
+
+/**
+ * Detect the operating system environment.
+ * @returns {'windows'|'macos'|'linux'|'wsl'}
+ */
+function detectOS() {
+  if (_cachedOS) return _cachedOS;
+
+  if (process.platform === 'win32') {
+    _cachedOS = 'windows';
+  } else if (process.platform === 'darwin') {
+    _cachedOS = 'macos';
+  } else {
+    // Linux — but might be WSL
+    try {
+      const ver = fs.readFileSync('/proc/version', 'utf8');
+      _cachedOS = /microsoft|wsl/i.test(ver) ? 'wsl' : 'linux';
+    } catch {
+      _cachedOS = 'linux';
+    }
+  }
+  return _cachedOS;
+}
+
+/**
+ * Reset cached OS (for tests only).
+ * @private
+ */
+function _resetCache() { _cachedOS = undefined; }
+
+// ── Home directory ──────────────────────────────────────────────────────────
+
+/**
+ * Platform-appropriate home directory.
+ * On Windows uses USERPROFILE, everywhere else uses os.homedir().
+ * @returns {string}
+ */
+function homedir() {
+  if (process.platform === 'win32') {
+    return process.env.USERPROFILE || os.homedir();
+  }
+  return process.env.HOME || os.homedir();
+}
+
+// ── Config directory ─────────────────────────────────────────────────────────
+
+const path = require('path');
+
+/**
+ * Platform-appropriate configuration directory for Agent Recon.
+ *
+ * - macOS:   ~/Library/Application Support/agent-recon
+ * - Windows: %APPDATA%\agent-recon  (falls back to ~/.config/agent-recon)
+ * - Linux/WSL: ~/.config/agent-recon
+ *
+ * @returns {string}
+ */
+function configDir() {
+  const osType = detectOS();
+  const home = homedir();
+  switch (osType) {
+    case 'macos':
+      return path.join(home, 'Library', 'Application Support', 'agent-recon');
+    case 'windows':
+      return path.join(process.env.APPDATA || path.join(home, '.config'), 'agent-recon');
+    default:
+      return path.join(home, '.config', 'agent-recon');
+  }
+}
+
+// ── NTFS / DrvFs detection ──────────────────────────────────────────────────
+
+/**
+ * Check whether a file path resides on an NTFS/DrvFs mount (WSL2).
+ * Reads /proc/mounts and looks for drvfs or 9p filesystem types covering
+ * the given path. Always returns false on non-Linux platforms.
+ *
+ * @param {string} filePath — absolute path to check
+ * @returns {boolean}
+ */
+function isNtfs(filePath) {
+  if (process.platform === 'win32' || process.platform === 'darwin') return false;
+  try {
+    const mounts = fs.readFileSync('/proc/mounts', 'utf8');
+    return _isNtfsFromMounts(mounts, filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pure-logic NTFS detection from mount content — testable without /proc.
+ * @param {string} mountsContent — raw contents of /proc/mounts
+ * @param {string} filePath — absolute path to check
+ * @returns {boolean}
+ */
+function _isNtfsFromMounts(mountsContent, filePath) {
+  for (const line of mountsContent.split('\n')) {
+    const parts = line.split(' ');
+    if (parts[2] === 'drvfs' || parts[2] === '9p') {
+      const mountPoint = parts[1];
+      if (mountPoint && filePath.startsWith(mountPoint)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// ── Credential backend selection ────────────────────────────────────────────
+
+/**
+ * Determine which credential storage backend to use.
+ *
+ * Priority: env var override → platform-native store → fallback.
+ * macOS and libsecret backends are stubs until Group B implements them.
+ *
+ * @returns {'env'|'dpapi'|'keychain'|'libsecret'|'pbkdf2'}
+ */
+function credentialBackend() {
+  if (process.env.AGENT_RECON_MASTER_KEY) return 'env';
+  const osType = detectOS();
+  switch (osType) {
+    case 'windows': return 'dpapi';
+    case 'wsl':     return 'dpapi';       // WSL uses DPAPI via PowerShell interop
+    case 'macos':   return 'keychain';    // Stub — implemented in Group B (Phase 7.2)
+    case 'linux':   return 'libsecret';   // Stub — implemented in Group B (Phase 7.3)
+    default:        return 'pbkdf2';
+  }
+}
+
+// ── Binary type detection ───────────────────────────────────────────────────
+
+/**
+ * Identify a native binary's platform from its magic bytes.
+ *
+ * Supported formats:
+ *   PE  (Windows)      — 0x4D 0x5A ("MZ")
+ *   ELF (Linux)        — 0x7F 0x45 0x4C 0x46
+ *   Mach-O x64 (macOS) — 0xCF 0xFA 0xED 0xFE
+ *   Mach-O arm64       — 0xFE 0xED 0xFA 0xCE  (actually — see note below)
+ *
+ * Note: Mach-O uses two magic numbers depending on byte order:
+ *   Little-endian (x86-64): 0xCF FA ED FE (MH_MAGIC_64 reversed)
+ *   Little-endian (arm64):  same 0xCF FA ED FE (arm64 macOS is also LE)
+ *   Big-endian:             0xFE ED FA CE (MH_MAGIC)
+ * Universal binaries (fat): 0xCA FE BA BE
+ *
+ * Since both x64 and arm64 macOS use little-endian Mach-O 64-bit,
+ * we distinguish them by the cputype field at offset 4:
+ *   x86-64: cputype = 0x01000007 → bytes[4] = 0x07
+ *   arm64:  cputype = 0x0100000C → bytes[4] = 0x0C
+ *
+ * @param {Buffer} headerBytes — at least 5 bytes from start of file
+ * @returns {'pe'|'elf'|'macho-x64'|'macho-arm64'|'macho-universal'|'unknown'}
+ */
+function detectBinaryType(headerBytes) {
+  if (!headerBytes || headerBytes.length < 4) return 'unknown';
+
+  // PE (Windows) — "MZ"
+  if (headerBytes[0] === 0x4D && headerBytes[1] === 0x5A) return 'pe';
+
+  // ELF (Linux) — 0x7F "ELF"
+  if (headerBytes[0] === 0x7F && headerBytes[1] === 0x45 &&
+      headerBytes[2] === 0x4C && headerBytes[3] === 0x46) return 'elf';
+
+  // Mach-O 64-bit little-endian — 0xCF FA ED FE
+  // Both x64 and arm64 macOS use little-endian Mach-O 64-bit, so they share
+  // the same 4-byte magic. We must inspect the cputype field at byte offset 4
+  // to tell them apart:
+  //   0x0C = CPU_TYPE_ARM64 (Apple Silicon)
+  //   0x07 = CPU_TYPE_X86_64 (Intel Mac)
+  if (headerBytes[0] === 0xCF && headerBytes[1] === 0xFA &&
+      headerBytes[2] === 0xED && headerBytes[3] === 0xFE) {
+    if (headerBytes.length >= 5) {
+      if (headerBytes[4] === 0x0C) return 'macho-arm64';
+      if (headerBytes[4] === 0x07) return 'macho-x64';
+    }
+    return 'macho-x64'; // default if cputype byte unavailable
+  }
+
+  // Mach-O 32-bit big-endian — 0xFE ED FA CE (rare, but handle it)
+  if (headerBytes[0] === 0xFE && headerBytes[1] === 0xED &&
+      headerBytes[2] === 0xFA && headerBytes[3] === 0xCE) return 'macho-x64';
+
+  // Universal/fat binary — 0xCA FE BA BE
+  if (headerBytes[0] === 0xCA && headerBytes[1] === 0xFE &&
+      headerBytes[2] === 0xBA && headerBytes[3] === 0xBE) return 'macho-universal';
+
+  return 'unknown';
+}
+
+/**
+ * Determine whether the current platform needs a native binary rebuild.
+ *
+ * @param {string} binaryType — return value of detectBinaryType()
+ * @returns {boolean}
+ */
+function needsRebuild(binaryType) {
+  if (binaryType === 'unknown') return false;
+  const osType = detectOS();
+  switch (osType) {
+    case 'windows':
+      return binaryType !== 'pe';
+    case 'macos':
+      // Any Mach-O variant is acceptable on macOS (x64, arm64, universal)
+      return !binaryType.startsWith('macho');
+    case 'linux':
+    case 'wsl':
+      return binaryType !== 'elf';
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get the backup file suffix for a mismatched binary.
+ *
+ * @param {string} binaryType — return value of detectBinaryType()
+ * @returns {string} e.g. '.win32', '.linux', '.macho-arm64'
+ */
+function backupSuffix(binaryType) {
+  switch (binaryType) {
+    case 'pe':              return '.win32';
+    case 'elf':             return '.linux';
+    case 'macho-x64':       return '.macos-x64';
+    case 'macho-arm64':     return '.macos-arm64';
+    case 'macho-universal':  return '.macos-universal';
+    default:                return '.unknown';
+  }
+}
+
+// ── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  detectOS,
+  homedir,
+  configDir,
+  isNtfs,
+  _isNtfsFromMounts,
+  credentialBackend,
+  detectBinaryType,
+  needsRebuild,
+  backupSuffix,
+  _resetCache,
+};