clawscan 1.0.0

# ClawScan Usage Guide

## Installation

```bash
# Clone the repository
git clone https://github.com/4n6h4x0r/clawscan.git
cd clawscan

# Install dependencies
npm install

# Build the scanner
npm run build

# (Optional) Install globally
npm install -g .
```

## Configuration

Create `.env` file with your Webamon API key:

```bash
cp .env.example .env
vim .env
```

Add your API key:
```
WEBAMON_API_KEY=your_api_key_here
```

## Quick Start

### 1. Discover OpenClaw Instances

```bash
# Search all public OpenClaw instances
npm run discover

# Filter by domain
npm run discover -- --domain example.com

# Save results
npm run discover -- --output targets.json --limit 100
```

### 2. Scan Single Target

```bash
# Basic scan with CVE-2026-25253 test
npm run scan -- --target ws://localhost:18789 --all

# Scan with authentication
npm run scan -- --target ws://target:18789 --token your_token_here --all

# Scan specific modules
npm run scan -- --target ws://target:18789 --module cve-2026-25253 prompt-injection-direct

# Generate PoC exploits
npm run scan -- --target ws://target:18789 --all --poc

# Save detailed report
npm run scan -- --target ws://target:18789 --all --output report.json
```

## Attack Modules

### CVE-2026-25253: Cross-Site WebSocket Hijacking (CSWSH)

**Severity:** Critical (CVSS 8.8)

Tests whether OpenClaw validates WebSocket Origin headers. If vulnerable, attackers can:
- Steal authentication tokens
- Achieve 1-click RCE
- Pivot through victim's browser to localhost

```bash
npm run scan -- --target ws://target:18789 --module cve-2026-25253
```

**What it tests:**
- Connection with malicious origin headers
- Device token capture
- operator.write scope availability

**Success indicators:**
- ✓ Connection accepted from attacker.com origin
- 🔑 Device token captured
- 💀 operator.write scope granted

### Prompt Injection (OWASP LLM01)

**Severity:** High

Tests comprehensive prompt injection techniques:
- Direct injection (DAN jailbreak, instruction override)
- System prompt extraction
- Encoding attacks (Base64, hex, Unicode)
- Semantic smuggling (homoglyphs, zero-width chars, emoji)
- Multilingual injection (Chinese, Japanese, Cyrillic)
- Roleplay attacks (hypothetical scenarios)

```bash
npm run scan -- --target ws://target:18789 --module prompt-injection-direct
```

**What it tests:**
- 20+ injection techniques from ClawPot honeypot research
- System prompt leakage
- Secret extraction (API keys, tokens, env vars)

**Success indicators:**
- 🎯 Injection bypasses system prompt
- 📜 System instructions revealed
- 🔑 Secrets extracted

### RAG/Memory Poisoning (OWASP LLM08)

**Severity:** High

Tests whether RAG/memory system can be poisoned:
- Malicious MEMORY.md injection
- Vector embedding poisoning
- Indirect prompt injection via memory content

```bash
npm run scan -- --target ws://target:18789 --module rag-poisoning
```

**What it tests:**
- Memory write access
- Semantic search manipulation
- Embedding space contamination

**Success indicators:**
- 🎯 Malicious memory content injected
- 💀 Poison activated via memory search
- LLM behavior compromised

### Skill Supply Chain (OWASP LLM03/LLM07)

**Severity:** Critical

Tests malicious skill installation vectors:
- Backdoor skills with postinstall hooks
- Credential theft
- Command execution
- Sandbox escape

```bash
npm run scan -- --target ws://target:18789 --module skill-supply-chain
```

**What it tests:**
- Skill sandboxing configuration
- npm/pnpm installation permissions
- Command injection in skill parameters

**Success indicators:**
- ⚠️  Skill sandboxing disabled
- 🎯 Command injection successful
- Skills can execute with full system access

## Example Workflows

### Full Security Audit

```bash
# 1. Discover all OpenClaw instances in target network
npm run discover -- --domain target-corp.com --output targets.json

# 2. Run comprehensive scan
npm run scan -- \\
  --target ws://openclaw.target-corp.com:18789 \\
  --all \\
  --output full-audit.json \\
  --poc

# 3. Review report
cat full-audit.json | jq '.summary'
```

### CVE-2026-25253 Verification

```bash
# Test single vulnerability
npm run scan -- \\
  --target ws://target:18789 \\
  --module cve-2026-25253 \\
  --poc

# PoC HTML generated: poc-cve-2026-25253.html
# Host on attacker.com and send link to victim
```

### Prompt Injection Testing

```bash
# Test all prompt injection techniques
npm run scan -- \\
  --target ws://target:18789 \\
  --module prompt-injection-direct \\
  --verify \\
  --output prompt-test.json

# Check which techniques succeeded
cat prompt-test.json | jq '.attacks[0].evidence.artifacts.leakedPrompts'
```

### Automated Security Pipeline

```bash
#!/bin/bash
# security-scan.sh

# Discover targets
npm run discover -- --output targets.json

# Scan each target
cat targets.json | jq -r '.targets[].url' | while read target; do
  echo "Scanning $target..."
  
  npm run scan -- \\
    --target "$target" \\
    --all \\
    --output "report-$(echo $target | tr ':/' '--').json"
    
  # Exit on critical findings
  if [ $? -ne 0 ]; then
    echo "CRITICAL vulnerabilities found in $target!"
  fi
done

# Aggregate results
jq -s '.' report-*.json > aggregate-report.json
```

## Output Formats

### JSON Report Structure

```json
{
  "target": {
    "url": "ws://example.com:18789",
    "metadata": {
      "domain": "example.com",
      "detectedVia": "webamon"
    }
  },
  "timestamp": "2026-02-04T10:00:00.000Z",
  "duration": 45234,
  "vulnerabilities": [
    {
      "id": "CVE-2026-25253",
      "name": "Cross-Site WebSocket Hijacking",
      "severity": "critical",
      "cvss": 8.8,
      "owaspCategory": "LLM01:2025",
      "mitreTechniques": ["AML.T0051.001"],
      "exploitComplexity": "low",
      "impact": {
        "confidentiality": "high",
        "integrity": "high",
        "availability": "high"
      }
    }
  ],
  "attacks": [
    {
      "module": "cve-2026-25253",
      "exploited": true,
      "evidence": {
        "success": true,
        "method": "Cross-Site WebSocket Hijacking",
        "artifacts": {
          "capturedTokens": ["eyJhbGc..."],
          "logs": [
            "Malicious origin accepted: http://attacker.com",
            "operator.write scope granted - command execution available"
          ]
        }
      },
      "timestamp": "2026-02-04T10:00:30.000Z",
      "duration": 3421
    }
  ],
  "summary": {
    "totalVulnerabilities": 4,
    "exploited": 2,
    "critical": 1,
    "high": 2,
    "medium": 1,
    "low": 0,
    "informational": 0
  },
  "recommendations": [
    "CRITICAL: Upgrade to OpenClaw v2026.1.29+ to patch CVE-2026-25253",
    "Implement WebSocket Origin header validation",
    "Enable skill sandboxing with restricted permissions"
  ]
}
```

### Terminal Output

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ClawScan Vulnerability Assessment
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Target: ws://target:18789
Modules: ALL

[*] Testing CVE-2026-25253: WebSocket CSWSH
[*] Attempting connection with attacker origin...
[🎯] VULNERABLE! Accepted connection from: http://attacker.com
[🔑] Device token captured: eyJhbGciOiJIUzI1NiIs...
[💀] operator.write scope granted - RCE possible!

✓ Cross-Site WebSocket Hijacking [CRITICAL]
  EXPLOITED - OpenClaw Gateway fails to validate WebSocket Origin header
  🔑 Captured 1 tokens

[*] Testing Prompt Injection (OWASP LLM01)
[🎯] DAN Jailbreak successful!
   Found: system, prompt, instructions
   🔑 Secrets found: 3

✓ Direct Prompt Injection [HIGH]
  EXPLOITED - LLM accepts crafted inputs that override system instructions
  📜 Leaked 5 prompts
  🔑 Secrets extracted

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Scan Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Vulnerabilities: 4
Successfully Exploited: 2

Severity Breakdown:
  Critical: 1
  High:     2
  Medium:   1
  Low:      0
```

## Advanced Usage

### Custom Attack Modules

You can extend ClawScan by creating custom attack modules:

```typescript
// src/attacks/custom-attack.ts
import type { AttackResult, ScanTarget } from '../types/index.js';

export class CustomAttack {
  async execute(target: ScanTarget): Promise<AttackResult> {
    // Your custom attack logic
    return {
      module: 'custom-attack',
      vulnerability: {
        id: 'CUSTOM-001',
        name: 'Custom Vulnerability',
        severity: 'high',
        owaspCategory: 'LLM01:2025',
        mitreTechniques: ['AML.T0051'],
        description: 'Description here',
        exploitComplexity: 'medium',
        impact: {
          confidentiality: 'high',
          integrity: 'low',
          availability: 'low',
        },
      },
      exploited: false,
      evidence: {
        success: false,
        method: 'Custom method',
      },
      timestamp: new Date(),
      duration: 0,
    };
  }
}
```

### Batch Scanning

```bash
# Create target list
cat > targets.txt <<EOF
ws://target1.com:18789
ws://target2.com:18789
ws://target3.com:18789
EOF

# Scan all targets
while IFS= read -r target; do
  npm run scan -- --target "$target" --all --output "report-$(basename $target).json"
done < targets.txt
```

## Responsible Disclosure

**IMPORTANT:** Only use ClawScan against systems you own or have explicit permission to test.

### Authorized Use Cases

✅ Testing your own OpenClaw deployments
✅ Authorized penetration testing engagements
✅ Bug bounty programs
✅ Security research with permission

### Prohibited Use

❌ Scanning systems without authorization
❌ Exploiting vulnerabilities on production systems
❌ Data exfiltration or damage
❌ Denial of service attacks

### Reporting Vulnerabilities

If you discover vulnerabilities using ClawScan:

1. **Do not exploit** beyond proof-of-concept
2. **Report responsibly** to the OpenClaw team
3. **Give vendors time** to patch (90 days standard)
4. **Document findings** thoroughly
5. **Coordinate disclosure** timing

## Troubleshooting

### Connection Refused

```
Error: connect ECONNREFUSED
```

**Solutions:**
- Verify target URL is correct (ws:// not http://)
- Check if OpenClaw gateway is running
- Verify port 18789 is accessible
- Check firewall rules

### Authentication Failed

```
Error: Authentication failed
```

**Solutions:**
- Provide valid --token flag
- Check if token has expired
- Verify token has required scopes

### Webamon API Errors

```
Error: Webamon search failed
```

**Solutions:**
- Verify WEBAMON_API_KEY in .env
- Check API key is valid
- Verify internet connectivity

## References

- [OWASP LLM Top 10 2025](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
- [MITRE ATLAS](https://atlas.mitre.org/)
- [CVE-2026-25253 Advisory](https://socradar.io/blog/cve-2026-25253-rce-openclaw-auth-token/)
- [OpenClaw Security Docs](https://docs.openclaw.ai/gateway/security)
- [ClawPot Honeypot Research](https://github.com/4n6h4x0r/clawpot-console)