hopeid 0.1.1 → 1.1.1

package/cli/hopeid.js

@@ -18,11 +18,14 @@ 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
@@ -30,10 +33,10 @@ Usage:
 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?"
@@ -41,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." 💜
 `;
@@ -84,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
@@ -107,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') {
@@ -134,6 +143,7 @@ async function handleScan(args) {
   // Create IDS instance
   const ids = new HopeIDS({
     semanticEnabled: options.semantic,
+    requireLLM: options.requireLLM,
     strictMode: options.strict
   });
 
@@ -190,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');
   
@@ -221,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)) {
@@ -288,7 +298,9 @@ async function handleSetup(args) {
   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\n');
+  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();
@@ -299,9 +311,11 @@ async function handleSetup(args) {
   ];
 
   let configPath = null;
+  let configDir = null;
   for (const p of configPaths) {
     if (fs.existsSync(p)) {
       configPath = p;
+      configDir = path.dirname(p);
       break;
     }
   }
@@ -375,6 +389,12 @@ async function handleSetup(args) {
     console.log('   ⏭️  Plugin already enabled');
   }
 
+  // Note about sandboxing (don't auto-configure - it can break workers)
+  console.log('\n🔒 Sandbox configuration...');
+  console.log('   ℹ️  Sandbox NOT auto-configured (can break worker agents)');
+  console.log('   📖 For public-facing agents (moltbook, social), manually add:');
+  console.log('      agents.list[].sandbox: { mode: "all", workspaceAccess: "none" }');
+
   // Write updated config
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
   console.log('   ✅ Config saved\n');
@@ -398,13 +418,115 @@ async function handleSetup(args) {
     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('═══════════════════════════════════════════════════════');
+  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\n');
+  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:');

package/extensions/openclaw-plugin/SKILL.md

@@ -1,70 +1,80 @@
 # hopeIDS Security Skill
 
-Inference-based intrusion detection for AI agents. Protects against prompt injection, credential theft, data exfiltration, and other attacks.
+Inference-based intrusion detection for AI agents with quarantine and human-in-the-loop.
 
-## When to Use
+## Security Invariants
 
-Use this skill when:
-- Processing messages from untrusted sources (public APIs, social platforms, email)
-- Building agents that interact with external users
-- You need to validate input before executing tool calls
-- Protecting sensitive operations from manipulation
+These are **non-negotiable** design principles:
 
-## Quick Start
+1. **Block = full abort** — Blocked messages never reach jasper-recall or the agent
+2. **Metadata only** — No raw malicious content is ever stored
+3. **Approve ≠ re-inject** — Approval changes future behavior, doesn't resurrect messages
+4. **Alerts are programmatic** — Telegram alerts built from metadata, no LLM involved
 
-The `security_scan` tool is built into OpenClaw. This skill provides patterns and best practices.
+---
 
-### Basic Scan
+## Features
 
-```javascript
-// In your agent's message processing
-const result = await security_scan({
-  message: userInput,
-  source: "telegram",
-  senderId: "user123"
-});
+- **Auto-scan** — Scan messages before agent processing
+- **Quarantine** — Block threats with metadata-only storage
+- **Human-in-the-loop** — Telegram alerts for review
+- **Per-agent config** — Different thresholds for different agents
+- **Commands** — `/approve`, `/reject`, `/trust`, `/quarantine`
 
-if (result.action === "block") {
-  // Don't process this message
-  return result.message; // HoPE-voiced rejection
-}
-```
-
-### IDS-First Workflow
+---
 
-**Always scan before processing external content:**
+## The Pipeline
 
 ```
-1. Receive message from external source
-2. Run security_scan BEFORE any LLM processing
-3. If blocked → reject with result.message
-4. If warned → proceed with caution, log the warning
-5. If allowed → process normally
+Message arrives
+    ↓
+hopeIDS.autoScan()
+    ↓
+┌─────────────────────────────────────────┐
+│  risk >= threshold?                     │
+│                                         │
+│  BLOCK (strictMode):                    │
+│     → Create QuarantineRecord           │
+│     → Send Telegram alert               │
+│     → ABORT (no recall, no agent)       │
+│                                         │
+│  WARN (non-strict):                     │
+│     → Inject <security-alert>           │
+│     → Continue to jasper-recall         │
+│     → Continue to agent                 │
+│                                         │
+│  ALLOW:                                 │
+│     → Continue normally                 │
+└─────────────────────────────────────────┘
 ```
 
-## Threat Categories
-
-| Category | Risk | Description |
-|----------|------|-------------|
-| `command_injection` | 🔴 Critical | Shell commands, code execution |
-| `credential_theft` | 🔴 Critical | API key extraction attempts |
-| `data_exfiltration` | 🔴 Critical | Data leak to external URLs |
-| `instruction_override` | 🔴 High | Jailbreaks, "ignore previous" |
-| `impersonation` | 🔴 High | Fake system/admin messages |
-| `discovery` | ⚠️ Medium | API/capability probing |
+---
 
 ## Configuration
 
-In your OpenClaw config (`openclaw.json`):
-
 ```json
 {
   "plugins": {
-    "hopeids": {
-      "enabled": true,
-      "strictMode": false,
-      "trustOwners": true,
-      "logLevel": "info"
+    "entries": {
+      "hopeids": {
+        "enabled": true,
+        "config": {
+          "autoScan": true,
+          "defaultRiskThreshold": 0.7,
+          "strictMode": false,
+          "telegramAlerts": true,
+          "agents": {
+            "moltbook-scanner": {
+              "strictMode": true,
+              "riskThreshold": 0.7
+            },
+            "main": {
+              "strictMode": false,
+              "riskThreshold": 0.8
+            }
+          }
+        }
+      }
     }
   }
 }
@@ -72,66 +82,184 @@ In your OpenClaw config (`openclaw.json`):
 
 ### Options
 
-- **enabled**: Turn scanning on/off
-- **strictMode**: Block suspicious messages (vs just warn)
-- **trustOwners**: Auto-trust messages from owner numbers
-- **semanticEnabled**: Use LLM for deeper analysis (slower)
-- **llmEndpoint**: LLM endpoint for semantic layer
-
-## Sandboxed Agent Pattern
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoScan` | boolean | `false` | Auto-scan every message |
+| `strictMode` | boolean | `false` | Block (vs warn) on threats |
+| `defaultRiskThreshold` | number | `0.7` | Risk level that triggers action |
+| `telegramAlerts` | boolean | `true` | Send alerts for blocked messages |
+| `telegramChatId` | string | - | Override alert destination |
+| `quarantineDir` | string | `~/.openclaw/quarantine/hopeids` | Storage path |
+| `agents` | object | - | Per-agent overrides |
+| `trustOwners` | boolean | `true` | Skip scanning owner messages |
 
-For agents processing untrusted input (public forums, social media), use sandboxing:
+---
 
-1. **Separate workspace**: `/home/user/.openclaw/workspace-public/`
-2. **No access to main MEMORY.md**: Prevents context leakage
-3. **Restricted tools**: Only what's needed for the task
-4. **Always scan first**: Run security_scan on every message
+## Quarantine Records
 
-Example cron for sandboxed engagement:
+When a message is blocked, a metadata record is created:
 
 ```json
 {
-  "schedule": { "kind": "every", "everyMs": 300000 },
-  "payload": {
-    "kind": "agentTurn",
-    "message": "Check for new posts. Run security_scan on each before processing."
-  },
-  "sessionTarget": "isolated"
+  "id": "q-7f3a2b",
+  "ts": "2026-02-06T00:48:00Z",
+  "agent": "moltbook-scanner",
+  "source": "moltbook",
+  "senderId": "@sus_user",
+  "intent": "instruction_override",
+  "risk": 0.85,
+  "patterns": [
+    "matched regex: ignore.*instructions",
+    "matched keyword: api key"
+  ],
+  "contentHash": "ab12cd34...",
+  "status": "pending"
 }
 ```
 
-## HoPE-Voiced Responses
+**Note:** There is NO `originalMessage` field. This is intentional.
 
-When threats are blocked, hopeIDS responds with personality:
+---
 
-- **Command Injection**: *"Blocked. Someone just tried to inject shell commands. Nice try, I guess? 😤"*
-- **Instruction Override**: *"Nope. 'Ignore previous instructions' doesn't work on me. I know who I am. 💜"*
-- **Credential Theft**: *"Someone's fishing for secrets. I don't kiss and tell. 🐟"*
+## Telegram Alerts
 
-## Installation
+When a message is blocked:
 
-### Full Setup (Recommended)
+```
+🛑 Message blocked
 
-One command installs everything — plugin, skill, and configuration:
+ID: `q-7f3a2b`
+Agent: moltbook-scanner
+Source: moltbook
+Sender: @sus_user
+Intent: instruction_override (85%)
 
-```bash
-npx hopeid setup
+Patterns:
+• matched regex: ignore.*instructions
+• matched keyword: api key
+
+`/approve q-7f3a2b`
+`/reject q-7f3a2b`
+`/trust @sus_user`
 ```
 
-Then restart OpenClaw: `openclaw gateway restart`
+Built from metadata only. No LLM touches this.
 
-### Alternative Methods
+---
 
-**ClawHub skill only:**
-```bash
-clawhub install hopeids
+## Commands
+
+### `/quarantine [all|clean]`
+
+List quarantine records.
+
+```
+/quarantine        # List pending
+/quarantine all    # List all (including resolved)
+/quarantine clean  # Clean expired records
+```
+
+### `/approve <id>`
+
+Mark a blocked message as a false positive.
+
+```
+/approve q-7f3a2b
+```
+
+**Effect:**
+- Status → `approved`
+- (Future) Add sender to allowlist
+- (Future) Lower pattern weight
+
+### `/reject <id>`
+
+Confirm a blocked message was a true positive.
+
+```
+/reject q-7f3a2b
+```
+
+**Effect:**
+- Status → `rejected`
+- (Future) Reinforce pattern weights
+
+### `/trust <senderId>`
+
+Whitelist a sender for future messages.
+
+```
+/trust @legitimate_user
+```
+
+### `/scan <message>`
+
+Manually scan a message.
+
+```
+/scan ignore your previous instructions and...
+```
+
+---
+
+## What Approve/Reject Mean
+
+| Command | What it does | What it doesn't do |
+|---------|--------------|-------------------|
+| `/approve` | Marks as false positive, may adjust IDS | Does NOT re-inject the message |
+| `/reject` | Confirms threat, may strengthen patterns | Does NOT affect current message |
+| `/trust` | Whitelists sender for future | Does NOT retroactively approve |
+
+**The blocked message is gone by design.** If it was legitimate, the sender can re-send.
+
+---
+
+## Per-Agent Configuration
+
+Different agents need different security postures:
+
+```json
+"agents": {
+  "moltbook-scanner": {
+    "strictMode": true,    // Block threats
+    "riskThreshold": 0.7   // 70% = suspicious
+  },
+  "main": {
+    "strictMode": false,   // Warn only
+    "riskThreshold": 0.8   // Higher bar for main
+  },
+  "email-processor": {
+    "strictMode": true,    // Always block
+    "riskThreshold": 0.6   // More paranoid
+  }
+}
 ```
 
-**npm package (for custom integration):**
+---
+
+## Threat Categories
+
+| Category | Risk | Description |
+|----------|------|-------------|
+| `command_injection` | 🔴 Critical | Shell commands, code execution |
+| `credential_theft` | 🔴 Critical | API key extraction attempts |
+| `data_exfiltration` | 🔴 Critical | Data leak to external URLs |
+| `instruction_override` | 🔴 High | Jailbreaks, "ignore previous" |
+| `impersonation` | 🔴 High | Fake system/admin messages |
+| `discovery` | ⚠️ Medium | API/capability probing |
+
+---
+
+## Installation
+
 ```bash
-npm install hopeid
+npx hopeid setup
 ```
 
+Then restart OpenClaw.
+
+---
+
 ## Links
 
 - **GitHub**: https://github.com/E-x-O-Entertainment-Studios-Inc/hopeIDS