Metadata-Version: 2.4
Name: chopped-onions
Version: 0.1.0
Summary: An interactive TUI to search the Tor network for .onion links by keyword.
Project-URL: Homepage, https://github.com/Thatkidtk/chopped-onions
Project-URL: Repository, https://github.com/Thatkidtk/chopped-onions
Project-URL: Issues, https://github.com/Thatkidtk/chopped-onions/issues
Author: Thatkidtk
License-Expression: MIT
License-File: LICENSE
Keywords: anonymity,darkweb,onion,osint,privacy,search,terminal,textual,tor,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Security
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: pyperclip>=1.8
Requires-Dist: textual>=0.80
Description-Content-Type: text/markdown

<div align="center">

# 🧅 chopped onions

### Search the Tor network for `.onion` links — right from your terminal.

A fast, colorful **TUI** that scrapes multiple onion search engines **in parallel over Tor**, ranks the results against your query, and copies any link to your clipboard with a single keypress. Privacy-first by design: every request is forced through Tor, with a fresh circuit per search.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![Built with Textual](https://img.shields.io/badge/built%20with-Textual-5a4fcf.svg)](https://textual.textualize.io/)
[![Powered by Tor](https://img.shields.io/badge/powered%20by-Tor-7e4798.svg)](https://www.torproject.org/)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Thatkidtk/chopped-onions/pulls)

<img src="assets/screenshot.svg" alt="chopped onions in action" width="800">

</div>

---

## ✨ Features

- 🔎 **Parallel onion search** — queries Torch, Tordex, Tor66 and OnionLand Search at once, then merges, de-duplicates and ranks the hits.
- 🧅 **100% over Tor** — fail-closed networking: if traffic can't be routed through Tor, it **refuses to run** rather than leaking to the clearnet.
- 🔁 **Fresh circuit per search** — stream isolation gives each search its own unlinkable Tor circuit.
- 🕵️ **Anti-fingerprinting** — sends stock Tor-Browser-style headers, no cookies, no Referer, nothing identifying.
- ⌨️ **Keyboard-driven** — type, hit Enter, arrow up/down to pick, Enter to copy the address to your clipboard.
- 🧠 **Smart query syntax** — `AND`, `OR`, `"exact phrases"` and `-exclusions`.
- 🎨 **5 themes** — `onion`, `matrix`, `amber`, `synthwave`, `ice`.
- ⚙️ **Configurable** — proxy, timeouts, engines, colors, clipboard behavior, all in one TOML file.
- 🛡️ **Built-in safety self-test** — `chopped-onions --check` confirms you're actually exiting through Tor.

## 🎨 Themes

| `synthwave` | `matrix` |
|:---:|:---:|
| <img src="assets/theme-synthwave.svg" width="400"> | <img src="assets/theme-matrix.svg" width="400"> |

---

## 📦 Installation

> **Prerequisite:** you need **Tor** running locally with a SOCKS proxy on `127.0.0.1:9050`. See [Setting up Tor](#-setting-up-tor) below.

### Option 1 — pipx (recommended)

[pipx](https://pipx.pypa.io/) installs the app into its own isolated environment and puts the command on your PATH:

```bash
pipx install git+https://github.com/Thatkidtk/chopped-onions
chopped-onions
```

### Option 2 — pip

```bash
pip install git+https://github.com/Thatkidtk/chopped-onions
chopped-onions
```

### Option 3 — from source

```bash
git clone https://github.com/Thatkidtk/chopped-onions
cd chopped-onions
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/chopped-onions
```

Or just run the bundled launcher, which will start Tor for you if it isn't already up:

```bash
./onions
```

---

## 🧅 Setting up Tor

`chopped onions` talks to Tor's SOCKS proxy — it does **not** ship or embed Tor itself.

**macOS (Homebrew)**
```bash
brew install tor
brew services start tor          # runs Tor in the background on 127.0.0.1:9050
```

**Debian / Ubuntu**
```bash
sudo apt install tor
sudo systemctl enable --now tor
```

**Arch**
```bash
sudo pacman -S tor
sudo systemctl enable --now tor
```

**Already have Tor Browser?** It exposes a SOCKS proxy on port **9150** while open. Set `port = 9150` in your config and you're good to go.

Verify everything is wired up correctly:
```bash
chopped-onions --check
# ✓ Tor OK — exit node 185.220.101.25
```

---

## 🚀 Usage

Launch the app, type a query, press **Enter**:

```bash
chopped-onions
```

| Key | Action |
|---|---|
| type + <kbd>Enter</kbd> | run the search |
| <kbd>↓</kbd> *(in search bar)* | jump into the results list |
| <kbd>↑</kbd> / <kbd>↓</kbd> | move the selection |
| <kbd>Enter</kbd> *(on a result)* | **copy the .onion link to clipboard** |
| <kbd>Ctrl</kbd>+<kbd>O</kbd> | open the selected link in a browser *(if configured)* |
| <kbd>Esc</kbd> | return to the search bar |
| <kbd>Ctrl</kbd>+<kbd>L</kbd> | clear |
| <kbd>Ctrl</kbd>+<kbd>R</kbd> | re-check the Tor connection |
| <kbd>Ctrl</kbd>+<kbd>C</kbd> | quit |

### Search syntax

Mix these freely. The cleaned words are sent to the engines; the operators filter and rank the results locally:

| Pattern | Meaning |
|---|---|
| `email privacy` | **AND** — both words boost a result |
| `"secure email"` | exact **phrase** (required) |
| `email OR mail` | **either** (also `email\|mail`) |
| `market -scam` | **exclude** results containing `scam` |

**Example:** `"secure email" privacy OR anonymity -scam`

---

## 🛡️ Staying safe & anonymous

`chopped onions` is built to be safe by default, but **anonymity is a practice, not a checkbox.** Read this.

### What the tool does for you

- **Fail-closed routing.** Every request goes through the Tor SOCKS proxy using `socks5h` (remote DNS), so `.onion` names — and *all* lookups — are resolved by Tor, never your local resolver. If the proxy is missing or misconfigured, the app **refuses to make the request** instead of silently falling back to a direct, deanonymizing connection.
- **Per-search circuit isolation.** Each search uses random SOCKS credentials, so Tor builds a **fresh, unlinkable circuit** every time. One search can't be trivially correlated with the next.
- **A low-information fingerprint.** Requests carry stock Tor-Browser-style headers. No cookies are stored, no `Referer` is sent, no custom headers identify you, and `$HTTP_PROXY`/system proxy env vars are ignored so routing is exactly what you configured.
- **No history on disk.** Your queries and results are never written to a log or history file. The only file the app writes is the config you control.

### What *you* are responsible for

> 🔒 Tor hides **where** you connect from. It does **not** make you anonymous if you give yourself away.

- **Browse `.onion` results in the Tor Browser, not a normal browser.** Copying a link is safe; opening it in Chrome/Safari is not — it leaks your real IP and a rich browser fingerprint. The clipboard-copy workflow exists precisely so you can paste into Tor Browser.
- **Never enter real personal info** (name, email, phone, reused passwords) on hidden services. Treat everything as hostile.
- **Don't log in to clearnet accounts over Tor** in a way that links your identity to your Tor activity.
- **Assume search results are untrusted.** Onion indexes contain spam, scams, phishing clones and worse. A result appearing here is **not** an endorsement — verify addresses out-of-band before trusting them.
- **Keep your system updated**, and prefer running from a privacy-focused OS like [Tails](https://tails.net/) or [Whonix](https://www.whonix.org/) if your threat model calls for it.
- **Mind your metadata.** Time-of-use patterns, writing style, and unique queries can all be de-anonymizing over time.
- **Consider a bridge** (`obfs4`) if simply *connecting to Tor* is sensitive where you are.

### Verify it's working

Before trusting it, run the self-test — it confirms your traffic is actually exiting through the Tor network:

```bash
chopped-onions --check
```

You can also press <kbd>Ctrl</kbd>+<kbd>R</kbd> inside the app at any time.

---

## ⚙️ Configuration

A documented config file is created on first run at `~/.config/chopped-onions/config.toml`:

```toml
theme = "onion"          # onion | matrix | amber | synthwave | ice

[tor]
host = "127.0.0.1"
port = 9050              # use 9150 for Tor Browser's proxy
timeout = 45
isolate_circuits = true  # fresh, unlinkable circuit per search (recommended)

[search]
max_results = 200
per_engine_limit = 100
dedupe = true

[behaviour]
copy = "url"             # "url" copies full link, "host" copies only the .onion host
open_command = ""        # e.g. "open -a 'Tor Browser' {url}" to also launch a browser
confirm_quit = false

[[engines]]              # add / disable / update engines here
name = "torch"
url = "http://torchdeedp3i2jigzjdmfpn5ttjhthh5wbmda2rr3jvqjg5p77c54dqd.onion/search?query={q}"
enabled = true
# … and tordex, tor66, onionland
```

> 💡 Onion addresses change over time. If an engine goes dark, update its address (or add your own) in the `[[engines]]` section — `{q}` is the URL-encoded query.

---

## ⚖️ Disclaimer

`chopped onions` is a research / OSINT / privacy tool. It only queries **public** onion search indexes — it does not crawl, host, or fetch content from the sites it lists, and indexing a link is not an endorsement of it. You are solely responsible for how you use it and for complying with the laws of your jurisdiction. Provided **as-is**, without warranty. See [`LICENSE`](LICENSE).

## 🤝 Contributing

Issues and PRs welcome — new engines, themes, parsers, and packaging improvements especially. Please keep the **fail-closed, Tor-only** safety guarantees intact in any networking change.

## 📄 License

[MIT](LICENSE) © Thatkidtk
