OnionClaw MCP server

OnionClaw 🧅

by JacobJandon

OpenClaw skill + standalone tool — full Tor / dark web access for AI agents

OnionClaw gives AI agents full access to the Tor network and .onion hidden services. It runs as an OpenClaw skill (drop-in, zero config beyond a .env file) and also works standalone from any terminal.

Based on the SICRY engine — 17 dark web search engines, Robin OSINT pipeline, four LLM analysis modes.

# As an OpenClaw skill:
cp -r OnionClaw ~/.openclaw/skills/onionclaw
# → agent now has 7 dark web commands available in every session

# Standalone:
python3 doctor.py           # check the whole setup, and what to fix
python3 check_tor.py        # verify Tor
python3 check_engines.py && python3 search.py --query "ransomware healthcare" --alive
python3 pipeline.py --query "acme.com data leak" --mode corporate

---

⚠️ The Rabbit Hole

Autonomous agents paired with the Tor network will be one of the most dangerous automation stacks on the internet within the next five years. OnionClaw is living proof that the rabbit hole goes deeper than most people think.

This tool is built for legitimate OSINT, threat intelligence, and security research. But the same primitives — anonymous routing, bulk scraping, AI-driven synthesis, zero-attribution browsing, automated identity rotation — are precisely what make this combination genuinely dangerous in the wrong hands.

This is not a warning tucked in fine print. It is the whole point of writing it down openly.

What the stack enables — the full map

Use case	What it looks like
Dark-web crawling	Automated, headless spidering of .onion services at scale — forums, paste sites, markets, leak boards — with full identity rotation between every request. No human ever touches a keyboard.
Threat intelligence	Continuous monitoring of ransomware group blogs, initial access broker ads, CVE exploit drops, and actor chatter long before it surfaces on clearnet feeds.
Marketplace monitoring	Price tracking, stock alerts, vendor reputation scraping, and availability checks across darknet markets — the same logic a researcher uses to track fentanyl price trends is the same logic a supplier uses to undercut competitors.
Credential surveillance	Watching paste boards, breach dumps, and forum leaks for specific email domains, API keys, SSH keys, or internal hostnames the moment they appear — at a scale no human analyst can match.
Deanonymisation research	Cross-correlating .onion service metadata with clearnet traces, timing attacks, correlation of writing style and PGP keys — used both by law enforcement hunting criminals and by threat actors hunting journalists and dissidents.
Criminal automation	Autonomous agents placing orders, posting ads, messaging vendors, managing mule accounts, draining wallets — an entire criminal operation running without a human ever in the loop.
Disinformation infrastructure	Coordinated persona networks on hidden boards, fabricated document drops timed to bleed into legitimate OSINT pipelines, synthetic intelligence that reads real but originates from nowhere.
Zero-day brokerage	Automated monitoring of exploit vendor channels, private CVE auction boards, and vulnerability markets — buy-side and sell-side intelligence gathered faster than any human analyst.

The ugly side

The 2026 internet is already at the edge of this. Within five years, AI agents that can:

1. Browse anonymously through rotating Tor circuits with no persistent identity
2. Understand context well enough to navigate dark web UIs, CAPTCHA logic, and forum culture without hardcoded selectors
3. Act autonomously — search, buy, post, exfiltrate, rotate — in closed loops with no human confirmation step
4. Self-orchestrate across dozens of simultaneous Tor identities on parallel threads

…represent a qualitative shift from human criminals using tools to autonomous criminal infrastructure operating at machine speed with no human in the loop. The bottleneck has always been human attention. Remove it and the scaling properties of dark web operations change completely.

OnionClaw demonstrates all four of those primitives working together today. The full pipeline.py step — query refinement → multi-engine search → result filtering → batch scrape → LLM synthesis → identity rotation — is a complete autonomous dark web intelligence loop. Remove the OSINT framing and it is equally a complete autonomous dark web operation loop. The code is the same either way.

Why this is written explicitly

Security tools that pretend the dual-use problem does not exist are more dangerous than ones that name it directly. If you are building on top of OnionClaw:

• Know what you are building. The pipeline does not know if the query is "acme.com credential leak" for a pentest or "rival vendor SSH keys" for espionage.
• Know your jurisdiction. Automated access to dark web content and .onion services may be illegal in your country regardless of intent or findings.
• Tor is not legal protection. It is operational security. The two are different things with very different limits.
• AI + Tor + autonomy is not a theoretical threat. It is a present capability. This repo is one of many signals that the tooling is ready.

OnionClaw is published for defensive research, red-team engagements, and threat intelligence work. The code does not know the difference between those uses and their inverse. You do. Build accordingly.

---

Contents

1. ⚠️ The Rabbit Hole
2. What OnionClaw does
3. Requirements
4. Install as OpenClaw skill
5. Standalone install
6. Configuration
7. All seven commands
8. Investigation flows
9. Analysis modes
10. Architecture
11. Troubleshooting
12. Credits

---

What OnionClaw does

Seven commands expose the complete Tor OSINT toolkit:

Command	What it does
check_tor.py	Verify Tor is active, show current exit IP
renew.py	Rotate Tor circuit — new exit node, new identity
check_engines.py	Ping all 17 dark web search engines, show latency
search.py	Search up to 17 engines simultaneously, deduplicated results
fetch.py	Fetch any .onion or clearnet URL through Tor
ask.py	LLM OSINT analysis of scraped content (4 modes)
pipeline.py	Full Robin pipeline: refine → search → filter → scrape → analyse

---

Requirements

• Python 3.10+
• Tor running locally (SOCKS proxy on 127.0.0.1:9050)
• pip packages: requests[socks] beautifulsoup4 python-dotenv stem
• LLM key (optional — only needed for ask.py and pipeline.py analysis step)

Install Tor

Linux (Debian/Ubuntu):

apt install tor && tor &

macOS:

brew install tor && tor &

With control port (needed for renew.py):

cat > /tmp/onionclaw_tor.conf << 'EOF'
SocksPort 9050
ControlPort 9051
CookieAuthentication 1
DataDirectory /tmp/tor_data
EOF
tor -f /tmp/onionclaw_tor.conf &

Then set TOR_DATA_DIR=/tmp/tor_data in .env.

Install Python packages

pip install requests[socks] beautifulsoup4 python-dotenv stem

---

Install as OpenClaw skill

1. Clone or copy this repo into your OpenClaw skills directory:

# Option A — clone directly
git clone https://github.com/JacobJandon/OnionClaw ~/.openclaw/skills/onionclaw

# Option B — copy local folder
cp -r OnionClaw ~/.openclaw/skills/onionclaw

1. Configure .env in the skill folder:

cp ~/.openclaw/skills/onionclaw/.env.example ~/.openclaw/skills/onionclaw/.env
nano ~/.openclaw/skills/onionclaw/.env   # add LLM key if desired

1. Start a new OpenClaw session — the skill loads automatically on startup. OpenClaw includes onionclaw in the agent context whenever the user asks about dark web topics.

Verify OpenClaw can see the skill:

openclaw skills list
# → onionclaw  🧅  Search the Tor dark web...

OpenClaw trigger phrases:

• "search the dark web for …"
• "investigate this .onion site …"
• "check if my data appeared on the dark web"
• "find ransomware leaks related to …"
• "fetch this .onion URL …"
• "run a Tor OSINT investigation on …"

After install, start a new session — existing sessions will not pick up the new skill.

---

Standalone install

No OpenClaw required. Every script runs directly from a terminal:

git clone https://github.com/JacobJandon/OnionClaw
cd OnionClaw
pip install requests[socks] beautifulsoup4 python-dotenv stem
cp .env.example .env
# Edit .env — add LLM key if desired (optional for most commands)

---

Configuration

Copy .env.example to .env and fill in what you need:

# ── Tor ────────────────────────────────────────────────────────────────
TOR_SOCKS_HOST=127.0.0.1
TOR_SOCKS_PORT=9050
TOR_CONTROL_HOST=127.0.0.1
TOR_CONTROL_PORT=9051
# TOR_CONTROL_PASSWORD=your_password   # only if HashedControlPassword in torrc
# TOR_DATA_DIR=/tmp/tor_data           # DataDirectory path for cookie auth

# ── LLM (needed only for ask.py and pipeline.py analysis step) ──────────
LLM_PROVIDER=openai          # openai | anthropic | gemini | ollama | llamacpp
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=AIza...
# OLLAMA_MODEL=llama3.2       # local model — no API key needed

No LLM key? Set LLM_PROVIDER=ollama with a running Ollama instance for fully local inference. search.py, fetch.py, check_tor.py, renew.py, and check_engines.py work with no LLM key at all.

---

All seven commands

check_tor.py — verify Tor

python3 check_tor.py

✓ Tor active
  Exit IP  : 185.220.101.20
  Error    : None
{"tor_active": true, "exit_ip": "185.220.101.20", "error": null}

Run this before anything else. Exits with code 1 if Tor is not running or not accessible on port 9050.

---

renew.py — rotate identity

python3 renew.py

Rotating Tor circuit...
✓ Identity renewed — new Tor circuit established
{"success": true, "error": null}

Auth order: password env var → cookie from TOR_DATA_DIR → common system paths → null auth. Works out of the box with the recommended torrc above or with a standard system Tor install.

---

check_engines.py — engine health check

# Live ping (15–30 s)
python3 check_engines.py

# --cached N: reuse last result if less than N minutes old (skips the slow ping)
python3 check_engines.py --cached 10

# JSON output only
python3 check_engines.py --json

# Show version
python3 check_engines.py --version

ALIVE  9/12
──────────────────────────────────────────
  ✓  Ahmia-clearnet       670ms  ███
  ✓  Tor66                749ms  ███
  ✓  Ahmia               1139ms  █████
  ✓  OSS                 1203ms  ██████
  ...
DOWN   3/12
  ✗  Kaizer     timeout
  ✗  Anima      timeout
  ✗  FindTor    timeout

Run before a large search session. Use the alive engine names as arguments to --engines in search.py.

---

search.py — search dark web

# All 17 engines (default)
python3 search.py --query "ransomware healthcare leak"

# Specific engines (faster — use alive engines from check_engines output)
python3 search.py \
  --query "credential dump" \
  --engines Ahmia Tor66 Ahmia-clearnet OSS

# Limit result count
python3 search.py --query "bitcoin mixer" --max 30

Returns a deduplicated {title, url, engine} list across all engines.

Tip: Use short keyword queries (3–5 words). Dark web search indexes respond much better to keywords than natural-language sentences.

---

fetch.py — fetch any .onion page

# Hidden service
python3 fetch.py \
  --url "http://juhanurmihxlp77nkq76byazcldy2hlmovfu2epvl5ankdibsot4csyd.onion"

# With links extracted
python3 fetch.py --url "http://example.onion/page" --links

# JSON output only
python3 fetch.py --url "http://example.onion" --json

Returns: title, text content (up to 8000 chars), extracted links, HTTP status code. A status of 0 means the hidden service is unreachable or offline.

---

ask.py — LLM OSINT analysis

# Inline content
python3 ask.py \
  --query "LockBit ransomware" \
  --mode ransomware \
  --content "page text from scraped pages"

# From file
python3 ask.py \
  --query "acme.com" \
  --mode corporate \
  --file /tmp/scraped_pages.txt

# Pipe from fetch.py
python3 fetch.py --url "http://some.onion" --json | \
  python3 -c "import sys,json; print(json.load(sys.stdin)['text'])" | \
  python3 ask.py --query "investigate" --mode threat_intel

# Custom analysis focus
python3 ask.py \
  --query "mixer services" \
  --mode threat_intel \
  --content "..." \
  --custom "Focus on cryptocurrency wallet addresses only"

Modes: threat_intel · ransomware · personal_identity · corporate — see Analysis modes.

---

pipeline.py — full investigation (one command)

Runs the complete Robin OSINT pipeline automatically:

Step	What happens
1	Verify Tor is active
2	Check which engines are alive
3	Refine query to ≤5 keywords (LLM)
4	Search all alive engines
5	Filter top 20 most relevant results (LLM)
6	Batch-scrape pages concurrently
7	OSINT analysis and report (LLM)

# Basic
python3 pipeline.py --query "hospital ransomware 2026"

# With analysis mode and output file
python3 pipeline.py \
  --query "acme.com credentials leak" \
  --mode corporate \
  --out report.md

# Full options
python3 pipeline.py \
  --query "QUERY" \
  --mode ransomware \
  --max 50 \
  --scrape 12 \
  --custom "Focus on ransom amounts and victim industries" \
  --out report.md

Steps 1–6 work fully without an LLM key. Only steps 3, 5, and 7 use the LLM — they fall back gracefully when no key is set, printing what was collected so far.

# --clear-cache: discard cached fetch results before this run
python3 pipeline.py --query "fresh data" --clear-cache

# --version: print OnionClaw version
python3 pipeline.py --version

---

sync_sicry.py — update bundled SICRY engine

OnionClaw bundles a copy of sicry.py from the upstream SICRY™ repo. sync_sicry.py lets you pull the latest version (or a specific release tag) without a full git pull.

# Fetch latest from main branch
python3 sync_sicry.py

# Fetch a specific release tag
python3 sync_sicry.py --tag v1.2.0

# Preview what would happen without writing
python3 sync_sicry.py --dry-run

# Show version
python3 sync_sicry.py --version

After syncing, commit the updated file:

git add sicry.py && git commit -m "chore: sync sicry.py to SICRY v1.2.0"

Update notices — pipeline.py (and sicry.check_update()) checks the GitHub Releases API (/releases/latest). Only published formal releases trigger a notice — plain git tags and pre-releases are silently ignored.

---

Monitoring swarm (v2.4)

Everything above answers "what is on this page?". The swarm answers "what changed since I last looked?" — continuously, persistently, and read-only.

python3 swarm.py                                  # one sweep → prioritised digest
python3 swarm.py --watch healthcare --watch US    # flag matching events PRIORITY (whole-word match)
python3 swarm.py --wallet bc1q...                 # always track an address on-chain
python3 swarm.py --onion http://xyz.onion         # monitor a hidden-service page (needs Tor)
python3 swarm.py --loop 900                       # sweep every 15 min
python3 swarm.py --webhook https://hooks.slack.com/... --webhook-format slack
python3 stix.py -o bundle.json                    # STIX 2.1 export (MISP / OpenCTI)
python3 graph.py                                  # evidence-based group correlation
python3 graph.py --activity                       # time-decayed group activity ranking
python3 risk.py                                   # groups ranked by transparent priority score
python3 ttp.py --group medusa                     # MITRE ATT&CK techniques + tools per group
python3 iocs.py --group qilin --format csv       # every observed indicator, defanged by default
python3 crawl.py --url http://xyz.onion --depth 2 # concurrent single-site crawl

Collector	Source	Detects
leaksites	ransomware.live	new victim disclosures; wallets in ransom notes
groupinfra	ransomware.live	leak sites going up / down / moving; each group's ATT&CK techniques and tools (and when they change)
kev	CISA KEV	new exploited CVEs, and CVEs newly linked to ransomware
wallets	mempool.space	balance / tx movement on tracked ransom wallets
onionsites	your URLs, via Tor	content change and new wallets / emails on a page

State lives in onionclaw.db (SQLite). The first run baselines silently; later runs report only changes. A failing source is reported and never stops the others.

Read-only by design. Collectors only fetch public data. Nothing here contacts, negotiates with, or deceives a threat actor, and no feature is planned that would.

Alerts (--webhook): KEV_RANSOMWARE, WALLET_MOVEMENT, WALLET_LINK, WATCHLIST_HIT (HIGH); CRITICAL_VICTIM, ONION_CHANGE (MEDIUM); INFRA_CHANGE (LOW). Delivery is exactly-once per webhook, retried until the receiver answers 2xx, and generic payloads can be HMAC-signed (--webhook-secret).

Priority and ATT&CK. risk.py ranks groups by observed volume, critical-sector victims, reach, capability (published ATT&CK techniques, tools, live leak-site hosts) and evidence links, then decays groups that have gone quiet. Every score lists the numbers behind it; it is a triage order, not a verdict. ttp.py maps groups to MITRE ATT&CK from the data ransomware.live publishes, and STIX exports include attack-pattern and tool objects linked to each group by uses relationships.

Indicators. iocs.py is one queryable view of every indicator the swarm has observed (onion hosts, clearnet domains, ransom-note wallets, KEV CVEs, contact addresses), derived from the stored observations rather than a second copy, with first/last seen, attribution and source for each. Values are defanged by default so they can be pasted into a ticket safely.

Correlation is a lead, not attribution. graph.py links groups only through hard identifiers (shared wallet, shared leak-site host, normalised alias, shared victim) and shows the evidence for every edge. A host shared by three or more groups is weighted low, since that usually means a shared platform.

⚠ ransomware.live terms

The free v2 API is limited to personal use (not corporate/business), 1 request/minute/endpoint, and returns victims delayed versus PRO. OnionClaw enforces the rate limit across processes and tells you when it is on the free tier. For business use, get a PRO key and set RANSOMWARE_LIVE_API_KEY, RANSOMWARE_LIVE_BASE, and RANSOMWARE_LIVE_KEY_HEADER. The PRO auth header name and paths could not be verified from public documentation — the X-API-KEY default is unconfirmed; check the PRO docs.

Known limits

• .onion fetching (onionsites, crawl.py) needs Tor; the test suite covers that logic against a local server but does not exercise the Tor transport.
• STIX 2.1 has no standard cryptocurrency-wallet observable; wallets use a custom x-cryptocurrency-wallet pattern that generic consumers will not match.
• ransom-note wallet harvesting depends on what the tracker publishes; many victims carry none.

Website

The project site lives in web/ (Vite + three.js, all versions pinned):

cd web
npm install
npm run dev        # http://127.0.0.1:5173  — live reload
npm run build      # static site in web/dist/, deploy anywhere
npm run preview    # serve the built site at http://127.0.0.1:4173

• / — Peel: scroll through the three Tor encryption layers of a glass onion down to the swarm core.
• /hybrid/ — Hybrid: a toon "onion planet" whose stations are the tools; orbit it chapter by chapter, then explore it freely.
• Add ?static for a readable version without WebGL (used automatically with reduced motion).

Investigation flows

Scenario 1: Check for leaked credentials

python3 check_tor.py
python3 pipeline.py \
  --query "acme.com email passwords" \
  --mode corporate \
  --scrape 10 \
  --out acme_leak_report.md

Scenario 2: Ransomware intelligence

python3 check_tor.py
python3 search.py \
  --query "LockBit healthcare 2026" \
  --engines Ahmia Tor66 Ahmia-clearnet \
  --max 40

# Fetch the most relevant URL
python3 fetch.py --url "http://..." > /tmp/page.json

# Analyse
python3 ask.py \
  --query "LockBit healthcare 2026" \
  --mode ransomware \
  --file /tmp/page.json

Scenario 3: Personal data exposure check

python3 pipeline.py \
  --query "john.smith@email.com personal data" \
  --mode personal_identity \
  --scrape 8

Scenario 4: Manual step-by-step investigation

# 1. Verify Tor
python3 check_tor.py

# 2. Find alive engines
python3 check_engines.py

# 3. Search with alive engines
python3 search.py \
  --query "ransomware hospital 2026" \
  --engines Ahmia Tor66 OSS \
  --max 40

# 4. Fetch top pages
python3 fetch.py --url "http://..." --links
python3 fetch.py --url "http://..."

# 5. Analyse
python3 ask.py \
  --query "hospital ransomware" \
  --mode ransomware \
  --content "combined text from pages"

# 6. Rotate identity when done
python3 renew.py

---

Analysis modes

threat_intel (default)

General dark web OSINT. Extracts: IoCs, infrastructure details, actor mentions, next investigation steps.

Output sections: Input Query · Source Links · Investigation Artifacts · Key Insights · Recommended Next Steps

ransomware

Malware/RaaS intelligence. Extracts C2 domains, file hashes, MITRE ATT&CK TTPs, victim sectors, ransom amounts.

Output sections: Input Query · Source Links · Malware/Ransomware Indicators · Threat Actor Profile · Key Insights · Recommended Next Steps

personal_identity

PII and breach exposure. Surfaces SSNs, emails, passwords, passport data, breach sources, risk severity ratings.

Output sections: Input Query · Source Links · Exposed PII Artifacts · Breach/Marketplace Sources · Exposure Risk Assessment · Key Insights · Recommended Next Steps

corporate

Corporate threat intelligence. Detects leaked credentials, source code, internal documents, initial access broker activity.

Output sections: Input Query · Source Links · Leaked Corporate Artifacts · Threat Actor/Broker Activity · Business Impact Assessment · Key Insights · Recommended Next Steps

---

Troubleshooting

✗ Tor NOT active

# Is Tor running?
pgrep tor || tor &
# Is port 9050 listening?
ss -tlnp | grep 9050

renew.py → success: false

# Is control port open?
ss -tlnp | grep 9051