athena-mcp 1.0.0

package/install.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * athena-mcp install script
+ * 
+ * Installs Athena MCP tools + Skills for Claude Code.
+ * This is a pure installer — the actual tools are Python scripts.
+ * 
+ * Usage:
+ *   npx athena-mcp install
+ *   npx athena-mcp install --skip-deps
+ *   npx athena-mcp install --skip-claude
+ */
+
+const { execSync, spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ── Config ──────────────────────────────────────────────────────────────────
+const GITHUB_REPO = 'https://github.com/tiyadegure/Athena.git';
+const INSTALL_DIR = path.join(os.homedir(), '.athena');
+const SKILL_NAME = 'athena-audit-skill';
+const SKILL_SOURCE = path.join(INSTALL_DIR, 'skills', 'glm-audit-skill');
+const SKILL_DEST = path.join(os.homedir(), '.claude', 'skills', SKILL_NAME);
+const SERVERS_JSON = path.join(INSTALL_DIR, 'mcp', 'servers.json');
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+function log(msg) { console.log(`${GREEN}✓${RESET} ${msg}`); }
+function warn(msg) { console.log(`${YELLOW}⚠${RESET} ${msg}`); }
+function error(msg) { console.log(`${RED}✗${RESET} ${msg}`); }
+function info(msg) { console.log(`${CYAN}ℹ${RESET} ${msg}`); }
+function header(msg) { console.log(`\n${BOLD}${msg}${RESET}`); }
+
+function run(cmd, opts = {}) {
+  try {
+    const result = execSync(cmd, { encoding: 'utf-8', stdio: opts.silent ? 'pipe' : 'inherit', ...opts });
+    return result ? result.trim() : '';
+  } catch (e) {
+    if (!opts.optional) throw e;
+    return null;
+  }
+}
+
+function commandExists(cmd) {
+  try {
+    execSync(os.platform() === 'win32' ? `where ${cmd}` : `command -v ${cmd}`, { stdio: 'pipe' });
+    return true;
+  } catch { return false; }
+}
+
+// ── Parse args ──────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const skipDeps = args.includes('--skip-deps');
+const skipClaude = args.includes('--skip-claude');
+const skipSystem = args.includes('--skip-system');
+const help = args.includes('--help') || args.includes('-h');
+
+if (help) {
+  console.log(`
+${BOLD}athena-mcp install${RESET}
+
+Installs Athena MCP tools + Skills for Claude Code.
+
+${BOLD}Options:${RESET}
+  --skip-deps     Skip Python dependency installation
+  --skip-system   Skip system tool installation (slither, aderyn, foundry)
+  --skip-claude   Skip Claude Code MCP configuration
+  -h, --help      Show this help
+
+${BOLD}What gets installed:${RESET}
+  1. Athena repo → ~/.athena/
+  2. Python deps from requirements.txt
+  3. System tools: slither, aderyn, foundry
+  4. Skill files → ~/.claude/skills/athena-audit-skill/
+  5. MCP server config for Claude Code
+`);
+  process.exit(0);
+}
+
+// ── Banner ──────────────────────────────────────────────────────────────────
+console.log(`
+${CYAN}${BOLD}
+   ╔═══════════════════════════════════════╗
+   ║          Athena MCP Installer         ║
+   ║   Smart Contract Security Audit Tools ║
+   ╚═══════════════════════════════════════╝${RESET}
+`);
+
+// ── Step 1: Clone / update repo ─────────────────────────────────────────────
+header('Step 1/5: Clone Athena repository');
+if (fs.existsSync(path.join(INSTALL_DIR, '.git'))) {
+  info('Athena repo already exists, pulling latest...');
+  run(`cd ${INSTALL_DIR} && git pull --ff-only`, { optional: true });
+  log('Repository updated');
+} else {
+  info(`Cloning to ${INSTALL_DIR}...`);
+  run(`git clone --depth 1 ${GITHUB_REPO} ${INSTALL_DIR}`);
+  log('Repository cloned');
+}
+
+// ── Step 2: Python dependencies ─────────────────────────────────────────────
+header('Step 2/5: Install Python dependencies');
+if (skipDeps) {
+  warn('Skipping Python deps (--skip-deps)');
+} else {
+  if (!commandExists('python3')) {
+    error('python3 not found. Please install Python 3.8+');
+    process.exit(1);
+  }
+
+  const pyVersion = run('python3 --version', { silent: true });
+  info(`Found ${pyVersion}`);
+
+  // Try pip3 first, then pip
+  const pip = commandExists('pip3') ? 'pip3' : commandExists('pip') ? 'pip' : null;
+  const reqFile = path.join(INSTALL_DIR, 'requirements.txt');
+  
+  // Check if we need --break-system-packages (PEP 668)
+  const needsBreak = run('python3 -c "import sys; print(1 if hasattr(sys, \'base_prefix\') and sys.base_prefix != sys.prefix else 0)" 2>/dev/null || echo 0', { silent: true });
+  const breakFlag = ' --break-system-packages';
+  
+  if (!pip) {
+    warn('pip not found, trying python3 -m pip...');
+    const result = run(`python3 -m pip install -r ${reqFile}${breakFlag}`, { optional: true, silent: true });
+    if (result === null) {
+      error('Python deps failed. Try: python3 -m venv ~/.athena/venv && source ~/.athena/venv/bin/activate && pip install -r requirements.txt');
+    } else {
+      log('Python dependencies installed');
+    }
+  } else {
+    const result = run(`${pip} install -r ${reqFile}${breakFlag}`, { optional: true, silent: true });
+    if (result === null) {
+      error('Python deps failed. Try: python3 -m venv ~/.athena/venv && source ~/.athena/venv/bin/activate && pip install -r requirements.txt');
+    } else {
+      log('Python dependencies installed');
+    }
+  }
+}
+
+// ── Step 3: System tools ────────────────────────────────────────────────────
+header('Step 3/5: Install system tools (slither, aderyn, foundry)');
+if (skipSystem) {
+  warn('Skipping system tools (--skip-system)');
+} else {
+  // Slither
+  if (commandExists('slither')) {
+    log('Slither already installed');
+  } else {
+    info('Installing Slither...');
+    const pip = commandExists('pip3') ? 'pip3' : 'pip';
+    run(`${pip} install slither-analyzer`, { optional: true });
+    if (commandExists('slither')) log('Slither installed');
+    else warn('Slither install failed — install manually: pip install slither-analyzer');
+  }
+
+  // Aderyn
+  if (commandExists('aderyn')) {
+    log('Aderyn already installed');
+  } else if (commandExists('cargo')) {
+    info('Installing Aderyn via cargo...');
+    run('cargo install aderyn', { optional: true });
+    if (commandExists('aderyn')) log('Aderyn installed');
+    else warn('Aderyn install failed — install manually: cargo install aderyn');
+  } else {
+    warn('cargo not found, skipping Aderyn. Install Rust first: https://rustup.rs');
+  }
+
+  // Foundry
+  if (commandExists('forge')) {
+    log('Foundry already installed');
+  } else {
+    info('Installing Foundry...');
+    run('curl -L https://foundry.paradigm.xyz | bash', { optional: true, stdio: 'pipe' });
+    // Source the env
+    const foundryBin = path.join(os.homedir(), '.foundry', 'bin');
+    if (fs.existsSync(foundryBin)) {
+      process.env.PATH = `${foundryBin}:${process.env.PATH}`;
+    }
+    run(`${foundryBin}/foundryup`, { optional: true });
+    if (commandExists('forge') || fs.existsSync(path.join(foundryBin, 'forge'))) {
+      log('Foundry installed');
+    } else {
+      warn('Foundry install failed — install manually: curl -L https://foundry.paradigm.xyz | bash');
+    }
+  }
+}
+
+// ── Step 4: Copy Skill files ────────────────────────────────────────────────
+header('Step 4/5: Install audit skill');
+if (fs.existsSync(SKILL_SOURCE)) {
+  // Create destination
+  fs.mkdirSync(path.dirname(SKILL_DEST), { recursive: true });
+  
+  // Copy recursively
+  function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+  
+  copyDir(SKILL_SOURCE, SKILL_DEST);
+  log(`Skill installed to ${SKILL_DEST}`);
+} else {
+  warn(`Skill source not found at ${SKILL_SOURCE}`);
+}
+
+// ── Step 5: Configure Claude Code MCP ───────────────────────────────────────
+header('Step 5/5: Configure Claude Code MCP servers');
+if (skipClaude) {
+  warn('Skipping Claude Code config (--skip-claude)');
+} else {
+  // Read servers.json
+  if (fs.existsSync(SERVERS_JSON)) {
+    const config = JSON.parse(fs.readFileSync(SERVERS_JSON, 'utf-8'));
+    const hasClaudeCmd = commandExists('claude');
+    
+    if (hasClaudeCmd) {
+      info('Found claude CLI, registering MCP servers...');
+      for (const server of config.servers) {
+        const toolPath = path.join(INSTALL_DIR, server.args[0]);
+        try {
+          // claude mcp add <name> -- <command> <args...>
+          const cmd = `claude mcp add athena-${server.name} -- ${server.command} ${toolPath}`;
+          run(cmd, { silent: true, optional: true });
+          log(`Registered: athena-${server.name}`);
+        } catch (e) {
+          warn(`Failed to register athena-${server.name}: ${e.message}`);
+        }
+      }
+    } else {
+      // Generate settings.json snippet
+      info('claude CLI not found, generating config snippet...');
+      
+      const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+      const mcpServers = {};
+      
+      for (const server of config.servers) {
+        const toolPath = path.join(INSTALL_DIR, server.args[0]);
+        mcpServers[`athena-${server.name}`] = {
+          command: server.command,
+          args: [toolPath],
+          env: server.env || {}
+        };
+      }
+      
+      const snippet = {
+        mcpServers
+      };
+      
+      const snippetPath = path.join(INSTALL_DIR, 'claude-mcp-config.json');
+      fs.writeFileSync(snippetPath, JSON.stringify(snippet, null, 2));
+      
+      console.log(`
+${YELLOW}${BOLD}Manual Configuration Required${RESET}
+${DIM}${'─'.repeat(50)}${RESET}
+
+Claude CLI not found. Add this to ${BOLD}~/.claude/settings.json${RESET}:
+
+${CYAN}${JSON.stringify(snippet, null, 2)}${RESET}
+
+Or install the Claude CLI and re-run:
+${DIM}  npx athena-mcp install${RESET}
+
+Config saved to: ${DIM}${snippetPath}${RESET}
+`);
+    }
+  } else {
+    warn('servers.json not found, skipping MCP configuration');
+  }
+}
+
+// ── Summary ─────────────────────────────────────────────────────────────────
+console.log(`
+${GREEN}${BOLD}
+   ╔═══════════════════════════════════════╗
+   ║       Installation Complete! ✨        ║
+   ╚═══════════════════════════════════════╝${RESET}
+
+${BOLD}Installed:${RESET}
+  📁 Athena repo     → ${DIM}${INSTALL_DIR}${RESET}
+  🔧 MCP tools       → ${DIM}${INSTALL_DIR}/mcp/tools/${RESET} (13 tools)
+  📚 Audit skill     → ${DIM}${SKILL_DEST}${RESET}
+  ⚙️  Python deps     → ${DIM}requirements.txt${RESET}
+
+${BOLD}Quick Start:${RESET}
+
+  ${CYAN}# Audit a Solidity contract${RESET}
+  claude "audit contracts/MyToken.sol"
+
+  ${CYAN}# Run Slither analysis directly${RESET}
+  python3 ${INSTALL_DIR}/mcp/tools/slither_runner.py
+
+  ${CYAN}# Full audit workflow${RESET}
+  claude "read ${INSTALL_DIR}/AGENT-WORKFLOW-FINAL.md and audit this project"
+
+${BOLD}MCP Tools:${RESET}
+  • slither      — Static analysis (Trail of Bits)
+  • aderyn       — Static analysis (Cyfrin, Rust-based)
+  • poc-generator — PoC exploit test generation
+  • fuzz-runner  — Foundry fuzz/invariant tests
+  • knowledge-base — RAG vulnerability database
+  • eas-attest   — On-chain EAS attestation
+  • exploit-simulator — Attack simulation
+  • evidence-chain — Merkle audit trail
+  • halmos       — Formal verification
+  • protocol-scanner — Protocol-level scanning
+  • repair-validator — Fix validation
+  • incremental-auditor — Diff-based auditing
+  • gev-analyzer — Governance/Economic/Value analysis
+
+${DIM}Docs: https://github.com/tiyadegure/Athena${RESET}
+`);

package/mcp/servers.json

@@ -0,0 +1,100 @@
+{
+  "servers": [
+    {
+      "name": "slither",
+      "command": "python3",
+      "args": ["mcp/tools/slither_runner.py"],
+      "description": "Slither static analysis for Solidity contracts",
+      "env": {}
+    },
+    {
+      "name": "aderyn",
+      "command": "python3",
+      "args": ["mcp/tools/aderyn_runner.py"],
+      "description": "Aderyn static analysis (Rust-based) for Solidity projects",
+      "env": {}
+    },
+    {
+      "name": "poc-generator",
+      "command": "python3",
+      "args": ["mcp/tools/poc_generator.py"],
+      "description": "Generate Foundry PoC exploit tests for vulnerabilities",
+      "env": {}
+    },
+    {
+      "name": "fuzz-runner",
+      "command": "python3",
+      "args": ["mcp/tools/fuzz_runner.py"],
+      "description": "Run Foundry fuzz and invariant tests",
+      "env": {}
+    },
+    {
+      "name": "knowledge-base",
+      "command": "python3",
+      "args": ["mcp/tools/knowledge_base.py"],
+      "description": "Query vulnerability knowledge base (ChromaDB RAG)",
+      "env": {
+        "KNOWLEDGE_PATH": "data/knowledge"
+      }
+    },
+    {
+      "name": "eas-attest",
+      "command": "python3",
+      "args": ["mcp/tools/eas_attest.py"],
+      "description": "Submit EAS attestation on Sepolia testnet",
+      "env": {
+        "SEPOLIA_RPC_URL": "https://sepolia.drpc.org",
+        "EAS_CONTRACT_ADDRESS": "0xC2679fBD37d54388Ce493F1DB75320D236e1815e"
+      }
+    },
+    {
+      "name": "exploit-simulator",
+      "command": "python3",
+      "args": ["mcp/tools/exploit_simulator.py"],
+      "description": "Simulate attack scenarios against smart contracts",
+      "env": {}
+    },
+    {
+      "name": "evidence-chain",
+      "command": "python3",
+      "args": ["mcp/tools/evidence_chain.py"],
+      "description": "Merkle-based audit evidence chain for verifiable audit trails",
+      "env": {}
+    },
+    {
+      "name": "halmos-runner",
+      "command": "python3",
+      "args": ["mcp/tools/halmos_runner.py"],
+      "description": "Symbolic execution and formal verification via Halmos",
+      "env": {}
+    },
+    {
+      "name": "protocol-scanner",
+      "command": "python3",
+      "args": ["mcp/tools/protocol_scanner.py"],
+      "description": "Protocol-level dependency and interaction scanning",
+      "env": {}
+    },
+    {
+      "name": "repair-validator",
+      "command": "python3",
+      "args": ["mcp/tools/repair_validator.py"],
+      "description": "Validate that vulnerability fixes are correct and complete",
+      "env": {}
+    },
+    {
+      "name": "incremental-auditor",
+      "command": "python3",
+      "args": ["mcp/tools/incremental_auditor.py"],
+      "description": "Incremental audit for contract updates and diffs",
+      "env": {}
+    },
+    {
+      "name": "gev-analyzer",
+      "command": "python3",
+      "args": ["mcp/tools/gev_analyzer.py"],
+      "description": "Governance, Economic, and Value analysis for DeFi protocols",
+      "env": {}
+    }
+  ]
+}

package/mcp/tools/README.md

@@ -0,0 +1,64 @@
+# MCP Tools
+
+Standalone MCP (Model Context Protocol) tool servers for Athena. Each tool runs as an independent process communicating via JSON-RPC over stdio.
+
+## Tools (13)
+
+| Tool | Script | Description |
+|------|--------|-------------|
+| Slither | `slither_runner.py` | Static analysis via Slither (Trail of Bits) |
+| Aderyn | `aderyn_runner.py` | Static analysis via Aderyn (Rust-based, Cyfrin) |
+| PoC Generator | `poc_generator.py` | Generates Foundry exploit test contracts |
+| Fuzz Runner | `fuzz_runner.py` | Runs Foundry fuzz tests with A1 signal extraction |
+| Knowledge Base | `knowledge_base.py` | ChromaDB RAG queries for vulnerability patterns |
+| EAS Attestation | `eas_attest.py` | On-chain audit attestation via EAS on Sepolia |
+| Exploit Simulator | `exploit_simulator.py` | Simulates attack scenarios against contracts |
+| Evidence Chain | `evidence_chain.py` | Merkle-based audit evidence chain |
+| Halmos | `halmos_runner.py` | Symbolic execution / formal verification via Halmos |
+| Protocol Scanner | `protocol_scanner.py` | Protocol-level dependency and interaction scanning |
+| Repair Validator | `repair_validator.py` | Validates that vulnerability fixes are correct |
+| Incremental Auditor | `incremental_auditor.py` | Incremental audit for contract updates |
+| GEV Analyzer | `gev_analyzer.py` | Governance/Economic/Value analysis |
+
+## Protocol
+
+Each tool implements MCP JSON-RPC over stdio:
+
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "slither_analyze", "arguments": {"contract_path": "./src/Token.sol"}}}
+```
+
+## Environment Variables
+
+| Variable | Tool | Description |
+|----------|------|-------------|
+| `OPENAI_API_BASE` | poc_generator | LLM API endpoint for PoC generation |
+| `OPENAI_API_KEY` | poc_generator | LLM API key |
+| `LLM_MODEL` | poc_generator | Model name (default: gpt-4) |
+| `CHROMA_DB_PATH` | knowledge_base | ChromaDB storage path |
+| `SEPOLIA_PRIVATE_KEY` | eas_attest | Private key for on-chain attestation |
+| `SEPOLIA_RPC_URL` | eas_attest | Sepolia RPC endpoint |
+
+## Running
+
+Each tool can be run standalone:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 slither_runner.py
+```
+
+## Dependencies
+
+- **slither_runner.py**: `pip install slither-analyzer`
+- **aderyn_runner.py**: `cargo install aderyn`
+- **poc_generator.py**: `pip install aiohttp` (optional, for LLM mode)
+- **fuzz_runner.py**: `forge` (Foundry)
+- **knowledge_base.py**: `pip install chromadb sentence-transformers` (optional, has fallback)
+- **eas_attest.py**: `pip install web3 eth-account` (optional, has mock mode)
+- **exploit_simulator.py**: `pip install web3 aiohttp`
+- **evidence_chain.py**: `pip install web3`
+- **halmos_runner.py**: `pip install halmos` (requires Foundry)
+- **protocol_scanner.py**: `pip install web3 aiohttp`
+- **repair_validator.py**: `pip install slither-analyzer`
+- **incremental_auditor.py**: `pip install chromadb`
+- **gev_analyzer.py**: `pip install web3 aiohttp`

package/mcp/tools/__init__.py

@@ -0,0 +1 @@
+# MCP Tools - Standalone wrappers for audit toolchain