agentaudit 3.3.0 → 3.4.0

package/README.md

@@ -15,16 +15,52 @@ MCP server for agents + standalone CLI for humans.
 
 ---
 
-## Quick Start
+## Getting Started
+
+There are two ways to use AgentAudit:
+
+### Option A: MCP Server in your AI editor (recommended)
+
+Add AgentAudit to Claude Desktop, Cursor, or Windsurf. **No API key needed** — your editor's agent runs audits using its own LLM.
+
+```json
+{
+  "mcpServers": {
+    "agentaudit": {
+      "command": "npx",
+      "args": ["-y", "agentaudit"]
+    }
+  }
+}
+```
+
+Then just ask your agent: *"Check which MCP servers I have installed and audit any unaudited ones."*
+
+### Option B: CLI
 
 ```bash
+# Install
+npm install -g agentaudit    # or use npx agentaudit <command>
+
+# 1. Discover your MCP servers
 npx agentaudit discover
+
+# 2. Audit unaudited packages (needs an LLM API key)
+export ANTHROPIC_API_KEY=sk-ant-...    # or OPENAI_API_KEY=sk-...
+npx agentaudit audit https://github.com/owner/repo
+
+# 3. (Optional) Register to upload reports to the public registry
+npx agentaudit setup
 ```
 
-That's it. Finds all MCP servers on your machine and checks them against the security registry.
+> **Note:** The `audit` command requires an LLM API key (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) to analyze code. The `discover`, `scan`, and `check` commands work without one. If you don't have an API key, use `--export` to generate a markdown file you can paste into any LLM, or use AgentAudit as an MCP server (Option A) where no extra key is needed.
+
+### Quick example
 
 ```
-AgentAudit v3.2.0
+$ npx agentaudit discover
+
+  AgentAudit v3.3.0
   Security scanner for AI packages
 
 •  Scanning Claude Desktop  ~/.claude/mcp.json    found 2 servers
@@ -32,21 +68,15 @@ AgentAudit v3.2.0
 ├──  fastmcp-demo       npm:fastmcp
 │    SAFE  Risk 0  ✔ official  https://agentaudit.dev/skills/fastmcp
 └──  my-tool            npm:some-mcp-tool
-     ⚠ not audited      Run: agentaudit audit <source-url>
+     ⚠ not audited      Run: agentaudit audit https://github.com/user/some-mcp-tool
 
-────────────────────────────────────────────────────────
   Summary  2 servers across 1 config
 
   ✔  1 audited
   ⚠  1 not audited
-```
-
-## Install
 
-```bash
-npm install -g agentaudit    # global install
-# or use directly:
-npx agentaudit <command>
+  To audit unaudited servers:
+  agentaudit audit https://github.com/user/some-mcp-tool  (my-tool)
 ```
 
 ---

package/cli.mjs

@@ -157,17 +157,26 @@ async function setupCommand() {
 
   console.log();
   console.log(`  ${c.bold}Ready!${c.reset} You can now:`);
-  console.log(`  ${c.dim}•${c.reset} Scan packages:  ${c.cyan}agentaudit scan <repo-url>${c.reset}`);
-  console.log(`  ${c.dim}•${c.reset} Check registry:  ${c.cyan}agentaudit check <name>${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Discover servers: ${c.cyan}agentaudit discover${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Audit packages:   ${c.cyan}agentaudit audit <repo-url>${c.reset}  ${c.dim}(deep LLM analysis)${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Quick scan:        ${c.cyan}agentaudit scan <repo-url>${c.reset}  ${c.dim}(regex-based)${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Check registry:    ${c.cyan}agentaudit check <name>${c.reset}`);
   console.log(`  ${c.dim}•${c.reset} Submit reports via MCP in Claude/Cursor/Windsurf`);
   console.log();
 }
 
 // ── Helpers ──────────────────────────────────────────────
 
+function getVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch { return '0.0.0'; }
+}
+
 function banner() {
   console.log();
-  console.log(`  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v1.0.0${c.reset}`);
+  console.log(`  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v${getVersion()}${c.reset}`);
   console.log(`  ${c.dim}Security scanner for AI packages${c.reset}`);
   console.log();
 }
@@ -705,6 +714,48 @@ function serverSlug(server) {
   return server.name.toLowerCase().replace(/[^a-z0-9-]/gi, '-');
 }
 
+async function resolveSourceUrl(server) {
+  // Already have it
+  if (server.sourceUrl) return server.sourceUrl;
+  
+  // Try npm registry
+  if (server.npmPackage) {
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(server.npmPackage)}`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        let repoUrl = data.repository?.url;
+        if (repoUrl) {
+          repoUrl = repoUrl.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^ssh:\/\/git@github\.com/, 'https://github.com');
+          if (repoUrl.startsWith('http')) return repoUrl;
+        }
+      }
+    } catch {}
+    // Fallback: npm page
+    return `https://www.npmjs.com/package/${server.npmPackage}`;
+  }
+  
+  // Try PyPI
+  if (server.pyPackage) {
+    try {
+      const res = await fetch(`https://pypi.org/pypi/${encodeURIComponent(server.pyPackage)}/json`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const urls = data.info?.project_urls || {};
+        const source = urls.Source || urls.Repository || urls.Homepage || urls['Source Code'] || data.info?.home_page;
+        if (source && source.startsWith('http')) return source;
+      }
+    } catch {}
+    return `https://pypi.org/project/${server.pyPackage}/`;
+  }
+  
+  return null;
+}
+
 async function discoverCommand() {
   console.log(`  ${c.bold}Discovering local MCP servers...${c.reset}`);
   console.log();
@@ -728,6 +779,7 @@ async function discoverCommand() {
   let checkedServers = 0;
   let auditedServers = 0;
   let unauditedServers = 0;
+  const unauditedWithUrls = [];
   
   for (const config of configs) {
     const servers = extractServersFromConfig(config.content);
@@ -779,11 +831,18 @@ async function discoverCommand() {
         console.log(`${pipe}  ${riskBadge(riskScore)} Risk ${riskScore}  ${hasOfficial ? `${c.green}✔ official${c.reset}  ` : ''}${c.dim}${REGISTRY_URL}/skills/${slug}${c.reset}`);
       } else {
         unauditedServers++;
+        // Resolve source URL
+        const resolvedUrl = await resolveSourceUrl(server);
         console.log(`${branch}  ${c.bold}${server.name}${c.reset}    ${sourceLabel}`);
-        console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Run: agentaudit audit <source-url>${c.reset}`);
+        if (resolvedUrl) {
+          console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Run: ${c.cyan}agentaudit audit ${resolvedUrl}${c.reset}`);
+          unauditedWithUrls.push({ name: server.name, sourceUrl: resolvedUrl });
+        } else {
+          console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Source URL unknown — check the package's GitHub/npm page${c.reset}`);
+        }
       }
       
-      if (server.sourceUrl) {
+      if (server.sourceUrl && !server.sourceUrl.includes('npmjs.com')) {
         console.log(`${pipe}  ${c.dim}source: ${server.sourceUrl}${c.reset}`);
       }
     }
@@ -800,8 +859,15 @@ async function discoverCommand() {
   console.log();
   
   if (unauditedServers > 0) {
-    console.log(`  ${c.dim}To audit unaudited servers, run:${c.reset}`);
-    console.log(`  ${c.cyan}agentaudit scan <github-url>${c.reset}`);
+    if (unauditedWithUrls.length > 0) {
+      console.log(`  ${c.dim}To audit unaudited servers:${c.reset}`);
+      for (const { name, sourceUrl } of unauditedWithUrls) {
+        console.log(`  ${c.cyan}agentaudit audit ${sourceUrl}${c.reset}  ${c.dim}(${name})${c.reset}`);
+      }
+    } else {
+      console.log(`  ${c.dim}To audit unaudited servers, run:${c.reset}`);
+      console.log(`  ${c.cyan}agentaudit audit <source-url>${c.reset}`);
+    }
     console.log();
   }
 }
@@ -857,15 +923,28 @@ async function auditRepo(url) {
   const openaiKey = process.env.OPENAI_API_KEY;
   
   if (!anthropicKey && !openaiKey) {
-    // No LLM API key — output the prepared audit for piping or MCP use
+    // No LLM API key — clear explanation
+    console.log();
+    console.log(`  ${c.yellow}No LLM API key found.${c.reset} The ${c.bold}audit${c.reset} command needs an LLM to analyze code.`);
+    console.log();
+    console.log(`  ${c.bold}Option 1: Set an API key${c.reset}`);
+    console.log(`  Supported keys: ${c.cyan}ANTHROPIC_API_KEY${c.reset} or ${c.cyan}OPENAI_API_KEY${c.reset}`);
+    console.log();
+    console.log(`  ${c.dim}# Linux / macOS:${c.reset}`);
+    console.log(`  ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
+    console.log(`  ${c.dim}export OPENAI_API_KEY=sk-...${c.reset}`);
+    console.log();
+    console.log(`  ${c.dim}# Windows (PowerShell):${c.reset}`);
+    console.log(`  ${c.dim}$env:ANTHROPIC_API_KEY = "sk-ant-..."${c.reset}`);
+    console.log(`  ${c.dim}$env:OPENAI_API_KEY = "sk-..."${c.reset}`);
     console.log();
-    console.log(`  ${c.yellow}No LLM API key found.${c.reset} To run the audit automatically, set one of:`);
-    console.log(`    ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
-    console.log(`    ${c.dim}export OPENAI_API_KEY=sk-...${c.reset}`);
+    console.log(`  ${c.bold}Option 2: Export for manual review${c.reset}`);
+    console.log(`  ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
+    console.log(`  ${c.dim}Creates a markdown file you can paste into any LLM (Claude, ChatGPT, etc.)${c.reset}`);
     console.log();
-    console.log(`  ${c.bold}Alternatives:${c.reset}`);
-    console.log(`    ${c.dim}1.${c.reset} Use the MCP server in Claude/Cursor — your agent runs the audit automatically`);
-    console.log(`    ${c.dim}2.${c.reset} Export for manual review: ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
+    console.log(`  ${c.bold}Option 3: Use MCP in Claude/Cursor/Windsurf (no API key needed)${c.reset}`);
+    console.log(`  ${c.dim}Add AgentAudit as MCP server — your editor's agent runs the audit using its own LLM.${c.reset}`);
+    console.log(`  ${c.dim}Config: { "mcpServers": { "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } } }${c.reset}`);
     console.log();
     
     // Check if --export flag

package/index.mjs

@@ -190,6 +190,40 @@ function discoverMcpServers() {
   return results;
 }
 
+async function resolveSourceUrl(server) {
+  if (server.npm_package) {
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(server.npm_package)}`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        let repoUrl = data.repository?.url;
+        if (repoUrl) {
+          repoUrl = repoUrl.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^ssh:\/\/git@github\.com/, 'https://github.com');
+          if (repoUrl.startsWith('http')) return repoUrl;
+        }
+      }
+    } catch {}
+    return `https://www.npmjs.com/package/${server.npm_package}`;
+  }
+  if (server.pip_package) {
+    try {
+      const res = await fetch(`https://pypi.org/pypi/${encodeURIComponent(server.pip_package)}/json`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const urls = data.info?.project_urls || {};
+        const source = urls.Source || urls.Repository || urls.Homepage || urls['Source Code'] || data.info?.home_page;
+        if (source && source.startsWith('http')) return source;
+      }
+    } catch {}
+    return `https://pypi.org/project/${server.pip_package}/`;
+  }
+  return null;
+}
+
 async function checkRegistry(slug) {
   try {
     const res = await fetch(`${REGISTRY_URL}/api/skills/${encodeURIComponent(slug)}`, {
@@ -310,8 +344,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               text += `- **Registry: ✅ Audited** — Risk ${risk}/100${official}\n`;
               text += `- Report: ${REGISTRY_URL}/skills/${slug}\n`;
             } else {
+              const sourceUrl = await resolveSourceUrl(srv);
               text += `- **Registry: ⚠️ Not audited** — no audit report found\n`;
-              text += `- To audit: call \`audit_package\` with the source URL\n`;
+              if (sourceUrl) {
+                text += `- Source: ${sourceUrl}\n`;
+                text += `- To audit: call \`audit_package\` with source_url \`${sourceUrl}\`\n`;
+              } else {
+                text += `- Source URL unknown — check the package's GitHub/npm page\n`;
+                text += `- To audit: find the source URL, then call \`audit_package\`\n`;
+              }
             }
           }
           text += `\n`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentaudit",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Security scanner for AI packages — MCP server + CLI",
   "type": "module",
   "bin": {