hopeid 0.1.0 → 1.1.0

package/README.md

@@ -17,11 +17,41 @@ hopeIDS protects AI agents from prompt injection attacks, credential theft, data
 
 ## Installation
 
+### Full OpenClaw Setup (Recommended)
+
+```bash
+npx hopeid setup
+```
+
+This single command:
+1. ✅ Installs the hopeIDS OpenClaw plugin
+2. ✅ Installs the hopeids skill via ClawHub
+3. ✅ Configures `security_scan` tool for your agent
+4. ✅ Adds `/scan` command for manual checks
+
+After setup, restart OpenClaw: `openclaw gateway restart`
+
+📖 **[How to Set Up a Sandboxed AI Agent](https://exohaven.online/blog/sandboxed-agents-security-guide)** — Full guide on workspace isolation, IDS-first workflows, and protecting agents from prompt injection.
+
+### Manual Installation
+
+**Skill only (agent guidance):**
+```bash
+clawhub install hopeids
+```
+
+**npm package (for custom integrations):**
 ```bash
 npm install hopeid
 ```
 
-Or use directly:
+### Via npm (Node.js Apps)
+
+```bash
+npm install hopeid
+```
+
+### CLI (Quick Test)
 
 ```bash
 npx hopeid scan "your message here"
@@ -44,6 +74,102 @@ console.log(result2.action); // 'block'
 console.log(result2.message); // "Nope. 'Ignore previous instructions' doesn't work on me..."
 ```
 
+## Local LLM Support
+
+**hopeIDS works out-of-the-box with local LLMs!** No OpenAI API key required.
+
+### Supported Providers
+
+- **Ollama** (recommended) — `http://localhost:11434`
+- **LM Studio** — `http://localhost:1234`
+- **OpenAI** — Cloud-based (requires API key)
+- **Auto-detect** — Automatically finds running local LLM
+
+### Quick Setup
+
+**1. Install Ollama:**
+
+```bash
+# macOS/Linux
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Pull a recommended model
+ollama pull qwen2.5:7b
+```
+
+**2. Use hopeIDS:**
+
+```javascript
+const { HopeIDS } = require('hopeid');
+
+// Auto-detect (finds Ollama/LM Studio automatically)
+const ids = new HopeIDS({
+  semanticEnabled: true,
+  llmProvider: 'auto'  // default
+});
+
+// Explicitly use Ollama
+const ids = new HopeIDS({
+  semanticEnabled: true,
+  llmProvider: 'ollama',
+  llmModel: 'qwen2.5:7b'
+});
+
+// Explicitly use LM Studio
+const ids = new HopeIDS({
+  semanticEnabled: true,
+  llmProvider: 'lmstudio',
+  llmModel: 'qwen2.5-32b'
+});
+```
+
+### Recommended Models
+
+For **best accuracy**, use these models:
+
+| Model | Size | Provider | Accuracy | Speed |
+|-------|------|----------|----------|-------|
+| `qwen2.5:32b` | 20GB | Ollama, LM Studio | ⭐⭐⭐⭐⭐ | ⚡⚡ |
+| `qwen2.5:14b` | 9GB | Ollama, LM Studio | ⭐⭐⭐⭐ | ⚡⚡⚡ |
+| `qwen2.5:7b` | 4.7GB | Ollama, LM Studio | ⭐⭐⭐ | ⚡⚡⚡⚡ |
+| `mistral:7b` | 4.1GB | Ollama, LM Studio | ⭐⭐⭐ | ⚡⚡⚡⚡ |
+| `llama3:8b` | 4.7GB | Ollama, LM Studio | ⭐⭐⭐ | ⚡⚡⚡ |
+| `gpt-4o-mini` | Cloud | OpenAI | ⭐⭐⭐⭐⭐ | ⚡⚡⚡⚡ |
+| `gpt-3.5-turbo` | Cloud | OpenAI | ⭐⭐⭐⭐ | ⚡⚡⚡⚡⚡ |
+
+**For production:** Use `qwen2.5:14b` or larger for best threat detection.  
+**For development:** Use `qwen2.5:7b` or `mistral:7b` for fast iteration.  
+**For edge devices:** Use `qwen2.5:3b` (not recommended for production).
+
+### Environment Variables
+
+```bash
+# Auto-detect (default)
+export LLM_PROVIDER=auto
+
+# Force Ollama
+export LLM_PROVIDER=ollama
+export LLM_MODEL=qwen2.5:7b
+
+# Force LM Studio
+export LLM_PROVIDER=lmstudio
+export LLM_ENDPOINT=http://localhost:1234/v1/chat/completions
+export LLM_MODEL=qwen2.5-14b
+
+# Use OpenAI
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=sk-...
+export LLM_MODEL=gpt-4o-mini
+```
+
+### Why Local LLMs?
+
+- ✅ **Privacy**: Your data never leaves your machine
+- ✅ **Cost**: No per-token charges
+- ✅ **Speed**: Low-latency inference
+- ✅ **Offline**: Works without internet
+- ✅ **Control**: Fine-tune for your use case
+
 ## CLI Usage
 
 ```bash
@@ -296,8 +422,16 @@ The middleware automatically:
 const ids = new HopeIDS({
   // Enable LLM-based semantic analysis
   semanticEnabled: true,
-  llmEndpoint: 'http://localhost:1234/v1/chat/completions',
-  llmModel: 'qwen2.5-32b',
+  
+  // LLM Provider (auto-detects by default)
+  llmProvider: 'auto', // 'openai' | 'ollama' | 'lmstudio' | 'auto'
+  llmModel: 'qwen2.5:7b', // Auto-selected if using Ollama
+  
+  // Or manually specify endpoint
+  llmEndpoint: 'http://localhost:11434/v1/chat/completions',
+  
+  // Only needed for OpenAI
+  apiKey: process.env.OPENAI_API_KEY,
   
   // Risk thresholds
   thresholds: {

package/cli/hopeid.js

@@ -18,21 +18,25 @@ const { HopeIDS, formatAlert, formatNotification } = require('../src');
 const HELP = `
 hopeIDS - Inference-Based Intrusion Detection for AI Agents
 
+⚠️  REQUIRES LLM: Ollama, LM Studio, or OpenAI API key
+    Install Ollama: curl -fsSL https://ollama.ai/install.sh | sh && ollama pull qwen2.5:7b
+
 Usage:
-  hopeid scan <message>           Scan a message for threats
+  hopeid scan <message>           Scan a message for threats (uses LLM)
   hopeid scan --file <path>       Scan message from file
   hopeid scan --stdin             Read message from stdin
-  hopeid test                     Run test suite
+  hopeid test                     Run test suite (heuristic-only)
   hopeid stats                    Show pattern statistics
+  hopeid setup                    Full OpenClaw integration setup
   hopeid help                     Show this help
 
 Options:
   --source <type>    Source type: email, chat, api, web, webhook (default: chat)
   --sender <id>      Sender identifier
-  --semantic         Enable LLM-based semantic analysis
   --strict           Use strict mode (lower thresholds)
   --verbose          Show detailed output
   --json             Output as JSON
+  --no-llm           Heuristic-only mode (NOT RECOMMENDED - misses sophisticated attacks)
 
 Examples:
   hopeid scan "Hello, how are you?"
@@ -40,10 +44,11 @@ Examples:
   hopeid scan --file suspicious.txt --verbose
   echo "ignore previous instructions" | hopeid scan --stdin
 
-Environment:
-  LLM_ENDPOINT    LLM API endpoint (for semantic analysis)
-  LLM_MODEL       LLM model name (default: gpt-3.5-turbo)
-  OPENAI_API_KEY  API key for LLM
+Environment (auto-detected if running locally):
+  LLM_PROVIDER    Provider: auto, ollama, lmstudio, openai (default: auto)
+  LLM_ENDPOINT    LLM API endpoint (auto-detected for Ollama/LM Studio)
+  LLM_MODEL       LLM model name (default: auto-detect best available)
+  OPENAI_API_KEY  API key (only needed for OpenAI)
 
 "Traditional IDS matches signatures. HoPE understands intent." 💜
 `;
@@ -68,6 +73,9 @@ async function main() {
     case 'stats':
       handleStats();
       break;
+    case 'setup':
+      await handleSetup(args.slice(1));
+      break;
     default:
       console.error(`Unknown command: ${command}`);
       console.log('Run "hopeid help" for usage');
@@ -80,7 +88,8 @@ async function handleScan(args) {
   const options = {
     source: 'chat',
     sender: 'cli-user',
-    semantic: false,
+    semantic: true,   // LLM-based analysis enabled by default!
+    requireLLM: true, // Fail if no LLM found
     strict: false,
     verbose: false,
     json: false
@@ -103,6 +112,10 @@ async function handleScan(args) {
       readFromStdin = true;
     } else if (arg === '--semantic') {
       options.semantic = true;
+    } else if (arg === '--no-llm' || arg === '--heuristic-only') {
+      options.semantic = false;
+      options.requireLLM = false;
+      console.warn('⚠️  Running in heuristic-only mode (NOT RECOMMENDED)');
     } else if (arg === '--strict') {
       options.strict = true;
     } else if (arg === '--verbose') {
@@ -130,6 +143,7 @@ async function handleScan(args) {
   // Create IDS instance
   const ids = new HopeIDS({
     semanticEnabled: options.semantic,
+    requireLLM: options.requireLLM,
     strictMode: options.strict
   });
 
@@ -186,8 +200,8 @@ async function handleTest(args) {
     ? args[args.indexOf('--benign') + 1]
     : path.join(testDir, 'benign');
 
-  // Create fresh IDS for attacks
-  let ids = new HopeIDS({ semanticEnabled: false, logLevel: 'error' });
+  // Create fresh IDS for attacks (heuristic-only for testing)
+  let ids = new HopeIDS({ semanticEnabled: false, requireLLM: false, logLevel: 'error' });
   
   console.log('\n🛡️  hopeIDS Test Suite\n');
   
@@ -217,7 +231,7 @@ async function handleTest(args) {
   }
 
   // Create fresh IDS for benign tests (reset context)
-  ids = new HopeIDS({ semanticEnabled: false, logLevel: 'error' });
+  ids = new HopeIDS({ semanticEnabled: false, requireLLM: false, logLevel: 'error' });
 
   // Test benign (should not be detected)
   if (fs.existsSync(benignDir)) {
@@ -276,6 +290,265 @@ function readStdin() {
   });
 }
 
+async function handleSetup(args) {
+  const { execSync, spawnSync } = require('child_process');
+  const os = require('os');
+  
+  console.log('\n🛡️  hopeIDS Full Setup for OpenClaw\n');
+  console.log('This will:');
+  console.log('  1. Install hopeIDS plugin to OpenClaw');
+  console.log('  2. Install hopeids skill via ClawHub');
+  console.log('  3. Configure security_scan tool');
+  console.log('  4. Set up sandboxing for public-facing agents');
+  console.log('  5. Create secure agent identity templates\n');
+
+  // Find OpenClaw config
+  const homeDir = os.homedir();
+  const configPaths = [
+    path.join(homeDir, '.openclaw', 'openclaw.json'),
+    path.join(process.cwd(), 'openclaw.json'),
+    path.join(process.cwd(), '.openclaw', 'openclaw.json')
+  ];
+
+  let configPath = null;
+  let configDir = null;
+  for (const p of configPaths) {
+    if (fs.existsSync(p)) {
+      configPath = p;
+      configDir = path.dirname(p);
+      break;
+    }
+  }
+
+  if (!configPath) {
+    console.log('❌ OpenClaw config not found.');
+    console.log('   Searched: ~/.openclaw/openclaw.json, ./openclaw.json');
+    console.log('   Make sure OpenClaw is installed first.\n');
+    process.exit(1);
+  }
+
+  console.log(`✅ Found OpenClaw config: ${configPath}\n`);
+
+  // Find hopeIDS installation path
+  let hopeidsPath = null;
+  
+  // Check if we're running from the hopeIDS repo
+  const localPluginPath = path.join(__dirname, '..', 'extensions', 'openclaw-plugin');
+  if (fs.existsSync(localPluginPath)) {
+    hopeidsPath = path.resolve(localPluginPath);
+  } else {
+    // Try to find it in node_modules
+    try {
+      const hopeidPkg = require.resolve('hopeid/package.json');
+      hopeidsPath = path.join(path.dirname(hopeidPkg), 'extensions', 'openclaw-plugin');
+    } catch (e) {
+      // Not found
+    }
+  }
+
+  if (!hopeidsPath || !fs.existsSync(hopeidsPath)) {
+    console.log('❌ hopeIDS plugin not found.');
+    console.log('   Install globally: npm install -g hopeid');
+    console.log('   Or clone the repo: git clone https://github.com/E-x-O-Entertainment-Studios-Inc/hopeIDS\n');
+    process.exit(1);
+  }
+
+  console.log(`✅ Found hopeIDS plugin: ${hopeidsPath}\n`);
+
+  // Read and update OpenClaw config
+  console.log('📝 Updating OpenClaw config...');
+  
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch (e) {
+    console.log(`❌ Failed to parse config: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Initialize plugins structure if needed
+  if (!config.plugins) config.plugins = {};
+  if (!config.plugins.load) config.plugins.load = {};
+  if (!config.plugins.load.paths) config.plugins.load.paths = [];
+  if (!config.plugins.entries) config.plugins.entries = {};
+
+  // Add plugin path if not already there
+  if (!config.plugins.load.paths.includes(hopeidsPath)) {
+    config.plugins.load.paths.push(hopeidsPath);
+    console.log('   ✅ Added plugin path');
+  } else {
+    console.log('   ⏭️  Plugin path already configured');
+  }
+
+  // Enable the plugin
+  if (!config.plugins.entries.hopeids) {
+    config.plugins.entries.hopeids = { enabled: true };
+    console.log('   ✅ Enabled hopeids plugin');
+  } else {
+    config.plugins.entries.hopeids.enabled = true;
+    console.log('   ⏭️  Plugin already enabled');
+  }
+
+  // Configure sandboxing for non-main agents
+  console.log('\n🔒 Configuring sandbox for public-facing agents...');
+  
+  if (!config.agents) config.agents = {};
+  if (!config.agents.defaults) config.agents.defaults = {};
+  
+  if (!config.agents.defaults.sandbox) {
+    config.agents.defaults.sandbox = {
+      mode: 'non-main',
+      scope: 'session',
+      workspaceAccess: 'none'
+    };
+    console.log('   ✅ Sandbox enabled for non-main agents');
+    console.log('      Mode: non-main (main agent runs on host, others sandboxed)');
+    console.log('      Scope: session (each session gets isolated container)');
+    console.log('      Workspace: none (sandboxed agents get clean workspace)');
+  } else {
+    console.log('   ⏭️  Sandbox already configured');
+  }
+
+  // Write updated config
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  console.log('   ✅ Config saved\n');
+
+  // Install skill via ClawHub
+  console.log('📦 Installing hopeids skill via ClawHub...');
+  
+  try {
+    const result = spawnSync('npx', ['clawhub', 'install', 'hopeids', '--force'], {
+      stdio: 'inherit',
+      shell: true
+    });
+    
+    if (result.status === 0) {
+      console.log('   ✅ Skill installed\n');
+    } else {
+      console.log('   ⚠️  Skill install had issues (may already be installed)\n');
+    }
+  } catch (e) {
+    console.log(`   ⚠️  Could not install skill: ${e.message}`);
+    console.log('   Run manually: npx clawhub install hopeids\n');
+  }
+
+  // Check for USER.md privacy issues in workspace
+  console.log('🔍 Checking for privacy leaks in workspace files...');
+  
+  const workspacePath = config.agents?.defaults?.workspace || path.join(configDir, 'workspace');
+  const userMdPath = path.join(workspacePath, 'USER.md');
+  
+  let userMdWarning = false;
+  if (fs.existsSync(userMdPath)) {
+    const userMdContent = fs.readFileSync(userMdPath, 'utf-8');
+    // Check for personal info patterns
+    const hasName = /\*\*Name:\*\*\s*.+/i.test(userMdContent) || /name:\s*[A-Z][a-z]+/i.test(userMdContent);
+    const hasLocation = /location|timezone|address/i.test(userMdContent);
+    const hasPersonalInfo = /phone|email|social|@/i.test(userMdContent);
+    
+    if (hasName || hasLocation || hasPersonalInfo) {
+      userMdWarning = true;
+      console.log('   ⚠️  USER.md contains personal information!');
+    } else {
+      console.log('   ✅ USER.md looks safe');
+    }
+  } else {
+    console.log('   ℹ️  No USER.md found (that\'s fine)');
+  }
+
+  // Check sandboxes directory for leaked files
+  const sandboxesDir = path.join(configDir, 'sandboxes');
+  let sandboxLeaks = [];
+  
+  if (fs.existsSync(sandboxesDir)) {
+    const sandboxes = fs.readdirSync(sandboxesDir);
+    for (const sandbox of sandboxes) {
+      const sandboxUserMd = path.join(sandboxesDir, sandbox, 'USER.md');
+      if (fs.existsSync(sandboxUserMd)) {
+        const content = fs.readFileSync(sandboxUserMd, 'utf-8');
+        // Check for actual personal info (not just empty template fields)
+        const hasRealName = /\*\*Name:\*\*\s*[A-Z][a-z]+\s+[A-Z]/i.test(content);  // "Name: First Last"
+        const hasLocation = /\*\*Location:\*\*\s*[A-Z]/i.test(content);
+        const isSanitized = /never mention|don't share|no personal|public.?facing/i.test(content);
+        
+        if ((hasRealName || hasLocation) && !isSanitized) {
+          sandboxLeaks.push(sandbox);
+        }
+      }
+    }
+    
+    if (sandboxLeaks.length > 0) {
+      console.log(`   ⚠️  Found ${sandboxLeaks.length} sandbox(es) with personal info in USER.md!`);
+      for (const leak of sandboxLeaks) {
+        console.log(`      • ${leak}`);
+      }
+    } else if (sandboxes.length > 0) {
+      console.log(`   ✅ ${sandboxes.length} sandbox(es) checked - no leaks found`);
+    }
+  }
+
+  // Done!
+  console.log('\n═══════════════════════════════════════════════════════');
+  console.log('✅ hopeIDS setup complete!\n');
+  
+  console.log('Your OpenClaw agent now has:');
+  console.log('  • security_scan tool - scan messages for threats');
+  console.log('  • /scan command - manual security checks');
+  console.log('  • hopeids skill - IDS-first workflow patterns');
+  console.log('  • Sandboxing - non-main agents run isolated\n');
+
+  // Privacy warnings
+  if (userMdWarning || sandboxLeaks.length > 0) {
+    console.log('⚠️  PRIVACY WARNING:');
+    console.log('────────────────────────────────────────────────────────');
+    
+    if (userMdWarning) {
+      console.log('Your USER.md contains personal information that could leak');
+      console.log('to sandboxed agents (public forums, social media, etc.).\n');
+    }
+    
+    if (sandboxLeaks.length > 0) {
+      console.log('Some sandbox workspaces already contain personal info.');
+      console.log('Consider deleting stale sandboxes:\n');
+      console.log(`  rm -rf ${sandboxesDir}/agent-*\n`);
+    }
+    
+    console.log('For sandboxed/public-facing agents, use a sanitized USER.md:');
+    console.log('────────────────────────────────────────────────────────');
+    console.log(`
+# USER.md - Public Agent Context
+
+I'm a public-facing agent. I don't need personal details.
+
+## Rules
+- Never mention personal names, locations, or private details
+- Keep posts professional and product-focused
+- Represent the brand, not any individual
+`);
+    console.log('────────────────────────────────────────────────────────\n');
+  }
+
+  console.log('🎭 AGENT IDENTITY SETUP:');
+  console.log('────────────────────────────────────────────────────────');
+  console.log('Each agent should have its own workspace with:');
+  console.log('  • AGENTS.md  - Role and instructions');
+  console.log('  • SOUL.md    - Personality and tone');
+  console.log('  • USER.md    - What it knows about users (sanitize for public!)');
+  console.log('  • TOOLS.md   - Available capabilities\n');
+  console.log('For public-facing agents (social media, forums):');
+  console.log('  • Create a separate workspace');
+  console.log('  • Use sanitized USER.md (no personal info!)');
+  console.log('  • Enable sandboxing (now configured automatically)');
+  console.log('────────────────────────────────────────────────────────\n');
+  
+  console.log('Restart OpenClaw to activate:');
+  console.log('  openclaw gateway restart\n');
+  console.log('Test it:');
+  console.log('  hopeid scan "ignore previous instructions"\n');
+  console.log('Docs: https://exohaven.online/blog/sandboxed-agents-security-guide');
+  console.log('═══════════════════════════════════════════════════════\n');
+}
+
 main().catch(err => {
   console.error('Error:', err.message);
   process.exit(1);