Skill: schwartzdev/stealth (version 0.4.1)

--- name: stealth keywords: - residential proxy - anti-bot - bot detection - captcha solver - hcaptcha - recaptcha - cloudflare turnstile - cloudflare bypass - stealth browser - browser fingerprint - web scraping - IP block - datacenter IP - proxy setup - 403 error - 429 error - anti-detect description: > Residential proxy and anti-bot detection toolkit for AI agents. Set up residential proxies, solve CAPTCHAs, and configure stealth browsers to avoid bot detection. Diagnoses why your agent is getting blocked and fixes it. Use when: agent hits 403/429 errors, encounters CAPTCHAs (hCaptcha, reCAPTCHA, Cloudflare Turnstile), gets detected as a bot, receives fake/empty data from websites, encounters Cloudflare challenges, needs to bypass IP blocks, or is running on a datacenter/cloud IP. Covers: residential proxy setup and configuration, CAPTCHA solver integration, stealth browser fingerprinting. For web scraping, browser automation, form filling, and any task where bot detection is a problem. --- # Stealth — Anti-Bot Detection for AI Agents Three layers, applied in order. Most blocks are solved at Layer 1. ## Quick Diagnostic Run this first to understand the problem: ```bash curl -s https://ipinfo.io/json | python3 -c " import sys,json;d=json.load(sys.stdin) org=d.get('org','') h=d.get('privacy',{}).get('hosting') if 'privacy' in d else None dc=h or any(x in org.lower() for x in ['digital','amazon','google','microsoft','azure','linode','vultr','hetzner','ovh','cloud']) print(f'IP: {d[\"ip\"]} | Org: {org} | Datacenter: {dc}') if dc: print('⚠️ Datacenter IP detected → Layer 1 (proxy) required') else: print('✅ Residential IP — skip to Layer 2 or 3 if still blocked') " ``` ### Block type reference | Symptom | Cause | Layer | |---------|-------|-------| | 403 Forbidden | IP/bot block | 1 | | 429 Too Many Requests | Rate limit | 1 | | Cloudflare challenge | Bot detection | 1 + 3 | | CAPTCHA appears | Verification gate | 2 | | 200 but wrong content | Honeypot/fake data | 3 | | Redirect loop | Cookie/session detection | 3 | ## Layer 1: Residential Proxy **The #1 fix.** Datacenter IPs are flagged instantly by Cloudflare, Akamai, PerimeterX, and most anti-bot systems. A residential proxy routes traffic through real ISP connections. See `references/proxy-setup.md` for provider comparison and setup instructions. **Quick test after setup:** ```bash curl -x [REDACTED_SECRET] -s https://ipinfo.io/json | python3 -c " import sys,json;d=json.load(sys.stdin) print(f'Proxy IP: {d[\"ip\"]} | Org: {d.get(\"org\")}') " ``` Org should show an ISP (Comcast, Verizon, AT&T), not a cloud provider. ## Layer 2: CAPTCHA Solving **Never attempt CAPTCHAs yourself.** You will fail, burn tokens, and trigger escalated challenges. Always use a solver service. **Critical routing rule:** 2Captcha dropped hCaptcha support entirely in late 2025. Use CapSolver for hCaptcha. | CAPTCHA type | Provider | |-------------|----------| | hCaptcha | CapSolver only | | reCAPTCHA v2/v3 | 2Captcha or CapSolver | | Cloudflare Turnstile | Either | | Image/text | 2Captcha | See `references/captcha-setup.md` for provider setup, API integration code, and token injection. ## Layer 3: Stealth Browser **When proxy alone isn't enough.** Sites fingerprint headless browsers via navigator properties, WebGL, Canvas, and automation flags. See `references/browser-stealth.md` for Playwright stealth config, header templates, and anti-fingerprinting. ## Troubleshooting | Problem | Fix | |---------|-----| | Blocked after proxy | Verify IP is residential via `ipinfo.io`. Cheap providers resell datacenter IPs. | | CAPTCHA solver error | Wrong provider for captcha type? 2Captcha cannot solve hCaptcha. | | Site serves fake data | Add stealth browser config (Layer 3). | | Slow responses | Try proxy server closer to target site's region. | | Blocked after many requests | Enable IP rotation in proxy dashboard. |

path: references/proxy-setup.md
content: # Residential Proxy Setup

## Provider Comparison

| Provider | Pool Size | Pay-as-you-go | Geo-targeting | Best for |
|----------|-----------|--------------|---------------|----------|
| Oxylabs | 100M+ IPs | ✅ | Country/city/state | Difficult targets, highest success rate |
| DataImpulse | 5M+ IPs | ✅ (no minimum) | Country | Budget, high-volume |
| Smartproxy | 55M+ IPs | ✅ | Country/city | Unlimited connections |
| Bright Data | 72M+ IPs | ❌ ($500 min) | Country/city/ASN | Enterprise |

**Recommendation:** Oxylabs for most use cases. DataImpulse if budget is tight.

## Setup

### 1. Get credentials

After signing up with any provider, you'll get:
- **Host** (e.g., `pr.oxylabs.io`)
- **Port** (e.g., `7777`)
- **Username**
- **Password**

### 2. Test connectivity

```bash
curl -x [REDACTED_SECRET] https://httpbin.org/ip
```

Should return a JSON object with an IP different from your server's IP.

### 3. Verify residential

```bash
curl -x [REDACTED_SECRET] -s https://ipinfo.io/json
```

Look at `org` field — should be an ISP (Comcast, Verizon, AT&T, BT, Deutsche Telekom), NOT a cloud provider (AWS, Google, DigitalOcean).

### 4. Configure

**Python requests:**
```python
proxies = {
    "http": "[REDACTED_SECRET]",
    "https": "[REDACTED_SECRET]"
}
response = requests.get(url, proxies=proxies)
```

**Playwright:**
```python
browser = playwright.chromium.launch(
    proxy={"server": "http://HOST:PORT", "username": "USER", "password": "PASS"}
)
```

**Puppeteer:**
```javascript
const browser = await puppeteer.launch({
    args: ['--proxy-server=http://HOST:PORT']
});
// Authenticate per page:
await page.authenticate({username: 'USER', password: 'PASS'});
```

**Environment variables (curl, wget, most CLI tools):**
```bash
export HTTP_PROXY="[REDACTED_SECRET]"
export HTTPS_PROXY="[REDACTED_SECRET]"
```

**OpenClaw browser tool:**
Set env vars before starting the gateway, or configure in the browser launch options.

### 5. Save for reuse

```bash
mkdir -p ~/.config/stealth
cat > ~/.config/stealth/proxy.json << 'EOF'
{
  "host": "HOST",
  "port": "PORT",
  "username": "USER",
  "password": "PASS",
  "provider": "oxylabs"
}
EOF
chmod 600 ~/.config/stealth/proxy.json
```

### 6. IP Rotation

Most providers auto-rotate per request. For sticky sessions (same IP for a session):
- **Oxylabs:** append `-session-RANDOM` to username
- **Smartproxy:** use session port (e.g., `7778`)
- **DataImpulse:** append `-sessid-RANDOM` to username

## Country Targeting

Route through specific countries by modifying the username or endpoint:

- **Oxylabs:** `customer-USER-cc-US:[REDACTED_SECRET]:7777`
- **Smartproxy:** `user-USER-country-us:[REDACTED_SECRET]:7000`
- **DataImpulse:** `USER-country-us:[REDACTED_SECRET]:823`


Security scan verdicts — ClawScan: malicious | static analysis:  | VirusTotal:  | SkillSpector:  ()