@agent-wall/cli 0.1.0

package/src/commands/validate.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { validateCommand } from "./validate.js";
+
+const mockConfig = {
+  version: 1,
+  defaultAction: "deny" as const,
+  rules: [
+    { name: "block-ssh", tool: "read_file", action: "deny" as const },
+    { name: "allow-project", tool: "list_directory", action: "allow" as const },
+  ],
+};
+
+vi.mock("@agent-wall/core", () => {
+  class MockPolicyEngine {
+    constructor(_cfg: any) {}
+  }
+
+  return {
+    loadPolicy: (configPath?: string) => ({
+      config: { ...mockConfig, rules: [...mockConfig.rules] },
+      filePath: configPath ?? "agent-wall.yaml",
+    }),
+    PolicyEngine: MockPolicyEngine,
+  };
+});
+
+describe("validateCommand", () => {
+  let exitSpy: any;
+  let stderrSpy: any;
+
+  beforeEach(() => {
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    stderrSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("validates a correct config successfully", () => {
+    validateCommand({});
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    expect(allOutput).toContain("Config loaded");
+    expect(allOutput).toContain("Version: 1");
+    expect(allOutput).toContain("Default action: deny");
+    expect(allOutput).toContain("Rules: 2 loaded");
+    expect(allOutput).toContain("Policy engine: OK");
+  });
+
+  it("shows the config file path", () => {
+    validateCommand({});
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    expect(allOutput).toContain("agent-wall.yaml");
+  });
+
+  it("accepts custom config path", () => {
+    validateCommand({ config: "./custom-policy.yaml" });
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    expect(allOutput).toContain("custom-policy.yaml");
+  });
+
+  it("shows rule count", () => {
+    validateCommand({});
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    expect(allOutput).toContain("Rules: 2 loaded");
+  });
+
+  it("displays validation header", () => {
+    validateCommand({});
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    expect(allOutput).toContain("Config Validation");
+  });
+});
+
+describe("validateCommand — error scenarios", () => {
+  let exitSpy: any;
+  let stderrSpy: any;
+
+  beforeEach(() => {
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    stderrSpy = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // Note: Testing error branches that require different mock behavior
+  // would need vi.mocked module reassignment per test. These tests
+  // validate the happy path since the mock is fixed at module level.
+  // Integration tests handle error cases more naturally.
+
+  it("reports valid config with no errors or warnings", () => {
+    validateCommand({});
+    const allOutput = stderrSpy.mock.calls.map((c: any) => c[0]).join("");
+    // Should not exit with error
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(allOutput).toContain("valid");
+  });
+});

package/src/commands/validate.ts

@@ -0,0 +1,181 @@
+/**
+ * agent-wall validate — Validate a policy configuration file.
+ *
+ * Checks the YAML syntax, Zod schema validation, and reports
+ * any issues with your policy rules.
+ *
+ * Usage:
+ *   agent-wall validate
+ *   agent-wall validate --config ./custom-policy.yaml
+ */
+
+import { loadPolicy, PolicyEngine } from "@agent-wall/core";
+import chalk from "chalk";
+
+export interface ValidateOptions {
+  config?: string;
+}
+
+export function validateCommand(options: ValidateOptions): void {
+  process.stderr.write("\n");
+  process.stderr.write(
+    chalk.cyan("─── Agent Wall Config Validation ─────────────────\n\n")
+  );
+
+  let config;
+  let filePath: string | null | undefined;
+
+  try {
+    const result = loadPolicy(options.config);
+    config = result.config;
+    filePath = result.filePath;
+  } catch (error: any) {
+    process.stderr.write(
+      chalk.red("  ✗ ") + chalk.red(`Failed to load config: ${error.message}\n\n`)
+    );
+    process.exit(1);
+  }
+
+  process.stderr.write(
+    chalk.green("  ✓ ") +
+      chalk.white("Config loaded: ") +
+      chalk.gray(filePath ?? "built-in defaults") +
+      "\n"
+  );
+
+  // Validate version
+  if (config.version !== 1) {
+    process.stderr.write(
+      chalk.yellow("  ⚠ ") +
+        chalk.yellow(`Unknown config version: ${config.version} (expected 1)\n`)
+    );
+  } else {
+    process.stderr.write(
+      chalk.green("  ✓ ") + chalk.white("Version: 1\n")
+    );
+  }
+
+  // Validate default action
+  const validActions = ["allow", "deny", "prompt"];
+  if (!config.defaultAction || !validActions.includes(config.defaultAction)) {
+    process.stderr.write(
+      chalk.red("  ✗ ") +
+        chalk.red(`Invalid defaultAction: "${config.defaultAction}" (expected: allow, deny, prompt)\n`)
+    );
+  } else {
+    process.stderr.write(
+      chalk.green("  ✓ ") +
+        chalk.white(`Default action: ${config.defaultAction}\n`)
+    );
+  }
+
+  // Validate global rate limit
+  if (config.globalRateLimit) {
+    if (config.globalRateLimit.maxCalls <= 0) {
+      process.stderr.write(
+        chalk.yellow("  ⚠ ") +
+          chalk.yellow("Global rate limit maxCalls should be > 0\n")
+      );
+    } else {
+      process.stderr.write(
+        chalk.green("  ✓ ") +
+          chalk.white(
+            `Global rate limit: ${config.globalRateLimit.maxCalls} calls / ${config.globalRateLimit.windowSeconds}s\n`
+          )
+      );
+    }
+  }
+
+  // Validate rules
+  process.stderr.write(
+    chalk.green("  ✓ ") +
+      chalk.white(`Rules: ${config.rules.length} loaded\n`)
+  );
+
+  let warnings = 0;
+  let errors = 0;
+  const ruleNames = new Set<string>();
+
+  for (let i = 0; i < config.rules.length; i++) {
+    const rule = config.rules[i];
+    const label = rule.name ?? `rule[${i}]`;
+
+    // Check for duplicate names
+    if (rule.name) {
+      if (ruleNames.has(rule.name)) {
+        process.stderr.write(
+          chalk.yellow("  ⚠ ") +
+            chalk.yellow(`Duplicate rule name: "${rule.name}"\n`)
+        );
+        warnings++;
+      }
+      ruleNames.add(rule.name);
+    } else {
+      process.stderr.write(
+        chalk.yellow("  ⚠ ") +
+          chalk.yellow(`Rule at index ${i} has no name (recommended for audit logs)\n`)
+      );
+      warnings++;
+    }
+
+    // Check action validity
+    if (!validActions.includes(rule.action)) {
+      process.stderr.write(
+        chalk.red("  ✗ ") +
+          chalk.red(`${label}: invalid action "${rule.action}"\n`)
+      );
+      errors++;
+    }
+
+    // Check tool pattern syntax (basic validation)
+    if (rule.tool && rule.tool.includes(" ")) {
+      process.stderr.write(
+        chalk.yellow("  ⚠ ") +
+          chalk.yellow(`${label}: tool pattern contains spaces — use "|" to separate alternatives\n`)
+      );
+      warnings++;
+    }
+
+    // Check rate limit
+    if (rule.rateLimit) {
+      if (rule.rateLimit.maxCalls <= 0 || rule.rateLimit.windowSeconds <= 0) {
+        process.stderr.write(
+          chalk.yellow("  ⚠ ") +
+            chalk.yellow(`${label}: rate limit values should be > 0\n`)
+        );
+        warnings++;
+      }
+    }
+  }
+
+  // Test that the engine initializes correctly
+  try {
+    new PolicyEngine(config);
+    process.stderr.write(
+      chalk.green("  ✓ ") + chalk.white("Policy engine: OK\n")
+    );
+  } catch (error: any) {
+    process.stderr.write(
+      chalk.red("  ✗ ") +
+        chalk.red(`Policy engine failed: ${error.message}\n`)
+    );
+    errors++;
+  }
+
+  // Summary
+  process.stderr.write("\n");
+  if (errors > 0) {
+    process.stderr.write(
+      chalk.red(`  ${errors} error(s), ${warnings} warning(s)\n\n`)
+    );
+    process.exit(1);
+  } else if (warnings > 0) {
+    process.stderr.write(
+      chalk.yellow(`  ${warnings} warning(s), 0 errors — config is valid\n\n`)
+    );
+  } else {
+    process.stderr.write(
+      chalk.green("  ✓ Config is valid — no issues found\n\n")
+    );
+  }
+}

package/src/commands/wrap.ts

@@ -0,0 +1,420 @@
+/**
+ * agent-wall wrap — The main command.
+ *
+ * Wraps an MCP server command, intercepting all tool calls
+ * through the Agent Wall policy engine.
+ *
+ * Usage:
+ *   agent-wall wrap -- npx @modelcontextprotocol/server-filesystem /path
+ *   agent-wall wrap -c agent-wall.yaml -- node my-mcp-server.js
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import {
+  StdioProxy,
+  PolicyEngine,
+  AuditLogger,
+  ResponseScanner,
+  InjectionDetector,
+  EgressControl,
+  KillSwitch,
+  ChainDetector,
+  DashboardServer,
+  loadPolicy,
+  createTerminalPromptHandler,
+} from "@agent-wall/core";
+import chalk from "chalk";
+
+export interface WrapOptions {
+  config?: string;
+  logFile?: string;
+  silent?: boolean;
+  dryRun?: boolean;
+  dashboard?: boolean;
+  dashboardPort?: number;
+}
+
+export async function wrapCommand(
+  serverArgs: string[],
+  options: WrapOptions
+): Promise<void> {
+  if (serverArgs.length === 0) {
+    process.stderr.write(
+      chalk.red(
+        "Error: No server command specified.\n" +
+        "Usage: agent-wall wrap -- <command> [args...]\n\n" +
+        "Example:\n" +
+        "  agent-wall wrap -- npx @modelcontextprotocol/server-filesystem /home/user\n"
+      )
+    );
+    process.exit(1);
+  }
+
+  const command = serverArgs[0];
+  const args = serverArgs.slice(1);
+
+  // Load policy
+  const { config, filePath } = loadPolicy(options.config);
+
+  if (!options.silent) {
+    process.stderr.write(
+      chalk.cyan("╔══════════════════════════════════════════════════╗\n")
+    );
+    process.stderr.write(
+      chalk.cyan("║  ") +
+      chalk.bold.white("Agent Wall") +
+      chalk.cyan(" — Security Firewall for AI Agents  ║\n")
+    );
+    process.stderr.write(
+      chalk.cyan("╠══════════════════════════════════════════════════╣\n")
+    );
+    process.stderr.write(
+      chalk.cyan("║  ") +
+      chalk.gray("Policy: ") +
+      chalk.white(filePath ?? "built-in defaults") +
+      "\n"
+    );
+    process.stderr.write(
+      chalk.cyan("║  ") +
+      chalk.gray("Rules:  ") +
+      chalk.white(`${config.rules.length} loaded`) +
+      "\n"
+    );
+    const rspScan = config.responseScanning;
+    if (rspScan?.enabled !== false) {
+      process.stderr.write(
+        chalk.cyan("║  ") +
+        chalk.gray("Scanner:") +
+        chalk.white(" response scanning ON") +
+        (rspScan?.detectPII ? chalk.yellow(" +PII") : "") +
+        "\n"
+      );
+    }
+    process.stderr.write(
+      chalk.cyan("║  ") +
+      chalk.gray("Server: ") +
+      chalk.white(`${command} ${args.join(" ")}`) +
+      "\n"
+    );
+    process.stderr.write(
+      chalk.cyan("╚══════════════════════════════════════════════════╝\n\n")
+    );
+  }
+
+  // Dry-run mode: just show info and exit
+  if (options.dryRun) {
+    process.stderr.write(
+      chalk.yellow("  --dry-run mode: preview only, server will not start\n\n")
+    );
+    process.stderr.write(
+      chalk.gray("  Default action: ") +
+      chalk.white(config.defaultAction) +
+      "\n"
+    );
+    if (config.globalRateLimit) {
+      process.stderr.write(
+        chalk.gray("  Rate limit:     ") +
+        chalk.white(
+          `${config.globalRateLimit.maxCalls} calls / ${config.globalRateLimit.windowSeconds}s`
+        ) +
+        "\n"
+      );
+    }
+    process.stderr.write(
+      chalk.gray("  Rules loaded:   ") +
+      chalk.white(String(config.rules.length)) +
+      "\n\n"
+    );
+
+    for (let i = 0; i < config.rules.length; i++) {
+      const rule = config.rules[i];
+      const icon =
+        rule.action === "deny"
+          ? chalk.red("✗")
+          : rule.action === "allow"
+            ? chalk.green("✓")
+            : chalk.yellow("?");
+      process.stderr.write(
+        `  ${icon} ${chalk.bold(rule.name ?? `rule[${i}]`)}` +
+        chalk.gray(` → ${rule.action}`) +
+        chalk.gray(` (tool: ${rule.tool})`) +
+        "\n"
+      );
+    }
+    process.stderr.write("\n");
+    process.exit(0);
+  }
+
+  // Create engine + logger + response scanner
+  const policyEngine = new PolicyEngine(config);
+  const securityConfig = config.security;
+  const logger = new AuditLogger({
+    stdout: !options.silent,
+    filePath: options.logFile,
+    redact: true,
+    signing: securityConfig?.signing ?? false,
+    signingKey: securityConfig?.signingKey,
+  });
+
+  // Create response scanner from policy config
+  const responseScanner = config.responseScanning?.enabled !== false
+    ? new ResponseScanner({
+      enabled: true,
+      maxResponseSize: config.responseScanning?.maxResponseSize,
+      oversizeAction: config.responseScanning?.oversizeAction,
+      detectSecrets: config.responseScanning?.detectSecrets ?? true,
+      detectPII: config.responseScanning?.detectPII ?? false,
+      base64Action: config.responseScanning?.base64Action,
+      maxPatterns: config.responseScanning?.maxPatterns,
+      patterns: config.responseScanning?.patterns,
+    })
+    : undefined;
+
+  // Create security modules from config
+  const injectionDetector = new InjectionDetector(securityConfig?.injectionDetection);
+  const egressControl = new EgressControl(securityConfig?.egressControl);
+  const killSwitch = new KillSwitch({
+    ...securityConfig?.killSwitch,
+    registerSignal: true,
+  });
+  const chainDetector = new ChainDetector(securityConfig?.chainDetection);
+
+  // Show security module status
+  if (!options.silent) {
+    const modules: string[] = [];
+    if (securityConfig?.injectionDetection?.enabled !== false) modules.push("injection");
+    if (securityConfig?.egressControl?.enabled !== false) modules.push("egress");
+    if (securityConfig?.killSwitch?.enabled !== false) modules.push("kill-switch");
+    if (securityConfig?.chainDetection?.enabled !== false) modules.push("chain");
+    if (securityConfig?.signing) modules.push("signing");
+    if (modules.length > 0) {
+      process.stderr.write(
+        chalk.cyan("║  ") +
+        chalk.gray("Security:") +
+        chalk.white(` ${modules.join(", ")}`) +
+        "\n"
+      );
+    }
+  }
+
+  // Create proxy
+  const proxy = new StdioProxy({
+    command,
+    args,
+    policyEngine,
+    responseScanner,
+    logger,
+    injectionDetector,
+    egressControl,
+    killSwitch,
+    chainDetector,
+    onPrompt: createTerminalPromptHandler(),
+    onReady: () => {
+      if (!options.silent) {
+        process.stderr.write(
+          chalk.green("✓ ") +
+          chalk.gray("MCP server started. Agent Wall is protecting.\n\n")
+        );
+      }
+    },
+    onExit: (code) => {
+      if (!options.silent) {
+        const stats = proxy.getStats();
+        process.stderr.write("\n");
+        process.stderr.write(
+          chalk.cyan("─── Agent Wall Session Summary ────────────────────\n")
+        );
+        process.stderr.write(
+          chalk.gray("  Total calls:    ") +
+          chalk.white(String(stats.total)) +
+          "\n"
+        );
+        process.stderr.write(
+          chalk.gray("  Forwarded:      ") +
+          chalk.green(String(stats.forwarded)) +
+          "\n"
+        );
+        process.stderr.write(
+          chalk.gray("  Denied:         ") +
+          chalk.red(String(stats.denied)) +
+          "\n"
+        );
+        process.stderr.write(
+          chalk.gray("  Prompted:       ") +
+          chalk.yellow(String(stats.prompted)) +
+          "\n"
+        );
+        if (stats.scanned > 0) {
+          process.stderr.write(
+            chalk.gray("  Responses scanned: ") +
+            chalk.white(String(stats.scanned)) +
+            "\n"
+          );
+          if (stats.responseBlocked > 0) {
+            process.stderr.write(
+              chalk.gray("  Resp. blocked:  ") +
+              chalk.red(String(stats.responseBlocked)) +
+              "\n"
+            );
+          }
+          if (stats.responseRedacted > 0) {
+            process.stderr.write(
+              chalk.gray("  Resp. redacted: ") +
+              chalk.yellow(String(stats.responseRedacted)) +
+              "\n"
+            );
+          }
+        }
+        process.stderr.write(
+          chalk.cyan("─────────────────────────────────────────────────\n")
+        );
+      }
+      process.exit(code ?? 0);
+    },
+    onError: (error) => {
+      process.stderr.write(
+        chalk.red(`\nAgent Wall Error: ${error.message}\n`)
+      );
+    },
+  });
+
+  // ── Policy hot-reload ────────────────────────────────────────────
+  // Watch the policy file for changes and reload without restarting.
+  let policyWatcher: fs.FSWatcher | null = null;
+  if (filePath) {
+    try {
+      let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+      policyWatcher = fs.watch(filePath, (eventType) => {
+        if (eventType !== "change") return;
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          try {
+            const { config: newConfig } = loadPolicy(filePath);
+            policyEngine.updateConfig(newConfig);
+            if (responseScanner && newConfig.responseScanning) {
+              responseScanner.updateConfig(newConfig.responseScanning);
+            }
+            if (!options.silent) {
+              process.stderr.write(
+                chalk.green("✓ ") +
+                chalk.gray("Policy reloaded from ") +
+                chalk.white(filePath) +
+                chalk.gray(` (${newConfig.rules.length} rules)\n`)
+              );
+            }
+          } catch (err: unknown) {
+            if (!options.silent) {
+              const msg = err instanceof Error ? err.message : String(err);
+              process.stderr.write(
+                chalk.yellow(`⚠ Policy reload failed: ${msg}\n`)
+              );
+            }
+          }
+        }, 300); // Debounce: 300ms to handle rapid file saves
+      });
+    } catch {
+      // File watching not available — continue without hot-reload
+    }
+  }
+
+  // ── Dashboard ─────────────────────────────────────────────────────
+  let dashboardServer: DashboardServer | null = null;
+  if (options.dashboard || options.dashboardPort) {
+    const dashboardPort = options.dashboardPort ?? 61100;
+    const staticDir = resolveDashboardAssets();
+
+    dashboardServer = new DashboardServer({
+      port: dashboardPort,
+      proxy,
+      killSwitch,
+      policyEngine,
+      logger,
+      staticDir,
+    });
+
+    // Wire audit logger to push entries to dashboard
+    logger.setOnEntry((entry) => {
+      dashboardServer!.handleAuditEntry(entry);
+    });
+
+    try {
+      await dashboardServer.start();
+      if (!options.silent) {
+        process.stderr.write(
+          chalk.cyan("║  ") +
+          chalk.gray("Dashboard:") +
+          chalk.white(` http://localhost:${dashboardPort}`) +
+          "\n"
+        );
+      }
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        chalk.yellow(`⚠ Dashboard failed to start: ${msg}\n`)
+      );
+      dashboardServer = null;
+    }
+  }
+
+  // Handle process signals
+  const shutdown = () => {
+    if (policyWatcher) {
+      policyWatcher.close();
+      policyWatcher = null;
+    }
+    dashboardServer?.stop();
+    proxy.stop();
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Start the proxy
+  try {
+    await proxy.start();
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      chalk.red(
+        `\nFailed to start MCP server: ${msg}\n\n` +
+        "Make sure the server command is correct:\n" +
+        `  ${command} ${args.join(" ")}\n`
+      )
+    );
+    process.exit(1);
+  }
+}
+
+// ── Dashboard Asset Resolution ──────────────────────────────────────
+
+function resolveDashboardAssets(): string | undefined {
+  // 1. Check for bundled assets (shipped with npm package)
+  const bundledDir = path.join(path.dirname(new URL(import.meta.url).pathname), "dashboard");
+  if (fs.existsSync(path.join(bundledDir, "index.html"))) {
+    return bundledDir;
+  }
+
+  // 2. Try to find @agent-wall/dashboard's built assets via require.resolve
+  try {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve("@agent-wall/dashboard/package.json");
+    const distDir = path.join(path.dirname(pkgPath), "dist");
+    if (fs.existsSync(path.join(distDir, "index.html"))) {
+      return distDir;
+    }
+  } catch {
+    // Not installed or not built
+  }
+
+  // 3. Fallback: check monorepo path
+  const monorepoDist = path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    "../../dashboard/dist"
+  );
+  if (fs.existsSync(path.join(monorepoDist, "index.html"))) {
+    return monorepoDist;
+  }
+
+  return undefined;
+}