Skip to content
Back to search

onionclaw

Check the OnionClaw setup, search the Tor dark web, fetch and crawl .onion hidden service pages, rotate Tor identity, run structured OSINT investigations, and monitor ransomware leak sites for changes. Use when user asks to search dark web, investigate .onion sites, find if data appeared on dark web, conduct Tor-based OSINT, look up dark web leaks, fetch or crawl any .onion URL, check for leaked credentials, investigate, monitor or prioritise ransomware groups, map them to MITRE ATT&CK, pull a list of indicators (onion hosts, domains, wallets, CVEs) to block, watch for new victims in a sector, or export threat intel as STIX 2.1.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/JacobJandon/OnionClaw with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/JacobJandon/OnionClaw'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jacobjandon--onionclaw/badge.svg)](/listings/jacobjandon--onionclaw)

HTML

<a href="/listings/jacobjandon--onionclaw"><img src="/api/listings/jacobjandon--onionclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: onionclaw
  3. description: Check the OnionClaw setup, search the Tor dark web, fetch and crawl .onion hidden service pages, rotate Tor identity, run structured OSINT investigations, and monitor ransomware leak sites for changes. Use when user asks to search dark web, investigate .onion sites, find if data appeared on dark web, conduct Tor-based OSINT, look up dark web leaks, fetch or crawl any .onion URL, check for leaked credentials, investigate, monitor or prioritise ransomware groups, map them to MITRE ATT&CK, pull a list of indicators (onion hosts, domains, wallets, CVEs) to block, watch for new victims in a sector, or export threat intel as STIX 2.1.
  4. homepage: https://github.com/JacobJandon/OnionClaw
  5. metadata:
  6. {
  7. "openclaw": {
  8. "emoji": "🧅",
  9. "os": ["darwin", "linux"],
  10. "requires": {
  11. "bins": ["python3", "pip3"],
  12. "pip": ["requests[socks]", "beautifulsoup4", "python-dotenv", "stem"]
  13. },
  14. "version": "2.4.0",
  15. "author": "JacobJandon",
  16. "license": "Apache-2.0",
  17. "repo": "https://github.com/JacobJandon/OnionClaw"
  18. }
  19. }
  20. ---
  21. # OnionClaw — Tor / Dark Web Access
  22. **by JacobJandon** · Apache License 2.0 · [github.com/JacobJandon/OnionClaw](https://github.com/JacobJandon/OnionClaw)
  23. OnionClaw routes all requests through the Tor network. It searches 17 dark web search engines simultaneously, fetches .onion hidden service pages, rotates Tor circuits, and produces structured OSINT reports using the Robin investigation pipeline.
  24. ## Setup (run once after install)
  25. Install Python dependencies:
  26. ```bash
  27. pip3 install requests[socks] beautifulsoup4 python-dotenv stem
  28. ```
  29. Run the interactive first-run wizard (sets up `.env` and torrc in one step):
  30. ```bash
  31. python3 {baseDir}/setup.py
  32. ```
  33. Or set up manually:
  34. ```bash
  35. cp {baseDir}/.env.example {baseDir}/.env
  36. # Edit {baseDir}/.env — add LLM_PROVIDER + API key (optional; search and fetch work without one)
  37. ```
  38. Start Tor (required before any command):
  39. ```bash
  40. # Linux: sudo apt install tor && sudo systemctl start tor
  41. # macOS: brew install tor && brew services start tor
  42. # Custom: tor -f /tmp/tor_data/torrc & (setup.py creates this)
  43. ```
  44. Enable circuit rotation (ControlPort) — required for `renew.py`:
  45. ```
  46. Add to /etc/tor/torrc:
  47. ControlPort 9051
  48. CookieAuthentication 1
  49. Then restart Tor. setup.py does this automatically.
  50. ```
  51. ---
  52. ## Commands
  53. ### Check the whole setup
  54. **Run this first when anything misbehaves.** It reports Python, dependencies, Tor, the
  55. ControlPort, `.env`, the LLM provider, the observation store and engine health in one
  56. pass, and prints the command that fixes each problem.
  57. ```bash
  58. python3 {baseDir}/doctor.py # full report
  59. python3 {baseDir}/doctor.py --deep # also makes one live request through Tor
  60. python3 {baseDir}/doctor.py --json # machine-readable
  61. ```
  62. Exit code 0 means everything required is in place. Tor and the LLM key are optional:
  63. search, fetch, crawl and the clearnet collectors work without them.
  64. ---
  65. ### Check Tor is running
  66. **Always run this first** before any search or fetch.
  67. ```bash
  68. python3 {baseDir}/check_tor.py
  69. ```
  70. Output: exit IP address and `tor_active: true/false`. If tor_active is false, tell the user to start Tor and stop.
  71. ---
  72. ### Rotate Tor identity
  73. Get a fresh exit node and new identity. Use between investigation sessions or when you need a new IP.
  74. ```bash
  75. python3 {baseDir}/renew.py
  76. ```
  77. Output: `success: true/false`. If false, the user needs to ensure ControlPort 9051 is enabled and `TOR_DATA_DIR` is set in `.env`.
  78. ---
  79. ### Search the dark web
  80. Search all 17 dark web engines simultaneously. Returns deduplicated `{title, url, engine}` results.
  81. **Basic search:**
  82. ```bash
  83. python3 {baseDir}/search.py --query "SEARCH_TERM"
  84. ```
  85. **With result limit:**
  86. ```bash
  87. python3 {baseDir}/search.py --query "SEARCH_TERM" --max 30
  88. ```
  89. **Specific engines only:**
  90. ```bash
  91. python3 {baseDir}/search.py --query "SEARCH_TERM" --engines Ahmia Tor66 Ahmia-clearnet
  92. ```
  93. **Only engines known to be alive (recommended):**
  94. ```bash
  95. python3 {baseDir}/check_engines.py # refresh the health list
  96. python3 {baseDir}/search.py --query "SEARCH_TERM" --alive
  97. ```
  98. Dark web indexes go down constantly. Every dead engine costs the full `TOR_TIMEOUT`
  99. (45s by default), so a default all-engine search can block for minutes. Measured on a
  100. live Tor circuit with 11 of 17 engines up: `--alive` returned in **3 seconds**, the
  101. unscoped search did not finish within 280. Prefer `--alive` and tell the user how many
  102. engines answered.
  103. Available engines: Ahmia, OnionLand, Amnesia, Torland, Excavator, Onionway, Tor66, OSS, Torgol, TheDeepSearches, DuckDuckGo-Tor, Ahmia-clearnet
  104. **Tip:** Use short keyword queries (≤5 words). Dark web indexes respond better to focused keywords than natural-language questions.
  105. ---
  106. ### Fetch a .onion page
  107. Fetch the full content of any .onion URL or clearnet URL through Tor.
  108. ```bash
  109. python3 {baseDir}/fetch.py --url "http://SOME.onion/path"
  110. ```
  111. Output: title, text (first 3000 chars), link list, HTTP status. If status is 0 or error is set, the hidden service is unreachable.
  112. ---
  113. ### Check which search engines are alive
  114. Ping all 12 engines via Tor and get latency + status for each.
  115. ```bash
  116. python3 {baseDir}/check_engines.py
  117. ```
  118. Output: per-engine up/down status, latency in ms. Use this before a large search run to pass only alive engines to `--engines`.
  119. ---
  120. ### OSINT analysis
  121. Analyse scraped dark web content with an LLM. Produces a structured sectioned report.
  122. **From a string:**
  123. ```bash
  124. python3 {baseDir}/ask.py --query "INVESTIGATION_QUERY" --mode MODE --content "RAW_TEXT"
  125. ```
  126. **From a file:**
  127. ```bash
  128. python3 {baseDir}/ask.py --query "INVESTIGATION_QUERY" --mode MODE --file /path/to/content.txt
  129. ```
  130. **From stdin (pipe):**
  131. ```bash
  132. echo "CONTENT" | python3 {baseDir}/ask.py --query "QUERY" --mode MODE
  133. ```
  134. **Analysis modes:**
  135. | Mode | Use for |
  136. |---|---|
  137. | `threat_intel` | General OSINT (default) — artifacts, insights, next steps |
  138. | `ransomware` | Malware/C2/MITRE TTPs, victim orgs, indicators |
  139. | `personal_identity` | PII/breach exposure, severity, protective actions |
  140. | `corporate` | Leaked credentials/code/docs, IR recommendations |
  141. **With custom focus:**
  142. ```bash
  143. python3 {baseDir}/ask.py --query "QUERY" --mode threat_intel --custom "Focus on cryptocurrency wallet addresses"
  144. ```
  145. ---
  146. ### Full OSINT pipeline (one command)
  147. Runs the complete Robin pipeline: refine query → check live engines → search → filter best results → batch scrape → OSINT analysis.
  148. ```bash
  149. python3 {baseDir}/pipeline.py --query "INVESTIGATION_QUERY" --mode MODE
  150. ```
  151. **With more results:**
  152. ```bash
  153. python3 {baseDir}/pipeline.py --query "INVESTIGATION_QUERY" --mode ransomware --max 50 --scrape 10
  154. ```
  155. **Without an LLM key (raw results only):**
  156. ```bash
  157. python3 {baseDir}/pipeline.py --query "INVESTIGATION_QUERY" --no-llm
  158. ```
  159. **Options:**
  160. - `--query` — investigation topic (natural language OK — it gets refined automatically)
  161. - `--mode` — `threat_intel` (default), `ransomware`, `personal_identity`, `corporate`
  162. - `--max` — max raw results from search (default 30)
  163. - `--scrape` — how many pages to batch-fetch (default 8)
  164. - `--custom` — custom LLM instructions appended to the mode prompt
  165. - `--out FILE` — write final report to a file
  166. - `--no-llm` — skip refine/filter/ask steps; dump raw scraped content (no API key needed)
  167. ---
  168. ### Crawl one hidden service
  169. Follow links within a single .onion site and collect checksum-validated entities (BTC/ETH/XMR wallets, emails, .onion links, Tox IDs, PGP blocks). Pages in a level are fetched concurrently.
  170. ```bash
  171. python3 {baseDir}/crawl.py --url "http://example.onion" --depth 2 --max-pages 15
  172. python3 {baseDir}/crawl.py --url "http://example.onion" --json
  173. ```
  174. Abuse material is never crawled; every refusal is listed with its reason in the output.
  175. ---
  176. ### Monitor for changes (swarm)
  177. Read-only collectors run in parallel and report only what changed since the last sweep. State is kept in `{baseDir}/onionclaw.db`; the first run records a quiet baseline.
  178. ```bash
  179. python3 {baseDir}/swarm.py # one sweep → prioritised digest
  180. python3 {baseDir}/swarm.py --watch healthcare --watch US # flag matching events as PRIORITY
  181. python3 {baseDir}/swarm.py --wallet bc1q... # track a Bitcoin address on-chain
  182. python3 {baseDir}/swarm.py --onion http://xyz.onion # watch a hidden-service page (needs Tor)
  183. python3 {baseDir}/swarm.py --json # machine-readable digest
  184. ```
  185. Collectors: `leaksites` (ransomware.live victims), `groupinfra` (leak-site up/down), `kev` (CISA KEV, incl. CVEs newly tied to ransomware), `wallets` (mempool.space), `onionsites` (your URLs via Tor). Clearnet sources work without Tor.
  186. Alerts: `--webhook URL --webhook-format slack|discord|generic` (exactly-once per webhook, optional `--webhook-secret` HMAC signing).
  187. ---
  188. ### Export STIX 2.1 and correlate groups
  189. ```bash
  190. python3 {baseDir}/stix.py -o bundle.json # STIX 2.1 bundle for MISP / OpenCTI
  191. python3 {baseDir}/graph.py # groups linked by shared wallet / host / alias, with evidence
  192. python3 {baseDir}/graph.py --activity # groups ranked by time-decayed activity
  193. ```
  194. Correlation is a lead for an analyst, not attribution — present the evidence with every link.
  195. ---
  196. ### Prioritise groups and map their ATT&CK techniques
  197. ```bash
  198. python3 {baseDir}/risk.py # groups ranked by a transparent priority score
  199. python3 {baseDir}/risk.py --group qilin # every factor behind one group's score
  200. python3 {baseDir}/ttp.py --group medusa # MITRE ATT&CK techniques + tools for a group
  201. python3 {baseDir}/ttp.py --technique T1078 # which observed groups use a technique
  202. python3 {baseDir}/ttp.py # most-used techniques across observed groups
  203. ```
  204. ### List every observed indicator
  205. ```bash
  206. python3 {baseDir}/iocs.py # all indicators, most actionable first
  207. python3 {baseDir}/iocs.py --group qilin # indicators attributed to one group
  208. python3 {baseDir}/iocs.py --type btc_wallet --type cve
  209. python3 {baseDir}/iocs.py --flag ransomware # KEV CVEs tied to ransomware campaigns
  210. python3 {baseDir}/iocs.py --format csv -o iocs.csv # table | json | csv
  211. ```
  212. Types: `onion_host`, `domain`, `btc_wallet`, `cve`, `email`, `tox`. The list is derived from
  213. stored observations, so it never disagrees with them. Values are **defanged** by default
  214. (`hxxp://`, `[.]`) for safe sharing; pass `--fanged` for machine-readable output. Attribution
  215. comes from what a leak site published, not analysis — present it as a lead.
  216. ---
  217. `ttp.py` uses the ATT&CK data ransomware.live publishes per group (confidence "high") and adds whole-word keyword hits from ransom notes (confidence "low", each with the sentence it came from). `risk.py` scores volume, critical-sector victims, reach, capability and evidence links, then decays groups that have gone quiet. Present the score as a triage order, not a threat verdict, and show the factors.
  218. ---
  219. ## Typical investigation flows
  220. ### "Search the dark web for X"
  221. 1. `python3 {baseDir}/check_tor.py` — verify connected
  222. 2. `python3 {baseDir}/search.py --query "X"` — search all engines
  223. 3. `python3 {baseDir}/fetch.py --url "URL"` on 2-3 top results
  224. 4. `python3 {baseDir}/ask.py --mode threat_intel --query "X" --content "..."` on combined text
  225. ### "Has company.com been leaked on the dark web"
  226. 1. `python3 {baseDir}/check_tor.py`
  227. 2. `python3 {baseDir}/pipeline.py --query "company.com data leak credentials" --mode corporate`
  228. 3. Present the structured report to the user
  229. ### "Investigate ransomware group X"
  230. 1. `python3 {baseDir}/check_tor.py`
  231. 2. `python3 {baseDir}/pipeline.py --query "GROUP_NAME ransomware" --mode ransomware`
  232. ### "Watch for new ransomware victims in sector X"
  233. 1. `python3 {baseDir}/swarm.py --watch "X"` — the first run baselines; later runs report only changes
  234. 2. Present the PRIORITY events first, then the rest of the digest
  235. ### "Give me indicators for group X we can block"
  236. 1. `python3 {baseDir}/swarm.py` — refresh observations
  237. 2. `python3 {baseDir}/iocs.py --group X --fanged --format csv -o X.csv`
  238. 3. Note which rows are flagged `live`; say plainly that attribution is the leak site's claim
  239. ### "Which ransomware groups should we worry about right now?"
  240. 1. `python3 {baseDir}/swarm.py` — refresh observations
  241. 2. `python3 {baseDir}/risk.py` — ranked list; then `risk.py --group NAME` for the top ones
  242. 3. `python3 {baseDir}/ttp.py --group NAME` — the ATT&CK techniques to defend against
  243. ### "Fetch this .onion URL"
  244. 1. `python3 {baseDir}/check_tor.py`
  245. 2. `python3 {baseDir}/fetch.py --url "URL"`
  246. 3. Show the user the title + text content
  247. ---
  248. ## Important notes
  249. - All traffic routes through Tor — tell the user this when relevant.
  250. - .onion sites are frequently offline — if fetch returns `status: 0`, the site is temporarily down.
  251. - Dark web search indexes go down often — run `check_engines.py` first, then search with `--alive`. Each dead engine costs the full `TOR_TIMEOUT`, so this is the difference between seconds and minutes.
  252. - LLM tools (`ask`) require an API key in `{baseDir}/.env`. Search and fetch work without any key.
  253. - The swarm's collectors only read public data; never use OnionClaw to contact, negotiate with, or deceive anyone.
  254. - ransomware.live's free API is for personal use and allows 1 request/minute per endpoint; OnionClaw enforces the limit. Business use needs a PRO key (`RANSOMWARE_LIVE_API_KEY`).
  255. - Use responsibly and lawfully — OSINT, security research, and threat intelligence only.
  256. ---
  257. ## Maintenance
  258. ### sync_sicry.py — update bundled sicry.py from upstream
  259. `sync_sicry.py` fetches the latest (or a tagged) `sicry.py` from the upstream
  260. [SICRY™ GitHub repo](https://github.com/JacobJandon/Sicry) and overwrites the
  261. bundled copy inside OnionClaw. Run it after a new SICRY™ release is published.
  262. ### Checking for OnionClaw updates
  263. OnionClaw will **automatically notify you** whenever a newer release is
  264. available — a one-line message is printed at startup of `pipeline.py` if an
  265. update exists. You can also check on demand:
  266. ```bash
  267. # Quick CLI update check (prints latest version, release URL, upgrade command):
  268. python3 {baseDir}/pipeline.py --check-update
  269. # Programmatic check from any Python environment:
  270. import sicry
  271. r = sicry.check_update()
  272. if not r["up_to_date"]:
  273. print(f"Update: {r['current']} → {r['latest']} {r['url']}")
  274. ```
  275. Upgrade after a new release:
  276. ```bash
  277. git -C {baseDir} pull # update the whole repo
  278. python3 {baseDir}/sync_sicry.py # re-sync sicry.py from SICRY™
  279. ```
  280. The check is clearnet-only (not through Tor), uses a 4-second timeout, and
  281. is always silent on network errors.
  282. ```bash
  283. # Pull latest main branch:
  284. python3 {baseDir}/sync_sicry.py
  285. # Pull a specific release tag:
  286. python3 {baseDir}/sync_sicry.py --tag v1.2.0
  287. # Preview without writing (dry run):
  288. python3 {baseDir}/sync_sicry.py --dry-run
  289. ```
  290. **Development workflow** (when editing sicry.py locally):
  291. 1. Edit `OnionClaw/sicry.py`.
  292. 2. Copy to parent repo: `cp OnionClaw/sicry.py Sicry/sicry.py`
  293. 3. Commit + tag both repos, then push.
  294. 4. Once the tag is live on GitHub, users can run `sync_sicry.py --tag vX.Y.Z`
  295. to update their OnionClaw copy.
  296. Flags:
  297. - `--tag REF` — git ref or tag to fetch (default: `main`)
  298. - `--dry-run` — show what would happen without writing anything
README.md · README · 793 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OnionClaw 🧅
  2. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/JacobJandon/OnionClaw/blob/main/LICENSE)
  3. [![CI](https://github.com/JacobJandon/OnionClaw/actions/workflows/ci.yml/badge.svg)](https://github.com/JacobJandon/OnionClaw/actions/workflows/ci.yml)
  4. [![OpenClaw Skill](https://img.shields.io/badge/OpenClaw-skill-blueviolet)](https://github.com/JacobJandon/OnionClaw)
  5. **by JacobJandon**
  6. <p align="center">
  7. <img src="OnionClaw-logo.png" alt="OnionClaw logo" width="200"/>
  8. </p>
  9. > **OpenClaw skill + standalone tool** — full Tor / dark web access for AI agents
  10. OnionClaw gives AI agents full access to the Tor network and .onion hidden services. It runs as an [OpenClaw](https://github.com/openclaw/openclaw) skill (drop-in, zero config beyond a `.env` file) and also works standalone from any terminal.
  11. Based on the [SICRY](https://github.com/JacobJandon/Sicry) engine — 17 dark web search engines, Robin OSINT pipeline, four LLM analysis modes.
  12. ```bash
  13. # As an OpenClaw skill:
  14. cp -r OnionClaw ~/.openclaw/skills/onionclaw
  15. # → agent now has 7 dark web commands available in every session
  16. # Standalone:
  17. python3 doctor.py # check the whole setup, and what to fix
  18. python3 check_tor.py # verify Tor
  19. python3 check_engines.py && python3 search.py --query "ransomware healthcare" --alive
  20. python3 pipeline.py --query "acme.com data leak" --mode corporate
  21. ```
  22. ---
  23. ## ⚠️ The Rabbit Hole
  24. > *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.*
  25. 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.
  26. This is not a warning tucked in fine print. It is the whole point of writing it down openly.
  27. ### What the stack enables — the full map
  28. | Use case | What it looks like |
  29. |---|---|
  30. | **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. |
  31. | **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. |
  32. | **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. |
  33. | **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. |
  34. | **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. |
  35. | **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. |
  36. | **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. |
  37. | **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. |
  38. ### The ugly side
  39. The 2026 internet is already at the edge of this. Within five years, AI agents that can:
  40. 1. **Browse anonymously** through rotating Tor circuits with no persistent identity
  41. 2. **Understand context** well enough to navigate dark web UIs, CAPTCHA logic, and forum culture without hardcoded selectors
  42. 3. **Act autonomously** — search, buy, post, exfiltrate, rotate — in closed loops with no human confirmation step
  43. 4. **Self-orchestrate** across dozens of simultaneous Tor identities on parallel threads
  44. …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.
  45. 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.
  46. ### Why this is written explicitly
  47. 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:
  48. - **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.
  49. - **Know your jurisdiction.** Automated access to dark web content and `.onion` services may be illegal in your country regardless of intent or findings.
  50. - **Tor is not legal protection.** It is operational security. The two are different things with very different limits.
  51. - **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.
  52. 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.
  53. ---
  54. ## Contents
  55. 1. [⚠️ The Rabbit Hole](#️-the-rabbit-hole)
  56. 2. [What OnionClaw does](#what-onionclaw-does)
  57. 3. [Requirements](#requirements)
  58. 4. [Install as OpenClaw skill](#install-as-openclaw-skill)
  59. 5. [Standalone install](#standalone-install)
  60. 6. [Configuration](#configuration)
  61. 7. [All seven commands](#all-seven-commands)
  62. 8. [Investigation flows](#investigation-flows)
  63. 9. [Analysis modes](#analysis-modes)
  64. 10. [Architecture](#architecture)
  65. 11. [Troubleshooting](#troubleshooting)
  66. 12. [Credits](#credits)
  67. ---
  68. ## What OnionClaw does
  69. Seven commands expose the complete Tor OSINT toolkit:
  70. | Command | What it does |
  71. |---|---|
  72. | `check_tor.py` | Verify Tor is active, show current exit IP |
  73. | `renew.py` | Rotate Tor circuit — new exit node, new identity |
  74. | `check_engines.py` | Ping all 17 dark web search engines, show latency |
  75. | `search.py` | Search up to 17 engines simultaneously, deduplicated results |
  76. | `fetch.py` | Fetch any `.onion` or clearnet URL through Tor |
  77. | `ask.py` | LLM OSINT analysis of scraped content (4 modes) |
  78. | `pipeline.py` | Full Robin pipeline: refine → search → filter → scrape → analyse |
  79. ---
  80. ## Requirements
  81. - **Python 3.10+**
  82. - **Tor** running locally (SOCKS proxy on `127.0.0.1:9050`)
  83. - **pip packages**: `requests[socks] beautifulsoup4 python-dotenv stem`
  84. - **LLM key** (optional — only needed for `ask.py` and `pipeline.py` analysis step)
  85. ### Install Tor
  86. **Linux (Debian/Ubuntu):**
  87. ```bash
  88. apt install tor && tor &
  89. ```
  90. **macOS:**
  91. ```bash
  92. brew install tor && tor &
  93. ```
  94. **With control port (needed for `renew.py`):**
  95. ```bash
  96. cat > /tmp/onionclaw_tor.conf << 'EOF'
  97. SocksPort 9050
  98. ControlPort 9051
  99. CookieAuthentication 1
  100. DataDirectory /tmp/tor_data
  101. EOF
  102. tor -f /tmp/onionclaw_tor.conf &
  103. ```
  104. Then set `TOR_DATA_DIR=/tmp/tor_data` in `.env`.
  105. ### Install Python packages
  106. ```bash
  107. pip install requests[socks] beautifulsoup4 python-dotenv stem
  108. ```
  109. ---
  110. ## Install as OpenClaw skill
  111. 1. **Clone or copy** this repo into your OpenClaw skills directory:
  112. ```bash
  113. # Option A — clone directly
  114. git clone https://github.com/JacobJandon/OnionClaw ~/.openclaw/skills/onionclaw
  115. # Option B — copy local folder
  116. cp -r OnionClaw ~/.openclaw/skills/onionclaw
  117. ```
  118. 2. **Configure** `.env` in the skill folder:
  119. ```bash
  120. cp ~/.openclaw/skills/onionclaw/.env.example ~/.openclaw/skills/onionclaw/.env
  121. nano ~/.openclaw/skills/onionclaw/.env # add LLM key if desired
  122. ```
  123. 3. **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.
  124. **Verify OpenClaw can see the skill:**
  125. ```bash
  126. openclaw skills list
  127. # → onionclaw 🧅 Search the Tor dark web...
  128. ```
  129. **OpenClaw trigger phrases:**
  130. - "search the dark web for …"
  131. - "investigate this .onion site …"
  132. - "check if my data appeared on the dark web"
  133. - "find ransomware leaks related to …"
  134. - "fetch this .onion URL …"
  135. - "run a Tor OSINT investigation on …"
  136. > After install, start a **new session** — existing sessions will not pick up the new skill.
  137. ---
  138. ## Standalone install
  139. No OpenClaw required. Every script runs directly from a terminal:
  140. ```bash
  141. git clone https://github.com/JacobJandon/OnionClaw
  142. cd OnionClaw
  143. pip install requests[socks] beautifulsoup4 python-dotenv stem
  144. cp .env.example .env
  145. # Edit .env — add LLM key if desired (optional for most commands)
  146. ```
  147. ---
  148. ## Configuration
  149. Copy `.env.example` to `.env` and fill in what you need:
  150. ```dotenv
  151. # ── Tor ────────────────────────────────────────────────────────────────
  152. TOR_SOCKS_HOST=127.0.0.1
  153. TOR_SOCKS_PORT=9050
  154. TOR_CONTROL_HOST=127.0.0.1
  155. TOR_CONTROL_PORT=9051
  156. # TOR_CONTROL_PASSWORD=your_password # only if HashedControlPassword in torrc
  157. # TOR_DATA_DIR=/tmp/tor_data # DataDirectory path for cookie auth
  158. # ── LLM (needed only for ask.py and pipeline.py analysis step) ──────────
  159. LLM_PROVIDER=openai # openai | anthropic | gemini | ollama | llamacpp
  160. OPENAI_API_KEY=sk-...
  161. # ANTHROPIC_API_KEY=sk-ant-...
  162. # GEMINI_API_KEY=AIza...
  163. # OLLAMA_MODEL=llama3.2 # local model — no API key needed
  164. ```
  165. > **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.
  166. ---
  167. ## All seven commands
  168. ### `check_tor.py` — verify Tor
  169. ```bash
  170. python3 check_tor.py
  171. ```
  172. ```
  173. ✓ Tor active
  174. Exit IP : 185.220.101.20
  175. Error : None
  176. {"tor_active": true, "exit_ip": "185.220.101.20", "error": null}
  177. ```
  178. Run this before anything else. Exits with code 1 if Tor is not running or not accessible on port 9050.
  179. ---
  180. ### `renew.py` — rotate identity
  181. ```bash
  182. python3 renew.py
  183. ```
  184. ```
  185. Rotating Tor circuit...
  186. ✓ Identity renewed — new Tor circuit established
  187. {"success": true, "error": null}
  188. ```
  189. 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.
  190. ---
  191. ### `check_engines.py` — engine health check
  192. ```bash
  193. # Live ping (15–30 s)
  194. python3 check_engines.py
  195. # --cached N: reuse last result if less than N minutes old (skips the slow ping)
  196. python3 check_engines.py --cached 10
  197. # JSON output only
  198. python3 check_engines.py --json
  199. # Show version
  200. python3 check_engines.py --version
  201. ```
  202. ```
  203. ALIVE 9/12
  204. ──────────────────────────────────────────
  205. ✓ Ahmia-clearnet 670ms ███
  206. ✓ Tor66 749ms ███
  207. ✓ Ahmia 1139ms █████
  208. ✓ OSS 1203ms ██████
  209. ...
  210. DOWN 3/12
  211. ✗ Kaizer timeout
  212. ✗ Anima timeout
  213. ✗ FindTor timeout
  214. ```
  215. Run before a large search session. Use the alive engine names as arguments to `--engines` in `search.py`.
  216. ---
  217. ### `search.py` — search dark web
  218. ```bash
  219. # All 17 engines (default)
  220. python3 search.py --query "ransomware healthcare leak"
  221. # Specific engines (faster — use alive engines from check_engines output)
  222. python3 search.py \
  223. --query "credential dump" \
  224. --engines Ahmia Tor66 Ahmia-clearnet OSS
  225. # Limit result count
  226. python3 search.py --query "bitcoin mixer" --max 30
  227. ```
  228. Returns a deduplicated `{title, url, engine}` list across all engines.
  229. **Tip:** Use short keyword queries (3–5 words). Dark web search indexes respond much better to keywords than natural-language sentences.
  230. ---
  231. ### `fetch.py` — fetch any .onion page
  232. ```bash
  233. # Hidden service
  234. python3 fetch.py \
  235. --url "http://juhanurmihxlp77nkq76byazcldy2hlmovfu2epvl5ankdibsot4csyd.onion"
  236. # With links extracted
  237. python3 fetch.py --url "http://example.onion/page" --links
  238. # JSON output only
  239. python3 fetch.py --url "http://example.onion" --json
  240. ```
  241. 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.
  242. ---
  243. ### `ask.py` — LLM OSINT analysis
  244. ```bash
  245. # Inline content
  246. python3 ask.py \
  247. --query "LockBit ransomware" \
  248. --mode ransomware \
  249. --content "page text from scraped pages"
  250. # From file
  251. python3 ask.py \
  252. --query "acme.com" \
  253. --mode corporate \
  254. --file /tmp/scraped_pages.txt
  255. # Pipe from fetch.py
  256. python3 fetch.py --url "http://some.onion" --json | \
  257. python3 -c "import sys,json; print(json.load(sys.stdin)['text'])" | \
  258. python3 ask.py --query "investigate" --mode threat_intel
  259. # Custom analysis focus
  260. python3 ask.py \
  261. --query "mixer services" \
  262. --mode threat_intel \
  263. --content "..." \
  264. --custom "Focus on cryptocurrency wallet addresses only"
  265. ```
  266. **Modes:** `threat_intel` · `ransomware` · `personal_identity` · `corporate` — see [Analysis modes](#analysis-modes).
  267. ---
  268. ### `pipeline.py` — full investigation (one command)
  269. Runs the complete Robin OSINT pipeline automatically:
  270. | Step | What happens |
  271. |---|---|
  272. | 1 | Verify Tor is active |
  273. | 2 | Check which engines are alive |
  274. | 3 | Refine query to ≤5 keywords (LLM) |
  275. | 4 | Search all alive engines |
  276. | 5 | Filter top 20 most relevant results (LLM) |
  277. | 6 | Batch-scrape pages concurrently |
  278. | 7 | OSINT analysis and report (LLM) |
  279. ```bash
  280. # Basic
  281. python3 pipeline.py --query "hospital ransomware 2026"
  282. # With analysis mode and output file
  283. python3 pipeline.py \
  284. --query "acme.com credentials leak" \
  285. --mode corporate \
  286. --out report.md
  287. # Full options
  288. python3 pipeline.py \
  289. --query "QUERY" \
  290. --mode ransomware \
  291. --max 50 \
  292. --scrape 12 \
  293. --custom "Focus on ransom amounts and victim industries" \
  294. --out report.md
  295. ```
  296. **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.
  297. ```bash
  298. # --clear-cache: discard cached fetch results before this run
  299. python3 pipeline.py --query "fresh data" --clear-cache
  300. # --version: print OnionClaw version
  301. python3 pipeline.py --version
  302. ```
  303. ---
  304. ### `sync_sicry.py` — update bundled SICRY engine
  305. OnionClaw bundles a copy of `sicry.py` from the upstream [SICRY™](https://github.com/JacobJandon/Sicry) repo.
  306. `sync_sicry.py` lets you pull the latest version (or a specific release tag) without a full `git pull`.
  307. ```bash
  308. # Fetch latest from main branch
  309. python3 sync_sicry.py
  310. # Fetch a specific release tag
  311. python3 sync_sicry.py --tag v1.2.0
  312. # Preview what would happen without writing
  313. python3 sync_sicry.py --dry-run
  314. # Show version
  315. python3 sync_sicry.py --version
  316. ```
  317. After syncing, commit the updated file:
  318. ```bash
  319. git add sicry.py && git commit -m "chore: sync sicry.py to SICRY v1.2.0"
  320. ```
  321. > **Update notices** — `pipeline.py` (and `sicry.check_update()`) checks the
  322. > GitHub **Releases API** (`/releases/latest`). Only published formal releases
  323. > trigger a notice — plain git tags and pre-releases are silently ignored.
  324. ---
  325. ## Monitoring swarm (v2.4)
  326. Everything above answers *"what is on this page?"*. The swarm answers *"what changed since I last looked?"* —
  327. continuously, persistently, and read-only.
  328. ```bash
  329. python3 swarm.py # one sweep → prioritised digest
  330. python3 swarm.py --watch healthcare --watch US # flag matching events PRIORITY (whole-word match)
  331. python3 swarm.py --wallet bc1q... # always track an address on-chain
  332. python3 swarm.py --onion http://xyz.onion # monitor a hidden-service page (needs Tor)
  333. python3 swarm.py --loop 900 # sweep every 15 min
  334. python3 swarm.py --webhook https://hooks.slack.com/... --webhook-format slack
  335. python3 stix.py -o bundle.json # STIX 2.1 export (MISP / OpenCTI)
  336. python3 graph.py # evidence-based group correlation
  337. python3 graph.py --activity # time-decayed group activity ranking
  338. python3 risk.py # groups ranked by transparent priority score
  339. python3 ttp.py --group medusa # MITRE ATT&CK techniques + tools per group
  340. python3 iocs.py --group qilin --format csv # every observed indicator, defanged by default
  341. python3 crawl.py --url http://xyz.onion --depth 2 # concurrent single-site crawl
  342. ```
  343. | Collector | Source | Detects |
  344. |---|---|---|
  345. | `leaksites` | ransomware.live | new victim disclosures; wallets in ransom notes |
  346. | `groupinfra` | ransomware.live | leak sites going up / down / moving; each group's ATT&CK techniques and tools (and when they change) |
  347. | `kev` | CISA KEV | new exploited CVEs, and CVEs **newly linked to ransomware** |
  348. | `wallets` | mempool.space | balance / tx movement on tracked ransom wallets |
  349. | `onionsites` | your URLs, via Tor | content change and new wallets / emails on a page |
  350. State lives in `onionclaw.db` (SQLite). The first run baselines silently; later runs report only changes.
  351. A failing source is reported and never stops the others.
  352. **Read-only by design.** Collectors only fetch public data. Nothing here contacts, negotiates with, or
  353. deceives a threat actor, and no feature is planned that would.
  354. **Alerts** (`--webhook`): `KEV_RANSOMWARE`, `WALLET_MOVEMENT`, `WALLET_LINK`, `WATCHLIST_HIT` (HIGH);
  355. `CRITICAL_VICTIM`, `ONION_CHANGE` (MEDIUM); `INFRA_CHANGE` (LOW). Delivery is exactly-once per webhook,
  356. retried until the receiver answers 2xx, and `generic` payloads can be HMAC-signed (`--webhook-secret`).
  357. **Priority and ATT&CK.** `risk.py` ranks groups by observed volume, critical-sector victims, reach,
  358. capability (published ATT&CK techniques, tools, live leak-site hosts) and evidence links, then decays
  359. groups that have gone quiet. Every score lists the numbers behind it; it is a triage order, not a verdict.
  360. `ttp.py` maps groups to MITRE ATT&CK from the data ransomware.live publishes, and STIX exports include
  361. `attack-pattern` and `tool` objects linked to each group by `uses` relationships.
  362. **Indicators.** `iocs.py` is one queryable view of every indicator the swarm has observed
  363. (onion hosts, clearnet domains, ransom-note wallets, KEV CVEs, contact addresses), derived from
  364. the stored observations rather than a second copy, with first/last seen, attribution and source
  365. for each. Values are defanged by default so they can be pasted into a ticket safely.
  366. **Correlation is a lead, not attribution.** `graph.py` links groups only through hard identifiers (shared
  367. wallet, shared leak-site host, normalised alias, shared victim) and shows the evidence for every edge.
  368. A host shared by three or more groups is weighted low, since that usually means a shared platform.
  369. ### ⚠ ransomware.live terms
  370. The free v2 API is limited to **personal use** (not corporate/business), **1 request/minute/endpoint**,
  371. and returns victims delayed versus PRO. OnionClaw enforces the rate limit across processes and tells you
  372. when it is on the free tier. For business use, get a PRO key and set `RANSOMWARE_LIVE_API_KEY`,
  373. `RANSOMWARE_LIVE_BASE`, and `RANSOMWARE_LIVE_KEY_HEADER`. *The PRO auth header name and paths could not be
  374. verified from public documentation — the `X-API-KEY` default is unconfirmed; check the PRO docs.*
  375. ### Known limits
  376. - `.onion` fetching (`onionsites`, `crawl.py`) needs Tor; the test suite covers that logic against a local
  377. server but does not exercise the Tor transport.
  378. - STIX 2.1 has no standard cryptocurrency-wallet observable; wallets use a custom
  379. `x-cryptocurrency-wallet` pattern that generic consumers will not match.
  380. - ransom-note wallet harvesting depends on what the tracker publishes; many victims carry none.
  381. ## Website
  382. The project site lives in `web/` (Vite + three.js, all versions pinned):
  383. ```bash
  384. cd web
  385. npm install
  386. npm run dev # http://127.0.0.1:5173 — live reload
  387. npm run build # static site in web/dist/, deploy anywhere
  388. npm run preview # serve the built site at http://127.0.0.1:4173
  389. ```
  390. - `/` — **Peel**: scroll through the three Tor encryption layers of a glass onion down to the swarm core.
  391. - `/hybrid/` — **Hybrid**: a toon "onion planet" whose stations are the tools; orbit it chapter by
  392. chapter, then explore it freely.
  393. - Add `?static` for a readable version without WebGL (used automatically with reduced motion).
  394. ## Investigation flows
  395. ### Scenario 1: Check for leaked credentials
  396. ```bash
  397. python3 check_tor.py
  398. python3 pipeline.py \
  399. --query "acme.com email passwords" \
  400. --mode corporate \
  401. --scrape 10 \
  402. --out acme_leak_report.md
  403. ```
  404. ### Scenario 2: Ransomware intelligence
  405. ```bash
  406. python3 check_tor.py
  407. python3 search.py \
  408. --query "LockBit healthcare 2026" \
  409. --engines Ahmia Tor66 Ahmia-clearnet \
  410. --max 40
  411. # Fetch the most relevant URL
  412. python3 fetch.py --url "http://..." > /tmp/page.json
  413. # Analyse
  414. python3 ask.py \
  415. --query "LockBit healthcare 2026" \
  416. --mode ransomware \
  417. --file /tmp/page.json
  418. ```
  419. ### Scenario 3: Personal data exposure check
  420. ```bash
  421. python3 pipeline.py \
  422. --query "john.smith@email.com personal data" \
  423. --mode personal_identity \
  424. --scrape 8
  425. ```
  426. ### Scenario 4: Manual step-by-step investigation
  427. ```bash
  428. # 1. Verify Tor
  429. python3 check_tor.py
  430. # 2. Find alive engines
  431. python3 check_engines.py
  432. # 3. Search with alive engines
  433. python3 search.py \
  434. --query "ransomware hospital 2026" \
  435. --engines Ahmia Tor66 OSS \
  436. --max 40
  437. # 4. Fetch top pages
  438. python3 fetch.py --url "http://..." --links
  439. python3 fetch.py --url "http://..."
  440. # 5. Analyse
  441. python3 ask.py \
  442. --query "hospital ransomware" \
  443. --mode ransomware \
  444. --content "combined text from pages"
  445. # 6. Rotate identity when done
  446. python3 renew.py
  447. ```
  448. ---
  449. ## Analysis modes
  450. ### `threat_intel` (default)
  451. General dark web OSINT. Extracts: IoCs, infrastructure details, actor mentions, next investigation steps.
  452. Output sections: Input Query · Source Links · Investigation Artifacts · Key Insights · Recommended Next Steps
  453. ### `ransomware`
  454. Malware/RaaS intelligence. Extracts C2 domains, file hashes, MITRE ATT&CK TTPs, victim sectors, ransom amounts.
  455. Output sections: Input Query · Source Links · Malware/Ransomware Indicators · Threat Actor Profile · Key Insights · Recommended Next Steps
  456. ### `personal_identity`
  457. PII and breach exposure. Surfaces SSNs, emails, passwords, passport data, breach sources, risk severity ratings.
  458. Output sections: Input Query · Source Links · Exposed PII Artifacts · Breach/Marketplace Sources · Exposure Risk Assessment · Key Insights · Recommended Next Steps
  459. ### `corporate`
  460. Corporate threat intelligence. Detects leaked credentials, source code, internal documents, initial access broker activity.
  461. Output sections: Input Query · Source Links · Leaked Corporate Artifacts · Threat Actor/Broker Activity · Business Impact Assessment · Key Insights · Recommended Next Steps
  462. ---
  463. ## Troubleshooting
  464. **`✗ Tor NOT active`**
  465. ```bash
  466. # Is Tor running?
  467. pgrep tor || tor &
  468. # Is port 9050 listening?
  469. ss -tlnp | grep 9050
  470. ```
  471. **`renew.py` → `success: false`**
  472. ```bash
  473. # Is control port open?
  474. ss -tlnp | grep 9051
  475. # Enable it in torrc:
  476. echo "ControlPort 9051" >> /etc/tor/torrc
  477. echo "CookieAuthentication 1" >> /etc/tor/torrc
  478. systemctl restart tor
  479. # Set correct DataDirectory in .env:
  480. TOR_DATA_DIR=/var/lib/tor # system Tor (Debian/Ubuntu)
  481. TOR_DATA_DIR=/tmp/tor_data # custom torrc DataDirectory
  482. ```
  483. **`fetch.py` → `status: 0`**
  484. The hidden service is offline. .onion sites go down frequently — try a different URL from `search.py` results. Confirm Tor is healthy with `check_tor.py`.
  485. **`search.py` returns 0 results**
  486. Dark web indexes fluctuate. Run `check_engines.py` to find alive engines, then use `--engines Ahmia Ahmia-clearnet` as reliable fallbacks.
  487. **`ask.py` / `pipeline.py` LLM error**
  488. Set `LLM_PROVIDER` and an API key in `.env`. For no-key local operation: `LLM_PROVIDER=ollama` with a running Ollama instance. All five non-LLM scripts (`check_tor`, `renew`, `check_engines`, `search`, `fetch`) work without any key.
  489. **`ERROR: sicry.py not found`**
  490. `sicry.py` must be in the OnionClaw root (same folder as `SKILL.md`). It is included in this repo — do not delete or move it. If you cloned and it is missing, re-clone fresh.
  491. ---
  492. ## Architecture
  493. How OnionClaw’s pieces fit together — from a command-line invocation all the way to a `.onion` response.
  494. ### Layer diagram
  495. ```
  496. ┌──────────────────────────────────────────────────────────────┐
  497. │ User / OpenClaw Agent / CI script │
  498. │ python3 pipeline.py --query … | pipeline.py --daemon-poll │
  499. └───────────────────────────┬───────────────────────────────┘
  500. │
  501. Python wrappers ▼
  502. ┌──────────────────────────────────────────────────────────────┐
  503. │ OnionClaw command layer │
  504. │ │
  505. │ check_tor.py renew.py fetch.py search.py ask.py │
  506. │ check_engines.py pipeline.py sync_sicry.py │
  507. │ │
  508. │ All call into ↓ one file │
  509. └────────────────────────────┬──────────────────────────────────┘
  510. │
  511. ▼
  512. ┌──────────────────────────────────────────────────────────────┐
  513. │ SICRY™ (sicry.py — bundled) │
  514. │ │
  515. │ check_tor() search(query, engines, …) │
  516. │ renew_identity() scrape_all(urls) │
  517. │ fetch(url) ask(content, mode, …) │
  518. │ check_search_engines() refine_query() filter_results() │
  519. │ │
  520. │ State: SQLite DB (watch jobs · engine stats · result cache) │
  521. └─────┬──────────────────────────┬──────────────────────────────┘
  522. │ SOCKS5 │ stem control
  523. │ 127.0.0.1:9050 │ 127.0.0.1:9051
  524. ▼ ▼
  525. ┌───────────────────┐ ┌───────────────────┐
  526. │ Tor (tor / TorPool) │ │ Tor Control Port │
  527. │ SOCKS5 proxy │◄─│ renew_identity() │
  528. └─────┬─────────────┘ └───────────────────┘
  529. │ onion routing (3 hops)
  530. ▼
  531. ┌──────────────────────────────────────────────────────────────┐
  532. │ Dark Web / Tor Network │
  533. │ │
  534. │ 17 search engines (.onion) Clearnet via Tor exit nodes │
  535. │ Ahmia · DuckDuckGo-Tor Any HTTPS/HTTP URL │
  536. │ Tor66 · + 15 more… │
  537. └──────────────────────────────────────────────────────────────┘
  538. ```
  539. ### pipeline.py flow
  540. ```
  541. --query / watch job
  542. │
  543. ▼
  544. [1] check_tor() → abort if not active
  545. [2] check_search_engines() → collect live engine list
  546. [3] refine_query() → LLM: natural language → ≤5 keywords
  547. [4] search(engines=live) → parallel queries over Tor
  548. [5] filter_results() → LLM: keep top 20 relevant
  549. [6] scrape_all(best[:N]) → concurrent batch-fetch over Tor
  550. [7] ask(content, mode=…) → LLM OSINT report
  551. │
  552. ▼
  553. report [→ --out file.md] [→ --watch-check --output-dir]
  554. ```
  555. ### TorPool mode (optional)
  556. Set `SICRY_POOL_SIZE=N` (recommended 2–4) to run N independent Tor processes
  557. for higher search throughput:
  558. ```
  559. pipeline.py ─→ TorPool
  560. ├── tor[0] :9050
  561. ├── tor[1] :9052
  562. └── tor[N-1]:...
  563. ```
  564. ### Update policy
  565. `pipeline.py --check-update` calls `sicry.check_update()`, which queries the
  566. GitHub **Releases API** (`/releases/latest`). Only **published formal releases**
  567. trigger a notice — plain git tags and pre-releases are silently ignored.
  568. ---
  569. ## File structure
  570. ```
  571. OnionClaw/
  572. ├── SKILL.md ← OpenClaw skill descriptor (YAML frontmatter)
  573. ├── sicry.py ← SICRY engine (bundled — no separate install needed)
  574. ├── .env.example ← Copy to .env and configure
  575. ├── README.md ← This file
  576. ├── check_tor.py ← Verify Tor / show exit IP
  577. ├── renew.py ← Rotate Tor circuit
  578. ├── check_engines.py ← Ping all 17 engines
  579. ├── search.py ← Search dark web
  580. ├── fetch.py ← Fetch .onion pages
  581. ├── ask.py ← OSINT analysis via LLM
  582. ├── pipeline.py ← Full Robin investigation pipeline
  583. └── sync_sicry.py ← Sync SICRY engine from upstream
  584. ```
  585. ---
  586. ## Credits
  587. - Dark web search engine list and Robin OSINT pipeline from [Robin](https://github.com/apurvsinghgautam/robin) by [@apurvsinghgautam](https://github.com/apurvsinghgautam) — MIT licence
  588. - Core engine: [SICRY](https://github.com/JacobJandon/Sicry)
  589. - .onion address verification via [dark.fail](https://dark.fail)
  590. - Agent runtime: [OpenClaw](https://github.com/openclaw/openclaw)
  591. - Network anonymisation: [Tor Project](https://www.torproject.org/)
  592. ---
  593. ## License
  594. Apache License 2.0 — Copyright (c) 2026 JacobJandon
  595. "OnionClaw" and the OnionClaw logo are owned by JacobJandon.
  596. See [LICENSE](LICENSE) for full text.
  597. ---
  598. > ⚠️ **Use responsibly and lawfully.** Built for OSINT, security research, and threat intelligence. Read [The Rabbit Hole](#️-the-rabbit-hole) section before deploying autonomously.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.