skills-ws 1.5.3 → 1.5.5

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skills-ws",
-  "version": "1.5.3",
-  "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.5",
+  "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"
   },

package/skills/polymarket-trading/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: polymarket-trading
+description: Polymarket prediction market trading — market analysis, edge calculation, bookmaker cross-referencing, order placement via CLOB API, position management, and redemption. Covers sports betting strategy, risk management, and the full Polymarket SDK workflow.
+version: 1.0.0
+---
+
+# Polymarket Trading
+
+Complete framework for analyzing, trading, and managing positions on Polymarket — the world's largest prediction market.
+
+## Table of Contents
+
+1. [Market Analysis Framework](#market-analysis-framework)
+2. [Edge Calculation](#edge-calculation)
+3. [Bookmaker Cross-Referencing](#bookmaker-cross-referencing)
+4. [Risk Management Rules](#risk-management-rules)
+5. [APIs & Data Sources](#apis--data-sources)
+6. [Trading via CLOB](#trading-via-clob)
+7. [Position Management & Redemption](#position-management--redemption)
+8. [Understanding Polymarket Mechanics](#understanding-polymarket-mechanics)
+9. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## Market Analysis Framework
+
+### The Scan Pipeline
+
+For every potential bet, follow this pipeline in order:
+
+```
+1. Polymarket prices → identify markets with volume > $10K
+2. Filter → bookmaker favorites > 65% implied probability
+3. Injury/news check → any material changes not priced in?
+4. Form & H2H analysis → recent performance, matchup history
+5. Cross-reference 3+ bookmaker sources → calculate true probability
+6. Calculate edge → only bet if edge > 10% vs Polymarket price
+7. Size the bet → based on edge magnitude and bankroll
+```
+
+### Market Selection Criteria
+
+**Good markets:**
+- High volume (> $10K) — ensures liquidity for entry and exit
+- Near-term resolution (days, not months) — capital efficiency
+- Binary outcomes with clear resolution criteria
+- Markets where bookmaker odds exist for cross-referencing
+
+**Bad markets:**
+- Low liquidity (< $5K volume) — wide spreads eat your edge
+- Subjective resolution criteria — dispute risk
+- Markets with insider information advantage (crypto governance, company decisions)
+- Long-dated futures that tie up capital for months
+
+---
+
+## Edge Calculation
+
+### The Math
+
+```
+Bookmaker Implied Probability = 1 / Decimal Odds
+Edge = (True Probability - Polymarket Price) / Polymarket Price × 100
+
+Example:
+  Bookmaker odds: -225 (decimal 1.44) → Implied probability: 69.4%
+  Polymarket price: $0.645 (64.5%)
+  Edge = (69.4 - 64.5) / 64.5 × 100 = 7.6%
+```
+
+### American Odds to Probability
+
+```
+Negative odds (favorites):  Probability = |odds| / (|odds| + 100)
+  -225 → 225 / 325 = 69.2%
+
+Positive odds (underdogs):  Probability = 100 / (odds + 100)
+  +150 → 100 / 250 = 40.0%
+```
+
+### Removing the Vig
+
+Bookmaker odds include a margin (vig). To get true probabilities:
+
+```
+1. Convert both sides to implied probabilities
+2. Sum them (will be > 100%, e.g., 105%)
+3. Divide each by the sum to normalize to 100%
+
+Example:
+  Team A: -200 → 66.7%    Team B: +170 → 37.0%
+  Sum: 103.7%
+  True A: 66.7 / 103.7 = 64.3%
+  True B: 37.0 / 103.7 = 35.7%
+```
+
+### Edge Thresholds
+
+| Edge | Action |
+|------|--------|
+| < 5% | Skip — too thin, transaction costs eat it |
+| 5-10% | Marginal — only if very high conviction + multiple sources agree |
+| **> 10%** | **Target zone — place the bet** |
+| > 20% | Strong edge — size up, but verify it's not a trap (news you missed?) |
+
+---
+
+## Bookmaker Cross-Referencing
+
+### Why Cross-Reference?
+
+Polymarket prices are set by traders, not oddsmakers. They systematically:
+- **Overvalue favorites** by 3-7% in major sports markets
+- **Undervalue underdogs/draws** in 3-way football markets
+- **Lag behind** sharp bookmaker lines by hours
+
+### Sources to Cross-Reference
+
+| Source | Use | Notes |
+|--------|-----|-------|
+| **Pinnacle** | Sharpest lines globally | Gold standard, lowest vig |
+| **Bet365** | Popular, liquid markets | Good for mainstream sports |
+| **DraftKings/FanDuel** | US sports | NFL, NBA, MLB, NHL |
+| **Betfair Exchange** | True market prices | No vig, just commission |
+| **OddsPortal/OddsChecker** | Aggregators | Compare across 20+ books |
+| **Action Network** | Analysis + odds | Good injury/form context |
+
+### The 3-Source Rule
+
+Never bet based on a single bookmaker. Always confirm with **3+ independent sources**:
+
+```
+✅ Good: Pinnacle -220, Bet365 -225, DraftKings -215 → consensus ~69%
+   Polymarket at 60¢ → 15% edge → BET
+
+❌ Bad: Only one bookmaker has odds, others don't list the market
+   → Information asymmetry, you might be wrong
+```
+
+---
+
+## Risk Management Rules
+
+### Bankroll Management
+
+```
+Max single bet:     10% of bankroll
+Typical bet size:   2-5% of bankroll
+Max daily exposure: 25% of bankroll
+```
+
+### Hard Rules
+
+1. **Sport only** — No crypto, politics, or geopolitics bets. Crypto markets are manipulated by insiders.
+2. **Only heavy favorites** — Bookmaker implied probability > 65%
+3. **Edge > 10%** — No exceptions for "gut feelings"
+4. **3+ sources minimum** — Cross-reference before every bet
+5. **No long shots** — Underdogs and parlays are money pits
+6. **The best trade is sometimes no trade** — Don't force action
+
+### When NOT to Bet
+
+- Market is illiquid (< $5K volume, wide spreads)
+- News is breaking and odds haven't settled
+- You can't find 3 bookmakers listing the event
+- The edge comes from a single outlier source
+- You're chasing losses from a previous bet
+- Resolution criteria are ambiguous
+
+### Track Record Requirements
+
+- Target **80%+ win rate** on individual bets
+- If below 60% over 10+ bets, stop and re-evaluate strategy
+- Log every bet: market, entry price, bookmaker consensus, edge, result
+
+---
+
+## APIs & Data Sources
+
+### Gamma API (Public, No Auth)
+
+Market discovery and search. Base: `https://gamma-api.polymarket.com`
+
+```
+GET /public-search?q=<query>             — Search markets/events
+GET /events?active=true&closed=false      — List active events
+GET /events?tag_slug=<slug>               — Events by category (sports, politics, crypto)
+GET /markets?slug=<slug>                  — Market details by slug
+GET /tags                                  — All available categories
+```
+
+**Key response fields:**
+- `outcomePrices` — Current Yes/No prices (JSON string, parse it)
+- `clobTokenIds` — Token IDs needed for CLOB trading (JSON string)
+- `volume` — Total dollar volume traded
+- `negRisk` — If true, uses negRisk contract (multi-outcome markets)
+- `groupItemTitle` — The outcome name in grouped markets
+
+### CLOB API (Public reads, Auth for trading)
+
+Order book and trading. Base: `https://clob.polymarket.com`
+
+```
+# Public (no auth)
+GET /midpoint?token_id=<id>              — Midpoint price
+GET /book?token_id=<id>                  — Full order book
+GET /spread?token_id=<id>               — Bid-ask spread
+GET /price?token_id=<id>&side=buy|sell  — Best available price
+GET /tick-size?token_id=<id>            — Min price increment
+
+# Authenticated (requires L2 API key)
+POST /order                              — Place order
+DELETE /order/<id>                       — Cancel order
+GET /orders                              — Open orders
+GET /balances                            — CLOB balances
+```
+
+### Data API (Public, No Auth)
+
+Positions and history. Base: `https://data-api.polymarket.com`
+
+```
+GET /positions?user=<wallet_address>     — All positions for a wallet
+GET /trades?user=<wallet_address>        — Trade history
+```
+
+### Authentication Model
+
+Two-layer auth system:
+- **L1 (Wallet Signature)**: EIP-712 signature from your Polygon wallet — used to derive API credentials
+- **L2 (API Key)**: HMAC-SHA256 headers for all trading operations
+
+**Headers for authenticated requests:**
+```
+POLY_ADDRESS      — Wallet address
+POLY_SIGNATURE    — HMAC signature of request
+POLY_TIMESTAMP    — Unix timestamp
+POLY_NONCE        — Request nonce
+POLY_API_KEY      — Your API key
+POLY_PASSPHRASE   — Your passphrase
+POLY_SECRET       — Your API secret (used for HMAC)
+```
+
+---
+
+## Trading via CLOB
+
+### Using the TypeScript SDK
+
+```javascript
+const { ClobClient, Side } = require('@polymarket/clob-client');
+const { Wallet } = require('ethers');
+
+// Initialize client
+const wallet = new Wallet(PRIVATE_KEY);
+const client = new ClobClient(
+  'https://clob.polymarket.com',
+  137, // Polygon chainId
+  wallet,
+  creds // { apiKey, secret, passphrase }
+);
+
+// Derive API credentials (first time)
+const creds = await client.createOrDeriveApiKey();
+
+// Place a limit buy order
+const order = await client.createAndPostOrder({
+  tokenID: '<token_id>',  // From Gamma API clobTokenIds
+  price: 0.65,            // Max price willing to pay
+  size: 10,               // Dollar amount
+  side: Side.BUY,
+}, { tickSize: '0.01' });  // Check tick-size endpoint first
+
+// Cancel an order
+await client.cancelOrder(orderId);
+
+// Get open orders
+const orders = await client.getOpenOrders();
+```
+
+### Order Flow
+
+```
+1. Search market on Gamma → get slug
+2. Get market details → extract clobTokenIds and outcomePrices
+3. Identify the outcome you want (Yes token ID vs No token ID)
+4. Check tick-size for that token
+5. Check current best price: GET /price?token_id=X&side=buy
+6. Place limit order at your target price
+7. Monitor: GET /orders to check if filled
+```
+
+### Token ID Selection
+
+Grouped markets (like "Who wins UFC 326?") have multiple outcomes. Each outcome has a Yes and No token:
+
+```
+Market: "UFC 326 Main Event"
+  Outcome: "Max Holloway"
+    → Yes Token ID: 7068099725...  (buy this if you think Holloway wins)
+    → No Token ID:  1293847561...  (buy this if you think Holloway loses)
+  Outcome: "Charles Oliveira"
+    → Yes Token ID: 8843920183...
+    → No Token ID:  5567382910...
+```
+
+The Gamma API returns `clobTokenIds` as a JSON string with `[NoTokenId, YesTokenId]` — **index 1 is Yes**.
+
+---
+
+## Position Management & Redemption
+
+### Checking Positions
+
+```
+GET https://data-api.polymarket.com/positions?user=<wallet_address>
+```
+
+Returns all current positions with:
+- `asset` — Token ID
+- `size` — Number of shares
+- `avgPrice` — Average entry price
+- `currentPrice` — Current market price
+- `pnl` — Unrealized P&L
+
+### Redeeming Resolved Positions
+
+When a market resolves, winning shares are worth $1.00. You need to call the contract to redeem:
+
+**Standard markets** (2-outcome, `negRisk: false`):
+```javascript
+// Call ConditionalTokens contract: redeemPositions()
+const CTF_ADDRESS = '0x4D97DCd97eC945f40cF65F87097ACe5EA0476045';
+```
+
+**NegRisk markets** (multi-outcome, `negRisk: true`):
+```javascript
+// Call NegRiskAdapter: redeemPositions()
+const NEG_RISK_ADAPTER = '0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296';
+// Also call NegRiskCTFExchange for conversion
+const NEG_RISK_EXCHANGE = '0xC5d563A36AE78145C45a50134d48A1215220f80a';
+```
+
+### Exit Strategies
+
+- **Winner**: Hold until resolution → redeem at $1.00
+- **Cut losses**: Sell on the CLOB if the market moves against you
+- **Take profit**: If price moved significantly in your favor before resolution, consider selling early to lock in gains and free capital
+
+---
+
+## Understanding Polymarket Mechanics
+
+### How Prices Work
+
+- Prices = probabilities ($0.65 = market says 65% chance of Yes)
+- Markets resolve to $1.00 (correct outcome) or $0.00 (incorrect)
+- Your profit = $1.00 - entry price (per share, if you win)
+- Your loss = entry price (per share, if you lose)
+
+### Where Polymarket Misprices
+
+| Pattern | Why | How to Exploit |
+|---------|-----|----------------|
+| Favorites overvalued by 3-7% | Retail bias toward "safe" bets | Compare vs sharp bookmaker lines |
+| Underdogs/draws undervalued | People avoid complexity | 3-way football markets (win/draw/lose) |
+| Slow to react to news | Traders aren't 24/7 | Fast reaction to injury reports, lineups |
+| Low-volume markets inefficient | Not enough informed traders | Small edges in niche markets |
+
+### Polymarket vs Bookmakers
+
+| Feature | Polymarket | Traditional Bookmaker |
+|---------|-----------|----------------------|
+| Vig/margin | 0% (peer-to-peer) | 3-10% |
+| Liquidity | Variable | Guaranteed |
+| Resolution | Smart contract | Bookmaker decides |
+| Settlement | USDC on Polygon | Fiat |
+| Edge | Retail-driven inefficiencies | Sharp lines, hard to beat |
+
+### Chain Details
+
+- **Chain**: Polygon (MATIC for gas, USDC.e for trading)
+- **USDC.e contract**: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
+- **Note**: Polymarket uses USDC.e (bridged), NOT native USDC
+- **Geo**: Restricted in some countries (US blocked, most of EU is fine)
+
+---
+
+## Common Pitfalls
+
+### ❌ Mistakes to Avoid
+
+1. **Betting on crypto/politics markets** — Insider manipulation is rampant (project teams, whale wallets, political operatives)
+2. **Chasing long shots** — A 5¢ token that could pay $1 sounds amazing; it almost never hits
+3. **Ignoring liquidity** — A "great price" means nothing if you can't exit
+4. **Single-source analysis** — One bookmaker can be wrong; always cross-reference
+5. **Overexposure** — Never have > 25% of bankroll in active bets
+6. **Ignoring the vig** — Bookmaker odds include margin; remove it before comparing
+7. **Trading illiquid markets** — Wide spreads (> 5¢) silently destroy your edge
+8. **Holding long-dated positions** — Capital is locked; shorter resolution = better capital efficiency
+9. **Not tracking results** — Without a log, you can't evaluate if your strategy works
+10. **Emotional trading** — If you just lost, don't immediately place another bet
+
+### ✅ Habits of Profitable Traders
+
+1. Systematic scan pipeline for every bet (not ad-hoc)
+2. Spreadsheet tracking all bets with entry, target, result, edge
+3. Walk away when there's no edge — most days have no good bets
+4. Focus on 1-2 sports you know deeply rather than spreading thin
+5. Check injury reports, team news, and lineup confirmations before betting
+6. Review win/loss ratio monthly and adjust thresholds if needed

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