nsauditor-ai 0.1.3 → 0.1.5

package/README.md

@@ -7,7 +7,7 @@ A modular, AI-assisted network security audit platform that scans, understands,
 [![npm](https://img.shields.io/npm/v/nsauditor-ai.svg)](https://www.npmjs.com/package/nsauditor-ai)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js 20+](https://img.shields.io/badge/node-20%2B-green.svg)](https://nodejs.org)
-[![Tests](https://img.shields.io/badge/tests-487%20passing-brightgreen.svg)](#tests)
+[![Tests](https://img.shields.io/badge/tests-493%20passing-brightgreen.svg)](#tests)
 
 ---
 
@@ -264,14 +264,20 @@ Security: SSRF protection on all host inputs (blocks RFC 1918, loopback, fc00::/
 
 ### Claude Desktop Setup
 
-Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):
+First install the package globally:
+
+```bash
+npm install -g nsauditor-ai
+```
+
+Then add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 ```json
 {
   "mcpServers": {
     "nsauditor-ai": {
-      "command": "npx",
-      "args": ["--package=nsauditor-ai", "nsauditor-ai-mcp"],
+      "command": "node",
+      "args": ["/path/to/global/node_modules/nsauditor-ai/mcp_server.mjs"],
       "env": {
         "AI_PROVIDER": "claude",
         "ANTHROPIC_API_KEY": "your-key-here",
@@ -283,6 +289,8 @@ Add this to your `claude_desktop_config.json` (Settings → Developer → Edit C
 }
 ```
 
+Find your global install path with `npm root -g`, then append `/nsauditor-ai/mcp_server.mjs`.
+
 - `NSA_ALLOW_ALL_HOSTS=1` — required to scan private/RFC 1918 addresses (e.g., `192.168.x.x`)
 - `PLUGIN_TIMEOUT_MS=5000` — reduces per-plugin timeout to 5s so the full scan completes within Claude Desktop's 60s MCP limit
 - `AI_PROVIDER` and API key — optional, enables AI-powered analysis of scan results
@@ -295,6 +303,38 @@ claude mcp add nsauditor-ai -- npx nsauditor-ai-mcp
 
 ---
 
+## Secure Credential Storage
+
+Store API keys in the macOS Keychain instead of plaintext `.env` files:
+
+```bash
+# Store keys
+nsauditor-ai security set ANTHROPIC_API_KEY
+nsauditor-ai security set OPENAI_API_KEY
+
+# List stored keys (masked)
+nsauditor-ai security list
+
+# Delete a key
+nsauditor-ai security delete OPENAI_API_KEY
+```
+
+Then reference them with the `keychain:` prefix in `.env` or Claude Desktop config:
+
+```env
+ANTHROPIC_API_KEY=keychain:ANTHROPIC_API_KEY
+```
+
+```json
+"env": {
+  "ANTHROPIC_API_KEY": "keychain:ANTHROPIC_API_KEY"
+}
+```
+
+The `keychain:` prefix works anywhere an API key is read — CLI, MCP server, or programmatic API.
+
+---
+
 ## CLI Reference
 
 ```

package/cli.mjs

@@ -92,11 +92,12 @@ async function maybeSendToOpenAI({ host, results, conclusion, promptMode = 'basi
     : aiProvider === 'ollama'
     ? toCleanPath(process.env.OLLAMA_MODEL || 'llama3')
     : toCleanPath(process.env.OPENAI_MODEL || 'gpt-4o-mini');
+  const { resolveSecret } = await import('./utils/keychain.mjs');
   const keyRaw        = aiProvider === 'claude'
-    ? process.env.ANTHROPIC_API_KEY
+    ? await resolveSecret(process.env.ANTHROPIC_API_KEY)
     : aiProvider === 'ollama'
     ? 'ollama'   // Ollama needs no real key; OpenAI SDK requires a non-empty string
-    : process.env.OPENAI_API_KEY;
+    : await resolveSecret(process.env.OPENAI_API_KEY);
   const key           = keyRaw ? String(keyRaw).trim() : null;
 
   // Base output folder (directory ONLY; if a file path is given, take its dir)
@@ -650,6 +651,27 @@ const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
  * @param {object} conclusion
  * @returns {number} highest severity rank found (0-4)
  */
+async function readSecretFromStdin(keyName) {
+  if (!process.stdin.isTTY) {
+    // Piped input
+    return new Promise((resolve) => {
+      let data = '';
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (chunk) => { data += chunk; });
+      process.stdin.on('end', () => resolve(data.trim() || null));
+    });
+  }
+  // Interactive prompt
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`Enter value for ${keyName}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || null);
+    });
+  });
+}
+
 function maxSeverityInConclusion(conclusion) {
   const services = conclusion?.result?.services || [];
   let max = 0;
@@ -709,6 +731,42 @@ async function main() {
     process.exit(0);
   }
 
+  if (cmd === 'security') {
+    const { keychainSet, keychainDelete, keychainList, keychainGet } = await import('./utils/keychain.mjs');
+    const rawArgs = process.argv.slice(2);
+    const subCmd = rawArgs[1]; // set | delete | list | get
+    const keyName = rawArgs[2];
+
+    if (subCmd === 'set' && keyName) {
+      // Read secret from stdin (piped) or prompt
+      const secret = await readSecretFromStdin(keyName);
+      if (!secret) { console.error('No secret provided.'); process.exit(1); }
+      await keychainSet(keyName, secret);
+      console.log(`Stored "${keyName}" in macOS Keychain (service: nsauditor-ai)`);
+    } else if (subCmd === 'delete' && keyName) {
+      const ok = await keychainDelete(keyName);
+      console.log(ok ? `Deleted "${keyName}" from Keychain` : `"${keyName}" not found in Keychain`);
+    } else if (subCmd === 'list') {
+      const entries = await keychainList();
+      if (entries.length === 0) {
+        console.log('No nsauditor-ai keys stored in Keychain.');
+      } else {
+        console.log('Stored keys (service: nsauditor-ai):\n');
+        for (const name of entries) {
+          const val = await keychainGet(name);
+          const masked = val ? `${val.slice(0, 8)}...(${val.length} chars)` : '(empty)';
+          console.log(`  ${name} = ${masked}`);
+        }
+      }
+    } else {
+      console.log(`Usage:
+  nsauditor-ai security set <KEY_NAME>     Store a secret in macOS Keychain
+  nsauditor-ai security delete <KEY_NAME>  Remove a secret from Keychain
+  nsauditor-ai security list               List stored secrets (masked)`);
+    }
+    process.exit(0);
+  }
+
   if (cmd !== 'scan') {
     console.error(`Unknown command: ${cmd}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,

package/utils/keychain.mjs

@@ -0,0 +1,120 @@
+// utils/keychain.mjs
+// macOS Keychain integration for secure credential storage.
+// Falls back gracefully on non-macOS platforms.
+
+import { execFile } from 'node:child_process';
+import { platform } from 'node:os';
+
+const SERVICE = 'nsauditor-ai';
+const isMac = platform() === 'darwin';
+
+function exec(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 5000 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(stderr?.trim() || err.message));
+      resolve(stdout.trim());
+    });
+  });
+}
+
+/**
+ * Read a secret from the macOS Keychain.
+ * @param {string} account - Key name (e.g., 'ANTHROPIC_API_KEY')
+ * @returns {Promise<string|null>} The secret value, or null if not found
+ */
+export async function keychainGet(account) {
+  if (!isMac) return null;
+  try {
+    return await exec('security', [
+      'find-generic-password', '-s', SERVICE, '-a', account, '-w'
+    ]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a secret in the macOS Keychain.
+ * Updates existing entry if present.
+ * @param {string} account - Key name
+ * @param {string} secret - The secret value
+ */
+export async function keychainSet(account, secret) {
+  if (!isMac) throw new Error('Keychain storage is only supported on macOS');
+  // Delete existing entry first (ignore errors if not found)
+  try {
+    await exec('security', ['delete-generic-password', '-s', SERVICE, '-a', account]);
+  } catch { /* not found — fine */ }
+  await exec('security', [
+    'add-generic-password', '-s', SERVICE, '-a', account, '-w', secret
+  ]);
+}
+
+/**
+ * Delete a secret from the macOS Keychain.
+ * @param {string} account - Key name
+ * @returns {Promise<boolean>} true if deleted, false if not found
+ */
+export async function keychainDelete(account) {
+  if (!isMac) throw new Error('Keychain storage is only supported on macOS');
+  try {
+    await exec('security', ['delete-generic-password', '-s', SERVICE, '-a', account]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List all nsauditor-ai entries in the Keychain.
+ * @returns {Promise<string[]>} Array of account names
+ */
+export async function keychainList() {
+  if (!isMac) return [];
+  try {
+    const raw = await exec('security', ['dump-keychain']);
+    const entries = [];
+    const lines = raw.split('\n');
+    let inOurService = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      // Match both formats: 0x00000007 <blob>="nsauditor-ai" and "svce"<blob>="nsauditor-ai"
+      if (trimmed.includes(`="${SERVICE}"`)) {
+        inOurService = true;
+      } else if (inOurService && trimmed.includes('"acct"<blob>="')) {
+        const m = trimmed.match(/"acct"<blob>="([^"]+)"/);
+        if (m) entries.push(m[1]);
+        inOurService = false;
+      } else if (trimmed.startsWith('keychain:') || trimmed.startsWith('class:')) {
+        inOurService = false;
+      }
+    }
+    return [...new Set(entries)];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve a value that may be a keychain reference.
+ * If the value starts with 'keychain:', read from Keychain.
+ * Otherwise return the value as-is.
+ * @param {string|undefined} value - Raw env var value
+ * @returns {Promise<string|null>} Resolved secret
+ */
+export async function resolveSecret(value) {
+  if (!value) return null;
+  const str = String(value).trim();
+  if (!str) return null;
+  if (str.startsWith('keychain:')) {
+    const label = str.slice('keychain:'.length).trim();
+    if (!label) return null;
+    const secret = await keychainGet(label);
+    if (!secret) {
+      console.error(`[keychain] No entry found for "${label}" in Keychain (service: ${SERVICE})`);
+      console.error(`[keychain] Store it with: nsauditor-ai security set ${label}`);
+    }
+    return secret;
+  }
+  return str;
+}