{"id":25188590,"url":"https://github.com/kleinpanic/toralizer","last_synced_at":"2025-04-04T10:14:26.277Z","repository":{"id":273459128,"uuid":"864784884","full_name":"kleinpanic/toralizer","owner":"kleinpanic","description":"Toralizer is a small, LD_PRELOAD-based tool that intercepts a program’s outgoing network connections and routes them through the Tor network via a SOCKS5 proxy. Instead of modifying or reconfiguring your software, Toralizer transparently hooks the connect() system call at runtime, sets up a SOCKS5 handshake with Tor (usually at 127.0.0.1:9050)","archived":false,"fork":false,"pushed_at":"2025-02-27T04:47:43.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-27T05:40:40.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kleinpanic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-29T06:41:49.000Z","updated_at":"2025-02-27T04:47:47.000Z","dependencies_parsed_at":"2025-01-21T03:35:46.201Z","dependency_job_id":null,"html_url":"https://github.com/kleinpanic/toralizer","commit_stats":null,"previous_names":["kleinpanic/toralizer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Ftoralizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Ftoralizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Ftoralizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2Ftoralizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kleinpanic","download_url":"https://codeload.github.com/kleinpanic/toralizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157277,"owners_count":20893221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-09T20:29:14.654Z","updated_at":"2025-04-04T10:14:26.267Z","avatar_url":"https://github.com/kleinpanic.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Toralizer**\n\nA **LD_PRELOAD-based** solution to transparently route application traffic through the [Tor](https://www.torproject.org/) network using **SOCKS5**.\n\n**Table of Contents**\n1. [Introduction](#introduction)\n2. [Features](#features)\n3. [Architecture \u0026 How It Works](#architecture--how-it-works)\n4. [What Is SOCKS5?](#what-is-socks5)\n5. [Installation](#installation)\n   - [Local Installation (No Global System Changes)](#local-installation-no-global-system-changes)\n   - [Global Installation (System-Wide)](#global-installation-system-wide)\n   - [Uninstallation](#uninstallation)\n6. [Usage](#usage)\n   - [Basic Usage](#basic-usage)\n   - [Examples](#examples)\n   - [Flags and Options](#flags-and-options)\n7. [Security \u0026 Privacy Considerations](#security--privacy-considerations)\n8. [Troubleshooting](#troubleshooting)\n9. [Development \u0026 Building from Source](#development--building-from-source)\n   - [Dependencies](#dependencies)\n   - [Compilation](#compilation)\n10. [Advanced Topics](#advanced-topics)\n   - [DNS Leakage](#dns-leakage)\n   - [IPv6 Details](#ipv6-details)\n   - [Intercepting Domain Names (SOCKS5 ATYP=3)](#intercepting-domain-names-socks5-atyp3)\n   - [Timeouts and Partial Reads/Writes](#timeouts-and-partial-readswrites)\n11. [License](#license)\n12. [Disclaimer](#disclaimer)\n13. [References \u0026 Further Reading](#references--further-reading)\n\n---\n\n## Introduction\n\n**Toralizer** aims to **“torify”** your networked applications by intercepting system calls (`connect()`) at runtime and funneling them through **Tor** via a **SOCKS5 proxy** (by default, `127.0.0.1:9050`).\n\n**Why use Toralizer?**\n\n- You don’t have to modify the source code of the application you want to tunnel through Tor.\n- You can **transparently** wrap programs such as `curl`, `wget`, or any other dynamically-linked binaries, forcing them to route TCP connections via the Tor network.\n- It’s an easy-to-use **script + `.so` library** approach with minimal overhead.\n\n---\n\n## Features\n\n- **LD_PRELOAD Hooking**: Leverages the dynamic linker’s `LD_PRELOAD` mechanism to intercept the `connect()` system call.\n- **SOCKS5** Implementation: Communicates with Tor’s SOCKS5 interface, enabling secure and anonymous outbound connections.\n- **IPv4 \u0026 IPv6** Support: The hooking library checks the `sa_family` and handles both `AF_INET` (IPv4) and `AF_INET6` (IPv6).\n- **Flexible Installation**:\n  - **Local** usage (no system-wide changes).\n  - **Global** installation (system-wide availability of `toralize` command).\n- **Optional** command-line flags: `--help`, `--version`, `--install`, `--uninstall`.\n\n---\n\n## Architecture \u0026 How It Works\n\n1. **LD_PRELOAD**:  \n   When you set `LD_PRELOAD=/path/to/toralizer.so`, the dynamic loader injects our library **before** the standard C library. Our implementation of `connect()` overrides the system’s default connect function.\n\n2. **Intercepting `connect()`**:  \n   - Whenever an application attempts to establish a TCP connection, it calls `connect()`.\n   - Our custom `connect()` function detects the target address and, instead, **opens a new socket** to your local Tor SOCKS5 proxy (`127.0.0.1:9050` by default).\n   - We then perform the **SOCKS5 handshake** with Tor, instructing it to connect to the original target IP and port.\n   - If successful, Tor returns a success code, and we `dup2()` the proxy socket onto the original file descriptor, so the application is none the wiser—it thinks it’s directly connected to the remote server.\n\n3. **Result**:  \n   All TCP traffic from that application flows **through Tor**. You get the anonymity benefits of Tor (though note [DNS Leakage](#dns-leakage) below).\n\n---\n\n## What Is SOCKS5?\n\n**SOCKS5** is a network proxy protocol widely supported by Tor. Key features:\n- **Client–Server** handshake:\n  1. **Greeting**: The client advertises supported authentication methods (e.g., “no auth”).\n  2. **Server Response**: The server picks an auth method.\n  3. **Client Connect Request**: The client requests a connection to a specific hostname/IP + port.\n  4. **Server Reply**: Indicates success or an error code.\n\n- **DNS via Proxy**: SOCKS5 can handle domain names (ATYP=0x03).  \n  However, if your application calls `getaddrinfo()` first (resolving the domain to an IP locally), that IP is used in the handshake. This can cause [DNS leakage](#dns-leakage).\n\n- **No Additional Encryption**: SOCKS5 itself doesn’t encrypt data (beyond the TCP connection). The anonymity comes from the **Tor network**.\n\n---\n\n## Installation\n\nToralizer can be used **locally** (no special privileges, no system changes) or **globally** (requires `root` or `sudo`).\n\n### Local Installation (No Global System Changes)\n\n1. **Build** (if not pre-built). See [Development \u0026 Building from Source](#development--building-from-source).\n2. **Keep** `toralize.sh` and `toralizer.so` in one folder.\n3. **Run** `toralize.sh your_command [args...]` to torify your desired program.\n\nNothing is installed to system directories. Everything remains in that local folder.\n\n### Global Installation (System-Wide)\n\n1. **Build** or obtain the `.so` library and the `toralize.sh` script.\n2. **Run**:\n   ```bash\n   sudo ./toralize.sh --install\n   ```\n3. **Follow the prompt**:\n   - Press `G` to install globally:\n     - The script copies `toralizer.so` into `/usr/local/share/toralizer/`.\n     - Installs a new script in `/usr/local/bin/toralize` that sets `LD_PRELOAD` automatically.\n   - Press `L` to do nothing (keep local).\n\nAfter a successful global install, you can:\n```bash\ntoralize curl http://check.torproject.org\n```\nNo need to reference `toralize.sh` or set `LD_PRELOAD` manually anymore.\n\n### Uninstallation\n\nRun:\n```bash\nsudo ./toralize.sh --uninstall\n```\nThis removes:\n- `/usr/local/bin/toralize`\n- `/usr/local/share/toralizer/`\n\n---\n\n## Usage\n\n### Basic Usage\n\nIn **local mode**:\n```bash\n# Use the script in the same directory as toralizer.so\n./toralize.sh curl http://check.torproject.org\n```\nBehind the scenes:\n- `LD_PRELOAD` is set to `toralizer.so`.\n- `curl`’s `connect()` calls are intercepted and routed through Tor.\n\n### Examples\n\n- **Check Tor**:\n  ```bash\n  ./toralize.sh curl -s https://check.torproject.org\n  ```\n  If the HTML states “Congratulations, this browser is configured to use Tor,” it worked.\n\n- **Download a file**:\n  ```bash\n  ./toralize.sh wget https://example.com/somefile.zip\n  ```\n\n- **SSH over Tor**: Potentially:\n  ```bash\n  ./toralize.sh ssh user@host.example\n  ```\n  (Note: This may have other implications, such as DNS leakage if `host.example` is resolved locally.)\n\n### Flags and Options\n\n**`--help`**  \nDisplays a help message describing usage, flags, and examples.\n\n**`--version`**  \nPrints the current version (e.g., `1.0.0`).\n\n**`--install`**  \nRuns an **interactive install** process:\n- Prompts whether to install **globally** or keep **local**.\n- If globally installed, requires `sudo` or root, copies `.so` to `/usr/local/share/toralizer/` and a script to `/usr/local/bin/toralize`.\n\n**`--uninstall`**  \nRemoves any previously installed global files.\n\n**(No flags)**  \nAny arguments after the script are treated as the **command to run** with `LD_PRELOAD` set.\n\n---\n\n## Security \u0026 Privacy Considerations\n\n1. **DNS Leakage**  \n   If the application resolves domain names **before** calling `connect()`, your system’s DNS resolver is used. This means DNS requests go **outside** Tor, potentially revealing your real IP or location (unless your system’s DNS also goes through Tor or is otherwise anonymized). See [DNS Leakage](#dns-leakage).\n\n2. **Infinite Recursion**  \n   The hooking library must detect when it’s connecting to the Tor SOCKS proxy itself (`127.0.0.1:9050` or `[::1]:9050`) to avoid recursively hooking that connection. Our code includes a check to skip hooking in that situation.\n\n3. **Partial Coverage**  \n   - Only **dynamically-linked** applications that use `connect()` from glibc (or similar) will be intercepted.  \n   - **Statically-linked** binaries bypass `LD_PRELOAD`.  \n   - Some applications may bypass standard library calls or have their own networking stack, in which case this hooking won’t work.\n\n4. **System Configuration**  \n   - Ensure Tor is running locally on `127.0.0.1:9050`.  \n   - Alternatively, update `TOR_PROXY_IP` and `TOR_PROXY_PORT` in the code if your Tor is bound elsewhere.\n\n---\n\n## Troubleshooting\n\n- **Tor not running**  \n  If you see errors like `connect(tor-proxy): Connection refused`, ensure Tor is running and listening on `127.0.0.1:9050`.\n  \n- **SOCKS5 error codes** (`SOCKS5 CONNECT failed, REP=0xXX`)  \n  Common issues:\n  - Tor’s `SocksPolicy` might be rejecting direct IP connections or a particular address range.\n  - The remote is unreachable or blocked by Tor exit policies.\n\n- **Permission denied**  \n  Installing globally requires root/sudo. If not, you’ll see permission errors.\n\n- **Not connecting**  \n  Try a verbose approach:\n  ```bash\n  TORALIZER_DEBUG=1 ./toralize.sh curl -v http://check.torproject.org\n  ```\n  (If you add debug prints to the C code, you can conditionally show them with an env variable.)\n\n---\n\n## Development \u0026 Building from Source\n\n### Dependencies\n\n- **gcc** or another C compiler\n- **make**\n- **libc6-dev** (standard libraries/headers)\n- **Tor** (to actually route traffic via SOCKS5)\n\n### Compilation\n\nA minimal `Makefile` might look like this:\n\n```make\nCC = gcc\nCFLAGS = -Wall -Wextra -fPIC -shared -ldl -D_GNU_SOURCE\nSRCS = toralize.c\nTARGET = toralizer.so\n\nall: $(TARGET)\n\n$(TARGET): $(SRCS)\n\t$(CC) $(CFLAGS) -o $(TARGET) $(SRCS)\n\nclean:\n\trm -f $(TARGET)\n```\n\n1. **Clone or copy** the `toralize.c` and `Makefile`.\n2. **Run** `make`.\n3. You should end up with `toralizer.so`.\n\nThen you can test locally:\n```bash\nexport LD_PRELOAD=/path/to/toralizer.so\ncurl http://check.torproject.org\nunset LD_PRELOAD\n```\n\nFor easier usage, use the provided **`toralize.sh`** script.\n\n---\n\n## Advanced Topics\n\n### DNS Leakage\n\n**DNS leakage** occurs when an application resolves a hostname **outside** Tor, typically by calling `getaddrinfo()`. By the time Toralizer intercepts `connect()`, the OS has already performed DNS resolution.  \n- **Solution**: Use SOCKS5 domain-based resolution (ATYP=0x03) or intercept `getaddrinfo()` as well. This is more complex but ensures DNS is done via Tor.\n\n### IPv6 Details\n\nToralizer checks `sa_family`:\n- If `AF_INET6`, it uses **ATYP=0x04** in the SOCKS5 handshake.\n- Tor must allow and handle IPv6 exits. Some Tor exit nodes don’t support IPv6, so your connection might fail if the remote site is IPv6-only and your chosen Tor exit doesn’t route IPv6.\n\n### Intercepting Domain Names (SOCKS5 ATYP=3)\n\nTo pass **raw domain names** to Tor (so Tor does the DNS resolution):\n- You’d need to catch the **domain** before the system resolver. Typically, that means hooking `getaddrinfo()` or rewriting library calls.  \n- Then send a SOCKS5 handshake with `ATYP=0x03`, length of domain, etc.  \n- This is **beyond** the minimal example we provide, but crucial for full anonymity.\n\n### Timeouts and Partial Reads/Writes\n\nThe code in `toralize.c` uses simplistic `recv()` and `send()` loops. In production, you may want to:\n- Implement **timeouts** to handle unresponsive or slow SOCKS5 servers.\n- Handle partial reads/writes more robustly.\n\n---\n\n## License\n\nThis project is typically distributed under an open-source license (e.g., MIT, GPL, etc.).  \nReplace this section with your actual license text. For example, the **MIT License**:\n\n```\nMIT License\n\nCopyright (c) 2025 ...\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files...\n```\n\n---\n\n## Disclaimer\n\n1. **Legal Compliance**: The Tor network and usage of anonymizing software may be regulated or restricted in certain jurisdictions. Ensure you comply with local laws and regulations.\n2. **Not Bulletproof**: Simply routing traffic through Tor does **not** guarantee perfect anonymity. Browser fingerprinting, DNS leaks, misconfigurations, or application-level data (e.g., cookies) can still deanonymize you.\n3. **Use at Your Own Risk**: I am not liable for any misuse or damages arising from its usage.\n\n---\n\n## References \u0026 Further Reading\n\n- [Tor Project – Official Documentation](https://support.torproject.org)\n- [SOCKS5 RFC 1928](https://datatracker.ietf.org/doc/html/rfc1928)\n- [LD_PRELOAD Tricks](https://blog.man7.org/linux/man-pages/man7/ld.so.7.html)\n- [Preventing DNS Leaks with Tor](https://2019.www.torproject.org/docs/faq.html.en#DoesTorProtectIPTunneling)\n\n**Happy Torifying!**  \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Ftoralizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkleinpanic%2Ftoralizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Ftoralizer/lists"}