@nuguardai/nuguard 0.5.7

package/README.md

@@ -0,0 +1,89 @@
+# @nuguardai/nuguard
+
+[![npm version](https://img.shields.io/npm/v/@nuguardai/nuguard)](https://www.npmjs.com/package/@nuguardai/nuguard)
+[![PyPI version](https://img.shields.io/pypi/v/nuguard)](https://pypi.org/project/nuguard/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/NuGuardAI/nuguard/blob/main/LICENSE)
+
+NuGuard is an open-source AI application security CLI. This npm package provides the `nuguard-mcp` launcher, which wires NuGuard as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server so AI-native tools (Claude Desktop, VS Code, Cursor, etc.) can invoke NuGuard capabilities directly.
+
+The underlying CLI is a Python package. This launcher automatically locates or installs it so you don't have to manage the Python environment manually.
+
+## Installation
+
+```bash
+npx @nuguardai/nuguard
+```
+
+Or install globally:
+
+```bash
+npm install -g @nuguardai/nuguard
+nuguard-mcp
+```
+
+## What the launcher does
+
+`nuguard-mcp` tries the following in order, using whichever succeeds first:
+
+1. `nuguard-mcp` already on `PATH` (pip-installed globally or in an active venv)
+2. `python3 -m nuguard.mcp` (nuguard installed but scripts not on `PATH`)
+3. `uvx --from nuguard[mcp] nuguard-mcp` (uv available)
+4. `pip install nuguard[mcp]` then `python -m nuguard.mcp` (one-time bootstrap)
+
+## MCP configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nuguard": {
+      "command": "npx",
+      "args": ["-y", "@nuguardai/nuguard"]
+    }
+  }
+}
+```
+
+### VS Code (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "nuguard": {
+      "command": "npx",
+      "args": ["-y", "@nuguardai/nuguard"]
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Python 3.12+ (or `uv` for zero-setup bootstrap)
+
+## CLI capabilities
+
+Once connected, the MCP server exposes NuGuard's full pipeline:
+
+| Command | Description |
+|---|---|
+| `nuguard sbom` | Generate an AI Bill of Materials from source code |
+| `nuguard analyze` | Static analysis of an AI-SBOM for security risks |
+| `nuguard policy` | Validate a cognitive policy document against a scan |
+| `nuguard behavior` | Behavioral testing against a live AI application |
+| `nuguard redteam` | Adversarial red-teaming with scenario-driven attacks |
+
+## Links
+
+- [GitHub](https://github.com/NuGuardAI/nuguard)
+- [Documentation](https://nuguardai.github.io/nuguard/)
+- [PyPI](https://pypi.org/project/nuguard/)
+- [Plugin guide](https://nuguardai.github.io/nuguard/plugin-guide.html)
+
+## License
+
+Apache-2.0

package/bin/nuguard-mcp.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Launcher for nuguard-mcp. Tries runners in order of least friction:
+ *   1. nuguard-mcp already on PATH (pip-installed globally or in active venv)
+ *   2. python/python3 -m nuguard.mcp (nuguard installed but scripts not on PATH)
+ *   3. uvx --from nuguard[mcp] nuguard-mcp  (uv available)
+ *   4. pip install nuguard[mcp] then python -m nuguard.mcp  (one-time setup)
+ */
+"use strict";
+
+const { spawn, spawnSync } = require("child_process");
+
+function which(cmd) {
+  const isWin = process.platform === "win32";
+  const r = spawnSync(isWin ? "where" : "which", [cmd], { encoding: "utf8", stdio: "pipe" });
+  return r.status === 0 && r.stdout.trim().length > 0;
+}
+
+function pyHasNuguardMcp(python) {
+  const r = spawnSync(python, ["-c", "import nuguard.mcp"], { encoding: "utf8", stdio: "pipe" });
+  return r.status === 0;
+}
+
+function run(command, args) {
+  const child = spawn(command, [...args], { stdio: "inherit" });
+  child.on("error", (err) => {
+    process.stderr.write(`nuguard-mcp: failed to start '${command}': ${err.message}\n`);
+    process.exit(1);
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+}
+
+const extra = process.argv.slice(2);
+
+// 1. Already pip-installed and on PATH
+if (which("nuguard-mcp")) {
+  return run("nuguard-mcp", extra);
+}
+
+// 2. Python with nuguard already installed
+const python = which("python3") ? "python3" : which("python") ? "python" : null;
+if (python && pyHasNuguardMcp(python)) {
+  return run(python, ["-m", "nuguard.mcp", ...extra]);
+}
+
+// 3. uvx
+if (which("uvx")) {
+  return run("uvx", ["--from", "nuguard[mcp]", "nuguard-mcp", ...extra]);
+}
+
+// 4. pip install then run
+if (python) {
+  process.stderr.write("nuguard-mcp: installing via pip (one-time setup)...\n");
+  const install = spawnSync(
+    python, ["-m", "pip", "install", "--quiet", "nuguard[mcp]"],
+    { stdio: "inherit" }
+  );
+  if (install.status === 0) {
+    return run(python, ["-m", "nuguard.mcp", ...extra]);
+  }
+  process.stderr.write("nuguard-mcp: pip install failed — try: pip install nuguard[mcp]\n");
+  process.exit(1);
+}
+
+process.stderr.write(
+  "nuguard-mcp: no suitable Python runtime found.\n" +
+  "Install via one of:\n" +
+  "  pip install nuguard[mcp]\n" +
+  "  uvx --from nuguard[mcp] nuguard-mcp\n" +
+  "See https://github.com/NuGuardAI/nuguard for details.\n"
+);
+process.exit(1);

package/bin/nuguard-mcp.test.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Tests for nuguard-mcp.js runner detection logic.
+ *
+ * Run with:  node npm/bin/nuguard-mcp.test.js
+ *
+ * Uses Node's built-in assert module — no external test framework needed.
+ */
+"use strict";
+
+const assert = require("assert");
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const WRAPPER = path.resolve(__dirname, "nuguard-mcp.js");
+
+/**
+ * Run the wrapper with a mocked environment via a child node process.
+ * We inject a tiny shim that overrides `which`, `pyHasNuguardMcp`, and
+ * `spawnSync` (for pip install) before the real module logic runs.
+ *
+ * Returns { stdout, stderr, exitCode }.
+ */
+function runWithMocks({ whichResults = {}, pyHasNuguard = false, pipOk = true } = {}) {
+  const shim = `
+"use strict";
+const cp = require("child_process");
+const original_spawnSync = cp.spawnSync.bind(cp);
+
+// Intercept spawnSync used by which() and pip install
+cp.spawnSync = function(cmd, args, opts) {
+  const isWin = process.platform === "win32";
+  const whichCmd = isWin ? "where" : "which";
+
+  if (cmd === whichCmd) {
+    const target = args[0];
+    const found = ${JSON.stringify(whichResults)}[target] === true;
+    return { status: found ? 0 : 1, stdout: found ? target : "", stderr: "" };
+  }
+
+  // python -c "import nuguard.mcp"
+  if (args && args[0] === "-c" && args[1] === "import nuguard.mcp") {
+    return { status: ${pyHasNuguard ? 0 : 1} };
+  }
+
+  // pip install
+  if (args && args[0] === "-m" && args[1] === "pip") {
+    return { status: ${pipOk ? 0 : 1} };
+  }
+
+  return { status: 1, stdout: "", stderr: "" };
+};
+
+// Intercept spawn used by run() — capture what would be launched
+const cp2 = require("child_process");
+const original_spawn = cp2.spawn.bind(cp2);
+cp2.spawn = function(cmd, args, opts) {
+  // Print what would be launched and exit cleanly
+  process.stdout.write(JSON.stringify({ cmd, args }) + "\\n");
+  return {
+    on: function(event, cb) {
+      if (event === "exit") cb(0);
+      if (event === "error") {}
+      return this;
+    }
+  };
+};
+
+require(${JSON.stringify(WRAPPER)});
+`;
+
+  const result = spawnSync(process.execPath, ["--eval", shim], {
+    encoding: "utf8",
+    stdio: "pipe",
+    timeout: 5000,
+  });
+
+  let launched = null;
+  if (result.stdout && result.stdout.trim()) {
+    try { launched = JSON.parse(result.stdout.trim()); } catch (_) {}
+  }
+
+  return {
+    launched,
+    stderr: result.stderr || "",
+    exitCode: result.status,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  ✗ ${name}`);
+    console.error(`    ${err.message}`);
+    failed++;
+  }
+}
+
+console.log("\nnuguard-mcp.js runner detection\n");
+
+// 1. nuguard-mcp already on PATH → run it directly
+test("uses nuguard-mcp directly when it is on PATH", () => {
+  const { launched } = runWithMocks({ whichResults: { "nuguard-mcp": true } });
+  assert.ok(launched, "should have launched something");
+  assert.strictEqual(launched.cmd, "nuguard-mcp");
+  assert.deepStrictEqual(launched.args, []);
+});
+
+// 2. python3 with nuguard installed → python3 -m nuguard.mcp
+test("uses python3 -m nuguard.mcp when nuguard-mcp not on PATH but python3 has it", () => {
+  const { launched } = runWithMocks({
+    whichResults: { python3: true },
+    pyHasNuguard: true,
+  });
+  assert.ok(launched);
+  assert.strictEqual(launched.cmd, "python3");
+  assert.ok(launched.args.includes("-m"), "should include -m flag");
+  assert.ok(launched.args.includes("nuguard.mcp"), "should target nuguard.mcp");
+});
+
+// 3. python (not python3) with nuguard installed
+test("falls back to python (not python3) when python3 not available", () => {
+  const { launched } = runWithMocks({
+    whichResults: { python: true },
+    pyHasNuguard: true,
+  });
+  assert.ok(launched);
+  assert.strictEqual(launched.cmd, "python");
+});
+
+// 4. uvx available, nuguard not pip-installed
+test("uses uvx when nuguard not pip-installed but uvx is available", () => {
+  const { launched } = runWithMocks({
+    whichResults: { uvx: true },
+    pyHasNuguard: false,
+  });
+  assert.ok(launched);
+  assert.strictEqual(launched.cmd, "uvx");
+  assert.ok(launched.args.includes("--from"));
+  assert.ok(launched.args.includes("nuguard[mcp]"));
+  assert.ok(launched.args.includes("nuguard-mcp"));
+});
+
+// 5. pip install fallback when python available but nuguard not installed
+test("pip-installs nuguard then launches python -m nuguard.mcp when only python present", () => {
+  const { launched, stderr } = runWithMocks({
+    whichResults: { python3: true },
+    pyHasNuguard: false,
+    pipOk: true,
+  });
+  assert.ok(launched, "should launch after pip install");
+  assert.strictEqual(launched.cmd, "python3");
+  assert.ok(launched.args.includes("nuguard.mcp"));
+  assert.ok(stderr.includes("installing via pip"), "should mention pip install");
+});
+
+// 6. No Python, no uvx → exit 1 with helpful message
+test("exits with code 1 and helpful message when no runtime found", () => {
+  const { launched, stderr, exitCode } = runWithMocks({
+    whichResults: {},
+    pyHasNuguard: false,
+  });
+  assert.strictEqual(launched, null, "should not launch anything");
+  assert.ok(stderr.includes("pip install") || stderr.includes("Python"), "stderr should contain install hint");
+});
+
+// 7. pip install fails → exit 1
+test("exits with code 1 when pip install fails", () => {
+  const { launched } = runWithMocks({
+    whichResults: { python3: true },
+    pyHasNuguard: false,
+    pipOk: false,
+  });
+  assert.strictEqual(launched, null, "should not launch after failed pip install");
+});
+
+// 8. nuguard-mcp takes precedence over python + uvx
+test("nuguard-mcp on PATH takes precedence over python and uvx", () => {
+  const { launched } = runWithMocks({
+    whichResults: { "nuguard-mcp": true, python3: true, uvx: true },
+    pyHasNuguard: true,
+  });
+  assert.ok(launched);
+  assert.strictEqual(launched.cmd, "nuguard-mcp", "nuguard-mcp should win over python/uvx");
+});
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`);
+process.exit(failed > 0 ? 1 : 0);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nuguardai/nuguard",
+  "version": "0.5.7",
+  "description": "AI Application Security — SBOM generation, static analysis, behavioral validation, and adversarial red-team testing for AI agents and LLM-powered applications.",
+  "keywords": [
+    "mcp",
+    "ai-security",
+    "sbom",
+    "red-team",
+    "llm",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/NuGuardAI/nuguard",
+  "bugs": {
+    "url": "https://github.com/NuGuardAI/nuguard/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NuGuardAI/nuguard.git"
+  },
+  "license": "Apache-2.0",
+  "author": "NuGuard <info@nuguard.ai>",
+  "bin": {
+    "nuguard-mcp": "bin/nuguard-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}