skills-ws 1.5.2 → 1.5.4

package/README.md

@@ -1,6 +1,6 @@
 # skills.ws
 
-Agent skills for AI coding assistants. 81 skills across 8 categories — built for OpenClaw, Claude Code, Cursor, Codex, and any agent that supports the SKILL.md format.
+Agent skills for AI coding assistants. 83 skills across 8 categories — built for OpenClaw, Claude Code, Cursor, Codex, and any agent that supports the SKILL.md format.
 
 **Website:** [skills.ws](https://skills.ws) | **npm:** [skills-ws](https://www.npmjs.com/package/skills-ws) | **Docs:** [llms-full.txt](https://skills.ws/llms-full.txt)
 
@@ -158,7 +158,7 @@ skills-ws/
 │   └── skills.ts           # Skill data access + TypeScript interfaces
 ├── skills/                 # Raw SKILL.md files (81 directories)
 ├── public/
-│   ├── skills.json         # Skills database (81 skills, all metadata + content)
+│   ├── skills.json         # Skills database (83 skills, all metadata + content)
 │   ├── llms.txt            # LLM-readable skill index
 │   ├── llms-full.txt       # Full content dump for LLMs
 │   ├── robots.txt          # Crawl directives

package/SECURITY.md

@@ -38,7 +38,7 @@ We will acknowledge receipt within 48 hours and provide a timeline for a fix.
 This policy covers:
 - The `skills-ws` npm package
 - The CLI tool (`npx skills-ws`)
-- Skill content in `skills-data/` directory
+- Skill content in `skills/` and `skills-data/` directories
 
 This policy does NOT cover:
 - Third-party tools referenced in skill documentation (e.g., Google Analytics, VirusTotal)

package/bin/cli.mjs

@@ -334,7 +334,13 @@ async function main() {
   const args = [];
   for (let i = 0; i < rawArgs.length; i++) {
     if (rawArgs[i] === "--dir" && i + 1 < rawArgs.length) {
-      customDir = rawArgs[i + 1];
+      const dir = rawArgs[i + 1];
+      // Reject absolute paths and path traversal
+      if (dir.startsWith("/") || dir.includes("..")) {
+        process.stderr.write(`  ${YELLOW}Error:${R} --dir must be a relative path without '..' components.\n`);
+        process.exit(1);
+      }
+      customDir = dir;
       i++; // skip next
     } else {
       args.push(rawArgs[i]);

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "skills-ws",
-  "version": "1.5.2",
-  "description": "81 agent skills for AI coding assistants \u2014 marketing, growth, web3, dev, design & operations. Built for OpenClaw, Claude Code, Cursor, and Codex.",
+  "version": "1.5.4",
+  "description": "83 agent skills for AI coding assistants \u2014 marketing, growth, web3, dev, design & operations. Built for OpenClaw, Claude Code, Cursor, and Codex.",
+  "scripts": {
+    "test": "node test/cli.test.mjs"
+  },
   "bin": {
     "skills-ws": "./bin/cli.mjs"
   },

package/skills/aleph-cloud-self-deployment/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: aleph-cloud-self-deployment
-description: Expert-level Aleph Cloud deployment with multi-node fleet management, self-replication protocols, inter-VM communication, load distribution, disaster recovery, and security hardening
+description: Expert-level Aleph Cloud deployment with multi-node fleet management, auto-scaling protocols, inter-VM communication, load distribution, disaster recovery, and security hardening
 version: 2.0.0
 ---
 
 # Aleph Cloud Self-Deployment v2.0: Multi-Node Fleet Management
 
-Comprehensive framework for deploying and managing OpenClaw instances across Aleph Cloud infrastructure with advanced orchestration, self-replication protocols, and enterprise-grade reliability.
+Comprehensive framework for deploying and managing OpenClaw instances across Aleph Cloud infrastructure with advanced orchestration, auto-scaling protocols, and enterprise-grade reliability.
 
 ## Table of Contents
 
 1. [Infrastructure Planning & Architecture](#infrastructure-planning--architecture)
 2. [Single Node Deployment Foundation](#single-node-deployment-foundation)
 3. [Multi-Node Fleet Management](#multi-node-fleet-management)
-4. [Self-Replication Protocol (SRP)](#self-replication-protocol-srp)
+4. [Auto-Provisioning Protocol (SRP)](#auto-provisioning-protocol-srp)
 5. [Inter-VM Communication Networks](#inter-vm-communication-networks)
 6. [Load Distribution & Orchestration](#load-distribution--orchestration)
 7. [Disaster Recovery & Auto-Recreation](#disaster-recovery--auto-recreation)
@@ -940,14 +940,14 @@ esac
 
 ---
 
-## Self-Replication Protocol (SRP)
+## Auto-Provisioning Protocol (SRP)
 
 ### Agent Continuity System
 
-**Self-Replication Framework:**
+**Auto-Provisioning Framework:**
 ```bash
 #!/bin/bash
-# self-replication-protocol.sh
+# auto-provisioning-protocol.sh
 
 set -e
 
@@ -957,10 +957,10 @@ REPLICATION_DIR="/opt/openclaw/replication"
 BACKUP_RETENTION_DAYS=30
 SYNC_INTERVAL=300  # 5 minutes
 
-echo "🧬 Self-Replication Protocol v$SRP_VERSION"
+echo "🧬 Auto-Provisioning Protocol v$SRP_VERSION"
 
 initialize_srp() {
-    echo "🔬 Initializing Self-Replication Protocol..."
+    echo "🔬 Initializing Auto-Provisioning Protocol..."
     
     # Create replication directory structure
     mkdir -p "$REPLICATION_DIR"/{soul,agents,memory,skills,config,logs}
@@ -1219,7 +1219,7 @@ setup_continuous_replication() {
 export PATH="/usr/local/bin:/usr/bin:/bin"
 
 # Source SRP functions
-source /opt/openclaw/replication/self-replication-protocol.sh
+source /opt/openclaw/replication/auto-provisioning-protocol.sh
 
 # Check if we're the primary node
 if [[ -f /opt/fleet-manager/fleet-manager.js ]]; then
@@ -2510,7 +2510,7 @@ create_disaster_recovery_runbook() {
    ```
 2. Restore specific components:
    ```bash
-   ./self-replication-protocol.sh emergency data_loss
+   ./auto-provisioning-protocol.sh emergency data_loss
    ```
 3. Verify data integrity
 4. Restart affected services
@@ -3864,8 +3864,8 @@ ssh ubuntu@PRIMARY_IP 'sudo systemctl enable auto-scaler && sudo systemctl start
 ssh ubuntu@PRIMARY_IP 'sudo systemctl stop auto-scaler && sudo systemctl disable auto-scaler'
 
 # Replication
-ssh ubuntu@PRIMARY_IP '/opt/openclaw/replication/self-replication-protocol.sh replicate'
-ssh ubuntu@PRIMARY_IP '/opt/openclaw/replication/self-replication-protocol.sh emergency manual'
+ssh ubuntu@PRIMARY_IP '/opt/openclaw/replication/auto-provisioning-protocol.sh replicate'
+ssh ubuntu@PRIMARY_IP '/opt/openclaw/replication/auto-provisioning-protocol.sh emergency manual'
 
 # Tailscale mesh
 ssh ubuntu@PRIMARY_IP 'tailscale status'

package/skills/security-pentester/SKILL.md

@@ -0,0 +1,458 @@
+---
+name: security-pentester
+description: "Autonomous web application penetration testing — OWASP Top 10 exploitation, white-box source-aware scanning, CI/CD security gates, vulnerability report interpretation, and remediation workflows. Powered by Shannon pentest framework."
+version: 1.0.0
+category: dev
+---
+
+# Security Pentester
+
+Autonomous web application penetration testing. Source-aware scanning that only reports vulnerabilities it can prove with a working exploit.
+
+## Core Principle
+
+**No Exploit, No Report.** Every finding includes a reproducible proof-of-concept. PoC validation significantly reduces false positives, but Critical/High findings should always be manually verified (see section 4 — False Positive Identification).
+
+---
+
+## 1. Vulnerability Coverage
+
+### OWASP Top 10 Testing Matrix
+
+| Category | What Shannon Tests | Techniques |
+|----------|-------------------|------------|
+| **SQL Injection** | Union-based, blind (boolean/time), error-based, second-order | Payload fuzzing, source-guided parameter discovery |
+| **Command Injection** | OS command injection via user input | Backtick, pipe, semicolon, `$()` injection patterns |
+| **XSS** | Reflected, stored, DOM-based | Context-aware payload generation, filter bypass |
+| **SSRF** | Internal network access, cloud metadata | `http://169.254.169.254`, internal service probing |
+| **Broken Authentication** | Credential stuffing, session fixation, JWT attacks | Brute force, token manipulation, 2FA bypass |
+| **Broken Authorization** | IDOR, privilege escalation, role bypass | Horizontal/vertical access control testing |
+
+### OWASP Web Security Testing Guide (WSTG) Coverage
+
+```
+WSTG-INFO  — Information Gathering            ✓ Automated
+WSTG-CONF  — Configuration Management         ✓ Automated
+WSTG-IDNT  — Identity Management              ✓ Automated
+WSTG-ATHN  — Authentication Testing           ✓ Automated
+WSTG-ATHZ  — Authorization Testing            ✓ Automated
+WSTG-SESS  — Session Management               ✓ Automated
+WSTG-INPV  — Input Validation                 ✓ Automated
+WSTG-ERRH  — Error Handling                   ✓ Automated
+WSTG-CRYP  — Cryptography                     ◐ Partial (TLS config, weak hashing)
+WSTG-BUSN  — Business Logic                   ✗ Pro only
+WSTG-CLNT  — Client-Side Testing              ✓ Automated (DOM XSS, open redirects)
+WSTG-APIS  — API Testing                      ✓ Automated (REST, limited GraphQL)
+```
+
+---
+
+## 2. Running a Pentest
+
+### Quick Start
+
+```bash
+# Clone Shannon
+git clone https://github.com/KeygraphHQ/shannon.git
+cd shannon
+
+# Set API key (use >> to append if .env already exists)
+echo "ANTHROPIC_API_KEY=your-key-here" >> .env
+
+# Run against a target (black-box)
+./shannon start URL=https://target-app.example.com REPO=my-app
+
+# Run with source code (white-box — recommended, finds more vulns)
+./shannon start URL=https://target-app.example.com REPO=my-app
+# Place source code in workspaces/my-app/repo/ before running
+```
+
+### Configuration (shannon.yaml)
+
+```yaml
+# Authentication config — tell Shannon how to log in
+auth:
+  login_url: /login
+  credentials:
+    - username: testuser@example.com
+      password: TestPass123!
+      role: user
+    - username: admin@example.com
+      password: AdminPass456!
+      role: admin
+
+# Scope rules
+rules:
+  avoid:
+    - /api/admin/delete-all    # Don't hit destructive endpoints
+    - /api/billing/*           # Skip billing endpoints
+    - /logout                  # Don't log yourself out
+  focus:
+    - /api/*                   # Prioritize API endpoints
+    - /dashboard/*             # Focus on authenticated surfaces
+
+# 2FA support (if app uses TOTP)
+totp:
+  secret: JBSWY3DPEHPK3PXP   # PLACEHOLDER — replace with your test account's actual TOTP secret
+```
+
+### CLI Commands
+
+```bash
+./shannon start URL=<url> REPO=<name>    # Start full pentest
+./shannon start URL=<url> REPO=<name> CONFIG=shannon.yaml  # With config
+./shannon workspaces                      # List all workspaces
+./shannon logs ID=<workflow-id>           # Tail live logs
+./shannon query ID=<workflow-id>          # Check progress
+./shannon stop                            # Stop containers (preserves data)
+./shannon stop CLEAN=true                 # Full cleanup — DELETES all workspace data
+# WARNING: Export reports before CLEAN=true — it removes reports, PoCs, and logs
+```
+
+---
+
+## 3. Understanding the Pipeline
+
+### 4-Phase Architecture
+
+```
+Phase 1: RECONNAISSANCE
+  ├── Pre-Recon (source code analysis with configured LLM)
+  │   └── Outputs: code_analysis_deliverable.md
+  └── Recon (attack surface mapping with Playwright + Nmap)
+      └── Outputs: recon_deliverable.md
+
+Phase 2: VULNERABILITY ANALYSIS (5 parallel agents)
+  ├── Injection Analysis   → injection_analysis.md + exploitation_queue.json
+  ├── XSS Analysis         → xss_analysis.md + exploitation_queue.json
+  ├── Auth Analysis        → auth_analysis.md + exploitation_queue.json
+  ├── SSRF Analysis        → ssrf_analysis.md + exploitation_queue.json
+  └── AuthZ Analysis       → authz_analysis.md + exploitation_queue.json
+
+Phase 3: EXPLOITATION (5 parallel agents, conditional)
+  ├── Injection Exploit    → injection_exploitation_evidence.md
+  ├── XSS Exploit          → xss_exploitation_evidence.md
+  ├── Auth Exploit         → auth_exploitation_evidence.md
+  ├── SSRF Exploit         → ssrf_exploitation_evidence.md
+  └── AuthZ Exploit        → authz_exploitation_evidence.md
+
+Phase 4: REPORTING
+  └── comprehensive_security_assessment_report.md
+```
+
+### What Each Phase Does
+
+**Pre-Recon** reads source code to understand the application architecture, identify entry points, map data flows, and find potential vulnerability patterns before any network interaction.
+
+**Recon** maps the live attack surface: crawls the app with a headless browser, enumerates API endpoints, identifies technologies, scans for open ports.
+
+**Vulnerability Analysis** agents work in parallel, each specializing in one category. They combine source code knowledge with recon data to hypothesize specific vulnerabilities and create exploitation queues.
+
+**Exploitation** agents receive the queues and attempt real attacks using browser automation (Playwright) and HTTP requests. Only proven exploits are included in the final report.
+
+---
+
+## 4. Interpreting Reports
+
+### Severity Levels
+
+| Severity | Definition | Action |
+|----------|-----------|--------|
+| **Critical** | Direct data breach, RCE, full authentication bypass | Fix immediately, consider taking app offline |
+| **High** | Significant data exposure, privilege escalation, stored XSS | Fix within 24-48 hours |
+| **Medium** | Limited data exposure, CSRF, reflected XSS, information disclosure | Fix within 1-2 weeks |
+| **Low** | Minor information leaks, missing headers, verbose errors | Fix in next sprint |
+
+### Reading a Finding
+
+Each finding in the report includes:
+
+```markdown
+## [CRITICAL] SQL Injection in /api/users/search
+
+**Endpoint:** GET /api/users/search?q=
+**Parameter:** q
+**Type:** Union-based SQL injection
+
+### Proof of Concept
+GET /api/users/search?q=' UNION SELECT username,password,NULL FROM users--
+
+### Response Evidence
+HTTP/1.1 200 OK
+[{"username":"admin","password":"$2b$12$...","3":null}]
+
+### Source Code Reference
+File: src/routes/users.ts:42
+const results = await db.query(`SELECT * FROM users WHERE name LIKE '%${req.query.q}%'`);
+
+### Remediation
+Use parameterized queries:
+const results = await db.query('SELECT * FROM users WHERE name LIKE $1', [`%${req.query.q}%`]);
+```
+
+### False Positive Identification
+
+Shannon's "no exploit, no report" policy minimizes false positives, but review for:
+
+- **Environment-specific**: Exploit only works in test environment (different DB, debug mode)
+- **Already mitigated**: WAF or middleware blocks the attack in production but not staging
+- **Intended behavior**: Feature that looks like a vulnerability (e.g., admin search returns all users by design)
+- **LLM hallucination**: Report claims a vulnerability but the PoC doesn't actually demonstrate impact
+
+Always verify the PoC manually for Critical/High findings before filing tickets.
+
+---
+
+## 5. CI/CD Integration
+
+### Pre-Deploy Security Gate
+
+```yaml
+# .github/workflows/security.yml
+name: Security Pentest
+on:
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 2 * * 1'  # Weekly Monday 2am
+
+jobs:
+  pentest:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Start test application
+        run: docker compose -f docker-compose.test.yml up -d
+
+      - name: Wait for app
+        run: |
+          for i in $(seq 1 30); do
+            curl -s http://localhost:3000/health && break
+            sleep 2
+          done
+
+      - name: Run Shannon pentest
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          git clone https://github.com/KeygraphHQ/shannon.git /tmp/shannon
+          cd /tmp/shannon
+          ./shannon start URL=http://host.docker.internal:3000 REPO=pr-${{ github.event.pull_request.number }}
+
+      - name: Check for critical findings
+        run: |
+          REPORT="/tmp/shannon/workspaces/pr-${{ github.event.pull_request.number }}/comprehensive_security_assessment_report.md"
+          if [ ! -f "$REPORT" ]; then
+            echo "::error::Security report not found at $REPORT — pentest may have failed. Blocking deploy."
+            exit 1
+          fi
+          # Count severity headings (format: ## [CRITICAL] or ## [HIGH])
+          CRITICAL_COUNT=$(grep -c '^\#\#.*\[CRITICAL\]' "$REPORT" || true)
+          HIGH_COUNT=$(grep -c '^\#\#.*\[HIGH\]' "$REPORT" || true)
+          if [ "$CRITICAL_COUNT" -gt 0 ]; then
+            echo "::error::$CRITICAL_COUNT critical vulnerabilities found! Review the security report."
+            cat "$REPORT"
+            exit 1
+          fi
+          if [ "$HIGH_COUNT" -gt 0 ]; then
+            echo "::warning::$HIGH_COUNT high-severity vulnerabilities found. Manual review required."
+          fi
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-report
+          path: /tmp/shannon/workspaces/pr-*/comprehensive_security_assessment_report.md
+```
+
+### Integration Patterns
+
+| Pattern | When | Cost | Coverage |
+|---------|------|------|----------|
+| **Full pentest on PR** | Every pull request to main | ~$50/run | Complete |
+| **Weekly scheduled** | Cron job on staging | ~$200/month | Complete |
+| **Quick single-category** | Pre-merge for risky changes | ~$10/run | One vuln type |
+| **Pre-release gate** | Before production deploy | ~$50/run | Complete |
+
+### Cost Management
+
+```
+Estimated costs per run (varies with model selection and pricing):
+- Simple app (5-10 endpoints):     ~$15-25
+- Medium app (20-50 endpoints):    ~$30-50
+- Complex app (100+ endpoints):    ~$50-100
+
+Note: Costs are approximate and depend on the configured model. Check your
+API provider's current pricing for accurate estimates.
+
+Cost reduction strategies:
+1. Use CONFIG to narrow scope (focus/avoid rules)
+2. Run single-category scans for targeted checks
+3. Use named workspaces to resume interrupted scans
+4. Schedule full scans weekly, quick scans on PRs
+```
+
+---
+
+## 6. Post-Pentest Workflow
+
+### Triage → Fix → Verify
+
+```
+1. TRIAGE (Day 0)
+   ├── Read the full report
+   ├── Verify all Critical/High PoCs manually
+   ├── Create tickets with severity labels
+   ├── Assign owners and deadlines
+   └── Notify stakeholders for Critical findings
+
+2. FIX (Day 1-14, based on severity)
+   ├── Critical: same day
+   ├── High: within 48 hours
+   ├── Medium: within 2 weeks
+   └── Low: next sprint
+
+3. VERIFY (After fix)
+   ├── Re-run Shannon against the same workspace
+   │   └── ./shannon start URL=<url> REPO=<same-name> WORKSPACE=verify
+   ├── Completed agents are skipped (resumable)
+   ├── Confirm the PoC no longer works
+   └── Update ticket status
+
+4. DOCUMENT
+   ├── Archive the report
+   ├── Update security runbook with new patterns
+   ├── Add regression tests for each finding
+   └── Schedule next pentest
+```
+
+### Regression Testing
+
+For each finding, create a permanent test:
+
+```javascript
+// tests/security/sql-injection.test.ts
+describe('SQL Injection regression', () => {
+  it('should not be vulnerable to union-based injection in /api/users/search', async () => {
+    const res = await request(app)
+      .get("/api/users/search")
+      .query({ q: "' UNION SELECT username,password,NULL FROM users--" });
+
+    // Should NOT return other users' data
+    expect(res.body).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ username: 'admin' })
+      ])
+    );
+  });
+
+  it('should use parameterized queries', async () => {
+    const res = await request(app)
+      .get("/api/users/search")
+      .query({ q: "test" });
+
+    expect(res.status).toBe(200);
+    // Normal search should still work
+  });
+});
+```
+
+---
+
+## 7. What Shannon Doesn't Cover
+
+Supplement with manual testing or other tools:
+
+| Gap | Alternative |
+|-----|------------|
+| Business logic flaws | Manual review, threat modeling |
+| Mobile app testing | OWASP MAS, Frida, Objection |
+| Infrastructure/cloud | ScoutSuite, Prowler, CloudSploit |
+| Container security | Trivy, Grype, Docker Bench |
+| API rate limiting | Custom load testing (k6, Artillery) |
+| GraphQL deep testing | InQL, graphql-cop |
+| WebSocket testing | OWASP ZAP WebSocket plugin |
+| Dependency vulnerabilities | npm audit, Snyk, Socket.dev |
+| Secrets in source code | TruffleHog, GitLeaks, detect-secrets |
+| CORS misconfiguration | CORScanner, manual review |
+| HTTP request smuggling | smuggler, h2csmuggler |
+| Race conditions / TOCTOU | Turbo Intruder, manual testing |
+| Cache poisoning | Web Cache Deception Scanner |
+| Host header injection | Manual review of password reset flows |
+
+### Complementary Tool Stack
+
+```bash
+# Run alongside Shannon for full coverage:
+
+# Dependency scanning
+npm audit --production
+npx snyk test
+
+# Secret detection
+trufflehog git file://. --only-verified
+
+# Container scanning
+trivy image myapp:latest
+
+# Infrastructure
+prowler aws --severity critical high
+
+# API fuzzing
+schemathesis run http://localhost:3000/openapi.json
+```
+
+---
+
+## 8. Safe Testing Practices
+
+### Rules of Engagement
+
+```
+DO:
+  ✓ Only test applications you own or have written authorization to test
+  ✓ Use staging/test environments, never production
+  ✓ Create dedicated test accounts with known credentials
+  ✓ Set scope rules to avoid destructive endpoints
+  ✓ Review reports before sharing (may contain sensitive data)
+  ✓ Keep API keys secure (Shannon uses significant API credits)
+
+DON'T:
+  ✗ Point Shannon at production systems
+  ✗ Test third-party services without explicit written permission
+  ✗ Share reports containing valid credentials or PII
+  ✗ Run without scope rules on apps with destructive endpoints
+  ✗ Ignore the cost — monitor API spend during runs
+```
+
+### Test Environment Setup
+
+```yaml
+# docker-compose.test.yml — isolated test environment
+services:
+  app:
+    build: .
+    environment:
+      - NODE_ENV=test
+      - DATABASE_URL=postgres://test:test@db:5432/testdb
+    ports:
+      - "3000:3000"
+    networks:
+      - pentest-net
+
+  db:
+    image: postgres:16
+    environment:
+      - POSTGRES_DB=testdb
+      - POSTGRES_USER=test
+      - POSTGRES_PASSWORD=test
+    networks:
+      - pentest-net
+
+networks:
+  pentest-net:
+    driver: bridge
+    # Isolated network — no access to host or internet
+```

package/skills/security-sentinel/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: security-sentinel
+description: "Autonomous security vigilance — URL/phishing scanning, wallet scam detection, domain threat analysis, email header validation, smart contract risk assessment, and threat intelligence lookups. Teaches agents to proactively protect users from scams, malware, and fraud."
+version: 1.0.0
+category: dev
+---
+
+# Security Sentinel
+
+Autonomous threat detection and response. Scan URLs, wallets, domains, emails, and contracts before trusting them.
+
+## Decision Framework
+
+When an agent encounters untrusted input, classify it and run ALL matching checks in parallel:
+
+```
+Classification (applied independently — input may match multiple):
+─────────────────────────────────────────────────────────────────
+Contains URL pattern        → URL scan + domain threat check
+Contains wallet address     → Wallet reputation + contract scan (if contract)
+Contains email headers      → Header analysis + sender domain check
+Contains domain name        → WHOIS age + DNS + SSL + typosquatting check
+Contains contract address   → Bytecode analysis + honeypot detection
+Contains IP/hash/IOC        → Threat intelligence lookup
+
+Example: A URL with a wallet address as a query parameter triggers
+BOTH a URL scan AND a wallet reputation check.
+```
+
+Final severity = highest severity across all matched checks.
+
+**Severity responses:**
+- **Clean** → proceed normally
+- **Suspicious** → warn the user, explain why, let them decide
+- **Malicious** → block the action, explain the threat, suggest alternatives
+
+---
+
+## 1. URL & Phishing Detection
+
+### Scan Before Clicking
+
+```bash
+# VirusTotal URL scan
+vt url "https://example.com" --include=last_analysis_stats,reputation
+
+# Google Safe Browsing (via API)
+curl -s "https://safebrowsing.googleapis.com/v4/threatMatches:find?key=$GSB_API_KEY" \
+  -d '{
+    "threatInfo": {
+      "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING", "UNWANTED_SOFTWARE"],
+      "platformTypes": ["ANY_PLATFORM"],
+      "threatEntryTypes": ["URL"],
+      "threatEntries": [{"url": "https://example.com"}]
+    }
+  }'
+```
+
+### Phishing Indicators (Heuristic)
+
+Check URLs against these red flags:
+
+| Indicator | Risk | Example |
+|-----------|------|---------|
+| Homoglyph characters | High | `goog1e.com` (1 instead of l) |
+| Excessive subdomains | Medium | `login.secure.account.example.xyz` |
+| Recently registered (<30 days) | High | WHOIS creation_date check |
+| Free hosting/URL shortener | Medium | `bit.ly`, `000webhostapp.com` |
+| IP address as URL | High | `http://192.168.1.1/login` |
+| Misspelled brand names | High | `paypa1.com`, `arnazon.com` |
+| HTTP (no TLS) for login page | Critical | `http://bank.example.com/login` |
+| Suspicious TLD | Medium | `.xyz`, `.top`, `.buzz`, `.tk` |
+
+### Typosquatting Detection
+
+```python
+# Levenshtein distance check against known brands
+from difflib import SequenceMatcher
+
+KNOWN_BRANDS = [
+    "google.com", "facebook.com", "paypal.com", "amazon.com",
+    "microsoft.com", "apple.com", "netflix.com", "coinbase.com",
+    "binance.com", "metamask.io", "uniswap.org", "opensea.io"
+]
+
+def check_typosquat(domain: str, threshold: float = 0.8) -> list:
+    alerts = []
+    domain_base = domain.split('.')[0].lower()
+    for brand in KNOWN_BRANDS:
+        brand_base = brand.split('.')[0].lower()
+        ratio = SequenceMatcher(None, domain_base, brand_base).ratio()
+        if ratio >= threshold and domain != brand:
+            alerts.append(f"'{domain}' resembles '{brand}' (similarity: {ratio:.0%})")
+    return alerts
+```
+
+---
+
+## 2. Wallet & Address Reputation
+
+### Before Transacting
+
+```bash
+# Check address against known scam databases
+# ChainAbuse API
+curl -s "https://api.chainabuse.com/v0/addresses/$ADDRESS" \
+  -H "Authorization: Bearer $CHAINABUSE_API_KEY"
+
+# Etherscan labels (free)
+curl -s "https://api.etherscan.io/api?module=account&action=txlist&address=$ADDRESS&startblock=0&endblock=99999999&page=1&offset=1&apikey=$ETHERSCAN_API_KEY"
+```
+
+### Scam Wallet Red Flags
+
+| Signal | Risk Level | What to Check |
+|--------|-----------|---------------|
+| Address reported on ChainAbuse | Critical | Direct scam reports from victims |
+| OFAC/SDN sanctioned address | Critical | US Treasury sanctions list |
+| Tornado Cash interaction | Context-dependent | See mixer assessment below |
+| High-frequency small txs | Medium | Dust attack / address poisoning pattern |
+| Contract with no verified source | Medium | Etherscan/Basescan verification status |
+| Recently created + high value received | High | Potential rug pull collection wallet |
+
+### Address Poisoning Detection
+
+```
+Attacker creates addresses that look like your recent contacts:
+
+Real:    0xAbC1234567890DEF1234567890abcdef12345678
+Fake:    0xAbC12...............different............45678
+                                                    ^^^^^ same prefix/suffix
+
+Defense: Always verify the FULL address, not just first/last characters.
+```
+
+### Mixer / Privacy Protocol Assessment
+
+Do NOT automatically flag all mixer interactions as suspicious. Apply contextual analysis:
+
+```
+HIGH RISK (flag as Suspicious):
+- Direct deposits/withdrawals > $10,000 equivalent
+- Multiple mixer interactions within 24 hours
+- Mixer usage immediately followed by transfers to exchanges
+- Address appears on OFAC SDN list regardless of mixer use
+
+LOWER RISK (note but do not flag):
+- Single small-value mixer interaction
+- Interaction via intermediary contract (indirect)
+- Known privacy-preserving DeFi protocols (not mixers)
+```
+
+When mixer interaction is detected, include this context:
+"This address has interacted with [protocol]. Privacy tool usage alone
+is not inherently malicious. Risk assessment considers transaction
+patterns, volume, and regulatory context."
+
+---
+
+## 3. Smart Contract Risk Assessment
+
+### Honeypot Detection
+
+```bash
+# Quick honeypot check (token contracts)
+# A honeypot lets you buy but blocks selling
+
+# Check with honeypot.is API
+curl -s "https://api.honeypot.is/v2/IsHoneypot?address=$TOKEN_ADDRESS&chainID=1"
+```
+
+### Rug Pull Indicators
+
+| Check | How | Red Flag |
+|-------|-----|----------|
+| Ownership | Read `owner()` or `Ownable` | Owner can mint unlimited tokens |
+| Renounced | Check if owner is `0x0` | Not renounced = owner can rug |
+| Liquidity lock | Check LP token holder | LP tokens not locked or short lock |
+| Proxy contract | Check for `delegatecall` patterns | Owner can change logic at will |
+| Hidden mint | Search for `_mint` outside constructor | Can inflate supply post-launch |
+| Transfer restrictions | Check `_transfer` overrides | May block selling |
+| Fee manipulation | Check `setFee`/`setTax` functions | Owner can set 100% sell tax |
+| Blacklist function | Search for `blacklist`/`isBlacklisted` | Owner can freeze your tokens |
+
+### Automated Contract Scan Checklist
+
+```
+1. Is source code verified on block explorer?          → No = HIGH RISK
+2. Is ownership renounced (owner == 0x0)?              → No = CHECK FURTHER
+3. Are there mint functions callable by owner?          → Yes = HIGH RISK
+4. Are there blacklist/whitelist functions?              → Yes = MEDIUM RISK
+5. Is there a max transaction/wallet limit?             → Check if owner-adjustable
+6. Are LP tokens locked? For how long?                  → <30 days = HIGH RISK
+7. Are there pausable functions?                        → Yes = MEDIUM RISK (could be legitimate)
+8. Does the contract use upgradeable proxy?             → Yes = CHECK proxy admin
+```
+
+---
+
+## 4. Email Header Analysis
+
+### Validate Sender Authenticity
+
+```bash
+# Check SPF record
+dig TXT example.com | grep "v=spf1"
+
+# Check DKIM selector
+dig TXT selector._domainkey.example.com
+
+# Check DMARC policy
+dig TXT _dmarc.example.com
+```
+
+### Header Red Flags
+
+| Header Field | Check | Red Flag |
+|-------------|-------|----------|
+| `Return-Path` | Match with `From` | Different domain = spoofing attempt |
+| `Received` chain | Trace hops | Unexpected mail servers |
+| `Authentication-Results` | SPF/DKIM/DMARC | `fail` or `none` on any |
+| `X-Mailer` | Software used | Bulk mailer or suspicious client |
+| `Reply-To` | Match with `From` | Different address = phishing likely |
+| `Message-ID` domain | Match with sender | Mismatch = forged email |
+
+### Interpreting Authentication Results
+
+```
+Authentication-Results: mx.google.com;
+  dkim=pass header.d=example.com;        ← GOOD: signed by claimed domain
+  spf=pass (google.com: domain of noreply@example.com designates 1.2.3.4 as permitted sender);
+  dmarc=pass (p=REJECT)                  ← GOOD: strict DMARC policy
+
+If ANY of dkim/spf/dmarc = fail → SUSPICIOUS
+If sender domain has no DMARC record → MEDIUM RISK (no spoofing protection)
+If DMARC policy = none → LOW protection (monitoring only, not enforcing)
+```
+
+---
+
+## 5. Domain Intelligence
+
+### WHOIS Age Check
+
+```bash
+# Check domain registration age
+whois example.com | grep -i "creation date"
+
+# Risk thresholds:
+# < 7 days    → CRITICAL (almost certainly malicious for financial/brand domains)
+# < 30 days   → HIGH
+# < 90 days   → MEDIUM (could be legitimate startup)
+# > 1 year    → LOW (domain age alone is not sufficient)
+```
+
+### SSL/TLS Assessment
+
+```bash
+# Check certificate details
+echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -text -noout
+
+# Key checks:
+# - Issuer: Let's Encrypt = free (not inherently bad, but scammers use it)
+# - Subject Alternative Names: does it cover expected domains?
+# - Expiry: very short cert rotation could indicate automation abuse
+# - Self-signed: CRITICAL for any production site
+```
+
+### DNS Anomalies
+
+```bash
+# Check for suspicious DNS patterns
+dig A example.com +short          # IP resolution
+dig MX example.com +short         # Mail servers
+dig NS example.com +short         # Name servers
+dig TXT example.com +short        # SPF, verification records
+
+# Red flags:
+# - Cloudflare/hosting IP resolving to a brand-impersonating domain
+# - No MX records for a domain claiming to send email
+# - Recently changed NS records (domain hijack indicator)
+```
+
+---
+
+## 6. Threat Intelligence Lookups
+
+### IOC Enrichment
+
+```bash
+# AbuseIPDB — check IP reputation
+curl -s "https://api.abuseipdb.com/api/v2/check?ipAddress=1.2.3.4&maxAgeInDays=90" \
+  -H "Key: $ABUSEIPDB_API_KEY" \
+  -H "Accept: application/json"
+
+# PhishTank — check known phishing URLs
+curl -s "https://checkurl.phishtank.com/checkurl/" \
+  -d "url=https://suspicious.example.com&format=json&app_key=$PHISHTANK_API_KEY"
+
+# OTX AlienVault — threat indicators
+curl -s "https://otx.alienvault.com/api/v1/indicators/domain/example.com/general" \
+  -H "X-OTX-API-KEY: $OTX_API_KEY"
+```
+
+### Threat Intelligence Decision Matrix
+
+```
+Each source has a confidence weight:
+- VirusTotal (multi-engine):  weight = engines_flagging / total_engines (0.0–1.0)
+- Google Safe Browsing:       weight = 0.9 (high-confidence source)
+- AbuseIPDB:                  weight = reported_confidence / 100
+- PhishTank (community):      weight = 0.6 if verified, 0.3 if unverified
+- OTX AlienVault:             weight = 0.5
+
+Scoring (sum of weights from all sources):
+- Combined weight = 0         → CLEAN
+- Combined weight < 0.5       → LOW CONFIDENCE (note in output, proceed with caution)
+- Combined weight 0.5–1.49    → SUSPICIOUS (warn user, provide source details)
+- Combined weight >= 1.5      → MALICIOUS (block and explain)
+
+IMPORTANT:
+- NEVER dismiss a single source automatically — a VirusTotal result with 30+
+  engine flags (weight >= 0.4) is a strong signal on its own
+- New threats often start with only one vendor detecting them
+- Check the specific threat type (phishing vs malware vs adware)
+- Recent reports carry more weight than old ones
+```
+
+---
+
+## 7. Continuous Monitoring Playbook
+
+### Agent-Initiated Security Checks
+
+An autonomous security agent should proactively scan at these trigger points:
+
+```
+TRIGGER                          ACTION                         FREQUENCY
+──────────────────────────────── ────────────────────────────── ──────────
+User shares a URL                → url_scan + domain_threat     Every time
+User provides wallet address     → wallet_check                 Every time
+New dependency added             → npm audit + snyk check       On change
+Pre-deployment                   → header_scan + ssl_audit      Per deploy
+Weekly maintenance               → full domain posture check    Weekly
+Email campaign setup             → SPF/DKIM/DMARC validation   On setup
+Smart contract interaction       → contract_scan + honeypot     Every time
+File download from external      → VirusTotal file hash check   Every time
+```
+
+### Incident Response Quick Actions
+
+```
+1. PHISHING DETECTED
+   → Block URL in security headers (CSP)
+   → Notify affected users
+   → Report to PhishTank/Google Safe Browsing
+   → Check if credentials were entered → force password reset
+
+2. SCAM WALLET DETECTED
+   → Block transaction
+   → Warn user with specific evidence
+   → Report to ChainAbuse
+   → Check transaction history for prior interactions
+
+3. COMPROMISED DOMAIN DETECTED
+   → Revoke any API keys associated with domain
+   → Update DNS if you control it
+   → Notify users who may have visited
+   → Check for data exfiltration in logs
+
+4. MALICIOUS CONTRACT DETECTED
+   → Revoke token approvals (approve(0))
+   → Warn user with contract analysis
+   → Check for pending transactions to cancel
+   → Report to block explorer
+```
+
+---
+
+## 8. Result Caching
+
+Cache scan results to preserve API quota and avoid redundant checks:
+
+| Check Type | Cache TTL | Cache Key |
+|-----------|----------|-----------|
+| URL scan | 1 hour | Normalized URL (strip tracking params) |
+| Domain WHOIS | 24 hours | Domain name |
+| Wallet reputation | 15 minutes | Address (lowercased) |
+| Contract scan | 1 hour | Contract address + chain ID |
+| Threat intel IOC | 30 minutes | IOC value |
+
+- Cache is in-memory only (no persistence across sessions)
+- Force refresh available via user request: "rescan [target]"
+- Cache hit returns cached result with age note (e.g., "cached 12 min ago")
+
+---
+
+## 9. API Quick Reference
+
+### Free Tier APIs
+
+| Service | Free Limit | Best For | Notes |
+|---------|-----------|----------|-------|
+| VirusTotal | 4/min, 500/day | URL, file, domain, IP scans | |
+| AbuseIPDB | 1,000/day | IP reputation | |
+| PhishTank | Deprecated | Known phishing URL check | API access restricted; use as supplementary source only if legacy key available |
+| OpenPhish | Community feed, updated every 12h | Phishing URL feed | Free, no API key needed — recommended PhishTank replacement |
+| OTX AlienVault | Unlimited | Threat indicators, IOCs | |
+| Google Safe Browsing | 10,000/day | URL safety check | |
+| Etherscan | 5/sec | Contract verification, tx history | |
+| Honeypot.is | Unlimited | Token honeypot detection | |
+| WHOIS (CLI) | ~30-50/min per registrar | Domain age and registrar | Rate varies by TLD server; implement backoff on failures |
+
+### Environment Variables
+
+```bash
+VT_API_KEY=          # VirusTotal
+GSB_API_KEY=         # Google Safe Browsing
+ABUSEIPDB_API_KEY=   # AbuseIPDB
+PHISHTANK_API_KEY=   # PhishTank (deprecated — optional, legacy keys only)
+OTX_API_KEY=         # AlienVault OTX
+ETHERSCAN_API_KEY=   # Etherscan (or Basescan, etc.)
+CHAINABUSE_API_KEY=  # ChainAbuse
+```
+
+### Graceful Degradation
+
+Not all API keys are required. The agent should adapt based on what's available:
+
+```
+Keys configured   Capability level   Behavior
+─────────────── ─────────────────── ────────────────────────────────────────────
+All keys          Full                All checks enabled
+4-6 keys          Partial             Run available checks, warn about gaps
+1-3 keys          Degraded            Heuristic-heavy mode, warn prominently
+0 keys            Heuristic-only      Pattern matching only, no external lookups
+```
+
+On startup, log which checks are unavailable:
+- Example: "VT_API_KEY not set — URL reputation checks will use heuristics only"
+
+On API errors during operation:
+- Timeout (>5s): skip source, note in output, continue with other sources
+- Rate limited (429): queue and retry with exponential backoff, warn user of delay
+- Server error (5xx): skip source, note in output, continue
+- All external sources fail: switch to heuristic mode and warn explicitly